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

  Version 2, Build 41


 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. Files distributed with CHICKEN:

    README 			the file your are currently reading
    NEWS 			what has changed since the previous release
    LICENSE                     BSD license
    INSTALL                     generic installation instructions for UNIX
    TASKS                       if you want to contribute
    INSTALL-CMake.txt           instructions for building CHICKEN with CMake
    ChangeLog    		new features and bugfixes
    vctk-install.txt            Instructions for using the free command-line tools from Microsoft
    chicken.html
    chicken.pdf
    chicken.texi   		user's manual in several format

    chicken.1
    chicken-setup.1
    chicken-profile.1
    csi.1                       manual pages

    build.scm			contains current build- and version number

    tweaks.scm
    chicken.scm		        
    support.scm
    graph.scm
    easyffi.scm
    easyffi.l.silex
    easyffi.l
    compiler.scm
    optimizer.scm
    batch-driver.scm
    c-platform.scm
    c-backend.scm       	the compiler in source form

    library.scm
    extras.scm 
    eval.scm
    srfi-1.scm
    srfi-4.scm
    srfi-13.scm
    srfi-14.scm
    match.scm
    regex.scm
    pregexp.scm
    pcre.scm
    regex-common.scm
    srfi-18.scm
    scheduler.scm
    lolevel.scm
    utils.scm
    stub.scm
    profiler.scm
    tinyclos.scm
    tcp.scm
    posix.scm
    posixwin.scm		libraries

    silex.scm                   Danny Dube's lexer generator

    runtime.c			the basic runtime system (garbage collector, memory manager, etc.)

    library.c
    extras.c
    eval.c
    srfi-1.c
    srfi-4.c
    srfi-13.c
    srfi-14.c
    match.c
    regex.c
    pregexp.c
    pcre.c
    srfi-18.c
    scheduler.c
    posix.c
    lolevel.c
    utils.c
    profiler.c
    tinyclos.c
    stub.c
    posixwin.c
    tcp.c            		compiled libraries

    ulibrary.c
    uextras.c
    ueval.c
    usrfi-1.c
    usrfi-4.c
    usrfi-13.c
    usrfi-14.c
    uregex.c
    upregexp.c
    upcre.c
    usrfi-18.c
    uposix.c
    ulolevel.c
    utcp.c
    uposixwin.c
    uutils.c			compiled libraries (unsafe version)

    parameters.scm		constant definitions for the library files and the compiler

    banner.scm                  silly banner

    nsample.scm                 nursery benchmarking
    nsample.c                   compiled form of a simple benchmark to measure nursery sizes

    chicken.h      		headerfile included by all modules compiled with CHICKEN

    chicken.c
    support.c
    graph.c
    easyffi.c
    compiler.c
    optimizer.c
    batch-driver.c
    c-platform.c
    c-backend.c                 the compiler (in compiled form)

    csi.scm                     source-file for the Scheme interpreter/REPL

    chicken-setup.scm
    chicken-profile.scm         tool sources

    chicken-more-macros.scm     some useful macros (SRFI-16, etc.)

    chicken.ico                 icon for Windows executables
    chicken.rc                  resource-script for Windows executables

    csc.scm.in                  templates for Shell/Scheme scripts

    chicken.spec.in		RPM spec-file template

    csibatch.bat		trampoline for Windows/DOS shell scripts

    *.exports                   export information files for core libraries

    aclocal.m4
    acconfig.h
    config.guess
    config.h.in
    config.sub
    configure
    configure.in
    install-sh
    ltmain.sh
    Makefile.am
    Makefile.in
    missing
    mkinstalldirs		the usual configuration stuff for UNIX and Linux systems    

    makefile.vc                 Makefile for MS nmake
    win-install.bat             installation script for Windows

    benchmarks/                 contains several benchmarks

    hen.el                      an emacs mode for editing Scheme programs, by Linh Dang


 3. Installation:

	If you already have CHICKEN installed, then it is recommended that you delete it first.
	Sometimes files are renamed, and this ensures that no unused junk remains.
	First unzip the package ("unzip chicken.zip" or "tar xvzf chicken.tar.gz"), then generate 
	the binaries by invoking make:

	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!!! <--- IMPORTANT ***

	
  	  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 many Linux systems (x86, Alpha, ARM, m68k, PPC) and Solaris.
	  Currently this feature has only been tested on x86 Linux.
	  (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.

	  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

	Windows (Visual C++):

	  If you have downloaded the binary package, just put the extracted directory at a convenient
	  place and setup your environment (see below).
	  If you are building from sources, make sure the compiler tools are available on your 
	  command-line. If "nmake" can't be found, you should run the batch file VCVARS32.BAT, which can 
	  be found in the VC/BIN directory of your Visual C++ installation.

	  To actually build the system, enter 

	    nmake -f makefile.vc

	  If you don't have the commercial version of Visual C++, you can download and install
	  Microsofts VCToolkit (command-line compiler and linker) and the Platform Core 
	  SDK (both available for free at Microsofts download area).
	  See the "vctk-install.txt" in this directory for more information.

	  For installation just add the CHICKEN directory to your PATH and set the CHICKEN_HOME
	  environment variable (for example in your AUTOEXEC.BAT), :

	    set PATH=%PATH%;<directory>
	    set CHICKEN_HOME=<directory>

	  Alternatively, run `win-install.bat' after setting CHICKEN_HOME, and it will create the directory
  	  for you and copy all needed files into that directory.

	MinGW:

	  Use the MSYS environment (http://www.mingw.org/msys.shtml)
	  available for MinGW.  This will let the installation be done
	  according to the UNIX instructions below.

	  (The BOOTSTRAP_PATH make option may be specified in a form like
	  C:/chicken-2.3 ... spaces in the path to the existing
	  CHICKEN installation will cause problems)

	  Sergey Khorev reported how to build Chicken under MinGW with support 
		for shared libraries with some hacking involved:

	  1) Install MinGW and MSYS
	  2) Don't use rxvt (default MSYS shortcut), better run MSYS's shell using command
		sh --login -i
	  3) ./configure
          4) edit Makefile to set BOOTSTRAP_PATH if required
	  5) patch libtool with
		sed -e 's/\(deplibs_check_method=\).*/\1"pass_all"/' libtool > libtool.new
		cp libtool.new libtool
  	    (it seems that libtool tries to be too smart, giving stupid results).
	  6) mkdir $MINGWDIR/lib/.libs;
	     cp $MINGWDIR/lib/libws2_32.a $MINGWDIR/lib/.libs/libws2_32.dll.a
	     where MINGWDIR is the where MinGW is installed
	  7) make, make install, enjoy


	    You might want to use C regular expressions package instead of the 
	    default one, written in Scheme. 
	    In this case you should download latest packages from 
	    http://gnuwin32.sf.net 
	    (either pcre-*-bin.zip, pcre-*-dep.zip, pcre-*-lib.zip
		or regex-spencer-*-bin.zip and regex-spencer-*-lib.zip).
	    Unpack downloaded zip files into one directory.
	    Steps 1) and 2) as above.
	    3a)
	    For simplicity create environment variable with its path, e.g.
		export RE_DIR=c:/Devel/pcre
	    Then copy import libraries:
		cd RE_DIR/lib
		mkdir .libs
	    If you use PCRE, issue
		cp libpcre.dll.a .libs
	    else
		cp libregex.dll.a .libs
	    Put libpcre0.dll or regex.dll somewhere to PATH 
				    (e.g. WINDOWS\System32)
	    3b)
		CFLAGS=-I$RE_DIR/include CPPFLAGS=-I$RE_DIR/include LDFLAGS=-L$RE_DIR/lib ./configure
	    Other steps like in normal MinGW build

        There is experimental support for building CHICKEN with the CMake build tool
	(http://www.cmake.org), courtesy by Brandon van Every. Currently it only builds CHICKEN
	from the development repository available via darcs or subversion. See INSTALL-CMake.txt
	for more information. Note that CMake support is still experimental and not completely
	tested.


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

	CHICKEN was developed first with Cygwin, later with Visual C++ 5.0 (both under Windows98), 
	then on Linux.If you port CHICKEN to another platform I would be delighted to hear something 
	about it.

	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.

	
 5. Platform issues:

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

	  The configuration script for Chicken assumes the headers and libaries for libdl are installed
	  in /sw. If they are installed at a different location on your system, edit configure.in and
	  replace the occurrences of /sw/include and /sw/lib with the proper pathnames.

	- 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. What's next?

	More information on the use and implementation of CHICKEN can be found in the manual
 	(%{prefix}/share/chicken/doc/chicken.html, or type "info chicken"). 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!
