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:

	  - For Mac OS X, Chicken requires libdl, for loading compiled
	    code dynamically. This library is available on Mac OS X 10.4
	    (Tiger) by default. For older versions you can find it here:

	      http://www.opendarwin.org/projects/dlcompat

	  - On Mac OS X, Chicken and its eggs can be built as universal 
	    binaries which will work on either Intel or PowerPC.
	    To build on Tiger (10.4):

	      make PLATFORM=macosx ARCH=universal

	    On Leopard (10.5), an extra step is required before `make',
	    and you must be sure to use GCC 4.0:

	      export MACOSX_DEPLOYMENT_TARGET=10.4
	      make C_COMPILER=gcc-4.0 PLATFORM=macosx ARCH=universal

	  - On Mac OS X, Chicken can be built in 64-bit mode on Intel
	    Core 2 Duo systems--basically, most recent machines.  The default
	    is 32-bit mode.  To enable 64-bit mode, invoke `make' thusly:

	      make PLATFORM=macosx ARCH=x86-64

   	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.