source: project/chicken/trunk/README @ 13452

Last change on this file since 13452 was 13452, checked in by felix winkelmann, 11 years ago

some cleanup, manual fixes, NEWS and README update

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