source: project/chicken/trunk/README @ 15414

Last change on this file since 15414 was 15414, checked in by felix winkelmann, 10 years ago

added support for VARDIR

File size: 14.7 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.1
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        C_COMPILER_OPTIMIZATION_OPTIONS=...
135          Override built-in C compiler optimization options. Available
136          for debug or release build.
137
138        PROGRAM_PREFIX=
139          A prefix to prepend to the names of all generated executables.
140          This allows having multiple CHICKEN versions in your PATH
141          (but note that they have to be installed at different locations).
142
143        PROGRAM_SUFFIX=
144          A suffix to be appended to the names of all generated executables.
145
146        HOSTSYSTEM=
147          A "<machine>-<platform>" name prefix to use for the C compiler to to
148          use to compile the runtime system and executables. Set this variable
149          if you want to compile CHICKEN for a different architecture than
150          the one on which you are building it.
151
152        TARGETSYSTEM=
153          Similar to "HOSTSYSTEM", but specifies the name
154          prefix to use for compiling code with the "csc" compiler
155          driver. This is required for creating a "cross chicken", a
156          specially built CHICKEN that invokes a cross C compiler to
157          build the final binaries. You will need a cross compiled
158          runtime system by building a version of CHICKEN with the
159          "HOST" option mentioned above. More information about this
160          process and the variables that you should set are provided
161          in the CHICKEN wiki at
162          <http://chicken.wiki.br/cross-compilation>.
163
164        SRCDIR=
165          Specifies that CHICKEN should be built outside of its source
166          tree. The SRCDIR variable indicates the location of the
167          CHICKEN source tree. The executables and object files will
168          be generated in the current directory.
169
170        VARDIR=
171          If set, this directory overrides the location where
172          extensions along with their metadata are stored. Normally
173          this will be equivalent to "<PREFIX>/lib/chicken/<BINARYVERSION>".
174          When VARDIR is specified, extensions will be stored in
175          "<VARDIR>/chicken/<BINARYVERSION>", conforming to the FHS.
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. Extensions:
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-install" program. See the CHICKEN User's Manual for
210        more information.
211
212        A selection of 3rd party libraries, together with source and
213        binary packages for tools helpful for development with CHICKEN
214        are also available at:
215        <http://www.call-with-current-continuation.org/tarballs/>.
216
217       
218 5. Platform issues:
219
220        - *BSD system users *must* use GNU make ("gmake") - the makefiles
221          can not be processed by BSD make.
222
223        - Some old Linux distributions ship with a buggy version of
224          the GNU C compiler (2.96). If the system is configured for
225          kernel recompilation, then an alternative GCC version is
226          available under the name `kgcc' (GCC 2.96 can not recompile
227          the kernel). CHICKEN's configuration script should normally
228          be able to handle this problem, but you have to remember to
229          compile your translated Scheme files with `kgcc' instead of
230          `gcc'.
231
232        - Older versions of Solaris have a bug in ld.so that causes
233          trouble with dynamic loading.  Patching Solaris fixes the
234          problem. Solaris 7 needs patch 106950-18. Solaris 8 has an
235          equivalent patch, 109147-16.
236
237          You can find out if you have these patches installed by
238          running:
239
240          % showrev -p | grep 106950    # solaris 7
241          % showrev -p | grep 109147    # solaris 8
242
243        - On NetBSD it might be possible that compilation fails with a
244          "virtual memory exhausted error".  Try the following:
245
246          % unlimit datasize
247
248        - Using external libraries on NetBSD may also be easier, if
249          you add the following definitions to `Makefile.bsd':
250
251            C_COMPILER_OPTIONS += -I/usr/pkg/lib
252            LINKER_OPTIONS += -L/usr/pkg/lib -Wl,-R/usr/pkg/lib
253
254          Note that this may cause build-problems, if you already have
255          an existing CHICKEN installation in the /usr/pkg prefix.
256
257        - For Mac OS X, Chicken requires libdl, for loading compiled
258          code dynamically. This library is available on Mac OS X 10.4
259          (Tiger) by default. For older versions you can find it here:
260
261            http://www.opendarwin.org/projects/dlcompat
262
263        - On Mac OS X, Chicken and its eggs can be built as universal
264          binaries which will work on either Intel or PowerPC.
265          To build on Tiger (10.4):
266
267            make PLATFORM=macosx ARCH=universal
268
269          On Leopard (10.5), an extra step is required before `make':
270
271            export MACOSX_DEPLOYMENT_TARGET=10.4
272            make PLATFORM=macosx ARCH=universal
273
274        - On Mac OS X, Chicken can be built in 64-bit mode on Intel
275          Core 2 Duo systems--basically, most recent machines.  The default
276          is 32-bit mode.  To enable 64-bit mode, invoke `make' thusly:
277
278            make PLATFORM=macosx ARCH=x86-64
279
280        - On Windows, mingw32, <http://mingw.sourceforge.net/> and
281          Cygwin are supported (Microsoft Visual Studio is *NOT*).
282          Makefiles for mingw under MSYS and Windows shell are provided
283          (`Makefile.mingw-msys' and `Makefile.mingw'). Please also
284          read the notes below.
285
286        - When installing under the mingw-msys platform, PREFIX must be an
287          absolute path name (i.e. it must include the drive letter) and
288          must use forward slashes (no backward slashes).
289
290        - When installing under mingw, with a windows shell ("cmd.exe"),
291          pass an absolute pathname as PREFIX and use forward slashes.
292
293        - When installing under mingw without MSYS, make sure that the
294          MSYS tools (in case you have some of them, in particular the
295          sh.exe UNIX shell) are *NOT* visible in your PATH.
296
297        - Cygwin will not be able to find the chicken shared libraries
298          until Windows is rebooted.
299
300        - gcc 3.4 shows sometimes warnings of the form
301
302            easyffi.c: In function `f_11735':
303            easyffi.c:18697: warning: `noreturn' function does return
304       
305          when compiling the system or compiled Scheme files. These
306          warnings are bogus and can be ignored.
307
308 6. Emacs support:
309
310        An emacs mode is provided in the file `hen.el'. To use it,
311        copy it somewhere into a location you normally use for emacs
312        extensions. If you want to add a specific location permanently
313        to the list of paths emacs should search for extensions, add
314        the following line to your `.emacs' file:
315
316          (setq load-path
317            (cons
318              "<directory-where-your-emacs-lisp-files-live>"
319              load-path))
320
321        Add
322
323          (require 'hen)
324       
325        To make "hen-mode" available, and enter it by issuing the
326        command M-x hen-mode.
327
328        A copy of Alex Shinn's highly useful tab-completion code is
329        also included in `scheme-complete.el'. Install it like `hen.el'
330        and add this code to your `.emacs':
331
332          (autoload 'scheme-smart-complete "scheme-complete" nil t)
333          (eval-after-load 'scheme
334            '(progn (define-key scheme-mode-map "\e\t" 'scheme-smart-complete)))
335
336        Or:
337
338          (eval-after-load 'scheme
339            '(progn (define-key scheme-mode-map "\t" 'scheme-complete-or-indent)))
340
341        If you use eldoc-mode (included in Emacs), you can also get live
342        scheme documentation with:
343
344        (add-hook 'scheme-mode-hook
345          (lambda ()
346              (setq eldoc-info-function 'scheme-get-current-symbol-info)
347                  (eldoc-mode)))
348
349        Replace "'scheme" in the elisp expressions above with "'hen", if
350        you want to add tab-completion to CHICKEN's own emacs mode.
351
352
353 7. Compatibility notes
354
355        CHICKEN 4 uses a completely reimplemented hygienic macro and
356        module system, which has considerably more felixbility and power,
357        but will require rewriting macros in code that previously was
358        used with CHICKEN 3. Notably, `define-macro' is not available
359        anymore. See the manual on how to translate such macros to
360        low-level hygienic macros or ask on the CHICKEN mailing list.
361
362
363 8. What's next?
364
365        If you find any bugs, or want to report a problem, please consider
366        using the "chicken-bug" tool to create a detailed bug report.
367
368        If you have any more questions or problems (even the slightest
369        problems, or the most stupid questions), then please subscribe
370        to the "chicken-users" mailing list and ask for help. It will
371        be answered.
372
373
374        Have fun!
Note: See TracBrowser for help on using the repository browser.