                         ============================
                            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.
    stack-walker        - Debugging on UNIX by walking the stack. Nowadays
                          directly in the run-time.
    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.
  tools/map-statistics  - Win32 MAP files.

----------
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
