[tclquadcode] Mapping the Code (was Re: New stuff for array accesses)

[Donal K. F. <don...@ma...>]

On 12/11/2017 11:37, Donal K. Fellows wrote:
> Also, thanks for the list of places I need to beware of. That's very 
> useful.

Thinking about this, it occurs to me that we could do with some crude 
maps of the code that says where to look for key things so that we can 
find our ways around each other's code. Yes, these things will change 
over time, but even an obsolete map is better than _terra incognita_.

Here's what's what in the code generator. As of 11/11/2017.

Front-End Code
--------------
jit.tcl
    Front-end drivers to connect the pieces together. (Probably badly
    misnamed; just not sure what to call it.)
config.tcl
    Configuration code for the code generator.

Quadcode Translation
--------------------
compile.tcl
    Takes quadcode and issues LLVM IR. The core of the code generator.

Binding Layer
-------------
build.tcl
    The interface between the code issuer and the back end implementation
    functions. (Glue. Lots of long-winded glue. See also the automatic
    type widener in struct.tcl.)
tycon.tcl
    Maps implementation types and constants.

Tcl Runtime Interface
---------------------
tclapi.tcl
    The binding to Tcl's API functions. (Exactly what is generated
    depends on whether we're building in stubs mode or not, but the rest
    of the code is entirely unaware.)
macros.tcl
    Versions of macros in Tcl's API. (Macros are complex to convert
    across, as we have exactly zero access to the C preprocessor.)
thunk.tcl
    The code to generate bindings of the functions we create to Tcl
    commands. (Without this, calling generated code from user code would
    be impossible.)

Inlineable Functions Implementing Quadcodes
-------------------------------------------
stdlib.tcl
    Definitions of functions that implement quadcodes. (These are all
    designed to be inlined.)
mathlib.tcl
    Math related functions (extracted from stdlib.tcl for reasons of file
    length).
varframe.tcl
    Tcl variable and callframe related functions (extracted from
    stdlib.tcl for reasons of file length).

LLVM API Binding
----------------
llvmbuilder.tcl
    Code to *safely* issue LLVM opcodes. (This is the part that I'm
    considering migrating into C or C++ first.)
debug.tcl
    Code to connect to the LLVM debugging metadata system.
struct.tcl
    Definitions of structural entities such as modules/code-units,
    functions and basic blocks. (Also includes definitions of all Tcl
    structures and the type widening logic used in build.tcl; those bits
    probably need to move elsewhere)


In terms of classes, there are these:

llvmEntity — support methods (logging, warnings, closures)
   TclCompiler — code generator core
     TclInterproceduralCompiler — miscellaneous wrappers
   BuildSupport — definitions of how to write an inlineable function
     LLVMBuilder — base instruction issuer that integrates with debugging
                   support layer
       Builder — adds the autowidening type system (through parsing of
                 method names)
     ThunkBuilder — interfaces to Tcl runtime
   Module — LLVM major code unit
   Function — LLVM function
   Block — LLVM basic block
   Debugging — LLVM debugging metadata generator

I'm not at all convinced that I've got this all right yet. Some parts 
are definitely good ideas, but others creak at the seams.

Donal.