Changeset 35447 in project

04/26/18 14:27:08 (5 weeks ago)

man/5: first try at chapter for units

2 edited


  • wiki/man/5/TODO/Units and linking model

    r35318 r35447  
     1[[tags: manual]]
     4== Units and the linking model
    3 == Statically linked applications
     6Compiling Scheme code to standalone executables or dynamically
     7loadable files is the most common and simplest way of using CHICKEN.
     8But for more advanced uses like static linking, creating dynamic
     9libraries or embedding compiled code into other (usually C/C++ based)
     10applications it is helpful to understand the internal model CHICKEN
     11uses to organize compiled code and separate compilation units.
     13Every compiled Scheme file (from here on called a ''compilation unit'')
     14consists of a ''toplevel'' C function holding the compiled toplevel
     15expressions in the order in which they appear in the source file. Scheme
     16functions ({{lambda}}s) are compiled 1-to-1 into additional C functions,
     17including the intermediate lambda-functions that are the result of the CPS
     18conversion that is done by the compiler.
    6 -----
     20The toplevel C function of a compilation unit is comparable to the
     21{{main}} function in C programs, and for standalone executables
     22the startup code inside the runtime system will eventually call this
     23toplevel function. Dynamically loaded compiled code is structured
     24in the same way, with a toplevel function that is dynamically looked
     25up in the loaded binary and invoked to execute the expressions from
     26the loaded code. Statically linked compilation units are treated similarly,
     27there also exists a toplevel function which is called at some stage in the
     28startup process to execute the forms of the file.
    8 The most portable way of creating separately linkable entities is
    9 supported by so-called ''unit''s.  A unit is a single
    10 compiled object module that contains a number of toplevel expressions that
    11 are executed either when the unit is the ''main'' unit or if the
    12 unit is ''used''.  To use a unit, the unit has to be ''declare''d
    13 as used, like this:
     30For standalone executables and dynamically loaded code the toplevel
     31function has a fixed, predefined name ({{C_toplevel}}). For static
     32linking or for using multiple toplevels in a shared library that combines
     33multiple compilation units (like {{libchicken}}, for example), non-internal
     34function names have to be different to be properly
     35distinguished, so we assign a unique ''unit'' name to each compilation unit that
     36is intended to be linked with other compilation units.
     38To set the name of a compilation unit, use
     40<enscript highlight=scheme>
     41(declare (unit UNITNAME))
     44''Invocation'' of a unit (actually running the toplevel code contained in it) is done
     45automatically for standalone programs and dynamically loaded compiled code,
     46but must be done explicitly for uniquely named units that are part of a larger
     47library or when doing static linking. To do so, use
    1549<enscript highlight=scheme>
    19 The toplevel expressions of used units are executed in the order in
    20 which the units appear in the {{uses}} declaration. Units
    21 may be used multiple times and {{uses}} declarations may
    22 be circular (the unit is initialized at most once).  To compile a file
    23 as a unit, add a {{unit}} declaration:
     53Invocation takes place at the start of the current compilation unit, so the
     54toplevel of any ''used'' units is executed before the toplevel of the compilation
     55unit that is ''using'' one. Invocation can also be done explicitly by using
     56{{load-library}} which takes the name of a unit to be invoked as an
    25 <enscript highlight=scheme>
    26 (declare (unit UNITNAME))
    27 </enscript>
     59Note that this model of using code from other compilation units does not
     60address syntax definitions, it's for running pure, fully expanded and compiled
     61code. Syntax and modules are handled at a higher level, using import
     62libraries, which are compiled or interpreted separate files setting up module
     63information to allow the compiler to properly resolve module namespaces
     64and imports.
    29 When compiling different object modules, make sure to have one main
    30 unit. This unit is called initially and initializes all used units
    31 before executing its toplevel expressions. The main-unit has no
    32 {{unit}} declaration.
    34 Another method of using definitions in separate source files is to
    35 ''include'' them. This simply inserts the code in a given file into
    36 the current file:
    38 <enscript highlight=scheme>
    39 (include "FILENAME")
    40 </enscript>
    42 Macro definitions are only available when processed by {{include}} or
    43 {{import}}. Macro definitions in separate units are not available,
    44 since they are defined at compile time, i.e the time when that other
    45 unit was compiled (macros can optionally be available at runtime, see
    46 {{define-syntax}} in [[Non-standard macros and special forms|Substitution forms and macros]]).
     67Previous: [[Using the compiler]]
     68Next: [[Cross development]]
  • wiki/man/5/TODO/Using the compiler

    r34052 r35447  
    479479Previous: [[Basic mode of operation]]
    481 Next: [[Using the interpreter]]
     481Next: [[Units and the linking model]]
Note: See TracChangeset for help on using the changeset viewer.