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

  Version 1, Build 63


 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
    README.CVS                  read this if you are building from CVS sources
    ChangeLog    		new features and bugfixes
    LICENSE                     BSD license
    INSTALL                     generic installation instructions for UNIX
    FAQ.html                    frequently asked questions
    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

    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
    pregexp.scm
    pcre.scm
    psyntax.scm
    syntax-case.scm
    srfi-18.scm
    scheduler.scm
    srfi-25.scm
    srfi-37.scm
    format.scm
    lolevel.scm
    utils.scm
    profiler.scm
    tinyclos.scm
    tcp.scm
    posix.scm			libraries

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

    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
    syntax-case.c
    srfi-18.c
    scheduler.c
    srfi-25.c
    srfi-37.c
    format.c
    posix.c
    lolevel.c
    utils.c
    profiler.c
    tinyclos.c
    tcp.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
    upregexp.c
    upcre.c
    usrfi-18.c
    usrfi-37.c
    uformat.c
    uposix.c
    ulolevel.c
    utcp.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

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

    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.scm.in                  templates for Shell/Scheme scripts

    formatprofile               Scheme script for profile output

    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

    hen.el                      an emacs mode for exiting 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:

	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.

	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
  	    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 and run some benchmarks, enter

 	    make bench

	  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 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 (but a little bit
	  more powerful). 

	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.


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


 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!
