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

  Version 0, Build 0.990


 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. The compiler-sources are available (and quite compact). Feel free to incorporate
       more optimizations and language features.


 2. Files distributed with CHICKEN:

    README 			the file your are currently reading
    README.txt                  the same file in MSDOS format
    NEWS  			new features and bugfixes
    INSTALL                     generic installation instructions for UNIX
    FAQ.html                    frequently asked questions
    manual.html 		user's manual in HTML
    format.txt                  specification of CL-style format
    chicken.gif                 the CHICKEN logo

    chicken.1
    csi.1                       manual pages

    build.scm
    tweaks.scm
    chicken.scm		        
    support.scm
    compiler.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
    syntax-case.scm
    modules.scm
    srfi-18.scm
    format.scm
    lolevel.scm
    unistd.scm			libraries

    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
    regex.c
    syntax-case.c
    modules.c
    srfi-18.c
    format.c
    unistd.c
    lolevel.c
    match.c		        compiled libraries

    ulibrary.c
    uextras.c
    ueval.c
    usrfi-1.c
    usrfi-4.c
    usrfi-13.c
    usrfi-14.c
    uregex.c
    usyntax-case.c
    umodules.c
    usrfi-18.c
    uformat.c
    uunistd.c
    ulolevel.c
    umatch.c		        compiled libraries (unsafe version)

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

    nsample.c                   compiled form of a simple benchmark to measure nursery sizes
    runsample.c                 compiled form of a program that runs "nsample"

    chicken.h      		headerfile included by all modules compiled with CHICKEN

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

    csi.scm                     the Scheme interpreter

    records.scm                 record types (SRFI-9)
    highlevel-macros.scm
    std-highlevel-macros.scm
    std-0-highlevel-macros.scm	macro definitions using syntax-case
    moremacros.scm              some useful macros (SRFI-16, etc.)
    describe.scm                a useful `describe' procedure
    process.scm                 invoking a subprocess with connection to it's standard I/O
    chicken.init                SLIB initialization file for the interpreter

    examples/                   directory with example code

    makefile.vc                 makefile for VC++ 5.0
    makefile.dj                 makefile for DJGPP
    makefile.mingw32            makefile for Mingw32 environment
    makefile.gcc                a very basic makefile for the GNU C compiler (in case "./configure; make" fails)
    makefile.guilibs            makefile for generating the CHICKEN runtime libraries suitable for Win32 GUI applications
	
    Makefile.d                  templace makefile for distribution of compiled programs
    Makefile.d.vc               Windows/VC++ version of `Makefile.d'

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

    chicken-config.in
    csc.in
    extend-chicken.in
    extend-csi.in               templates for various Shell scripts

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


 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.

	UNIX or Linux or Windows (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 the example programs enter

          make examples

	  (see examples/README for more information)


	Normally this should work without a glitch. 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'.

        When the build process should fail, then you can try to issue

 	  make -f makefile.gcc

	This builds the compiler and runtime system without any fancy compiler options or 
	system dependent stuff and should work on any system with the GNU C compiler.

	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 only available on systems that
	provide the GNU regex library.


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

        - Under the Cygwin environment CHICKEN can be used to generate Win32 GUI applications.
	  This needs special versions of the runtime libraries, which can be created by issuing

	  % make -f makefile.guilibs

	  on the command line. This builds four libraries named `libwin32-gui-chicken.a',
	  `libwin32-embedded-gui-chicken.a' plus the unsafe versions. Link these instead of the normal
	  libraries. If you use the bash shell, then the shell script `chicken-config' provides 
	  options to emit the appropriate compiler switches.
	  The GUI libraries are not installed with the normal `make install'. You have to copy the 
	  files by hand into the proper installation directory.

	- For the Mingw32 environment, you should invoke make with `makefile.mingw32`:

	  % make -f makefile.mingw32

	  This makefile handles some problems specific to Mingw32 and builds the normal and GUI libraries
	  (Note that this makefile doesn't perform nursery sampling and has no install target).


 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!
