
  README file for the CHICKEN compiler
  (c)2000-2007 Felix L. Winkelmann

  Version 2.6


 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:

	First unzip the package ("unzip chicken-<version>.zip", "tar
        xvzf chicken-<version>.tar.gz" on UNIX or use your favorite
        extraction program on Windows), then configure the system and
        generate the binaries by invoking the "make" program.

	CHICKEN can be built either using the "CMake"
	<http://www.cmake.org> build system or via the traditional
	UNIX "configure/make/make install". On Windows it is generally
	recommended to use CMake. CMake offers more features than the
	autoconf build and is easier to maintain. See
	"INSTALL-CMake.txt" for detailed explanations about
	configuring, building and installing CHICKEN.

	If you prefer to use the autoconf generated build scripts,
	read on.

	Linux, Mac OS X, UNIX and Cygwin:

          See INSTALL for generic instructions on how to pass
	  different options to the configuration process. The default
	  installation directories are /usr/local/bin, /usr/local/lib,
	  /usr/local/include and /usr/local/share. Invoke
	    
	    ./configure --prefix=<PATHNAME> 
	  
	  to change the installation directory prefix.

	    ./configure
  	    gmake
	    gmake install


  	  IMPORTANT ---> GNU make is required for building the
  	  system!!!

	
  	  This compiles the runtime-library, the compiler and the
          interpreter.  To force creation of statically linked
          libraries and executables, Invoke

            ./configure --disable-shared

	  Entering "make install-strip" instead of "make install"
	  strips the executables from symbol- information which makes
	  them much smaller.

	  To make `apply' work, C function calls have to be
	  constructed at run-time, which can not be portably
	  implemented, unless using a big `switch' statement for every
	  possible number of arguments. If the libffi library is
	  available for this platform and if it is installed, then
	  CHICKEN can take advantage of this to construct function
	  calls for an (theoretical) unlimited number of arguments
	  (currently there is an arbitrary limit of 1000 arguments
	  maximum). To build CHICKEN with support for libffi, download
	  and install libffi from http://sources.redhat.com/libffi/
	  before running "./configure".  libffi is supposed to work on
	  Mac OS X, many Linux systems (x86, Alpha, ARM, m68k, PPC)
	  and Solaris.

	  (Note: a more recent development snapshot of libffi is
	  available at
	  http://www.call-with-current-continuation.org/tarballs/libffi-3.tgz).
	  If you experience any problems with your libffi installation,
	  you can disable support for it by passing "--without-libffi"
	  to configure.

	  To build and run some benchmarks, enter

 	    gmake bench

          It should be possible to build the system with Intel's C
          compiler (icc). Enter
	  
	    ./configure --with-icc --disable-shared

	  to compile all C files with icc. Note that shared libraries
	  are not yet supported for this configuration.

	  If you always want to enable garbage collection for unused
          symbols in the symbols table by default, pass the
          `-enable-symbol-gc' option to `configure'. 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 on
          a per-program basis by passing the `-:w' runtime option when
          running the program.

	  If you want maximum performance, consider passing
	  "--disable-apply-hook" to "configure", which will disable
	  support for breakpoints, but speed up procedure invocation
	  in safe code. Smaller binaries can be obtained by also
	  giving "--disable-procedure-tables", but that means
	  serialization (available separately) of procedures will not
	  be available.

	  A note for Mac OS X users: if you install the chicken
          runtime libraries (libchicken.*) into a non-standard
          directory, the dynamic linker might not be able to find them
          when executing chicken or programs generated by it. In that
          case you might want to set the environment variable
          DYLD_LIBRARY_PATH to the location where the libraries are
          installed.

	  To remove CHICKEN from your file-system, enter (probably as
	  root):

	    make uninstall

 3. Usage:

	Documentation can be found in the directory
	<prefix>/share/chicken/doc, where <prefix> is the prefix
	specified in the `--prefix' option to `configure', which
	defaults to `/usr/local'. The HTML documentation (in
	"<prefix>/share/chicken/doc/html") is automatically generated
	from the Wiki pages at <http://chicken.wiki.br/>. Go there to
	read the most up to date documentation.

	An emacs mode is provided in the file `hen.el'. To use it,
	copy it somewhere into a location you normally use for emacs
	extensions. If you want to add a specific location permanently
	to the list of paths emacs should search for extensions, add
	the following line to your `.emacs' file:

	  (setq load-path (cons
	  "<directory-where-your-emacs-lisp-files-live>" load-path))

	Add 

 	  (require 'hen)
	
	To make "hen-mode" available, and enter it by issuing the
	command M-x hen-mode.


 4. Extension:

        A large number of extension libraries for CHICKEN are
	available at
	<http://www.call-with-current-continuation.org/eggs/>. You can
	automatically download, compile and install extensions with
	the "chicken-setup" program. See the CHICKEN User's Manual for
	more information.

	Windows users: Note that you must have "tar" and "gunzip"
	programs installed and available through the "PATH"
	environment variable to extract extensions. If you don't
	download and extract the extensions ("eggs") manually using a
	browser and the decompression program of your choice and run
	"chicken-setup" in the directory where you extracted the
	extension archive.

	Windows binaries for common UNIX utilities (most notably "tar"
	and "gunzip") are available here:
	<http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip>.

	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:

	- 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'.

	- There seems to be a problem with the GNU linker on HP/PA
	  systems. In this case it is recommended to use the HP
	  linker. If not available, try to add `-ffunction-sections'
	  to the gcc compiler flags.

        - 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

        - On NetBSD it might be possible that compilation fails with a
	  "virtual memory exhausted error".  Try the following:

          % unlimit datasize

     	- 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 version you can find it here:

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

	- 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.


 5. What's next?

	If you have any more questions or problems (even the slightest
        problems, or the most stupid questions), then please contact
        me at:

	<felix@call-with-current-continuation.org>.


	Have fun!
