~ chicken-core (chicken-5) /manual/Units and linking model

 1[[tags: manual]]
 2[[toc:]]
 3
 4== Units and the linking model
 5
 6Compiling Scheme code to standalone executables or dynamically
 7loadable files is the most common and simplest way of using CHICKEN.
 8The extension system handles straightforward cases of static linking 
 9of modules in a mostly transparent way, which is usually sufficient
10for normal situations.
11
12But for more advanced uses like static linking, creating dynamic 
13libraries or embedding compiled code into other (usually C/C++ based)
14applications it is helpful to understand the internal model CHICKEN
15uses to organize compiled code and separate compilation units.
16
17Every compiled Scheme file (from here on called a ''compilation unit'')
18consists of a ''toplevel'' C function holding the compiled toplevel
19expressions in the order in which they appear in the source file. Scheme
20functions ({{lambda}}s) are compiled 1-to-1 into additional C functions,
21including the intermediate lambda-functions that are the result of the CPS
22conversion that is done by the compiler.
23
24The toplevel C function of a compilation unit is comparable to the
25{{main}} function in C programs, and for standalone executables
26the startup code inside the runtime system will eventually call this
27toplevel function. Dynamically loaded compiled code is structured
28in the same way, with a toplevel function that is dynamically looked
29up in the loaded binary and invoked to execute the expressions from
30the loaded code. Statically linked compilation units are treated similarly,
31there also exists a toplevel function which is called at some stage in the
32startup process to execute the forms of the file.
33
34For standalone executables and dynamically loaded code the toplevel
35function has a fixed, predefined name ({{C_toplevel}}). For static
36linking or for using multiple toplevels in a shared library that combines
37multiple compilation units (like {{libchicken}}, for example), non-internal 
38function names have to be different to be properly
39distinguished, so we assign a unique ''unit'' name to each compilation unit that
40is intended to be linked with other compilation units.
41
42To set the name of a compilation unit, use
43
44<enscript highlight=scheme>
45(declare (unit UNITNAME))
46</enscript>
47
48''Invocation'' of a unit (actually running the toplevel code contained in it) is done
49automatically for standalone programs and dynamically loaded compiled code,
50but must be done explicitly for uniquely named units that are part of a larger
51library or when doing static linking. To do so, use
52
53<enscript highlight=scheme>
54(declare (uses UNITNAME))
55</enscript>
56
57Invocation takes place at the start of the current compilation unit, so the
58toplevel of any ''used'' units is executed before the toplevel of the compilation
59unit that is ''using'' one. Invocation can also be done explicitly by using
60{{load-library}} (from the {{(chicken load)}}) module,
61which takes the name of a unit to be invoked as an
62argument.
63
64Note that this model of using code from other compilation units does not
65address syntax definitions, it's for running pure, fully expanded and compiled
66code. Syntax and modules are handled at a higher level, using import 
67libraries, which are compiled or interpreted separate files setting up module
68information to allow the compiler to properly resolve module namespaces 
69and imports. 
70
71----
72Previous: [[Egg specification format]]
73
74Next: [[Deployment]]