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

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

merged changes from trunk (rev 6579)

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