~ chicken-core (chicken-5) b363a4f86dc364f1c0036d98d2ac9fcef7b324c1
commit b363a4f86dc364f1c0036d98d2ac9fcef7b324c1
Author: Evan Hanson <evhan@foldling.org>
AuthorDate: Mon Apr 4 15:46:06 2016 +1200
Commit: Evan Hanson <evhan@foldling.org>
CommitDate: Mon Apr 4 15:46:06 2016 +1200
Update the "distributing C files" manual section
It had fallen far out of date and contained some minor errors. Also,
sort the file listings and fix some noise caused by a merge conflict.
diff --git a/manual/Using the compiler b/manual/Using the compiler
index e5aeb983..bcc4a0f5 100644
--- a/manual/Using the compiler
+++ b/manual/Using the compiler
@@ -361,11 +361,11 @@ purpose.
The compiler supplies a couple of hooks to add user-level passes to the
compilation process. Before compilation commences any Scheme source files
or compiled code specified using the {{-extend}} option are loaded
-and evaluated. The parameters {{user-options-pass, user-read-pass,
-user-preprocessor-pass, user-pass}} and {{user-post-analysis-pass}} can be set
-to procedures that are called to perform certain compilation passes
-instead of the usual processing (for more information about parameters
-see: [[Supported language]].
+and evaluated. The parameters {{user-options-pass}}, {{user-read-pass}},
+{{user-preprocessor-pass}}, {{user-pass}} and {{user-post-analysis-pass}}
+can be set to procedures that are called to perform certain compilation
+passes instead of the usual processing (for more information about
+parameters see [[Supported language]]).
<parameter>user-options-pass</parameter>
@@ -387,27 +387,23 @@ Holds a procedure of one argument. This procedure is applied to each toplevel ex
Holds a procedure that will be called after every performed program analysis pass. The procedure (when defined) will be called with seven arguments: a symbol indicating the analysis pass, the program database, the current node graph, a getter and a setter-procedure which can be used to access and manipulate the program database, which holds various information about the compiled program, a pass iteration count, and an analysis continuation flag. The getter procedure should be called with two arguments: a symbol representing the binding for which information should be retrieved, and a symbol that specifies the database-entry. The current value of the database entry will be returned or {{#f}}, if no such entry is available. The setter procedure is called with three arguments: the symbol and key and the new value. The pass iteration count currently is meaningful only for the 'opt pass. The analysis continuation flag will be {{#f}} for the last 'opt pass. For information about the contents of the program database contact the author.
-Loaded code (via the {{-extend}} option) has access to the library
-units {{extras, srfi-4, utils, regex}} and the pattern matching macros.
-Multithreading is not available.
-
Note that the macroexpansion/canonicalization phase of the compiler adds
-certain forms to the source program. These extra expressions are not
-seen by {{user-preprocessor-pass}} but by {{user-pass}}.
+certain forms to the source program. These extra expressions are not
+seen by {{user-preprocessor-pass}}, but are seen by {{user-pass}}.
=== Distributing compiled C files
It is relatively easy to create distributions of Scheme projects that
have been compiled to C. The runtime system of CHICKEN consists of only
-three handcoded C files ({{runtime.c}} and {{chicken.h}}), plus
-the file {{chicken-config.h}}, which is generated by the build process. All
-other modules of the runtime system and the extension libraries are just
-compiled Scheme code.The following example shows a minimal application, which
-should run without changes on the most frequent operating systems, like Windows,
-Linux or FreeBSD (Static binaries are NOT supported on Mac OS X):
-
+two handcoded C files ({{runtime.c}} and {{chicken.h}}), plus the files
+{{chicken-config.h}} and {{buildtag.h}}, which are generated by the
+build process. All other modules of the runtime system and the extension
+libraries are just compiled Scheme code. The following example shows a
+minimal application, which should run without changes on most operating
+systems, like Windows, Linux or FreeBSD (note however that static
+binaries are not supported on Mac OS X).
-Let's take a simple example.
+Take the following "Hello World" program:
<enscript highlight=scheme>
; hello.scm
@@ -417,37 +413,36 @@ Let's take a simple example.
% csc -t hello.scm -optimize-level 3 -output-file hello.c
-Compiled to C, we get {{hello.c}}. We need the files {{chicken-config.h}},
-{{chicken.h}}, {{buildtag.h}} and {{runtime.c}}, which contain the basic runtime
-system, plus the library files {{library.c}}, {{internal.c}}, {{eval.c}},
-{{expand.c}}, {{modules.c}} and {{build-version.c}}, which contain the same
-functionality as the library linked into a plain CHICKEN-compiled application,
-or which is available by default in the interpreter, {{csi}}:
+Compiled to C, we get {{hello.c}}. We need the files {{chicken.h}},
+{{chicken-config.h}}, {{buildtag.h}} and {{runtime.c}}, which contain
+the basic runtime system, plus the library files {{build-version.c}},
+{{chicken-syntax.c}}, {{eval.c}}, {{expand.c}}, {{internal.c}},
+{{library.c}} and {{modules.c}}, which contain the same functionality as
+the library that is linked into plain CHICKEN-compiled applications:
% cd /tmp
% echo '(print "Hello World.")' > hello.scm
- % cp $CHICKEN_BUILD/runtime.c .
- % cp $CHICKEN_BUILD/library.c .
- % cp $CHICKEN_BUILD/eval.c .
- % cp $CHICKEN_BUILD/extras.c .
- % cp $CHICKEN_BUILD/expand.c .
- % cp $CHICKEN_BUILD/modules.c .
- % cp $CHICKEN_BUILD/build-version.c .
- % cp $CHICKEN_BUILD/chicken.h .
- % cp $CHICKEN_BUILD/chicken-config.h .
- % cp $CHICKEN_BUILD/buildtag.h .
- % gcc -static -Os -fomit-frame-pointer -DHAVE_CHICKEN_CONFIG_H runtime.c build-version.c \
- library.c eval.c expand.c modules.c hello.c -o hello -lm
-
-Now we have all files together, and can create an tarball containing all the files:
-
-<<<<<<< HEAD
- % tar cf hello.tar hello.c runtime.c build-version.c library.c eval.c extras.c \
- expand.c modules.c chicken.h chicken-config.h
-=======
- % tar cf hello.tar hello.c runtime.c build-version.c library.c internal.c \
- eval.c extras.c expand.c modules.c chicken.h chicken-config.h
->>>>>>> 0b88ca1... Add core form for library tracking
+ % csc -t hello.scm
+ % cp $CHICKEN_BUILD/build-version.c .
+ % cp $CHICKEN_BUILD/chicken-syntax.c .
+ % cp $CHICKEN_BUILD/eval.c .
+ % cp $CHICKEN_BUILD/expand.c .
+ % cp $CHICKEN_BUILD/internal.c .
+ % cp $CHICKEN_BUILD/library.c .
+ % cp $CHICKEN_BUILD/modules.c .
+ % cp $CHICKEN_BUILD/runtime.c .
+ % cp $CHICKEN_BUILD/chicken.h .
+ % cp $CHICKEN_BUILD/chicken-config.h .
+ % cp $CHICKEN_BUILD/buildtag.h .
+ % gcc -static -Os -fomit-frame-pointer -DHAVE_CHICKEN_CONFIG_H hello.c \
+ build-version.c eval.c expand.c internal.c library.c modules.c runtime.c \
+ -o hello -lm
+
+Once we have all the files together, we can create a tarball:
+
+ % tar cf hello.tar hello.c build-version.c chicken-syntax.c eval.c \
+ expand.c internal.c library.c modules.c runtime.c chicken.h \
+ chicken-config.h buildtag.h
% gzip hello.tar
This is naturally rather simplistic. Things like enabling dynamic
@@ -456,12 +451,14 @@ more configuration- and build-time support. All this can be addressed
using more elaborate build-scripts, makefiles or by using
autoconf/automake.
-The {{chicken-config.h}} file may contain wrong settings for your
-deployment target. Especially when the architecture is different.
-In that case you will have to adjust the values as needed.
+The {{chicken-config.h}} file may contain incorrect settings for your
+deployment target. Especially when the architecture is different. In
+that case you will have to adjust the values as needed.
-Note also that the size of the application can still be reduced by removing
-{{eval}} and compiling {{hello.scm}} with the {{-explicit-use}} option.
+Note that the size of the application can still be reduced by removing
+any of the C files besides {{build-version.c}}, {{library.c}}, and
+{{runtime.c}}, and compiling {{hello.scm}} with the {{-explicit-use}}
+option.
For more information, study the CHICKEN source code and/or ask on the CHICKEN
mailing list.
Trap