Dig currently only compiles on HP/Ux and Win32, and is probably not useful on the latter. Feel free to get it working on other platforms. dig is not strictly necessary in any case, but it does sugarcoat some of the naming issues.

DIG Commands

print

This command extends the existing print command by allowing it to print Dylan values and call Dylan functions. This actually comprises three different special capabilities:

1. DIG applies heuristics to translate Dylan variable names into their C equivalents. It guess right most of the time, but the results are not guaranteed. Sometimes there are several possibilities -- in this case it will ask you for clarification.
2. If the expression value is a Dylan object then DIG invokes "print" to provide a meaningful description of the object. (The choice of which "print" to use depends upon the setting of *warning-output*.) Because DIG calls a function within your program, the program must be running before Dylan values may be printed.
3. If the expression contains a Dylan function call, then DIG invokes that Dylan function. Arguments of the form "foo: bar" are translated correctly.

find

prints the translation of a Dylan variable name into its C equivalent.

break

if you specify a Dylan generic function, then DIG will set breakpoints in all of that function's methods. Let me know if this feature proves to be useful.

interactive

by default, anything typed into DIG is assumed to be a DIG command. If you need to provide input to your program, you must use this command to toggle the "interactive mode". In interactive mode, you may type data into your process. However, any type-ahead may produce strange and unpredictable results.

prompt

change DIG's command prompt. (You should not use gdb's native "set prompt" command. Bad things will happen.)

quit

does about what you'd expect, but does some extra clean-up work.

gdb

passes the following text to GDB verbatim. This allows you, for example, to use GDB's "print" command instead of DIG's.

DIG Gotchas

• Because of the challenges of name translation, the "print" and "break" commands may be noticeably slower than you expect. Since translations are cached, it will get faster as you go along.
• If you try to print something that looks like a Dylan object, but isn't valid, DIG will encounter a "beg fault" and have to recover. This has the annoying side-effect of changing the "current frame" to be at the bottom of the call stack, regardless of where you were before.
• Like GDB, DIG has problems with optimized code. Variables may be re-used (or eliminated), function calls may be inlined, and things will generally be less predictable. In addition, some Dylan functions may disappear if you do not pass the "-g" switch to D2C.
• There are probably many other gotchas, but I don't know about them. Please tell me about anything not mentioned above.

DYLANDIR

The root of the installed Gwydion tree. In the default configuration, this defaults to "/usr/local" on Unix and "c:\dylan" on win32. This variable in turn establishes the defaults for DYLANPATH and the "platforms.descr" file.

DYLANPATH

The search path for dylan libraries. Directories in the DYLANPATH are searched after any directories specified by explicit -L options. If not set, this defaults to ".:$DYLANDIR/lib/dylan" (".;%DYLANDIR%\lib\dylan" on Win32). If set, the value must include the directory where the "Dylan" library is to be found.

PATH

d2c expects to find make and the C compiler in PATH. On Unix we use the gnu tools gmake, gcc, and ldb. Other compilers can work, but at a minimum this requires a new platform description in "$DYLANDIR/etc/platforms.descr". You must also have some of the GNU-win32 tools to run d2c on Windows, though make and Visual C++ are normally used for compilation. To build d2c, you also need perl and the various scripts in the tools/" directory.

The gnu assembler must be used in conjunction with the generated code from gcc. If you somehow end up running the HP/UX "as" with gcc, it will produce many errors about STAB entries, etc.

CCFLAGS

This variable holds the flags passed to the C compiler. The default is platform specific, but always includes "-I$DYLANDIR/include". If you do set this variable, you must also specify the Dylan system include directory. The default optimization flags for gcc are " -g -O4 -finline-functions". You can roughly halve the size of the executable by omitting the -g, but at the cost of debuggability. Leaving out the other optimize flags will speed compilation at the cost of runtime speed.

The actual C code comes in three pieces, or entries, with each entry being a separate C function. At a call site, the compiler can either know exactly what function is being called or it might not have a clue (e.g. inside map where it calls the passed in function). So to keep from having to pay the penalty of runtime checking everything all the time instead of just when necessary, we generate multiple entry points for each function.

The main entry is the entry that is used when the compiler can determine that everything is fine. It doesn't have to check any argument types or figure out what values correspond to what keywords.

The general entry is the entry that is used in a random call where the compiler can't tell anything. It checks the argument types, decodes the keywords, and then calls the main entry.

The generic entry is like the general entry, except that it is only used when the method was invoked via some generic function. The generic function dispatch stuff already guarantees that they argument types are okay, so it only has to decode the keywords before calling the main entry.

Note:

the various entries are just different pieces of C code. There is no dylan object that correspond to them. If the compiler can prove a given entry won't be used, d2c will omit that entry.

Character Set Translation

' ' => "BLANK"
'!' => "D"
'%' => "PCT"
'$' => "C"
'&' => "AND"
'*' => "V"
'+' => "PLUS"
'-' => "_"
'/' => "SLASH"
'<' => "LESS"
'=' => "EQUAL"
'>' => "GREATER"
'?' => "QUERY"
'^' => "RAISE"
'_' => "X_"
'|' => "OR"
'~' => "NOT"
otherwise => "Xhex code"

Basic Name Translation

unix prefixZmodule nameZbasic name

Derived Name Translation

GF name_METH

Some method on the base name.

GF name_DISCRIM

Discriminator for a generic function.

method name_GENERAL

Default entry for a method.

method name_GENERIC

Method entry used by GF dispatch.

method name_MAIN

The actual body of a method.

method name_INT_local method name

Local method inside named method.

method name_INT_method

Some method form inside the named method.

slot name_DEFER

Deferred evaluation of a slot type.

slot name_INIT

Slot init function.

slot name_SETTER

Method used to implement setting a slot.

slot name_GETTER

Method used to implement setting a slot

var name_TYPE

Holds the type of a variable when the type isn't constant.

var name_VAR

The actual value of a Dylan variable.

class name_MAKER

Internal constructor for a class.

LINE_542

Some function resulting from compiling line 542.

UNKNOWN

As above, except we don't where it came from.

some name_542

The 542'nd distinct instance of name. _VAR names are guaranteed never to have this uniquifier suffix.

As you might infer from the preceding, some suffixes can be combined, but except for _INT_ not to an arbitrary depth. Some examples:

	dylanZdylan_visceraZCLS_type    /* <type> */

        /* general-entry for maker for <type-error> */
	dylanZdylan_visceraZCLS_type_error_MAKER_GENERAL

	/* signal{<condition>} internal search */
	dylanZdylan_visceraZsignal_METH_INT_search_MAIN

	dylanZdylan_visceraZVdebuggerV_VAR     /* *debugger* */

known dylan type	c type
<integer>	long
<single-float>	float
<double-float>	double
<extended-float>	long double
<raw-pointer>	void *
no data word	heapptr_t
<object>	descriptor_t

Note:

There isn't a dylan type that can describe the set of objects that use the heapptr_t representation. See above.

Note 2:

If a functional (see below) class has exactly one data slot that can be magically represented, it is also magically represented in the same way. <character> falls into this category.

An immediate representation is one where the actual data is directly there. As opposed to a pointer representation where the actual data lives in the heap and is referenced via a pointer.

The general representation is the fully general representation that can be used to represent any Dylan object. It consists of a heap pointer and a data word. (i.e. descriptor_t) The heap pointer representation is used to represent anything that doesn't need the data word. (i.e. heapptr_t)

"Boxed" and "unboxed" are somewhat vague terms that one will often hear on the 'net. Unboxed data is the raw data, the good stuff, with no overhead. The drawback is that if you don't know the type of the raw data (is it an integer, a character, or a float?), it's just a bunch of bits. Boxing means to add meta-data (the type of the data) so that the data can be interpreted unambiguously. The d2c immediate representation is an unboxed representation, while the d2c general representation is a boxed representation. Depending on the situation, the heap pointer representation might be considered either boxed or unboxed.

inline

Methods can be declared inline. If a method is inline, then the body of the method is duplicated at all valid call sites. This allows optimization of the called code based on the calling context.

movable

Methods and generic functions can be declared movable. A movable function is one that doesn't depend on when it happens. In other words, in can't depend on any global state, just the arguments.

Plus is an example of a movable function: 2 + 2 is always 4 no matter when. movable implies flushable; see below.

flushable

Methods and generic functions can be declared flushable. This means that the function may depend on global state, but cannot change any global state. Extracting the value of a slot is a flushable operation (assuming the slot is guaranteed to be initialized). If the result of a flushable function isn't used, the call can be dropped.

functional

Classes can be declared functional. The slots of functional classes have to be constant (and in fact, default to constant). Furthermore, equality (==) is defined in terms of the slot values, not the pointer identity of the heap representation of the object. Actually, currently you have to define a functional-== method that checks to see if two instances of a functional class are the same yourself. So you could intentionally get it wrong, and then strange things would happen. But the idea is that the instances will be == iff the object-class for them both is the same and all slots are ==. Functional classes may have subclasses, but be sure to define functional-== methods accordingly.

d2c performs the following optimizations:

common sub-expression elimination (CSE), optimistic type inferencing, compile time method selection, inlining, code motion.

d2c generates a variety of files. They are:

*.c

d2c generates a .c file for each .dylan file it processes.

unitprefix-inits.c

contains code for performing various initializations for this particular library. This includes executing any top-level expressions contained in the library.

unitprefix-heap.s

contains the initial heap image for this particular library.

cc-unitprefix-files.mak

A makefile which contains rules for compiling all the .c and .s files, and linking either an executable or a library, depending on which the LID file specifies.

library.lib.du

(Only generated when not building an executable) Contains various information about the library that d2c needs to remember.

inits.c

(Only generated when building an executable) It invokes each library's initialization routines, then calls the entry-point function (if any).

heap.s

(Only generated when building an executable) It contains initial heap information that is of a global nature. For instance, because all symbols with the same value are ==, the literal #"foo" in the String-extensions library is == to the literal #"foo" in the Streams library, and so cannot go in either library's unitprefix-heap.s. Currently symbols are the only object with this property.

If the type expression isn't an obvious compile-time constant, then d2c gains no useful information from it, but is required to go to extra work to implement a run-time check. For this reason, your code will compile much better if you only use type expressions which d2c can recognize as being constant. The notion of compile time constant lies at the heart of many of d2c's optimizations.

To start with, some terminology:

ctype

The compile-time representation of a Dylan type. If a type is not constant, it is represented as an <unknown-ctype>, which frustrates any attempt at further type inference.

ct-value

A compile-time value. The phrase "compile time constant" is synonymous. <ct-value> is not a subclass of <ctype>, nor the other way around. However, there are many classes which are subtypes of both <ctype> and <ct-value>.

EQL-value

A value is an eql-value if members of its class can be compared with ==. <class>es, <integer>s, <character>s, and <symbol>s are eql-values; in d2c non-class <type>s are not.

eql-ct-value

A ct-value which is also an eql-value.

If we can figure out a ct-value equivalent to an expression parse, we say that expression is ct-evaluable. An expression is ct-evaluable if any of the following holds:

• The expression is a literal.
• The expression is a body (e.g. the guts of a begin/end), and each expression in the body is ct-evaluable. (A body whose last component expression is ct-evaluable, but which also has non-ct-evaluable expressions in it, might have side effects. Thus, the body can't be ct-evaluable because that might suppress the side effects.)
• The expression is a reference to a binding, and that binding is to a module binding rather than a local binding, and the definition it is bound to is ct-evaluable (see below).
• The expression is a function call, and the arguments to the function are all ct-evaluable, and the function itself is a direct reference to a module binding which is a function (ie, we know which function to invoke), and the function has built-in support, and the function call meets the conditions of that specific function (see below).

Some definitions are ct-evaluable, and some are not:

• A "define variable" definition is never ct-evaluable, because it is variable.
• A "define constant" is ct-evaluable if the type constraint is ct-evaluable and the initial value is ct-evaluable.
• A "define generic" is ct-evaluable if all specializers, all result types, and the type constraints on #rest types are ct-evaluable.
• A "define method" doesn't usually define a module binding; define generics do. However, if the define method introduces an implicit generic, that implicit generic is ct-evaluable.
• "define function" in d2c is equivalent to "define method".
• "define class" is ct-evaluable if all its superclasses are ct-evaluable. (Note that d2c currently will puke if a class has a non-ct-evaluable superclass, so effectively all classes in d2c are ct-evaluable.)
• "define macro", "define module", and "define library" don't produce module bindings.

For function calls to most functions with built-in support, simply knowing that the arguments and the function are ct-evaluable is enough to make the function call ct-evaluable. These functions include:

type-union, false-or, subclass, direct-instance, negative, abs, \+, \-, \*, ash, \^, logior, logxor, logand, lognot

However, two functions are different. In addition to requiring that the arguments and the function are ct-evaluable, they impose additional constraints:

singleton(obj) is ct-evaluable only if obj is an eql-ct-value.

one-of(obj1, obj2, ...) is ct-evaluable only if every arg is an eql-ct-value.

The most common way to construct a type which is not ct-evaluable is to create a singleton of a non-class type. For instance, although

        type-union(<foo>, <bar>)

        singleton(type-union(<foo>, <bar>))