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

  Version 2.5


 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.

 2. Installation:

	First unzip the package ("unzip chicken-<version>.zip", "tar xvzf chicken-<version>.tar.gz" 
        on UNIX or useyour 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/libffi-3.tgz).
	  If you experience any problems with your libfi 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 prefer to use Dorai Sitaram's PREGEXP regular expression package instead
	  of the one in the C runtime library, add the option `--with-pregexp' to the
	  invocation of "./configure". Note that PREGEXP is much slower.

	  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://galinha.ucpel.tche.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.

	
 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 ou 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!
