source: project/chicken/branches/release/README @ 7931

Last change on this file since 7931 was 7931, checked in by felix winkelmann, 12 years ago

merged from prerelease branch rev. 7930 - release version 3.0.0; fixed wrong version numbers in some files

File size: 12.0 KB
Line 
1
2  README file for the CHICKEN compiler
3  (c)2000-2008 Felix L. Winkelmann
4
5  version 3.0.0
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 defaults 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 "chicken" executable, the system
82        is rebuilt using the static compiler.
83
84        The build may show errors when creating the info(1)
85        documentation, if you do not have GNU texinfo installed.
86        This is not fatal - the build should proceed.
87
88        If CHICKEN is build successfully, you can install it on your
89        system by entering
90
91          make PLATFORM=<platform> PREFIX=<destination> install
92
93        "PREFIX" defaults to "/usr/local". Note that the PREFIX is
94        compiled into several CHICKEN tools and must be the same
95        while building the system and during installation.
96
97        To install CHICKEN for a particular PREFIX on a different
98        location, set the "DESTDIR" variable in addition to "PREFIX":
99        It designates the directory where the files are installed
100        into.
101
102        You can further enable various optional features by adding
103        one or more of the following variables to the "make"
104        invocation:
105
106        DEBUGBUILD=1
107          Disable optimizations in compiled C code and enable
108          debug information.
109
110        STATICBUILD=1
111          Build only static versions of the runtime library, compiler
112          and interpreter. `chicken-setup' will not be generated,
113          as it is mostly unless compiled code can be loaded.
114
115        SYMBOLGC=1
116          Always enable garbage collection for unused symbols in the
117          symbol table by default. This will result in slightly slower
118          garbage collection, but minimizes the amount of garbage
119          retained at runtime (which might be important for long
120          running server applications). If you don't specify this
121          option you can still enable symbol GC at runtime by passing
122          the `-:w' runtime option when running the program.
123
124        NOAPPLYHOOK=1
125          For maximum performance this will disable support for
126          breakpoints, but speed up procedure invocation in safe
127          code. Smaller binaries can be obtained by also giving
128          "NOPTABLES=1", but that means serialization (available
129          as a separate package) of procedures will not be available.
130
131        C_COMPILER_OPTIMIZATION_OPTIONS=...
132          Override built-in C compiler optimization options. Available
133          for debug or release build.
134
135        PROGRAM_PREFIX=
136          A prefix to prepend to the names of all generated executables.
137          This allows having multiple CHICKEN versions in your PATH
138          (but note that they have to be installed at different locations).
139
140        PROGRAM_SUFFIX=
141          A suffix to be appended to the names of all generated executables.
142
143        HOSTSYSTEM=
144          A "<machine>-<platform>" name prefix to use for the C compiler to to
145          use to compile the runtime system and executables. Set this variable
146          if you want to compile CHICKEN for a different architecture than
147          the one on which you are building it.
148
149        TARGETSYSTEM=
150          Similar to "HOSTSYSTEM", but specifies the name
151          prefix to use for compiling code with the "csc" compiler
152          driver. This is required for creating a "cross chicken", a
153          specially built CHICKEN that invokes a cross C compiler to
154          build the final binaries. You will need a cross compiled
155          runtime system by building a version of CHICKEN with the
156          "HOST" option mentioned above. More information about this
157          process and the variables that you should set are provided
158          in the CHICKEN wiki at
159          <http://chicken.wiki.br/cross-compilation>.
160
161        USE_HOST_PCRE=
162          The PCRE library is included with the CHICKEN
163          distribution to remove external dependencies and to avoid
164          incompatibilities with any previously installed version. If
165          you want to link with an installed libpcre, set this
166          variable to a non-empty value. Only use this feature if you
167          know what you are doing.
168
169        To remove CHICKEN from your file-system, enter (probably as
170        root):
171
172            make PLATFORM=<platform> PREFIX=<destination> uninstall
173
174        (If you gave DESTDIR during installation, you have to pass
175        the same setting to "make" when uninstalling)
176
177        In case you invoke "make" with different configuration parameters,
178        it is advisable to run
179
180            make PLATFORM=<platform> confclean
181
182        to remove old configuration files.
183
184
185 3. Usage:
186
187        Documentation can be found in the directory
188        PREFIX/share/chicken/doc. The HTML documentation (in
189        "PREFIX/share/chicken/doc/html") is automatically generated
190        from the Wiki pages at <http://chicken.wiki.br/>. Go there to
191        read the most up to date documentation.
192
193
194 4. Extension:
195
196        A large number of extension libraries for CHICKEN are
197        available at
198        <http://www.call-with-current-continuation.org/eggs/>. You can
199        automatically download, compile and install extensions with
200        the "chicken-setup" program. See the CHICKEN User's Manual for
201        more information.
202
203        Windows users: Note that you must have "tar" and "gunzip"
204        programs installed and available through the "PATH"
205        environment variable to extract extensions. If you don't
206        download and extract the extensions ("eggs") manually using a
207        browser and the decompression program of your choice and run
208        "chicken-setup" in the directory where you extracted the
209        extension archive.
210
211        Windows binaries for common UNIX utilities (most notably "tar"
212        and "gunzip") are available here:
213        <http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip>.
214
215        A selection of 3rd party libraries, together with source and
216        binary packages for tools helpful for development with CHICKEN
217        are also available at:
218        <http://www.call-with-current-continuation.org/tarballs/>.
219
220       
221 5. Platform issues:
222
223        - *BSD system users *must* use GNU make ("gmake") - the makefiles
224          can not be processed by BSD make.
225
226        - Some old Linux distributions ship with a buggy version of
227          the GNU C compiler (2.96). If the system is configured for
228          kernel recompilation, then an alternative GCC version is
229          available under the name `kgcc' (GCC 2.96 can not recompile
230          the kernel). CHICKEN's configuration script should normally
231          be able to handle this problem, but you have to remember to
232          compile your translated Scheme files with `kgcc' instead of
233          `gcc'.
234
235        - Older versions of Solaris have a bug in ld.so that causes
236          trouble with dynamic loading.  Patching Solaris fixes the
237          problem. Solaris 7 needs patch 106950-18. Solaris 8 has an
238          equivalent patch, 109147-16.
239
240          You can find out if you have these patches installed by
241          running:
242
243          % showrev -p | grep 106950    # solaris 7
244          % showrev -p | grep 109147    # solaris 8
245
246        - On NetBSD it might be possible that compilation fails with a
247          "virtual memory exhausted error".  Try the following:
248
249          % unlimit datasize
250
251        - For Mac OS X, Chicken requires libdl, for loading compiled
252          code dynamically. This library is available on Mac OS X 10.4
253          (Tiger) by default. For older version you can find it here:
254
255            http://www.opendarwin.org/projects/dlcompat
256
257        - On Mac OS X, Chicken and its eggs can be built as universal
258          binaries which will work on either Intel or PowerPC.
259
260            make PLATFORM=macosx ARCH=universal
261
262        - On Mac OS X, Chicken can be built in 64-bit mode on Intel
263          Core 2 Duo systems--basically, most recent machines.  The default
264          is 32-bit mode.  To enable 64-bit mode, invoke `make` thusly:
265
266            make PLATFORM=macosx ARCH=x86-64
267
268        - On Windows, only mingw32 <http://mingw.sourceforge.net/> and
269          Cygwin is supported (Microsoft Visual Studio is
270          NOT). Makefiles for mingw under MSYS and Windows shell are
271          provided (`Makefile.mingw-msys' and `Makefile.mingw').
272         
273        - Cygwin will not be able to find the chicken shared libraries
274          until Windows is rebooted.
275
276        - gcc 3.4 shows sometimes warnings of the form
277
278            easyffi.c: In function `f_11735':
279            easyffi.c:18697: warning: `noreturn' function does return
280       
281          when compiling the system or compiled Scheme files. These
282          warnings are bogus and can be ignored.
283
284
285 6. Emacs support:
286
287        An emacs mode is provided in the file `hen.el'. To use it,
288        copy it somewhere into a location you normally use for emacs
289        extensions. If you want to add a specific location permanently
290        to the list of paths emacs should search for extensions, add
291        the following line to your `.emacs' file:
292
293          (setq load-path
294            (cons
295              "<directory-where-your-emacs-lisp-files-live>"
296              load-path))
297
298        Add
299
300          (require 'hen)
301       
302        To make "hen-mode" available, and enter it by issuing the
303        command M-x hen-mode.
304
305        A copy of Alex Shinn's highly useful tab-completion code is
306        also included in `scheme-complete.el'. Install it like `hen.el'
307        and add this code to your `.emacs':
308
309          (autoload 'scheme-smart-complete "scheme-complete" nil t)
310          (eval-after-load 'scheme
311            '(progn (define-key scheme-mode-map "\e\t" 'scheme-smart-complete)))
312
313        Or:
314
315          (eval-after-load 'scheme
316            '(progn (define-key scheme-mode-map "\t" 'scheme-complete-or-indent)))
317
318        If you use eldoc-mode (included in Emacs), you can also get live
319        scheme documentation with:
320
321        (add-hook 'scheme-mode-hook
322          (lambda ()
323              (setq eldoc-info-function 'scheme-get-current-symbol-info)
324                  (eldoc-mode)))
325
326        Replace "'scheme" in the elisp expressions above with "'hen", if
327        you want to add tab-completion to CHICKEN's own emacs mode.
328
329
330 7. What's next?
331
332        If you find any bugs, or want to report a problem, please consider
333        using the "chicken-bug" tool to create a detailed bug report.
334
335        If you have any more questions or problems (even the slightest
336        problems, or the most stupid questions), then please subscribe
337        to the "chicken-users" mailing list or contact me at:
338
339        <felix@call-with-current-continuation.org>
340
341
342        Have fun!
Note: See TracBrowser for help on using the repository browser.