~ chicken-core (chicken-5) /README
Trap1234 _/_/_/ _/ _/ _/_/_/ _/_/_/ _/ _/ _/_/_/_/ _/ _/5 _/ _/ _/ _/ _/ _/ _/ _/ _/_/ _/6 _/ _/_/_/_/ _/ _/ _/_/ _/_/_/ _/ _/ _/7_/ _/ _/ _/ _/ _/ _/ _/ _/ _/_/8 _/_/_/ _/ _/ _/_/_/ _/_/_/ _/ _/ _/_/_/_/ _/ _/9101112 README file for the CHICKEN Scheme system13 =========================================141516 (c) 2008-2022, The CHICKEN Team17 (c) 2000-2007, Felix L. Winkelmann1819 version 5.4.1202122 1. Introduction2324 CHICKEN is a Scheme-to-C compiler supporting the language25 features as defined in the 'Revised^5 Report on26 Scheme'. Separate compilation is supported and full27 tail-recursion and efficient first-class continuations are28 available.2930 Some things that CHICKEN has to offer:3132 1. CHICKEN generates quite portable C code and compiled files33 generated by it (including itself) should work without any34 changes on Windows, most UNIX-like platforms, and with35 minor changes on other systems.3637 2. The whole package is distributed under a BSD style license38 and as such is free to use and modify as long as you agree39 to its terms.4041 3. Linkage to C modules and C library functions is42 straightforward. Compiled programs can easily be embedded43 into existing C code.4445 4. Loads of extra libraries.4647 Note: Should you have any trouble in setting up and using48 CHICKEN, please ask questions on the CHICKEN users mailing49 list. Check http://wiki.call-cc.org/discussion-groups for50 information on how to subscribe to CHICKEN mailing lists.515253 2. Installation5455 Building CHICKEN requires GNU Make. Other "make" derivates are56 not supported. If you are using a Windows system and do not57 have GNU Make, download58 http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip.59 It contains a precompiled set of UNIX utilities, which among60 other useful tools contains "make".6162 Configuration and customization of the build process is done by63 either setting makefile variables on the "make" command line or64 by editing the platform-specific makefile.6566 2.1. Building from a release tarball6768 To build CHICKEN, first extract the archive ("tar xzf69 chicken-<version>.tar.gz" on UNIX or use your favorite70 extraction program on Windows), then change to the71 chicken-<version> directory and invoke "make" like this:7273 make PLATFORM=<platform> PREFIX=<destination>7475 where "PLATFORM" specifies on what kind of system CHICKEN76 shall be built and "PREFIX" specifies where the executables77 and libraries shall be installed. Out-of-directory builds are78 currently not supported, so you must be in the toplevel source79 directory to invoke "make".8081 If you enter "make" without the PLATFORM option, CHICKEN will82 attempt to figure out what platform you are using. If it cannot83 do so, you will see a list of supported platforms. If you are84 cross-building, you must specify PLATFORM; for example,85 PLATFORM=cross-linux-mingw will build CHICKEN on Linux to86 deploy on Windows.8788 If CHICKEN somehow detects the wrong platform, type8990 make PLATFORM=""9192 to get a list of available platforms, and re-run "make" using93 the correct platform.9495 Note that parallel builds (using the "-j" make(1) option) are96 *not* supported.9798 If you invoke "make" later with different configuration parameters,99 it is advisable to run:100101 make confclean102103 to remove old configuration files.104105 2.2. Building from Git106107 If you build CHICKEN directly from the development sources out108 of the git repository, you will need a "chicken" executable to109 generate the compiled C files from the Scheme library sources.110 See section 2.1 for platform detection issues.111112 If you are building in a checkout where you have built other113 versions of chicken, you need to make sure that all traces of114 the previous build are removed. "make clean" is insufficient,115 and you should do the following:116117 make spotless118119 You will need to have a "chicken" binary installed, ideally120 from the development snapshot tarball that is closest to the121 git version you are trying to build (significantly older or122 newer ones are unlikely to work), and then use that chicken123 to build from your git sources. Installing this CHICKEN is124 recommended, if necessary you can install it to a temporary125 location in your homedir for example.126127 Then, to build you can run:128129 make CHICKEN=<install-dir>/bin/chicken130131 In some cases, the sources may have diverged enough to132 become unbuildable even with the snapshot. Then you'll need133 to first build a bootstrapping compiler with the installed134 CHICKEN and then use that to build the version from git.135 See the "Bootstrapping" section below.136137 2.3. Finishing the installation138139 If CHICKEN is built successfully, you can install it on your140 system by entering141142 make PREFIX=<destination> install143144 "PREFIX" defaults to "/usr/local". Note that the PREFIX is145 compiled into several CHICKEN tools and must be the same146 while building the system and during installation.147148 To install CHICKEN for a particular PREFIX on a different149 location, set the "DESTDIR" variable in addition to "PREFIX":150 It designates the directory where the files are installed151 into.152153 2.4. Verifying your installation is correct154155 You can check whether CHICKEN is functioning correctly by156 running157158 make <vars> check159160 where <vars> are all the variables you used while building161 CHICKEN.162163 This will run the test scripts, which show a lot of output.164 The only thing that matters is the exit status at the end.165 If it exits with status 0, everything is fine, if it exits166 with a nonzero status, the failing test's output should be167 the final lines before Make's "error; exit" output. If the168 check fails on unmodified sources, please file a bugreport.169170 2.5. Optional features171172 You can further enable various optional features by adding173 one or more of the following variables to the "make"174 invocation:175176 DEBUGBUILD=1177 Disable optimizations in compiled C code and enable178 debug information.179180 STATICBUILD=1181 Build only static versions of the runtime library, compiler182 and interpreter.183184 EXTRA_CHICKEN_OPTIONS=...185 Additional options that should be passed to `chicken' when186 building the system.187188 C_COMPILER_OPTIMIZATION_OPTIONS=...189 Override built-in C compiler optimization options. Available190 for debug or release build.191192 PROGRAM_PREFIX=193 A prefix to prepend to the names of all generated executables.194 This allows having multiple CHICKEN versions in your PATH195 (but note that they have to be installed at different locations).196197 PROGRAM_SUFFIX=198 A suffix to be appended to the names of all generated executables.199200 HOSTSYSTEM=201 A "<machine>-<platform>" name prefix to use for the C compiler to202 use to compile the runtime system and executables. Set this variable203 if you want to compile CHICKEN for a different architecture than204 the one on which you are building it.205206 TARGETSYSTEM=207 Similar to "HOSTSYSTEM", but specifies the name208 prefix to use for compiling code with the "csc" compiler209 driver. This is required for creating a "cross chicken", a210 specially built CHICKEN that invokes a cross C compiler to211 build the final binaries. You will need a cross compiled212 runtime system by building a version of CHICKEN with the213 "HOST" option mentioned above. More information about this214 process and the variables that you should set are provided215 in the manual (see the "Cross development" chapter).216217 SRCDIR=218 Specifies that CHICKEN should be built outside of its source219 tree. The SRCDIR variable indicates the location of the220 CHICKEN source tree. The executables and object files will221 be generated in the current directory.222223 VARDIR=224 If set, this directory overrides the location where225 extensions along with their metadata are stored. Normally226 this will be equivalent to "<PREFIX>/lib/chicken/<BINARYVERSION>".227 When VARDIR is specified, extensions will be stored in228 "<VARDIR>/chicken/<BINARYVERSION>", conforming to the FHS.229230 CONFIG=231 If you build CHICKEN often, passing all those make variables232 can get annoying. An alternative is to create a configuration233 file defining the required variables and passing234 "CONFIG=<configfile>" to make(1).235 Even simpler is editing the included "config.make"236 and just invoke make(1) without any extra parameters.237238 C_COMPILER=239 You can select an alternative compiler by setting this variable.240 The default compiler is "gcc". CHICKEN can be built with the241 LLVM version of gcc and with "clang", the LLVM-based C compiler,242 just set C_COMPILER to "llvm-gcc" or "clang".243244 LINKER=245 Selects the linker to be used for creating executables and246 dynamic libraries from compiled C code. This should normally247 be the same as C_COMPILER.248249 PROFILE_OBJECTS=250 This variable allows you to profile (parts of) CHICKEN itself.251 Just pass in a whitespace-separated list of objects, without252 the .scm-extension. (An "object" here is an individual253 .scm-file which gets compiled to a .c-file)254 To build with profiling support, run "make spotless" first.255 Be warned that this is a highly experimental option and256 profiling doesn't work for every component of CHICKEN.257258 2.6. Uninstalling CHICKEN259260 To remove CHICKEN from your file-system, enter (probably as261 root):262263 make PREFIX=<destination> uninstall264265 (If you gave DESTDIR during installation, you have to pass266 the same setting to "make" when uninstalling)267268 2.7. What gets installed269270 These files will be installed under the prefix given during271 build and installation:272273 <PREFIX>274 |-- bin275 | |-- chicken276 | |-- chicken-install277 | |-- chicken-profile278 | |-- chicken-status279 | |-- chicken-uninstall280 | |-- libchicken.dll (Windows)281 | |-- csc282 | |-- csi283 | |-- feathers.bat (Windows)284 | `-- feathers (Unix)285 |-- include286 | `-- chicken287 | |-- chicken-config.h288 | `-- chicken.h289 |-- lib290 | |-- chicken291 | | `-- 9292 | | |-- chicken.base.import.so293 | | |-- chicken.bitwise.import.so294 | | |-- chicken.blob.import.so295 | | |-- chicken.compiler.user-pass.import.so296 | | |-- chicken.condition.import.so297 | | |-- chicken.continuation.import.so298 | | |-- chicken.csi.import.so299 | | |-- chicken.errno.import.so300 | | |-- chicken.eval.import.so301 | | |-- chicken.file.import.so302 | | |-- chicken.file.posix.import.so303 | | |-- chicken.fixnum.import.so304 | | |-- chicken.flonum.import.so305 | | |-- chicken.foreign.import.so306 | | |-- chicken.format.import.so307 | | |-- chicken.gc.import.so308 | | |-- chicken.internal.import.so309 | | |-- chicken.io.import.so310 | | |-- chicken.irregex.import.so311 | | |-- chicken.keyword.import.so312 | | |-- chicken.load.import.so313 | | |-- chicken.locative.import.so314 | | |-- chicken.memory.import.so315 | | |-- chicken.memory.representation.import.so316 | | |-- chicken.pathname.import.so317 | | |-- chicken.platform.import.so318 | | |-- chicken.plist.import.so319 | | |-- chicken.port.import.so320 | | |-- chicken.pretty-print.import.so321 | | |-- chicken.process.import.so322 | | |-- chicken.process.signal.import.so323 | | |-- chicken.process-context.import.so324 | | |-- chicken.process-context.posix.import.so325 | | |-- chicken.random.import.so326 | | |-- chicken.repl.import.so327 | | |-- chicken.sort.import.so328 | | |-- chicken.string.import.so329 | | |-- chicken.read-syntax.import.so330 | | |-- chicken.syntax.import.so331 | | |-- chicken.tcp.import.so332 | | |-- chicken.time.import.so333 | | |-- chicken.time.posix.import.so334 | | |-- modules.db335 | | |-- srfi-4.import.so336 | | `-- types.db337 | |-- libchicken.a338 | |-- libchicken.dll.a (Windows)339 | |-- libchicken.dylib (Macintosh)340 | |-- libchicken.so -> libchicken.so.11 (Unix)341 | `-- libchicken.so.11 (Unix)342 `-- share343 |-- chicken344 | |-- doc345 | | |-- LICENSE346 | | |-- README347 | | |-- DEPRECATED348 | | |-- manual-html349 | | |-- chicken.png350 | | `-- *.html351 | |-- chicken.rc.o (Windows)352 | |-- feathers.tcl353 | `-- setup.defaults354 `-- man355 `-- man1356 |-- chicken-install.1357 |-- chicken-profile.1358 |-- chicken-status.1359 |-- chicken-uninstall.1360 |-- chicken.1361 |-- csc.1362 |-- csi.1363 `-- feathers.1364365366 3. Usage367368 Documentation can be found in the directory369 PREFIX/share/chicken/doc in HTML format. The manual is370 maintained in a wiki at http://wiki.call-cc.org. Go there to371 read the most up to date documentation.372373374 4. Extensions375376 A large number of extension libraries for CHICKEN are377 available at http://wiki.call-cc.org/eggs. You can378 automatically download, compile and install extensions with379 the "chicken-install" program. See the CHICKEN User's Manual380 for more information.381382 A selection of 3rd party libraries, together with source and383 binary packages for tools helpful for development with CHICKEN384 are also available at:385 <http://www.call-with-current-continuation.org/tarballs/>.386387388 5. Platform issues389390 Android:391392 - The Android SDK and NDK are required. Make sure you have393 set up a project and have a suitable NDK toolchain394 available. You will have to override the make(1) variable395 C_COMPILER to contain the correct compiler; see396 docs/STANDALONE-TOOLCHAIN.html in your NDK root for notes397 on how to call the correct compiler. You will also need to398 override the ARCH variable to match the device you're399 targeting. The build will produce a libchicken.so that400 can then be integrated into your project as a prebuilt401 shared library. See the android section on402 http://wiki.call-cc.org/embedding for a complete example.403404 - It is possible to use eggs, by copying them into the right405 place and probably renaming the files. This is somewhat406 awkward and requires various hacks to make the407 loading/linking of eggs work. It may be easier to build408 the eggs you need manually and linking them statically to409 your executable.410411 - By default debug-logging is enabled and written to the412 Android log.413414 FreeBSD/NetBSD/OpenBSD:415416 - *BSD system users *must* use GNU make ("gmake") - the makefiles417 can not be processed by BSD make.418419 - On NetBSD it might be possible that compilation fails with a420 "virtual memory exhausted error". Try the following:421422 % unlimit datasize423424 - When using -deploy on NetBSD, currently the kernel only425 supports running the program through its absolute path,426 otherwise you will get an error message stating:427428 execname not specified in AUX vector: No such file or directory429430 Deployed binaries can also be run without an explicit path,431 through $PATH; only relative pathnames do not work.432433 - Using external libraries on NetBSD may also be easier, if434 you add the following definitions to `Makefile.bsd':435436 C_COMPILER_OPTIONS += -I/usr/pkg/lib437 LINKER_OPTIONS += -L/usr/pkg/lib -Wl,-rpath=/usr/pkg/lib438439 Note that this may cause build-problems, if you already have440 an existing CHICKEN installation in the /usr/pkg prefix.441442 Linux:443444 - If you want to build Linux binaries which use the "X32 ABI",445 you can pass ARCH=x32 on the Make command line.446447 - There have been reports where the library directory448 "/usr/lib64" could not be found at build-time on a Fedora449 12 system. If you build a 64-bit version of CHICKEN and450 the library directory is set incorrectly, you can override451 it by passing "LIBDIR=/usr/lib64" as an additional452 argument when you invoke "make".453454 Solaris:455456 - By default, CHICKEN is build with the GNU C compiler (`gcc').457 To use the SunPro C compiler (`cc') instead, pass458459 C_COMPILER=cc460461 to the "make" invocation.462463 - Older versions of Solaris have a bug in ld.so that causes464 trouble with dynamic loading. Patching Solaris fixes the465 problem. Solaris 7 needs patch 106950-18. Solaris 8 has an466 equivalent patch, 109147-16.467468 You can find out if you have these patches installed by469 running:470471 % showrev -p | grep 106950 # solaris 7472 % showrev -p | grep 109147 # solaris 8473474 Mac OS X:475476 - The build currently assumes the C toolchain is in the path,477 use the "xcode-select(1)" tool to make them available on the478 command line if you haven't already done so.479480 - CHICKEN will normally select a 32-bit or 64-bit build481 automatically when you use the normal build step:482483 make484485 Specifically, the defaults are:486487 10.4: 32-bit488 10.5: 32-bit489 10.6: 64-bit (32-bit on original Core Duo, circa early 2006)490 10.7: 64-bit491492 On 10.5, you can optionally build in 64-bit mode on machines493 released in late 2006 or later (i.e. with a Core 2 Duo or Xeon494 CPU), by specifying ARCH=x86-64:495496 make ARCH=x86-64497498 - Universal binaries: On 10.4 and 10.5 only, CHICKEN and its eggs499 can be built as universal binaries which will work on either500 Intel or PowerPC. Most users will not want to do this.501502 For 10.4 universal build:503 make ARCH=universal504505 For 10.5 universal build:506 export MACOSX_DEPLOYMENT_TARGET=10.4507 make C_COMPILER=gcc-4.0 ARCH=universal508509 For 10.6 and later, universal builds are not supported.510511 - On 10.3 and earlier, you must first install `dlcompat'512 which can be found at http://distfiles.macports.org/dlcompat/.513514515 iOS:516517 - Make sure the "XCODE_PATH" setting is correct (see518 Makefile.ios), it defaults to "/Applications/Xcode.app".519520 - The paths for the various build tools changed between521 Xcode 4 and 5. The makefile used for iOS builds of CHICKEN522 assume Xcode 5 is used. If you are using Xcode 4, override523 the XCODE_TOOLPATH and C_COMPILER make-variables providing524 the correct paths, see Makefile.ios for suggestions.525526 - The iOS build is static (iOS doesn't support dynamic527 loading of executable code). Only the runtime library528 (libchicken.a) is of interest. To use it, integrate529 libchicken.a in your Xcode project and use a normal MacOS530 build to compile your Scheme sources into C files, adding531 them to you project.532533 - Core library units must by accessed via "(declare (uses534 ...))" and "(import ...)", "require", "require-library",535 "require-extension" and "use" will not work, due to the536 reasons mentioned above.537538 - As dynamic loading is not supported, eggs can not be used539 as usual, you will have to compile them manually and540 integrate what you need into your project.541542 - If you want to build for the iPhone Simulator, override543 the ARCH and XCODE_SDK variables accordingly, see also in544 Makefile.ios for suggestions.545546 Windows:547548 - On Windows, mingw32, <http://mingw.sourceforge.net/> and549 Cygwin are supported (Microsoft Visual Studio is *NOT*).550 Makefiles for mingw under MSYS and the Windows shell are551 provided (`Makefile.mingw-msys' and `Makefile.mingw').552 Please also read the notes below.553554 - When installing under the mingw-msys platform, PREFIX must be an555 absolute path name (i.e. it must include the drive letter) and556 must use forward slashes (no backward slashes), for example557 "PREFIX=C:/chicken/".558559 - When installing under mingw, with a windows shell560 ("cmd.exe"), pass an absolute pathname (including the561 drive letter) as PREFIX and use forward slashes. If you562 are building the sources from git, use backslashes to563 specify the path to `chicken' (the "CHICKEN" variable).564565 - When installing under mingw without MSYS, make sure that the566 MSYS tools (in case you have some of them, in particular the567 sh.exe UNIX shell) are *NOT* visible in your PATH.568569 - 64-bit Windows is supported, invoke mingw32-make with the570 "ARCH=x86-64" argument (this is currently not detected571 automatically). The build has been tested on Windows 7572 with the SJLJ binary package from "MinGW-builds", which573 can be found here:574575 http://sourceforge.net/projects/mingwbuilds/576577 - Cygwin will not be able to find the chicken shared libraries578 until Windows is rebooted.579580 - During "make check" you may see these intermittent errors:581582 ld.exe: cannot open output file a.out: Permission denied583584 When this happens, the virusscanner is holding open585 the file of the previous test while the compiler is586 preparing the next test.587 To work around this in Windows Defender (the default),588 disable "realtime protection" under tools->options.589590 AIX:591592 - CHICKEN is built with the GNU C compiler (`gcc'). IBM's XL593 C compiler is not supported at this time.594595 - AIX users *must* use GNU make ("gmake") - the makefiles can not be596 processed with IBM's version of make.597598 - Deployment doesn't work. See manual/Deployment for more details.599600 - The AIX linker may occasionally show warnings of the form:601602 ld: 0711-783 WARNING: TOC overflow. TOC size: 66656603 Maximum size: 65536604 Extra instructions are being generated for each reference to a TOC605 symbol if the symbol is in the TOC overflow area.606607 Such messages indicate that lookups for some symbols in the608 effected library/executable may be somewhat slower at runtime as an609 auxiliary symbol table is needed to accommodate all of the symbols.610611 - The AIX assembler may show warnings of the form:612613 /tmp//ccycPGzK.s: line 527244: 1252-171 The displacement must be614 greater than or equal to -32768 and less than or equal to 32767.615616 This is a known issue between the GNU toolchain and IBM's assembler:617618 http://gcc.gnu.org/bugzilla/show_bug.cgi?id=4587619620 The problem arises because the PPC architecture cannot perform jumps621 to addresses that differ more than what a 16-bit integer can622 represent. Adding support for IBM's XL C compiler may resolve this623 issue.624625 Instructing gcc to optimize the size of generated code (-Os)626 mitigates this to some degree, but very large C files may still be627 uncompilable. This is known to affect the html-tags egg.628629 Haiku:630631 - The default GCC compiler is too old to support the -fwrapv632 option. You can either remove the flag from Makefile.haiku,633 use a newer GCC, or supply your own C_COMPILER_OPTIONS on634 the Make command line.635636 - The default Haiku BFS file system only supports timestamps637 with a granularity of one second. This may cause trouble638 with pregenerated release or development snapshot tarballs639 due to the way files are pre-translated to C. You'll either640 need to have CHICKEN installed, or touch the641 build-version.c file before building.642643644 6. Bootstrapping645646 To build a bootstrapping compiler yourself, get the most647 recent development snapshot tarball from648 http://code.call-cc.org, unpack it, build and install it.649 Then change to the directory containing the git code and run:650651 make CHICKEN=<path-to-existing-chicken> \652 boot-chicken653654 This will produce a statically linked binary with the name655 "chicken-boot[.exe]" that can be given as the value of the656 "CHICKEN" argument when invoking make(1). Note that the path657 to an existing `chicken' binary must be given to use it for658 compiling the Scheme code of the runtime-system and compiler.659660 "scripts/bootstrap.sh" automates this process; use this script661 if you are unsure how to build from the repository sources. It662 downloads the necessary development snapshot with wget(1) and663 builds the boot-chicken that you can use to compile the664 development sources. The invocation is:665666 scripts/bootstrap.sh ...667668 You can add additional parameters if you like to customize the669 build, but this should not be necessary. Note that your current670 working directory must be the root directory of the CHICKEN671 git(1) repository. Once the boot-chicken is built, proceed by672 invoking make(1) as described above (in 2.2, Building from Git),673 with the additional parameter:674675 make CHICKEN=./chicken-boot ...676677678 7. Emacs support679680 See http://wiki.call-cc.org/emacs for tips and links to emacs681 extensions for Scheme and CHICKEN programming.682683684 8. What's next?685686 If you find any bugs, or want to report a problem, please send687 a detailed bug report.688689 If you have any more questions or problems (even the slightest690 problems, or the most stupid questions), then please subscribe691 to the "chicken-users"692 (http://lists.nongnu.org/mailman/listinfo/chicken-users)693 mailing list and ask for help. It will be answered.