============================
OPEN DYLAN SOURCE CODE
CONVENTIONS AND ORGANIZATION
============================
========================
Acronyms and Definitions
========================
CG -
MPS - A memory management system. http://www.ravenbrook.com/project/mps/
When using a HARP back-end, either MPS or Boehm GC can be
used for garbage collection. When using a C back-end, the Boehm GC does
garbage collection.
DFM - Dylan Flow Machine. The intermediate high-level language of the compiler
DFMC - Dylan Flow Machine Compiler. Takes care about DFM
HARP - Harlequin Abstract RISC Processor. An artificial assembly language.
HARP code is transformed into the target processor's actual assembly
language. The other back-ends are Java byte-code and C.
RTG - Runtime Generator
DOOD - File-based object-oriented database.
========================
Platforms and Registries
========================
A platform is a combination of CPU and OS. Dylan-only code is platform
independent, but calling specific OS functions or specifying a library for the
linker introduces a platform dependency.
A platform-specific Dylan library is created through a platform-specific LID
file. The association between LID file and platform is created through files
in "sources/registry" directory. The files will contain a single line that
indicates the LID file for that library on that platform. The location of the
LID file is given relative to the "sources" directory.
The LID file will be in the source-code directory corresponding to that
library. There will be several LID files in that directory, with names that
indicate what platforms each applies to.
==================
Naming Conventions
==================
OD uses the following special character prefixes to indicate different things:
%name - An internal name.
&name - A model class. It models a run-time value at compile time.
^name - A compile-time computation on run-time value via a model class.
======================
Commenting Conventions
======================
"///" - Documentation of a function, macro, etc.
"---" - Interim solution or questionable code.
"---***" - Serious concerns or bug work-arounds.
===========
Directories
===========
The directory structure doesn't provide enough context to say which file is
used where, so I've attempted to catalog each directory's purpose myself.
---------------
Compiler System
---------------
sources
dfmc
core - Module imports and re-exports.
conversion - Converts definitions to DFM by emitting corresponding
control and data flow nodes, initializer methods, etc.
definitions - Takes input from parser and adds some semantics to it.
Like 'this is a class definition' etc.
flow-graph - Defines the DFM language by defining classes involved.
linker - Linker generics. Makefile prototype.
management - Safeguards and progress of compilation. Compilation
driver.
mangling - Mangle Dylan names into [a-zA-Z0-9_] names.
modeling - Bridge between compile time and runtime, contains the
classes and methods which are available at runtime,
but also at compile time (e.g. for optimizations).
namespace - Bindings, libraries, modules, lib structure.
optimization - Analyzes and performs optimizations.
reader - Lexer and parser. Also, formatted output.
typist - Type inferencing engine.
lib
build-system - Jam-based build system.
jam - Jam script interpreter.
parser-run-time - Support for parsers.
source-records - Reads source files and tracks location.
walker - Build has-a tree.
project-manager - Takes care about dependencies of projects and actual
invocation of linker, etc.
projects - Shared code between user and registry projects,
general API.
registry-projects - Code handling projects in the registry.
tools-interface - Hookup for libraries into a release.
user-projects - Code handling user projects.
------------------------
IDE and Tool Source Code
------------------------
sources
environment - Main code for IDE and tools.
commands - Defines various shell commands.
console - Console IDE declarations.
core - Module imports and re-exports.
debugger - Debugger GUI.
deuce - Deuce customizations for IDE.
dfmc - Introspection and IDE interactor - glue between DFM and environment
dummy - Interactor environment.
dswank - SLIME back-end for Open Dylan
editor - External editor support.
framework - Generic GUI elements.
manager - Client/server communication.
profiler - Profiler GUI.
protocols - Models of various project elements for display and
introspection.
source-control - External source control system interface.
target-application - Access control to application being debugged.
tools - Miscellaneous, mostly GUI-related.
lib
disasm - x86 disassembler for debugger.
grammar-compiler - Used by parser-generator.
motley - OLE stub generator.
parser-generator - Generates Dylan code that can parse a grammar.
ppml - Pretty-printer formatting and markup.
release-info - Copyrights, banners, and setting retrieval. Also
includes a simple XML parser.
----------
Registries
----------
These files are installed as part of an Open Dylan release, and indicate what
libraries go together and how a library should be built for a specific
platform.
sources
Library-Packs
registry
generic - This code is platform-independent.
... - Each platform gets its own directory. Platforms are
named for their processor and operating system.
--------------------------------------------
Dylan Language, Extensions, Run-Time Support
--------------------------------------------
By "extension," I mean a library that extends built-in definitions and class
hierarchies.
sources
collections - Collection extensions.
common-dylan - Common language extensions shared by Open Dylan and
Gwydion Dylan.
dylan - Dylan Reference Manual implementation.
lib
big-integers - Mathematical library for big integers (> 28 bits).
generic-arithmetic - Arithmetic prototypes for all numeric libraries.
memory-manager - Abstraction layer for memory manager (MPS or Boehm).
run-time - Memory management and threading primitives.
---------------------------------
Main Libraries Used by Open Dylan
---------------------------------
sources
deuce - OD advanced text editor.
duim - Platform-independent GUI wrapper.
io - I/O library.
lib
c-ffi - General C API wrapper.
channels - Intra-application messaging.
dood - File database library.
variable-search - Locate a binding in DLLs or libs.
system - OS-specific code for file system, environment
variables, Windows registry, dates and times.
Architecture definitions.
---------------
Other Libraries
---------------
These libraries aren't used by Open Dylan, or are only used in a minor
capacity, but they do have use.
sources
corba - CORBA library.
databases - SQL and ODBC library.
lib
cl - Common Lisp plists, sequences, and strings.
c-lexer - C lexer.
commands - Win32 inter-process communication helper, intended
for things like DDE via command shell.
collection-extensions - Extensions from Gwydion Dylan.
midi - MIDI library.
strings - Additional string methods.
t-list - A variation of a <deque>. Don't know its purpose.
network - Socket and protocol libraries.
ole - COM and OLE libraries.
win32 - Win32 API wrappers.
-----------
Sample Code
-----------
sources
app - Sample applications.
examples - Sample applications.
------------
Unclassified
------------
These may or may not be used or useful, but either I haven't looked at them,
or I don't know what they do, or I don't know how to properly describe them.
admin
install
packages
sources
benchmarks
dfmc
back-end
back-end-protocol
browser-support
c-back-end
c-compiler
c-ffi
c-linker
common
conditions
debug-back-end
dylan
harp-browser-support
harp-cg
harp-cg-linker
harp-native-cg
harp-x86-cg
macro-expander
environment
gtk
project-wizard
property-pages
reports
server
splash-screen
tests
harp
lib
dispatch-profiler
qa
runtime-manager
tools