source: project/chicken/trunk/README @ 11712

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

Version set to 3.3.10

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