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

  Version 1, Build 9


 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:

    doc/README 			the file your are currently reading
    doc/README.txt              the same file in MSDOS format
    doc/README.CVS              read this if you are building from CVS sources
    doc/ChangeLog  		new features and bugfixes
    doc/LICENSE                 BSD license
    INSTALL                     generic installation instructions for UNIX
    doc/FAQ.html                frequently asked questions
    doc/manual.tex   		user's manual in TeX format
    doc/manual.html.gen         timestamp for HTML manual
    doc/manual                  the user's manual in HTML format
    doc/format.txt              specification of CL-style format
    doc/chicken.jpg
    doc/chicken.eps
    doc/chicken.png             the CHICKEN logo
    doc/tex2page                Dorai Sitaram's TeX2page TeX->HTML converter
    doc/COPYING.tex2page        licensing policy for tex2page

    chicken.1
    chicken-config.1
    csi.1                       manual pages

    build.scm			contains current build- and version number

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

    psyntax.pp
    psyntax-chicken.pp
    library.scm
    extras.scm 
    eval.scm
    srfi-1.scm
    srfi-4.scm
    srfi-13.scm
    srfi-14.scm
    match-support.scm
    regex.scm
    psyntax.scm
    syntax-case.scm
    srfi-18.scm
    scheduler.scm
    srfi-25.scm
    srfi-37.scm
    format.scm
    lolevel.scm
    script-utils.scm
    profiler.scm
    tinyclos.scm
    chicken-setup.scm
    tcp.scm
    posix.scm			libraries

    psyntax-bootstrap.scm       bootstrapping code for syntax-case macro system

    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
    syntax-case.c
    srfi-18.c
    scheduler.c
    srfi-25.c
    srfi-37.c
    format.c
    posix.c
    lolevel.c
    script-utils.c
    profiler.c
    tinyclos.c
    tcp.c
    chicken-setup.c		compiled libraries

    ulibrary.c
    uextras.c
    ueval.c
    usrfi-1.c
    usrfi-4.c
    usrfi-13.c
    usrfi-14.c
    usrfi-25.c
    umatch-support.c
    uregex.c
    usrfi-18.c
    usrfi-37.c
    uformat.c
    uposix.c
    ulolevel.c
    utcp.c
    uscript-utils.c		compiled libraries (unsafe version)

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

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

    highlevel-macros.scm	non-standard macro definitions using syntax-case
    moremacros.scm              some useful macros (SRFI-16, etc.)
    match.scm			pattern matching macros
    srfi-13-syntax.scm          macros for SRFI-13

    examples/                   directory with example code

    testsuites/			directory with some testing code

    makefile.vc                 makefile for VC++ 5.0
    makefile.dj                 makefile for DJGPP
    makefile.guilibs            makefile for generating the CHICKEN runtime libraries suitable for Win32 GUI applications
	
    chicken.ico                 icon for Windows executables
    chicken.rc                  resource-script for Windows executables

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

    formatprofile               Scheme script for profile output

    scheme-chicken.c
    scheme-ieee-1178-1990.c
    scheme-r4rs.c
    scheme-r5rs.c
    scheme-srfi-0.c
    scheme-srfi-7.c             SRFI-22 interpreter trampolines

    chicken.spec.in		RPM spec-file template

    csc.bat			compiler driver for Windows
    csibatch.bat		trampoline for Windows/DOS shell scripts
    formatprofile.bat           profile-formatter for Windows/DOS

    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    

    mingw/			Mingw32-specific installation scripts

    testsuites/			some testing code


 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:

	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

	  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>

        DOS (DJGPP):

	    make -f makefile.dj

	  Installation works as in Windows. If unpacking the files in an environment with an 8.3
	  character filename limit, djtar will report name-clashes. These can be safely ignored.

	Mingw32:

	  See mingw/INSTALL for instructions on how to build and install Chicken under this
	  environment.

	UNIX or 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
  	    make
	    make install

  	  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 build and run some simple tests (warning: takes long), enter

	    make test

	  To build the example programs enter

            make examples

	  (see examples/README for more information)

          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 want to use the extension mechanism (that is `require' and `require-for-syntax'),
	  you have to create a "registry" first. Enter

	    csi -setup

	  to create it. You might have to be root for this to succeed, if you don't have
	  write-access to the registry directory. See the manual for alternative locations
	  at which you can place your registry-directory.


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

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

	It is recommended that you set the environment variable "CHICKEN_HOME" to the pathname of the 
	directory which contains the executables and optional include files. This ensures that
	the hygienic macro-package and include-files are always accessible.

	The installation process for UNIX/Linux/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 Scheme script `csc'. 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.


 4. Platform dependencies:

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

	- Building shared libraries on Cygwin systems needs an alpha-release of libtool (1.4e, find it in
	  the `libtool-devel' package). You will have to create the proper libtool version by hand, like
	  this:

	    libtoolize --force --copy --automake && aclocal && autoheader && automake --foreign -a --copy && autoconf

	  Then run configure + make as usual.

	- 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


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