source: project/chicken/trunk/README @ 15720

Last change on this file since 15720 was 15720, checked in by Ivan Raikov, 10 years ago

trunk version set to 4.1.8

File size: 15.0 KB
Line 
1
2  README file for the CHICKEN Scheme system
3  (c) 2000-2007, Felix L. Winkelmann
4  (c) 2008-2009, The Chicken Team
5
6  version 4.1.8
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        Note that parallel builds (using the "-j" make(1) option) is
69        *not* supported.
70
71        If you build CHICKEN directly from the development sources out
72        of the subversion repository, you will need a "chicken"
73        executable to generate the compiled C files from the Scheme
74        library sources. If you have a recent version of CHICKEN
75        installed, then pass "CHICKEN=<chicken-executable>" to the
76        "make" invocation to override this setting. "CHICKEN" defaults
77        to "$PREFIX/bin/chicken".
78
79        If you do not have a "chicken" binary installed, enter
80
81          make PLATFORM=<platform> PREFIX=<destination> bootstrap
82
83        which will unpack a tarball containing precompiled C sources
84        that are recent enough to generate the current version. After
85        building a statically linked compiler executable (named
86        "chicken-boot") all *.scm files are marked for rebuilt. By
87        passing "CHICKEN=./chicken-boot" to "make", you can force
88        using this bootstrapped compiler to build the system.
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-install', `chicken-uninstall' and
115          `chicken-status' will not be generated, as it is mostly
116          useless unless compiled code can be loaded.
117
118        SYMBOLGC=1
119          Always enable garbage collection for unused symbols in the
120          symbol table by default. This will result in slightly slower
121          garbage collection, but minimizes the amount of garbage
122          retained at runtime (which might be important for long
123          running server applications). If you don't specify this
124          option you can still enable symbol GC at runtime by passing
125          the `-:w' runtime option when running the program.
126
127        NOAPPLYHOOK=1
128          For maximum performance this will disable support for
129          breakpoints, but speed up procedure invocation in safe
130          code. Smaller binaries can be obtained by also giving
131          "NOPTABLES=1", but that means serialization (available
132          as a separate package) of procedures will not be available.
133
134        OPTIMIZE_FOR_SPEED=1
135          Use C optimization options that prefer speed over size. For
136          the GNU C compiler this will currently select "-O3" (the
137          default is "-Os"). You can also se
138          C_COMPILER_OPTIMIZATION_OPTIONS (see below) to have more
139          control over the options given to the C compiler.
140
141        C_COMPILER_OPTIMIZATION_OPTIONS=...
142          Override built-in C compiler optimization options. Available
143          for debug or release build.
144
145        PROGRAM_PREFIX=
146          A prefix to prepend to the names of all generated executables.
147          This allows having multiple CHICKEN versions in your PATH
148          (but note that they have to be installed at different locations).
149
150        PROGRAM_SUFFIX=
151          A suffix to be appended to the names of all generated executables.
152
153        HOSTSYSTEM=
154          A "<machine>-<platform>" name prefix to use for the C compiler to to
155          use to compile the runtime system and executables. Set this variable
156          if you want to compile CHICKEN for a different architecture than
157          the one on which you are building it.
158
159        TARGETSYSTEM=
160          Similar to "HOSTSYSTEM", but specifies the name
161          prefix to use for compiling code with the "csc" compiler
162          driver. This is required for creating a "cross chicken", a
163          specially built CHICKEN that invokes a cross C compiler to
164          build the final binaries. You will need a cross compiled
165          runtime system by building a version of CHICKEN with the
166          "HOST" option mentioned above. More information about this
167          process and the variables that you should set are provided
168          in the CHICKEN wiki at
169          <http://chicken.wiki.br/cross-compilation>.
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        VARDIR=
178          If set, this directory overrides the location where
179          extensions along with their metadata are stored. Normally
180          this will be equivalent to "<PREFIX>/lib/chicken/<BINARYVERSION>".
181          When VARDIR is specified, extensions will be stored in
182          "<VARDIR>/chicken/<BINARYVERSION>", conforming to the FHS.
183
184
185        To remove CHICKEN from your file-system, enter (probably as
186        root):
187
188            make PLATFORM=<platform> PREFIX=<destination> uninstall
189
190        (If you gave DESTDIR during installation, you have to pass
191        the same setting to "make" when uninstalling)
192
193        In case you invoke "make" with different configuration parameters,
194        it is advisable to run
195
196            make PLATFORM=<platform> confclean
197
198        to remove old configuration files.
199
200
201 3. Usage:
202
203        Documentation can be found in the directory
204        PREFIX/share/chicken/doc. The HTML documentation (in
205        "PREFIX/share/chicken/doc/html") is automatically generated
206        from the Wiki pages at <http://chicken.wiki.br/>. Go there to
207        read the most up to date documentation.
208
209
210 4. Extensions:
211
212        A large number of extension libraries for CHICKEN are
213        available at
214        <http://www.call-with-current-continuation.org/eggs/>. You can
215        automatically download, compile and install extensions with
216        the "chicken-install" program. See the CHICKEN User's Manual for
217        more information.
218
219        A selection of 3rd party libraries, together with source and
220        binary packages for tools helpful for development with CHICKEN
221        are also available at:
222        <http://www.call-with-current-continuation.org/tarballs/>.
223
224       
225 5. Platform issues:
226
227        - *BSD system users *must* use GNU make ("gmake") - the makefiles
228          can not be processed by BSD make.
229
230        - Some old Linux distributions ship with a buggy version of
231          the GNU C compiler (2.96). If the system is configured for
232          kernel recompilation, then an alternative GCC version is
233          available under the name `kgcc' (GCC 2.96 can not recompile
234          the kernel). CHICKEN's configuration script should normally
235          be able to handle this problem, but you have to remember to
236          compile your translated Scheme files with `kgcc' instead of
237          `gcc'.
238
239        - Older versions of Solaris have a bug in ld.so that causes
240          trouble with dynamic loading.  Patching Solaris fixes the
241          problem. Solaris 7 needs patch 106950-18. Solaris 8 has an
242          equivalent patch, 109147-16.
243
244          You can find out if you have these patches installed by
245          running:
246
247          % showrev -p | grep 106950    # solaris 7
248          % showrev -p | grep 109147    # solaris 8
249
250        - On NetBSD it might be possible that compilation fails with a
251          "virtual memory exhausted error".  Try the following:
252
253          % unlimit datasize
254
255        - Using external libraries on NetBSD may also be easier, if
256          you add the following definitions to `Makefile.bsd':
257
258            C_COMPILER_OPTIONS += -I/usr/pkg/lib
259            LINKER_OPTIONS += -L/usr/pkg/lib -Wl,-R/usr/pkg/lib
260
261          Note that this may cause build-problems, if you already have
262          an existing CHICKEN installation in the /usr/pkg prefix.
263
264        - For Mac OS X, Chicken requires libdl, for loading compiled
265          code dynamically. This library is available on Mac OS X 10.4
266          (Tiger) by default. For older versions you can find it here:
267
268            http://www.opendarwin.org/projects/dlcompat
269
270        - On Mac OS X, Chicken and its eggs can be built as universal
271          binaries which will work on either Intel or PowerPC.
272          To build on Tiger (10.4):
273
274            make PLATFORM=macosx ARCH=universal
275
276          On Leopard (10.5), an extra step is required before `make':
277
278            export MACOSX_DEPLOYMENT_TARGET=10.4
279            make PLATFORM=macosx ARCH=universal
280
281        - On Mac OS X, Chicken can be built in 64-bit mode on Intel
282          Core 2 Duo systems--basically, most recent machines.  The default
283          is 32-bit mode.  To enable 64-bit mode, invoke `make' thusly:
284
285            make PLATFORM=macosx ARCH=x86-64
286
287        - On Windows, mingw32, <http://mingw.sourceforge.net/> and
288          Cygwin are supported (Microsoft Visual Studio is *NOT*).
289          Makefiles for mingw under MSYS and Windows shell are provided
290          (`Makefile.mingw-msys' and `Makefile.mingw'). Please also
291          read the notes below.
292
293        - When installing under the mingw-msys platform, PREFIX must be an
294          absolute path name (i.e. it must include the drive letter) and
295          must use forward slashes (no backward slashes).
296
297        - When installing under mingw, with a windows shell ("cmd.exe"),
298          pass an absolute pathname as PREFIX and use forward slashes.
299
300        - When installing under mingw without MSYS, make sure that the
301          MSYS tools (in case you have some of them, in particular the
302          sh.exe UNIX shell) are *NOT* visible in your PATH.
303
304        - Cygwin will not be able to find the chicken shared libraries
305          until Windows is rebooted.
306
307        - gcc 3.4 shows sometimes warnings of the form
308
309            easyffi.c: In function `f_11735':
310            easyffi.c:18697: warning: `noreturn' function does return
311       
312          when compiling the system or compiled Scheme files. These
313          warnings are bogus and can be ignored.
314
315 6. Emacs support:
316
317        An emacs mode is provided in the file `hen.el'. To use it,
318        copy it somewhere into a location you normally use for emacs
319        extensions. If you want to add a specific location permanently
320        to the list of paths emacs should search for extensions, add
321        the following line to your `.emacs' file:
322
323          (setq load-path
324            (cons
325              "<directory-where-your-emacs-lisp-files-live>"
326              load-path))
327
328        Add
329
330          (require 'hen)
331       
332        To make "hen-mode" available, and enter it by issuing the
333        command M-x hen-mode.
334
335        A copy of Alex Shinn's highly useful tab-completion code is
336        also included in `scheme-complete.el'. Install it like `hen.el'
337        and add this code to your `.emacs':
338
339          (autoload 'scheme-smart-complete "scheme-complete" nil t)
340          (eval-after-load 'scheme
341            '(progn (define-key scheme-mode-map "\e\t" 'scheme-smart-complete)))
342
343        Or:
344
345          (eval-after-load 'scheme
346            '(progn (define-key scheme-mode-map "\t" 'scheme-complete-or-indent)))
347
348        If you use eldoc-mode (included in Emacs), you can also get live
349        scheme documentation with:
350
351        (add-hook 'scheme-mode-hook
352          (lambda ()
353              (setq eldoc-info-function 'scheme-get-current-symbol-info)
354                  (eldoc-mode)))
355
356        Replace "'scheme" in the elisp expressions above with "'hen", if
357        you want to add tab-completion to CHICKEN's own emacs mode.
358
359
360 7. Compatibility notes
361
362        CHICKEN 4 uses a completely reimplemented hygienic macro and
363        module system, which has considerably more felixbility and power,
364        but will require rewriting macros in code that previously was
365        used with CHICKEN 3. Notably, `define-macro' is not available
366        anymore. See the manual on how to translate such macros to
367        low-level hygienic macros or ask on the CHICKEN mailing list.
368
369
370 8. What's next?
371
372        If you find any bugs, or want to report a problem, please consider
373        using the "chicken-bug" tool to create a detailed bug report.
374
375        If you have any more questions or problems (even the slightest
376        problems, or the most stupid questions), then please subscribe
377        to the "chicken-users" mailing list and ask for help. It will
378        be answered.
379
380
381        Have fun!
Note: See TracBrowser for help on using the repository browser.