


     _/_/_/  _/    _/  _/_/_/    _/_/_/  _/    _/  _/_/_/_/  _/      _/
  _/        _/    _/    _/    _/        _/  _/    _/        _/_/    _/
 _/        _/_/_/_/    _/    _/        _/_/      _/_/_/    _/  _/  _/
_/        _/    _/    _/    _/        _/  _/    _/        _/    _/_/
 _/_/_/  _/    _/  _/_/_/    _/_/_/  _/    _/  _/_/_/_/  _/      _/



  README file for the CHICKEN Scheme system
  =========================================


  (c) 2008-2022, The CHICKEN Team
  (c) 2000-2007, Felix L. Winkelmann

  version 6.0.0rc3


 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 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 users mailing
    list.  Check http://wiki.call-cc.org/discussion-groups for
    information on how to subscribe to CHICKEN mailing lists.


 2. Installation

    Building CHICKEN requires GNU Make. Other "make" derivates are
    not supported.

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

    2.1. Building from a release tarball

    To build CHICKEN, first extract the archive ("tar xzf
    chicken-<version>.tar.gz" on UNIX or use your favorite
    extraction program on Windows), then change to the
    chicken-<version> directory and invoke "configure" like this:

        ./configure [OPTION ...]

    This will overwrite a configuration file for the subsequent
    "make" invocation that builds the CHICKEN tools and libraries.
    Enter "./configure --help" to see the available options.
    Usually you want to set the installation prefix where the
    results of the build should be installed:

        ./configure --prefix $HOME/.local

    If not given, the installation prefix defaults to "/usr/local".
    You can also define the build platform and whether you want to
    build with debug-information, in addition to other specialized
    settings. The platform is determined automatically if not
    specified.

    Once you have configured the system you can start building it
    by entering

        make

    Note that GNU make is currently required, so use

        gmake

    On systems that use BSD make.

    The old style invocation of "make" is still supported, where
    you pass platform and prefix information on the make command
    line, like this:

        make PLATFORM=<platform> PREFIX=<destination>

    Out-of-directory builds are currently not supported, so you must
    be in the toplevel source directory to invoke "configure" and
    "make".

    If CHICKEN somehow detects the wrong platform, type

        ./configure --platform=list

    to get a list of available platforms, and re-run "configure" using
    the correct platform.

    If you invoke "make" later with different configuration parameters,
    it is advisable to run:

        make confclean

    to remove old configuration files.

    2.2. Building from Git

    If you build CHICKEN directly from the development sources out
    of the git repository, you will need a "chicken" executable to
    generate the compiled C files from the Scheme library sources.
    See section 2.1 for platform detection issues.

    Configuration is the same as when building from the distribution
    tarball. You may have to use the "--chicken" option to define
    which "chicken" compiler binary should be used to translate the
    Scheme source code in the repository:

        ./configure --prefix ... --chicken <install-dir>/bin/chicken

    If you do not want to use the "configure" script, create an empty
    "config.make", like this:

        touch config.make

    "Config.make" is required by the build process, even if it
    contains no settings.

    If you are building in a checkout where you have built other
    versions of chicken, you need to make sure that all traces of
    the previous build are removed. "make clean" is insufficient,
    and you should do the following:

        make spotless

    You will need to have a "chicken" binary installed, ideally
    from the development snapshot tarball that is closest to the
    git version you are trying to build (significantly older or
    newer ones are unlikely to work), and then use that chicken
    to build from your git sources.  Installing this CHICKEN is
    recommended, if necessary you can install it to a temporary
    location in your homedir for example.

    In some cases, the sources may have diverged enough to
    become unbuildable even with the snapshot.  Then you'll need
    to first build a bootstrapping compiler with the installed
    CHICKEN and then use that to build the version from git.
    See the "Bootstrapping" section below.

    2.3. Finishing the installation

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

        make install

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

    2.4. Verifying your installation is correct

    You can check whether CHICKEN is functioning correctly by
    running

        make check

    This will run the test scripts, which show a lot of output.
    The only thing that matters is the exit status at the end.
    If it exits with status 0, everything is fine, if it exits
    with a nonzero status, the failing test's output should be
    the final lines before Make's "error; exit" output.  If the
    check fails on unmodified sources, please file a bugreport.

    2.5. Optional features

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

    --debugbuild
      Disable optimizations in compiled C code and enable
      debug information.

    --staticbuild
      Build only static versions of the runtime library, compiler
      and interpreter.

    --program-prefix 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 SUFFIX
      A suffix to be appended to the names of all generated executables.

    --host SYSTEM
      A "<machine>-<platform>" name prefix to use for the C compiler 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.

    --target SYSTEM
      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 manual (see the "Cross development" chapter).

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

    --vardir DIRECTORY
      If set, this directory overrides the location where
      extensions along with their metadata are stored. Normally
      this will be equivalent to "<PREFIX>/lib/chicken/<BINARYVERSION>".
      When VARDIR is specified, extensions will be stored in
      "<VARDIR>/chicken/<BINARYVERSION>", conforming to the FHS.

    --c-compiler PROGRAM
      If set, determines the C compiler used to compiler C sources.

    --linker PROGRAM
      Determines the executable used for linking compiled object files,
      usually the same as the C compiler executable.

    --profile-object "FILENAME ..."
      This option allows you to profile (parts of) CHICKEN itself.
      Just pass in a whitespace-separated list of objects, without
      the .scm-extension.  (An "object" here is an individual
      .scm-file which gets compiled to a .c-file)
      To build with profiling support, run "make spotless" first.
      Be warned that this is a highly experimental option and
      profiling doesn't work for every component of CHICKEN.

    The "configure" script respects the "CC" and "CFLAGS" environment
    variables which allow overriding the C compiler to use and any
    additional C compiler flags that should be used when compiling
    the runtime system and C files generated by "chicken".

    The default compiler is "gcc" ("cc" on *BSD systems). CHICKEN
    can be built with the LLVM version of gcc and with "clang",
    the LLVM-based C compiler, just set C_COMPILER to "llvm-gcc"
    or "clang". CHICKEN has also been successfully built with "zig cc",
    the C frontend of the "Zig" language toolchain.

    Less frequently used settings are available by variables that can
    be passed on the "make" command line:

    2.6. Uninstalling CHICKEN

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

        make uninstall

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

    2.7. What gets installed

    These files will be installed under the prefix given during
    build and installation:

    <PREFIX>
    |-- bin
    |   |-- chicken
    |   |-- chicken-install
    |   |-- chicken-profile
    |   |-- chicken-status
    |   |-- chicken-uninstall
    |   |-- libchicken.dll                        (Windows)
    |   |-- csc
    |   `-- csi
    |-- include
    |   `-- chicken
    |       |-- chicken-config.h
    |       `-- chicken.h
    |-- lib
    |   |-- chicken
    |   |   `-- 12
    |   |       |-- chicken.base.import.so
    |   |       |-- chicken.bitwise.import.so
    |   |       |-- chicken.bytevector.import.so
    |   |       |-- chicken.compiler.user-pass.import.so
    |   |       |-- chicken.condition.import.so
    |   |       |-- chicken.continuation.import.so
    |   |       |-- chicken.csi.import.so
    |   |       |-- chicken.errno.import.so
    |   |       |-- chicken.eval.import.so
    |   |       |-- chicken.file.import.so
    |   |       |-- chicken.file.posix.import.so
    |   |       |-- chicken.fixnum.import.so
    |   |       |-- chicken.flonum.import.so
    |   |       |-- chicken.foreign.import.so
    |   |       |-- chicken.format.import.so
    |   |       |-- chicken.gc.import.so
    |   |       |-- chicken.internal.import.so
    |   |       |-- chicken.io.import.so
    |   |       |-- chicken.irregex.import.so
    |   |       |-- chicken.keyword.import.so
    |   |       |-- chicken.load.import.so
    |   |       |-- chicken.locative.import.so
    |   |       |-- chicken.memory.import.so
    |   |       |-- chicken.memory.representation.import.so
    |   |       |-- chicken.pathname.import.so
    |   |       |-- chicken.platform.import.so
    |   |       |-- chicken.plist.import.so
    |   |       |-- chicken.port.import.so
    |   |       |-- chicken.pretty-print.import.so
    |   |       |-- chicken.process.import.so
    |   |       |-- chicken.process.signal.import.so
    |   |       |-- chicken.process-context.import.so
    |   |       |-- chicken.process-context.posix.import.so
    |   |       |-- chicken.random.import.so
    |   |       |-- chicken.repl.import.so
    |   |       |-- chicken.sort.import.so
    |   |       |-- chicken.string.import.so
    |   |       |-- chicken.read-syntax.import.so
    |   |       |-- chicken.syntax.import.so
    |   |       |-- chicken.tcp.import.so
    |   |       |-- chicken.time.import.so
    |   |       |-- chicken.time.posix.import.so
    |   |       |-- chicken.version.import.so
    |   |       |-- scheme.file.import.so
    |   |       |-- scheme.process-context.import.so
    |   |       |-- scheme.time.import.so
    |   |       |-- scheme.write.import.so
    |   |       |-- modules.db
    |   |       |-- srfi-4.import.so
    |   |       `-- types.db
    |   |-- libchicken-static.a
    |   |-- libchicken.dll.a                      (Windows)
    |   |-- libchicken.dylib                      (Macintosh)
    |   |-- libchicken.so -> libchicken.so.12     (Unix)
    |   `-- libchicken.so.12                      (Unix)
    `-- share
        |-- chicken
        |   |-- doc
        |   |   |-- LICENSE
        |   |   |-- README
        |   |   |-- DEPRECATED
        |   |   |-- chicken.png
        |   |   |-- manual-html
        |   |       `-- *.html
        |   |-- chicken.rc.o                      (Windows)
        |   `-- setup.defaults
        `-- man
        `-- man1
            |-- chicken-install.1
            |-- chicken-profile.1
            |-- chicken-status.1
            |-- chicken-uninstall.1
            |-- chicken.1
            |-- csc.1
            `-- csi.1


 3. Usage

    Documentation can be found in the directory
    PREFIX/share/chicken/doc in HTML format. The manual is
    maintained in a wiki at http://wiki.call-cc.org. Go there to
    read the most up to date documentation.


 4. Extensions

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

    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

    Android:

      - The Android SDK and NDK are required. Make sure you have
        set up a project and have a suitable NDK toolchain
        available. You will have to override the make(1) variable
        C_COMPILER to contain the correct compiler; see
        docs/STANDALONE-TOOLCHAIN.html in your NDK root for notes
        on how to call the correct compiler. You will also need to
        override the ARCH variable to match the device you're
        targeting.  The build will produce a libchicken.so that
        can then be integrated into your project as a prebuilt
        shared library.  See the android section on
        http://wiki.call-cc.org/embedding for a complete example.

      - It is possible to use eggs, by copying them into the right
        place and probably renaming the files. This is somewhat
        awkward and requires various hacks to make the
        loading/linking of eggs work. It may be easier to build
        the eggs you need manually and linking them statically to
        your executable.

      - By default debug-logging is enabled and written to the
        Android log.

    FreeBSD/NetBSD/OpenBSD:

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

      - On NetBSD it might be possible that compilation fails with a
        "virtual memory exhausted error".  Try the following:

        % unlimit datasize

      - When using -deploy on NetBSD, currently the kernel only
        supports running the program through its absolute path,
        otherwise you will get an error message stating:

          execname not specified in AUX vector: No such file or directory

        Deployed binaries can also be run without an explicit path,
        through $PATH; only relative pathnames do not work.

      - Using external libraries on NetBSD may also be easier, if
        you add the following definitions to `Makefile.bsd':

          C_COMPILER_OPTIONS += -I/usr/pkg/lib
          LINKER_OPTIONS += -L/usr/pkg/lib -Wl,-rpath=/usr/pkg/lib

        Note that this may cause build-problems, if you already have
        an existing CHICKEN installation in the /usr/pkg prefix.

    Linux:

      - If you want to build Linux binaries which use the "X32 ABI",
        you can pass ARCH=x32 on the Make command line.

      - There have been reports where the library directory
        "/usr/lib64" could not be found at build-time on a Fedora
        12 system. If you build a 64-bit version of CHICKEN and
        the library directory is set incorrectly, you can override
        it by passing "LIBDIR=/usr/lib64" as an additional
        argument when you invoke "make".

    Solaris:

      - By default, CHICKEN is build with the GNU C compiler (`gcc').
        To use the SunPro C compiler (`cc') instead, override the
        used compiler like this:

          CC=cc ./configure ...

      - 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

    Mac OS X:

      - The build currently assumes the C toolchain is in the path,
        use the "xcode-select(1)" tool to make them available on the
        command line if you haven't already done so.

      - CHICKEN will normally select a 32-bit or 64-bit build
        automatically when you use the normal build step:

          make

        Specifically, the defaults are:

          10.4: 32-bit
          10.5: 32-bit
          10.6: 64-bit (32-bit on original Core Duo, circa early 2006)
          10.7: 64-bit

        On 10.5, you can optionally build in 64-bit mode on machines
        released in late 2006 or later (i.e. with a Core 2 Duo or Xeon
        CPU), by specifying ARCH=x86-64:

          make ARCH=x86-64

      - Universal binaries: On 10.4 and 10.5 only, CHICKEN and its eggs
        can be built as universal binaries which will work on either
        Intel or PowerPC.  Most users will not want to do this.

        For 10.4 universal build:
          make ARCH=universal

        For 10.5 universal build:
          export MACOSX_DEPLOYMENT_TARGET=10.4
          make C_COMPILER=gcc-4.0 ARCH=universal

        For 10.6 and later, universal builds are not supported.

      - On 10.3 and earlier, you must first install `dlcompat'
        which can be found at http://distfiles.macports.org/dlcompat/.

    iOS:

      - Make sure the "XCODE_PATH" setting is correct (see
        Makefile.ios), it defaults to "/Applications/Xcode.app".

      - The paths for the the various build tools changed between
        Xcode 4 and 5. The makefile used for iOS builds of CHICKEN
        assume Xcode 5 is used. If you are using Xcode 4, override
        the XCODE_TOOLPATH and C_COMPILER make-variables providing
        the correct paths, see Makefile.ios for suggestions.

      - The iOS build is static (iOS doesn't support dynamic
        loading of executable code). Only the runtime library
        (libchicken.a) is of interest. To use it, integrate
        libchicken.a in your Xcode project and use a normal MacOS
        build to compile your Scheme sources into C files, adding
        them to you project.

      - Core library units must by accessed via "(declare (uses
        ...))" and "(import ...)", "require", "require-library",
        "require-extension" and "use" will not work, due to the
        reasons mentioned above.

      - As dynamic loading is not supported, eggs can not be used
        as usual, you will have to compile them manually and
        integrate what you need into your project.

      - If you want to build for the iPhone Simulator, override
        the ARCH and XCODE_SDK variables accordingly, see also in
        Makefile.ios for suggestions.

    Windows:

      - On Windows, native builds using the "MingW" toolchain and
        Cygwin are supported (Microsoft Visual Studio is *NOT*).
        Makefiles for MingW are provided (`Makefile.MingW').
        GNU make and a POSIX sh(1) are required to build the system.
        Please also read the notes below.

      - Since there are various distributions of the MingW toolchain
        we recommend to use "w64devkit" by Chrstopher Wellons:

          https://github.com/skeeto/w64devkit

        This toolset is very complete, includes GNU make and a
        POSIX shell and is the development environment we use to
        test CHICKEN. Other distributions of MingW may work but
        are not tested by us.

      - When installing under the MingW platform, PREFIX must be an
        absolute path name (i.e. it must include the drive letter) and
        must use forward slashes (no backward slashes), for example

          ./configure --prefix C:/chicken/

      - Under MingW, the "csc" compiler driver and "chicken-install"
        expect the compiler executable and the usual UNIX tools are
        in the PATH, so make sure to run them inside a shell that
        provides the necessary stuff.

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

      - During "make check" you may see these intermittent errors:

          ld.exe: cannot open output file a.out: Permission denied

        When this happens, the virusscanner is holding open
        the file of the previous test while the compiler is
        preparing the next test.
        To work around this in Windows Defender (the default),
        disable "realtime protection" under tools->options.

    AIX:

      - CHICKEN is built with the GNU C compiler (`gcc').  IBM's XL
        C compiler is not supported at this time.

      - AIX users *must* use GNU make ("gmake") - the makefiles can not be
        processed with IBM's version of make.

      - Deployment doesn't work.  See manual/Deployment for more details.

      - The AIX linker may occasionally show warnings of the form:

          ld: 0711-783 WARNING: TOC overflow. TOC size: 66656
          Maximum size: 65536
          Extra instructions are being generated for each reference to a TOC
          symbol if the symbol is in the TOC overflow area.

        Such messages indicate that lookups for some symbols in the
        effected library/executable may be somewhat slower at runtime as an
        auxiliary symbol table is needed to accommodate all of the symbols.

      - The AIX assembler may show warnings of the form:

          /tmp//ccycPGzK.s: line 527244: 1252-171 The displacement must be
          greater than or equal to -32768 and less than or equal to 32767.

        This is a known issue between the GNU toolchain and IBM's assembler:

        http://gcc.gnu.org/bugzilla/show_bug.cgi?id=4587

        The problem arises because the PPC architecture cannot perform jumps
        to addresses that differ more than what a 16-bit integer can
        represent.  Adding support for IBM's XL C compiler may resolve this
        issue.

        Instructing gcc to optimize the size of generated code (-Os)
        mitigates this to some degree, but very large C files may still be
        uncompilable.  This is known to affect the html-tags egg.

    Haiku:

      - The default GCC compiler is too old to support the -fwrapv
        option.  You can either remove the flag from Makefile.haiku,
        use a newer GCC, or supply your own C_COMPILER_OPTIONS on
        the Make command line.

      - The default Haiku BFS file system only supports timestamps
        with a granularity of one second.  This may cause trouble
        with pregenerated release or development snapshot tarballs
        due to the way files are pre-translated to C.  You'll either
        need to have CHICKEN installed, or touch the
        build-version.c file before building.


 6. Bootstrapping

    To build a bootstrapping compiler yourself, get the most
    recent development snapshot tarball from
    http://code.call-cc.org, unpack it, build and install everything.
    Then change to the directory containing the git code and run:

        ./configure --chicken <path-to-existing-chicken>
        make boot-chicken

    This will produce a statically linked binary with the name
    "chicken-boot[.exe]" that can be given as the value of the
    "--chicken" configuration option. Note that the path to an
    existing `chicken' binary must be given to use it for
    compiling the Scheme code of the runtime-system and compiler.

    "scripts/bootstrap.sh" automates this process; use this script
    if you are unsure how to build from the repository sources. It
    downloads the necessary development snapshot with wget(1) and
    builds the boot-chicken that you can use to compile the
    development sources. The invocation is:

        ./scripts/bootstrap.sh ...

    You can add additional parameters if you like to customize the
    build, but this should not be necessary. Note that your current
    working directory must be the root directory of the CHICKEN
    git(1) repository. Once the boot-chicken is built, proceed by
    invoking make(1) as described above (in 2.2, Building from Git),
    with the additional parameter:

        make CHICKEN=./chicken-boot ...

    or run "configure" again:

        ./configure --chicken ./chicken-boot ...
        make


 7. Emacs support

    See http://wiki.call-cc.org/emacs for tips and links to emacs
    extensions for Scheme and CHICKEN programming.


 8. What's next?

    If you find any bugs, or want to report a problem, please send
    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"
    (http://lists.nongnu.org/mailman/listinfo/chicken-users)
    mailing list and ask for help. It will be answered.
