source: project/chicken/trunk/README @ 11925

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

  version 3.3.14


 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.

        Note: Should you have any trouble in setting up and using
        CHICKEN, please ask questions on the Chicken mailing list. You
        can subscribe to the list from the Chicken homepage,
        http://www.call-with-current-continuation.org)


 2. Installation:

        First unzip the package ("unzip chicken-<version>.zip" or "tar
        xzf chicken-<version>.tar.gz" on UNIX or use your favorite
        extraction program on Windows).

        Building CHICKEN requires GNU Make. Other "make" derivates are
        not supported. If you are using a Windows system and do not
        have GNU Make, see below for a link to a precompiled set of
        UNIX utilities, which among other useful tools contains "make".

        Configuration and customization of the build process is done by 
        either setting makefile variables on the "make" command line or 
        by editing the platform-specific makefile.

        Invoke "make" like this:

          make PLATFORM=<platform> PREFIX=<destination>

        where "PLATFORM" specifies on what kind of system CHICKEN
        shall be built and "PREFIX" specifies where the executables
        and libraries shall be installed. Out-of-directory builds are
        currently not supported, so you must be in the toplevel source
        directory to invoke "make".

        Enter "make" without any options to see a list of supported 
        platforms.

        If you build CHICKEN directly from the development sources out
        of the subversion repository, you will need a "chicken"
        executable to generate the compiled C files from the Scheme
        library sources. If you have a recent version of CHICKEN
        installed, then pass "CHICKEN=<chicken-executable>" to the
        "make" invocation to override this setting. "CHICKEN" defaults
        to "$PREFIX/bin/chicken".

        If you do not have a "chicken" binary installed, enter

          make PLATFORM=<platform> PREFIX=<destination> bootstrap

        which will unpack a tarball containing precompiled C sources
        that are recent enough to generate the current version. After
        building a statically linked compiler executable (named
        "chicken-boot") all *.scm files are marked for rebuilt. By
        passing "CHICKEN=./chicken-boot" to "make", you can force
        using this bootstrapped compiler to build the system.

        The build may show errors when creating the info(1)
        documentation, if you do not have GNU texinfo installed.
        This is not fatal - the build should proceed.

        If CHICKEN is build successfully, you can install it on your
        system by entering

          make PLATFORM=<platform> PREFIX=<destination> install

        "PREFIX" defaults to "/usr/local". Note that the PREFIX is
        compiled into several CHICKEN tools and must be the same
        while building the system and during installation.

        To install CHICKEN for a particular PREFIX on a different
        location, set the "DESTDIR" variable in addition to "PREFIX":
        It designates the directory where the files are installed
        into.

        You can further enable various optional features by adding
        one or more of the following variables to the "make"
        invocation:

        DEBUGBUILD=1
          Disable optimizations in compiled C code and enable
          debug information.

        STATICBUILD=1
          Build only static versions of the runtime library, compiler
          and interpreter. `chicken-setup' will not be generated,
          as it is mostly useless unless compiled code can be loaded.

        SYMBOLGC=1
          Always enable garbage collection for unused symbols in the 
          symbol table by default. 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 at runtime by passing 
          the `-:w' runtime option when running the program.

        NOAPPLYHOOK=1
          For maximum performance this will disable support for 
          breakpoints, but speed up procedure invocation in safe 
          code. Smaller binaries can be obtained by also giving 
          "NOPTABLES=1", but that means serialization (available 
          as a separate package) of procedures will not be available.

        C_COMPILER_OPTIMIZATION_OPTIONS=...
          Override built-in C compiler optimization options. Available
          for debug or release build.

        PROGRAM_PREFIX= 
          A prefix to prepend to the names of all generated executables. 
          This allows having multiple CHICKEN versions in your PATH 
          (but note that they have to be installed at different locations).

        PROGRAM_SUFFIX=
          A suffix to be appended to the names of all generated executables.

        HOSTSYSTEM=
          A "<machine>-<platform>" name prefix to use for the C compiler to to
          use to compile the runtime system and executables. Set this variable
          if you want to compile CHICKEN for a different architecture than
          the one on which you are building it.

        TARGETSYSTEM= 
          Similar to "HOSTSYSTEM", but specifies the name
          prefix to use for compiling code with the "csc" compiler
          driver. This is required for creating a "cross chicken", a
          specially built CHICKEN that invokes a cross C compiler to
          build the final binaries. You will need a cross compiled
          runtime system by building a version of CHICKEN with the
          "HOST" option mentioned above. More information about this
          process and the variables that you should set are provided
          in the CHICKEN wiki at
          <http://chicken.wiki.br/cross-compilation>.

        USE_HOST_PCRE= 
          The PCRE library is included with the CHICKEN
          distribution to remove external dependencies and to avoid
          incompatibilities with any previously installed version. If
          you want to link with an installed libpcre, set this
          variable to a non-empty value. Only use this feature if you
          know what you are doing.

        SRCDIR= 
          Specifies that CHICKEN should be built outside of its source
          tree. The SRCDIR variable indicates the location of the
          CHICKEN source tree. The executables and object files will
          be generated in the current directory.


        To remove CHICKEN from your file-system, enter (probably as
        root):

            make PLATFORM=<platform> PREFIX=<destination> uninstall

        (If you gave DESTDIR during installation, you have to pass
        the same setting to "make" when uninstalling)

        In case you invoke "make" with different configuration parameters,
        it is advisable to run 

            make PLATFORM=<platform> confclean

        to remove old configuration files.


 3. Usage:

        Documentation can be found in the directory
        PREFIX/share/chicken/doc. The HTML documentation (in
        "PREFIX/share/chicken/doc/html") is automatically generated
        from the Wiki pages at <http://chicken.wiki.br/>. Go there to
        read the most up to date documentation.


 4. Extension:

        A large number of extension libraries for CHICKEN are
        available at
        <http://www.call-with-current-continuation.org/eggs/>. You can
        automatically download, compile and install extensions with
        the "chicken-setup" program. See the CHICKEN User's Manual for
        more information.

        Windows users: Note that you must have "tar" and "gunzip"
        programs installed and available through the "PATH"
        environment variable to extract extensions. If you don't
        download and extract the extensions ("eggs") manually using a
        browser and the decompression program of your choice and run
        "chicken-setup" in the directory where you extracted the
        extension archive.

        Windows binaries for common UNIX utilities (most notably "tar"
        and "gunzip") are available here:
        <http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip>.

        A selection of 3rd party libraries, together with source and
        binary packages for tools helpful for development with CHICKEN
        are also available at:
        <http://www.call-with-current-continuation.org/tarballs/>.

        
 5. Platform issues:

        - *BSD system users *must* use GNU make ("gmake") - the makefiles
          can not be processed by BSD make.

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

        - 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 versions you can find it here:

            http://www.opendarwin.org/projects/dlcompat

        - On Mac OS X, Chicken and its eggs can be built as universal 
          binaries which will work on either Intel or PowerPC.
          To build on Tiger (10.4):

            make PLATFORM=macosx ARCH=universal

          On Leopard (10.5), an extra step is required before `make':

            export MACOSX_DEPLOYMENT_TARGET=10.4
            make PLATFORM=macosx ARCH=universal

        - On Mac OS X, Chicken can be built in 64-bit mode on Intel
          Core 2 Duo systems--basically, most recent machines.  The default
          is 32-bit mode.  To enable 64-bit mode, invoke `make' thusly:

            make PLATFORM=macosx ARCH=x86-64

        - On Windows, mingw32, <http://mingw.sourceforge.net/>,
          Cygwin, and Visual C/C++ (PLATFORM=msvc) are supported.
          Makefiles for mingw under MSYS and Windows shell are provided
          (`Makefile.mingw-msys' and `Makefile.mingw').

        - When installing under the mingw-msys platform, PREFIX must be an
          absolute path name (i.e. it must include the drive letter).

        - Cygwin will not be able to find the chicken shared libraries
          until Windows is rebooted.

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

        - The Visual C build requires GNU make and other POSIX
          utilities.  Both cygwin and msys (with the Developer's
          Toolkit) have the necessary utilities. When setting PREFIX,
          use forward slashes:

          make PLATFORM=msvc PREFIX=c:/development/chicken

          The build has been tested with Visual Studio 2003 and 2008.  If
          you are able to build Chicken with other versions, please let
          us know.

          The following additional issues apply when using Chicken with
          Visual C:

          - Add the /DPIC flag when compiling your source files.  Otherwise
            you will encounter undefined symbols when linking.  Note that csc
            does this automatically for dlls but NOT for programs.

          - csc generates dynamics libraries with a .so extension, not .dll.

 6. Emacs support:

        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.

        A copy of Alex Shinn's highly useful tab-completion code is
        also included in `scheme-complete.el'. Install it like `hen.el'
        and add this code to your `.emacs':

          (autoload 'scheme-smart-complete "scheme-complete" nil t)
          (eval-after-load 'scheme
            '(progn (define-key scheme-mode-map "\e\t" 'scheme-smart-complete)))

        Or:

          (eval-after-load 'scheme
            '(progn (define-key scheme-mode-map "\t" 'scheme-complete-or-indent)))

        If you use eldoc-mode (included in Emacs), you can also get live
        scheme documentation with:

        (add-hook 'scheme-mode-hook
          (lambda ()
              (setq eldoc-info-function 'scheme-get-current-symbol-info)
                  (eldoc-mode)))

        Replace "'scheme" in the elisp expressions above with "'hen", if
        you want to add tab-completion to CHICKEN's own emacs mode.


 7. What's next?

        If you find any bugs, or want to report a problem, please consider
        using the "chicken-bug" tool to create a detailed bug report.

        If you have any more questions or problems (even the slightest
        problems, or the most stupid questions), then please subscribe
        to the "chicken-users" mailing list and ask for help. It will
        be answered.


        Have fun!