Fork of the Chicken Scheme core, backporting bugfixes and small features to release versions. Now also included in the primary repository. See README.stability for details.
Fetching latest commit…
Cannot retrieve the latest commit at this time
README file for the CHICKEN Scheme system ========================================= (c) 2008-2011, The Chicken Team (c) 2000-2007, Felix L. Winkelmann version 4.7.0 1. Introduction CHICKEN is a Scheme-to-C compiler supporting the language features as defined in the 'Revised^5 Report on Scheme'. Separate compilation is supported and full tail-recursion and efficient first-class continuations are available. Some things that CHICKEN has to offer: 1. CHICKEN generates quite portable C code and compiled files generated by it (including itself) should work without any changes on DOS, Windows, most UNIX-like platforms, and with minor changes on other systems. 2. The whole package is distributed under a BSD style license and as such is free to use and modify as long as you agree to its terms. 3. Linkage to C modules and C library functions is straightforward. Compiled programs can easily be embedded into existing C code. 4. Loads of extra libraries. Note: Should you have any trouble in setting up and using CHICKEN, please ask questions on the Chicken mailing list. You can subscribe to the list from the Chicken homepage, http://www.call-with-current-continuation.org) 2. Installation Building CHICKEN requires GNU Make. Other "make" derivates are not supported. If you are using a Windows system and do not have GNU Make, download http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip. It contains a precompiled set of UNIX utilities, which among other useful tools contains "make". Configuration and customization of the build process is done by either setting makefile variables on the "make" command line or by editing the platform-specific makefile. To build CHICKEN, first extract the archive ("tar xzf chicken-<version>.tar.gz" on UNIX or use your favorite extraction program on Windows), then change to the chicken-<version> directory and invoke "make" like this: make PLATFORM=<platform> PREFIX=<destination> where "PLATFORM" specifies on what kind of system CHICKEN shall be built and "PREFIX" specifies where the executables and libraries shall be installed. Out-of-directory builds are currently not supported, so you must be in the toplevel source directory to invoke "make". Enter "make" without any options to see a list of supported platforms. Note that parallel builds (using the "-j" make(1) option) are *not* supported. If you build CHICKEN directly from the development sources out of the git repository, you will need a "chicken" executable to generate the compiled C files from the Scheme library sources. If you have a recent version of CHICKEN installed, then pass "CHICKEN=<chicken-executable>" to the "make" invocation to override this setting. "CHICKEN" defaults to "$PREFIX/bin/chicken". If you do not have a "chicken" binary installed, you will have to obtain a "bootstrapping" compiler, which can either be built from a release tarball (see below for instructions) or by using a precompiled and statically linked compiler binary from here: http://code.call-cc.org/bootstrap/ If CHICKEN is built successfully, you can install it on your system by entering make PLATFORM=<platform> PREFIX=<destination> install "PREFIX" defaults to "/usr/local". Note that the PREFIX is compiled into several CHICKEN tools and must be the same while building the system and during installation. To install CHICKEN for a particular PREFIX on a different location, set the "DESTDIR" variable in addition to "PREFIX": It designates the directory where the files are installed into. You can further enable various optional features by adding one or more of the following variables to the "make" invocation: DEBUGBUILD=1 Disable optimizations in compiled C code and enable debug information. STATICBUILD=1 Build only static versions of the runtime library, compiler and interpreter. `chicken-install', `chicken-uninstall' and `chicken-status' will not be generated, as it is mostly useless unless compiled code can be loaded. SYMBOLGC=1 Always enable garbage collection for unused symbols in the symbol table by default. This will result in slightly slower garbage collection, but minimizes the amount of garbage retained at runtime (which might be important for long running server applications). If you don't specify this option you can still enable symbol GC at runtime by passing the `-:w' runtime option when running the program. EXTRA_CHICKEN_OPTIONS=... Additional options that should be passed to `chicken' when building the system. C_COMPILER_OPTIMIZATION_OPTIONS=... Override built-in C compiler optimization options. Available for debug or release build. PROGRAM_PREFIX= A prefix to prepend to the names of all generated executables. This allows having multiple CHICKEN versions in your PATH (but note that they have to be installed at different locations). PROGRAM_SUFFIX= A suffix to be appended to the names of all generated executables. HOSTSYSTEM= A "<machine>-<platform>" name prefix to use for the C compiler to to use to compile the runtime system and executables. Set this variable if you want to compile CHICKEN for a different architecture than the one on which you are building it. TARGETSYSTEM= Similar to "HOSTSYSTEM", but specifies the name prefix to use for compiling code with the "csc" compiler driver. This is required for creating a "cross chicken", a specially built CHICKEN that invokes a cross C compiler to build the final binaries. You will need a cross compiled runtime system by building a version of CHICKEN with the "HOST" option mentioned above. More information about this process and the variables that you should set are provided in the CHICKEN wiki at <http://wiki.call-cc.org/cross-compilation>. SRCDIR= Specifies that CHICKEN should be built outside of its source tree. The SRCDIR variable indicates the location of the CHICKEN source tree. The executables and object files will be generated in the current directory. VARDIR= If set, this directory overrides the location where extensions along with their metadata are stored. Normally this will be equivalent to "<PREFIX>/lib/chicken/<BINARYVERSION>". When VARDIR is specified, extensions will be stored in "<VARDIR>/chicken/<BINARYVERSION>", conforming to the FHS. CONFIG= If you build CHICKEN often, passing all those make variables can get annoying. An alternative is to create a configuration file defining the required variables and passing "CONFIG=<configfile>" to make(1). Even simpler is editing the included "config.make" and just invoke make(1) without any extra parameters. C_COMPILER= You can select an alternative compiler by setting this variable. The default compiler is "gcc". CHICKEN can be built with the LLVM version of gcc and with "clang", the LLVM-based C compiler, just set C_COMPILER to "llvm-gcc" or "clang". To remove CHICKEN from your file-system, enter (probably as root): make PLATFORM=<platform> PREFIX=<destination> uninstall (If you gave DESTDIR during installation, you have to pass the same setting to "make" when uninstalling) In case you invoke "make" with different configuration parameters, it is advisable to run make PLATFORM=<platform> confclean to remove old configuration files. These files will be installed under the prefix given during build and installation: <PREFIX> |-- bin | |-- chicken | |-- chicken-bug | |-- chicken-install | |-- chicken-profile | |-- chicken-status | |-- chicken-uninstall | |-- libchicken.dll (Windows) | |-- csc | `-- csi |-- include | `-- chicken | |-- chicken-config.h | `-- chicken.h |-- lib | |-- chicken | | `-- 6 | | |-- chicken.import.so | | |-- csi.import.so | | |-- data-structures.import.so | | |-- extras.import.so | | |-- files.import.so | | |-- foreign.import.so | | |-- irregex.import.so | | |-- lolevel.import.so | | |-- modules.db | | |-- ports.import.so | | |-- posix.import.so | | |-- scheme.import.so | | |-- setup-api.import.so | | |-- setup-api.so | | |-- setup-download.import.so | | |-- setup-download.so | | |-- srfi-1.import.so | | |-- srfi-13.import.so | | |-- srfi-14.import.so | | |-- srfi-18.import.so | | |-- srfi-4.import.so | | |-- srfi-69.import.so | | |-- tcp.import.so | | |-- types.db | | `-- utils.import.so | |-- libchicken.a | |-- libchicken.dll.a (Windows) | |-- libchicken.so -> libchicken.so.6 (Unix) | `-- libchicken.so.6 (Unix) `-- share |-- chicken | |-- doc | | |-- CHICKEN.icns (Macintosh) | | |-- LICENSE | | |-- README | | |-- mac.r (Macintosh) | | |-- manual-html | | |-- chicken.png | | `-- *.html | `-- setup.defaults `-- man `-- man1 |-- chicken-bug.1 |-- chicken-install.1 |-- chicken-profile.1 |-- chicken-status.1 |-- chicken-uninstall.1 |-- chicken.1 |-- csc.1 `-- csi.1 3. Usage Documentation can be found in the directory PREFIX/share/chicken/doc in HTML format. The manual is maintained in a wiki at http://wiki.call-cc.org. Go there to read the most up to date documentation. 4. Extensions A large number of extension libraries for CHICKEN are available at http://wiki.call-cc.org/eggs. You can automatically download, compile and install extensions with the "chicken-install" program. See the CHICKEN User's Manual for more information. A selection of 3rd party libraries, together with source and binary packages for tools helpful for development with CHICKEN are also available at: <http://www.call-with-current-continuation.org/tarballs/>. 5. Platform issues FreeBSD/NetBSD/OpenBSD: - *BSD system users *must* use GNU make ("gmake") - the makefiles can not be processed by BSD make. - On NetBSD it might be possible that compilation fails with a "virtual memory exhausted error". Try the following: % unlimit datasize - Using external libraries on NetBSD may also be easier, if you add the following definitions to `Makefile.bsd': C_COMPILER_OPTIONS += -I/usr/pkg/lib LINKER_OPTIONS += -L/usr/pkg/lib -Wl,-R/usr/pkg/lib Note that this may cause build-problems, if you already have an existing CHICKEN installation in the /usr/pkg prefix. Linux: - Some old Linux distributions ship with a buggy version of the GNU C compiler (2.96). If the system is configured for kernel recompilation, then an alternative GCC version is available under the name `kgcc' (GCC 2.96 can not recompile the kernel). CHICKEN's configuration script should normally be able to handle this problem, but you have to remember to compile your translated Scheme files with `kgcc' instead of `gcc'. Solaris: - By default, CHICKEN is build with the GNU C compiler (`gcc'). To use the SunPro C compiler (`cc') instead, pass C_COMPILER=cc to the "make" invocation. - Older versions of Solaris have a bug in ld.so that causes trouble with dynamic loading. Patching Solaris fixes the problem. Solaris 7 needs patch 106950-18. Solaris 8 has an equivalent patch, 109147-16. You can find out if you have these patches installed by running: % showrev -p | grep 106950 # solaris 7 % showrev -p | grep 109147 # solaris 8 Mac OS X: - On 10.7, Chicken will hang and use 100% CPU when you try to run or install it, due to an incompatibility with the LLVM version of gcc (which became the default in 10.7). To fix this, compile with plain gcc: make PLATFORM=macosx C_COMPILER=gcc-4.2 Unfortunately, this will still hang with XCode 4.2 or later. However, there is an experimental fix for this problem; please ask for details on the chicken-users mailing list. - On 10.6 and 10.7, Chicken may incorrectly select a 32-bit build environment when it should be building 64-bit, resulting in a build error. This occurs when you have a 32-bit kernel and a 64-bit gcc (that is, on Core 2 Duo systems running 10.6 Desktop). If this bites you, you'll get the following error or similar: apply-hack.x86.S:35:suffix or operands invalid for `call' As a workaround, manually force the build into 64-bit mode: make PLATFORM=macosx ARCH=x86-64 - Chicken will normally select a 32-bit or 64-bit build automatically when you use the normal build step: make PLATFORM=macosx Specifically, the defaults are: 10.4: 32-bit 10.5: 32-bit 10.6: 64-bit (32-bit on original Core Duo, circa early 2006) 10.7: 64-bit On 10.5, you can optionally build in 64-bit mode on machines released in late 2006 or later (i.e. with a Core 2 Duo or Xeon CPU), by specifying ARCH=x86-64: make PLATFORM=macosx ARCH=x86-64 - Universal binaries: On 10.4 and 10.5 only, Chicken and its eggs can be built as universal binaries which will work on either Intel or PowerPC. Most users will not want to do this. For 10.4 universal build: make PLATFORM=macosx ARCH=universal For 10.5 universal build: export MACOSX_DEPLOYMENT_TARGET=10.4 make C_COMPILER=gcc-4.0 PLATFORM=macosx ARCH=universal For 10.6 and later, universal builds are not supported. - On 10.3 and earlier, you must first install `dlcompat' which can be found at http://distfiles.macports.org/dlcompat/. Windows: - On Windows, mingw32, <http://mingw.sourceforge.net/> and Cygwin are supported (Microsoft Visual Studio is *NOT*). Makefiles for mingw under MSYS and the Windows shell are provided (`Makefile.mingw-msys' and `Makefile.mingw'). Please also read the notes below. - When installing under the mingw-msys platform, PREFIX must be an absolute path name (i.e. it must include the drive letter) and must use forward slashes (no backward slashes). - When installing under mingw, with a windows shell ("cmd.exe"), pass an absolute pathname (including the drive letter) as PREFIX and use forward slashes. - When installing under mingw without MSYS, make sure that the MSYS tools (in case you have some of them, in particular the sh.exe UNIX shell) are *NOT* visible in your PATH. - Cygwin will not be able to find the chicken shared libraries until Windows is rebooted. - gcc 3.4 shows sometimes warnings of the form easyffi.c: In function `f_11735': easyffi.c:18697: warning: `noreturn' function does return when compiling the system or compiled Scheme files. These warnings are bogus and can be ignored. 6. Bootstrapping To build a bootstrapping compiler yourself, obtain a recent release tarball, unpack it, change into the extracted directory and enter make PLATFORM=<platform> CHICKEN=<path-to-existing-chicken> \ boot-chicken This will produce a statically linked binary with the name "chicken-boot[.exe]" that can be given as the value of the "CHICKEN" argument when invoking make(1). Note that the path to an existing `chicken' binary must be given to use it for compiling the Scheme code of the runtime-system and compiler. 7. Emacs support See http://wiki.call-cc.org/emacs for tips and links to emacs extensions for Scheme and CHICKEN programming. 8. Compatibility notes In CHICKEN 4, the macro system has been reimplemented completely and provides module system, which has considerably more flexibility and power, but will require the re-implementation of macros in code that previously was used with CHICKEN 3. Notably, `define-macro' is not available anymore. See the manual on how to translate such macros to low-level hygienic macros or ask on the CHICKEN mailing list. 9. What's next? If you find any bugs, or want to report a problem, please consider using the "chicken-bug" tool to create a detailed bug report. If you have any more questions or problems (even the slightest problems, or the most stupid questions), then please subscribe to the "chicken-users" (http://lists.nongnu.org/mailman/listinfo/chicken-users) mailing list and ask for help. It will be answered.