source: project/chicken/branches/prerelease/README @ 9381

Last change on this file since 9381 was 9381, checked in by Ivan Raikov, 12 years ago

Merged trunk into prerelease

File size: 13.0 KB
Line 
1
2  README file for the CHICKEN compiler
3  (c)2000-2008 Felix L. Winkelmann
4
5  version 3.0.3
6
7 1. Introduction:
8
9        CHICKEN is a Scheme-to-C compiler supporting the language
10        features as defined in the 'Revised^5 Report on
11        Scheme'. Separate compilation is supported and full
12        tail-recursion and efficient first-class continuations are
13        available.
14
15        Some things that CHICKEN has to offer:
16
17        1. CHICKEN generates quite portable C code and compiled files
18           generated by it (including itself) should work without any
19           changes on DOS, Windows, most UNIX-like platforms, and with
20           minor changes on other systems.
21
22        2. The whole package is distributed under a BSD style license
23           and as such is free to use and modify as long as you agree
24           to its terms.
25
26        3. Linkage to C modules and C library functions is
27           straightforward. Compiled programs can easily be embedded
28           into existing C code.
29
30        4. Loads of extra libraries.
31
32        Note: Should you have any trouble in setting up and using
33        CHICKEN, please ask questions on the Chicken mailing list. You
34        can subscribe to the list from the Chicken homepage,
35        http://www.call-with-current-continuation.org)
36
37
38 2. Installation:
39
40        First unzip the package ("unzip chicken-<version>.zip" or "tar
41        xzf chicken-<version>.tar.gz" on UNIX or use your favorite
42        extraction program on Windows).
43
44        Building CHICKEN requires GNU Make. Other "make" derivates are
45        not supported. If you are using a Windows system and do not
46        have GNU Make, see below for a link to a precompiled set of
47        UNIX utilities, which among other useful tools contains "make".
48
49        Configuration and customization of the build process is done by
50        either setting makefile variables on the "make" command line or
51        by editing the platform-specific makefile.
52
53        Invoke "make" like this:
54
55          make PLATFORM=<platform> PREFIX=<destination>
56
57        where "PLATFORM" specifies on what kind of system CHICKEN
58        shall be built and "PREFIX" specifies where the executables
59        and libraries shall be installed. Out-of-directory builds are
60        currently not supported, so you must be in the toplevel source
61        directory to invoke "make".
62
63        Enter "make" without any options to see a list of supported
64        platforms.
65
66        If you build CHICKEN directly from the development sources out
67        of the subversion repository, you will need a "chicken"
68        executable to generate the compiled C files from the Scheme
69        library sources. If you have a recent version of CHICKEN
70        installed, then pass "CHICKEN=<chicken-executable>" to the
71        "make" invocation to override this setting. "CHICKEN" defaults
72        to "$PREFIX/bin/chicken".
73
74        If you do not have a "chicken" binary installed, enter
75
76          make PLATFORM=<platform> PREFIX=<destination> bootstrap
77
78        which will unpack a tarball containing precompiled C sources
79        that are recent enough to generate the current version. After
80        building a statically linked compiler executable (named
81        "chicken-boot") all *.scm files are marked for rebuilt. By
82        passing "CHICKEN=./chicken-boot" to "make", you can force
83        using this bootstrapped compiler to build the system.
84
85        The build may show errors when creating the info(1)
86        documentation, if you do not have GNU texinfo installed.
87        This is not fatal - the build should proceed.
88
89        If CHICKEN is build successfully, you can install it on your
90        system by entering
91
92          make PLATFORM=<platform> PREFIX=<destination> install
93
94        "PREFIX" defaults to "/usr/local". Note that the PREFIX is
95        compiled into several CHICKEN tools and must be the same
96        while building the system and during installation.
97
98        To install CHICKEN for a particular PREFIX on a different
99        location, set the "DESTDIR" variable in addition to "PREFIX":
100        It designates the directory where the files are installed
101        into.
102
103        You can further enable various optional features by adding
104        one or more of the following variables to the "make"
105        invocation:
106
107        DEBUGBUILD=1
108          Disable optimizations in compiled C code and enable
109          debug information.
110
111        STATICBUILD=1
112          Build only static versions of the runtime library, compiler
113          and interpreter. `chicken-setup' will not be generated,
114          as it is mostly useless unless compiled code can be loaded.
115
116        SYMBOLGC=1
117          Always enable garbage collection for unused symbols in the
118          symbol table by default. This will result in slightly slower
119          garbage collection, but minimizes the amount of garbage
120          retained at runtime (which might be important for long
121          running server applications). If you don't specify this
122          option you can still enable symbol GC at runtime by passing
123          the `-:w' runtime option when running the program.
124
125        NOAPPLYHOOK=1
126          For maximum performance this will disable support for
127          breakpoints, but speed up procedure invocation in safe
128          code. Smaller binaries can be obtained by also giving
129          "NOPTABLES=1", but that means serialization (available
130          as a separate package) of procedures will not be available.
131
132        C_COMPILER_OPTIMIZATION_OPTIONS=...
133          Override built-in C compiler optimization options. Available
134          for debug or release build.
135
136        PROGRAM_PREFIX=
137          A prefix to prepend to the names of all generated executables.
138          This allows having multiple CHICKEN versions in your PATH
139          (but note that they have to be installed at different locations).
140
141        PROGRAM_SUFFIX=
142          A suffix to be appended to the names of all generated executables.
143
144        HOSTSYSTEM=
145          A "<machine>-<platform>" name prefix to use for the C compiler to to
146          use to compile the runtime system and executables. Set this variable
147          if you want to compile CHICKEN for a different architecture than
148          the one on which you are building it.
149
150        TARGETSYSTEM=
151          Similar to "HOSTSYSTEM", but specifies the name
152          prefix to use for compiling code with the "csc" compiler
153          driver. This is required for creating a "cross chicken", a
154          specially built CHICKEN that invokes a cross C compiler to
155          build the final binaries. You will need a cross compiled
156          runtime system by building a version of CHICKEN with the
157          "HOST" option mentioned above. More information about this
158          process and the variables that you should set are provided
159          in the CHICKEN wiki at
160          <http://chicken.wiki.br/cross-compilation>.
161
162        USE_HOST_PCRE=
163          The PCRE library is included with the CHICKEN
164          distribution to remove external dependencies and to avoid
165          incompatibilities with any previously installed version. If
166          you want to link with an installed libpcre, set this
167          variable to a non-empty value. Only use this feature if you
168          know what you are doing.
169
170        To remove CHICKEN from your file-system, enter (probably as
171        root):
172
173            make PLATFORM=<platform> PREFIX=<destination> uninstall
174
175        (If you gave DESTDIR during installation, you have to pass
176        the same setting to "make" when uninstalling)
177
178        In case you invoke "make" with different configuration parameters,
179        it is advisable to run
180
181            make PLATFORM=<platform> confclean
182
183        to remove old configuration files.
184
185
186 3. Usage:
187
188        Documentation can be found in the directory
189        PREFIX/share/chicken/doc. The HTML documentation (in
190        "PREFIX/share/chicken/doc/html") is automatically generated
191        from the Wiki pages at <http://chicken.wiki.br/>. Go there to
192        read the most up to date documentation.
193
194
195 4. Extension:
196
197        A large number of extension libraries for CHICKEN are
198        available at
199        <http://www.call-with-current-continuation.org/eggs/>. You can
200        automatically download, compile and install extensions with
201        the "chicken-setup" program. See the CHICKEN User's Manual for
202        more information.
203
204        Windows users: Note that you must have "tar" and "gunzip"
205        programs installed and available through the "PATH"
206        environment variable to extract extensions. If you don't
207        download and extract the extensions ("eggs") manually using a
208        browser and the decompression program of your choice and run
209        "chicken-setup" in the directory where you extracted the
210        extension archive.
211
212        Windows binaries for common UNIX utilities (most notably "tar"
213        and "gunzip") are available here:
214        <http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip>.
215
216        A selection of 3rd party libraries, together with source and
217        binary packages for tools helpful for development with CHICKEN
218        are also available at:
219        <http://www.call-with-current-continuation.org/tarballs/>.
220
221       
222 5. Platform issues:
223
224        - *BSD system users *must* use GNU make ("gmake") - the makefiles
225          can not be processed by BSD make.
226
227        - Some old Linux distributions ship with a buggy version of
228          the GNU C compiler (2.96). If the system is configured for
229          kernel recompilation, then an alternative GCC version is
230          available under the name `kgcc' (GCC 2.96 can not recompile
231          the kernel). CHICKEN's configuration script should normally
232          be able to handle this problem, but you have to remember to
233          compile your translated Scheme files with `kgcc' instead of
234          `gcc'.
235
236        - Older versions of Solaris have a bug in ld.so that causes
237          trouble with dynamic loading.  Patching Solaris fixes the
238          problem. Solaris 7 needs patch 106950-18. Solaris 8 has an
239          equivalent patch, 109147-16.
240
241          You can find out if you have these patches installed by
242          running:
243
244          % showrev -p | grep 106950    # solaris 7
245          % showrev -p | grep 109147    # solaris 8
246
247        - On NetBSD it might be possible that compilation fails with a
248          "virtual memory exhausted error".  Try the following:
249
250          % unlimit datasize
251
252        - For Mac OS X, Chicken requires libdl, for loading compiled
253          code dynamically. This library is available on Mac OS X 10.4
254          (Tiger) by default. For older versions you can find it here:
255
256            http://www.opendarwin.org/projects/dlcompat
257
258        - On Mac OS X, Chicken and its eggs can be built as universal
259          binaries which will work on either Intel or PowerPC.
260          To build on Tiger (10.4):
261
262            make PLATFORM=macosx ARCH=universal
263
264          On Leopard (10.5), an extra step is required before `make':
265
266            export MACOSX_DEPLOYMENT_TARGET=10.4
267            make PLATFORM=macosx ARCH=universal
268
269        - On Mac OS X, Chicken can be built in 64-bit mode on Intel
270          Core 2 Duo systems--basically, most recent machines.  The default
271          is 32-bit mode.  To enable 64-bit mode, invoke `make' thusly:
272
273            make PLATFORM=macosx ARCH=x86-64
274
275        - On Windows, mingw32, <http://mingw.sourceforge.net/>,
276          Cygwin, and Visual C/C++ (PLATFORM=msvc) are supported.
277          Makefiles for mingw under MSYS and Windows shell are provided
278          (`Makefile.mingw-msys' and `Makefile.mingw').
279
280        - Cygwin will not be able to find the chicken shared libraries
281          until Windows is rebooted.
282
283        - gcc 3.4 shows sometimes warnings of the form
284
285            easyffi.c: In function `f_11735':
286            easyffi.c:18697: warning: `noreturn' function does return
287       
288          when compiling the system or compiled Scheme files. These
289          warnings are bogus and can be ignored.
290
291        - The Visual C build requires GNU make and other POSIX
292          utilities.  Both cygwin and msys (with the Developer's
293          Toolkit) have the necessary utilities. When setting PREFIX,
294          use forward slashes:
295
296          make PLATFORM=msvc PREFIX=c:/development/chicken
297
298          The build has been tested with Visual Studio 2003 and 2008.  If
299          you are able to build Chicken with other versions, please let
300          us know.
301
302          The following additional issues apply when using Chicken with
303          Visual C:
304
305          - Add the /DPIC flag when compiling your source files.  Otherwise
306            you will encounter undefined symbols when linking.  Note that csc
307            does this automatically for dlls but NOT for programs.
308
309          - csc generates dynamics libraries with a .so extension, not .dll.
310
311 6. Emacs support:
312
313        An emacs mode is provided in the file `hen.el'. To use it,
314        copy it somewhere into a location you normally use for emacs
315        extensions. If you want to add a specific location permanently
316        to the list of paths emacs should search for extensions, add
317        the following line to your `.emacs' file:
318
319          (setq load-path
320            (cons
321              "<directory-where-your-emacs-lisp-files-live>"
322              load-path))
323
324        Add
325
326          (require 'hen)
327       
328        To make "hen-mode" available, and enter it by issuing the
329        command M-x hen-mode.
330
331        A copy of Alex Shinn's highly useful tab-completion code is
332        also included in `scheme-complete.el'. Install it like `hen.el'
333        and add this code to your `.emacs':
334
335          (autoload 'scheme-smart-complete "scheme-complete" nil t)
336          (eval-after-load 'scheme
337            '(progn (define-key scheme-mode-map "\e\t" 'scheme-smart-complete)))
338
339        Or:
340
341          (eval-after-load 'scheme
342            '(progn (define-key scheme-mode-map "\t" 'scheme-complete-or-indent)))
343
344        If you use eldoc-mode (included in Emacs), you can also get live
345        scheme documentation with:
346
347        (add-hook 'scheme-mode-hook
348          (lambda ()
349              (setq eldoc-info-function 'scheme-get-current-symbol-info)
350                  (eldoc-mode)))
351
352        Replace "'scheme" in the elisp expressions above with "'hen", if
353        you want to add tab-completion to CHICKEN's own emacs mode.
354
355
356 7. What's next?
357
358        If you find any bugs, or want to report a problem, please consider
359        using the "chicken-bug" tool to create a detailed bug report.
360
361        If you have any more questions or problems (even the slightest
362        problems, or the most stupid questions), then please subscribe
363        to the "chicken-users" mailing list and ask for help. It will
364        be answered.
365
366
367        Have fun!
Note: See TracBrowser for help on using the repository browser.