README file for the CHICKEN Scheme system ========================================= (c) 2008-2015, The CHICKEN Team (c) 2000-2007, Felix L. Winkelmann version 4.10.0 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 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. If you are using a Windows system and do not have GNU Make, download http://code.call-cc.org/legacy-eggs/tarballs/UnxUtils.zip. It contains 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. 2.1. Building from a release tarball To build CHICKEN, first extract the archive ("tar xzf chicken-.tar.gz" on UNIX or use your favorite extraction program on Windows), then change to the chicken- directory and invoke "make" like this: make PLATFORM= PREFIX= 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. Note that parallel builds (using the "-j" make(1) option) are *not* supported. If you invoke "make" later with different configuration parameters, it is advisable to run: make PLATFORM= 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. 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 PLATFORM= spotless If you have a recent version of CHICKEN installed, then pass "CHICKEN=" to the "make" invocation to override this setting. "CHICKEN" defaults to "chicken". If you do not have a "chicken" binary installed, you will have to build from the closest release tarball 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. You don't need to install the release tarball chicken; simply unpack and build it in its own directory with "make PLATFORM=", then use it to build your git chicken like so: LD_LIBRARY_PATH= make PLATFORM= \ CHICKEN=/chicken The LD_LIBRARY_PATH is needed on Linux to allow chicken to find libchicken; it may or may not be needed on your platform, but probably won't do any harm. 2.3. Finishing the installation If CHICKEN is built successfully, you can install it on your system by entering make PLATFORM= PREFIX= 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. 2.4. Verifying your installation is correct You can check whether CHICKEN is functioning correctly by running make check where are all the variables you used while building CHICKEN. 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. Currently "make check" only works if you have installed CHICKEN. 2.5. Optional features 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-install', `chicken-uninstall' and `chicken-status' 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. EXTRA_CHICKEN_OPTIONS=... Additional options that should be passed to `chicken' when building the system. 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 "-" 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 manual (see the "Cross development" chapter). 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. VARDIR= If set, this directory overrides the location where extensions along with their metadata are stored. Normally this will be equivalent to "/lib/chicken/". When VARDIR is specified, extensions will be stored in "/chicken/", conforming to the FHS. CONFIG= If you build CHICKEN often, passing all those make variables can get annoying. An alternative is to create a configuration file defining the required variables and passing "CONFIG=" to make(1). Even simpler is editing the included "config.make" and just invoke make(1) without any extra parameters. C_COMPILER= You can select an alternative compiler by setting this variable. The default compiler is "gcc". 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". LINKER= Selects the linker to be used for creating executables and dynamic libraries from compiled C code. This should normally be the same as C_COMPILER. PROFILE_OBJECTS= This variable 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. 2.6. Uninstalling CHICKEN To remove CHICKEN from your file-system, enter (probably as root): make PLATFORM= PREFIX= 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: |-- bin | |-- chicken | |-- chicken-bug | |-- chicken-install | |-- chicken-profile | |-- chicken-status | |-- chicken-uninstall | |-- libchicken.dll (Windows) | |-- csc | `-- csi |-- include | `-- chicken | |-- chicken-config.h | `-- chicken.h |-- lib | |-- chicken | | `-- 7 | | |-- chicken.import.so | | |-- csi.import.so | | |-- data-structures.import.so | | |-- extras.import.so | | |-- files.import.so | | |-- foreign.import.so | | |-- irregex.import.so | | |-- lolevel.import.so | | |-- modules.db | | |-- ports.import.so | | |-- posix.import.so | | |-- setup-api.import.so | | |-- setup-api.so | | |-- setup-download.import.so | | |-- setup-download.so | | |-- srfi-1.import.so | | |-- srfi-13.import.so | | |-- srfi-14.import.so | | |-- srfi-18.import.so | | |-- srfi-4.import.so | | |-- srfi-69.import.so | | |-- tcp.import.so | | |-- types.db | | `-- utils.import.so | |-- libchicken.a | |-- libchicken.dll.a (Windows) | |-- libchicken.dylib (Macintosh) | |-- libchicken.so -> libchicken.so.7 (Unix) | `-- libchicken.so.7 (Unix) `-- share |-- chicken | |-- doc | | |-- LICENSE | | |-- README | | |-- mac.r (Macintosh) | | |-- CHICKEN.icns (Macintosh) | | |-- manual-html | | |-- chicken.png | | `-- *.html | `-- setup.defaults `-- man `-- man1 |-- chicken-bug.1 |-- 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: . 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,-R/usr/pkg/lib Note that this may cause build-problems, if you already have an existing CHICKEN installation in the /usr/pkg prefix. Linux: - 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'. - 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, pass C_COMPILER=cc to the "make" invocation. - 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 Xcode application path is "/Applications/Xcode.app/", with the C compiler and build tools being located in the "Contents/Developer/usr/bin" and "Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin" subdirectories, respectively. To override these locations, set XCODE_DEVELOPER and XCODE_TOOL_PATH on the make(3) command line. - On 10.6 and 10.7, CHICKEN may incorrectly select a 32-bit build environment when it should be building 64-bit, resulting in a build error. This occurs when you have a 32-bit kernel and a 64-bit gcc (that is, on Core 2 Duo systems running 10.6 Desktop). If this bites you, you'll get the following error or similar: apply-hack.x86.S:35:suffix or operands invalid for `call' As a workaround, manually force the build into 64-bit mode: make PLATFORM=macosx ARCH=x86-64 - CHICKEN will normally select a 32-bit or 64-bit build automatically when you use the normal build step: make PLATFORM=macosx 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 PLATFORM=macosx 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 PLATFORM=macosx ARCH=universal For 10.5 universal build: export MACOSX_DEPLOYMENT_TARGET=10.4 make C_COMPILER=gcc-4.0 PLATFORM=macosx 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, mingw32, and Cygwin are supported (Microsoft Visual Studio is *NOT*). Makefiles for mingw under MSYS and the Windows shell are provided (`Makefile.mingw-msys' and `Makefile.mingw'). Please also read the notes below. - When installing under the mingw-msys platform, PREFIX must be an absolute path name (i.e. it must include the drive letter) and must use forward slashes (no backward slashes). - When installing under mingw, with a windows shell ("cmd.exe"), pass an absolute pathname (including the drive letter) as PREFIX and use forward slashes. If you are building the sources from git, use backslashes to specify the path to `chicken' (the "CHICKEN" variable). - When installing under mingw without MSYS, make sure that the MSYS tools (in case you have some of them, in particular the sh.exe UNIX shell) are *NOT* visible in your PATH. - 64-bit Windows is supported, invoke mingw32-make with the "ARCH=x86-64" argument (this is currently not detected automatically). The build has been tested on Windows 7 with the SJLJ binary package from "MinGW-builds", which can be found here: http://sourceforge.net/projects/mingwbuilds/ - 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. - 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. 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 release tarball from http://code.call-cc.org, unpack it, build and install it. Then change to the directory containing the git code and run: make PLATFORM= CHICKEN= \ 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" argument when invoking make(1). 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. 7. Emacs support See http://wiki.call-cc.org/emacs for tips and links to emacs extensions for Scheme and CHICKEN programming. 8. Compatibility notes In CHICKEN 4, the macro system has been reimplemented completely and provides module system, which has considerably more flexibility and power, but will require the re-implementation of macros in code that previously was used with CHICKEN 3. Notably, `define-macro' is not available anymore. See the manual on how to translate such macros to low-level hygienic macros or ask on the CHICKEN mailing list. 9. 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" (http://lists.nongnu.org/mailman/listinfo/chicken-users) mailing list and ask for help. It will be answered.