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

  Version 2, Build 0


 1. Introduction:

    CHICKEN is a simple Scheme-to-C compiler supporting the language features as defined 
    in the 'Revised^5 Report on Scheme'. Since the design and implementation of the 
    compilation process is relatively simple, it should be easy to port and extend.
    Separate compilation poses no problem and full tail-recursion and first-class
    continuations are suported.

    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
    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
    format.txt                  specification of CL-style format

    chicken.1
    chicken-config.1
    chicken-setup.1
    chicken-format-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-support.scm
    regex.scm
    pregexp.scm
    pcre.scm
    srfi-18.scm
    scheduler.scm
    format.scm
    lolevel.scm
    utils.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-support.c
    regex.c
    pregexp.c
    pcre.c
    srfi-18.c
    scheduler.c
    format.c
    posix.c
    lolevel.c
    utils.c
    profiler.c
    tinyclos.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
    umatch-support.c
    uregex.c
    upregexp.c
    upcre.c
    usrfi-18.c
    uformat.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-format-profile.scm  tool sources

    chicken-more-macros.scm     some useful macros (SRFI-16, etc.)
    match.scm			pattern matching macros
    default-entry-points.scm    boilerplate entry points for embedding compiled code in other applications
    entry-points.scm            definitions of `define-entry-point' and `define-embedded' macros

    makefile.vc                 makefile for VC++ 5.0
    makefile.dj                 makefile for DJGPP
	
    chicken.ico                 icon for Windows executables
    chicken.rc                  resource-script for Windows executables

    chicken-config.in
    csc.scm.in                  templates for Shell/Scheme scripts

    chicken.spec.in		RPM spec-file template

    csibatch.bat		trampoline for Windows/DOS shell scripts

    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    

    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, UNIX, Mac OS X 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/ and add the `--with-libffi' switch to configure:

            ./configure --with-libffi

          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.

	  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.

	Windows (Visual C++):

	  (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)

  	    nmake /f makefile.vc

	  (If you prefer to build the libraries with the dynamically linked C runtime support code,
	   add "DYNAMIC_C_RUNTIME=yes" to the above invocation of "nmake")

	  If you don't have nmake (for example, if you are using the VCToolkit (Microsofts command-line
	  compiler and linker) and the Platform Core SDK (both available for free at Microsofts download
	  area), you can run the batch file "vcbuild.bat", which performs all necessary build steps.
	  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-1.66 ... 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:

	  "Meanwhile I built Chicken with shared libs on MinGW. There is some
	  hacking though. For those interested:

	  1) ./configure
          2) edit Makefile to set BOOTSTRAP_PATH
	  3) edit libtool, change 'deplibs_check_method' value to "pass_all" (it
	     seems that libtool tries to be too smart, giving stupid results).
	  4) mkdir $MINGWDIR/lib/.libs;
	     cp $MINGWDIR/lib/libws2_32.a $MINGWDIR/lib/.libs
	     where MINGWDIR is the where MinGW is installed
	  5) make, make install, enjoy"

  4. Usage:

	Normally this should work without problems. 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.
	Some Scheme files are compiled with the freshly built compiler which will emit a couple
	of warnings, which can be safely ignored.

	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 installation process for UNIX, Linux, Mac OS X and Cygwin creates a shell script named
	"chicken-config" that can be used to emit the proper compiler flags for the GNU
	C compiler. You can use it like this:

	  chicken foo.scm -output-file foo.c
	  gcc foo.c `chicken-config -cflags -libs` -o foo

	Enter "chicken-config -help" for more information.

	An even simpler way of invoking the compiler is the `csc' program. For the previous
	example one could enter:

	  csc foo.scm

        Enter `csc -help' for a list of available options. `csc' is not available under DOS.

	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. You 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
 	(manual.html) and in the list of frequently asked questions (FAQ.html). 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!
