~ chicken-core (master) /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 6.0.0202122 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.5758 Configuration and customization of the build process is done by59 either using the "configure" script, setting makefile variables60 on the "make" command line or by editing the platform-specific61 makefile.6263 2.1. Building from a release tarball6465 To build CHICKEN, first extract the archive ("tar xzf66 chicken-<version>.tar.gz" on UNIX or use your favorite67 extraction program on Windows), then change to the68 chicken-<version> directory and invoke "configure" like this:6970 ./configure [OPTION ...]7172 This will overwrite a configuration file for the subsequent73 "make" invocation that builds the CHICKEN tools and libraries.74 Enter "./configure --help" to see the available options.75 Usually you want to set the installation prefix where the76 results of the build should be installed:7778 ./configure --prefix $HOME/.local7980 If not given, the installation prefix defaults to "/usr/local".81 You can also define the build platform and whether you want to82 build with debug-information, in addition to other specialized83 settings. The platform is determined automatically if not84 specified.8586 Once you have configured the system you can start building it87 by entering8889 make9091 Note that GNU make is currently required, so use9293 gmake9495 On systems that use BSD make.9697 The old style invocation of "make" is still supported, where98 you pass platform and prefix information on the make command99 line, like this:100101 make PLATFORM=<platform> PREFIX=<destination>102103 Out-of-directory builds are currently not supported, so you must104 be in the toplevel source directory to invoke "configure" and105 "make".106107 If CHICKEN somehow detects the wrong platform, type108109 ./configure --platform=list110111 to get a list of available platforms, and re-run "configure" using112 the correct platform.113114 If you invoke "make" later with different configuration parameters,115 it is advisable to run:116117 make confclean118119 to remove old configuration files.120121 2.2. Building from Git122123 If you build CHICKEN directly from the development sources out124 of the git repository, you will need a "chicken" executable to125 generate the compiled C files from the Scheme library sources.126 See section 2.1 for platform detection issues.127128 Configuration is the same as when building from the distribution129 tarball. You may have to use the "--chicken" option to define130 which "chicken" compiler binary should be used to translate the131 Scheme source code in the repository:132133 ./configure --prefix ... --chicken <install-dir>/bin/chicken134135 If you do not want to use the "configure" script, create an empty136 "config.make", like this:137138 touch config.make139140 "Config.make" is required by the build process, even if it141 contains no settings.142143 If you are building in a checkout where you have built other144 versions of chicken, you need to make sure that all traces of145 the previous build are removed. "make clean" is insufficient,146 and you should do the following:147148 make spotless149150 You will need to have a "chicken" binary installed, ideally151 from the development snapshot tarball that is closest to the152 git version you are trying to build (significantly older or153 newer ones are unlikely to work), and then use that chicken154 to build from your git sources. Installing this CHICKEN is155 recommended, if necessary you can install it to a temporary156 location in your homedir for example.157158 In some cases, the sources may have diverged enough to159 become unbuildable even with the snapshot. Then you'll need160 to first build a bootstrapping compiler with the installed161 CHICKEN and then use that to build the version from git.162 See the "Bootstrapping" section below.163164 2.3. Verifying your installation is correct165166 You can check whether CHICKEN is functioning correctly by167 running168169 make check170171 This will run the test scripts, which show a lot of output.172 The only thing that matters is the exit status at the end.173 If it exits with status 0, everything is fine, if it exits174 with a nonzero status, the failing test's output should be175 the final lines before Make's "error; exit" output. If the176 check fails on unmodified sources, please file a bugreport.177178 2.4. Finishing the installation179180 If CHICKEN is built successfully, you can install it on your181 system by entering182183 make install184185 To install CHICKEN for a particular prefix on a different186 location, set the "DESTDIR" variable: It designates the187 directory where the files are installed into.188189 2.5. Optional features190191 You can further enable various optional features by adding192 one or more of the following variables to the "configure"193 invocation:194195 --debugbuild196 Disable optimizations in compiled C code and enable197 debug information.198199 --staticbuild200 Build only static versions of the runtime library, compiler201 and interpreter.202203 --program-prefix PREFIX204 A prefix to prepend to the names of all generated executables.205 This allows having multiple CHICKEN versions in your PATH206 (but note that they have to be installed at different locations).207208 --program-suffix SUFFIX209 A suffix to be appended to the names of all generated executables.210211 --host SYSTEM212 A "<machine>-<platform>" name prefix to use for the C compiler to213 use to compile the runtime system and executables. Set this variable214 if you want to compile CHICKEN for a different architecture than215 the one on which you are building it.216217 --target SYSTEM218 Similar to "HOSTSYSTEM", but specifies the name219 prefix to use for compiling code with the "csc" compiler220 driver. This is required for creating a "cross chicken", a221 specially built CHICKEN that invokes a cross C compiler to222 build the final binaries. You will need a cross compiled223 runtime system by building a version of CHICKEN with the224 "HOST" option mentioned above. More information about this225 process and the variables that you should set are provided226 in the manual (see the "Cross development" chapter).227228 --srcdir DIRECTORY229 Specifies that CHICKEN should be built outside of its source230 tree. The SRCDIR variable indicates the location of the231 CHICKEN source tree. The executables and object files will232 be generated in the current directory.233234 --vardir DIRECTORY235 If set, this directory overrides the location where236 extensions along with their metadata are stored. Normally237 this will be equivalent to "<PREFIX>/lib/chicken/<BINARYVERSION>".238 When VARDIR is specified, extensions will be stored in239 "<VARDIR>/chicken/<BINARYVERSION>", conforming to the FHS.240241 --c-compiler PROGRAM242 If set, determines the C compiler used to compiler C sources.243244 --linker PROGRAM245 Determines the executable used for linking compiled object files,246 usually the same as the C compiler executable.247248 --profile-object "FILENAME ..."249 This option allows you to profile (parts of) CHICKEN itself.250 Just pass in a whitespace-separated list of objects, without251 the .scm-extension. (An "object" here is an individual252 .scm-file which gets compiled to a .c-file)253 To build with profiling support, run "make spotless" first.254 Be warned that this is a highly experimental option and255 profiling doesn't work for every component of CHICKEN.256257 The "configure" script respects the "CC" and "CFLAGS" environment258 variables which allow overriding the C compiler to use and any259 additional C compiler flags that should be used when compiling260 the runtime system and C files generated by "chicken".261262 The default compiler is "gcc" ("cc" on *BSD systems). CHICKEN263 can be built with the LLVM version of gcc and with "clang",264 the LLVM-based C compiler, just set C_COMPILER to "llvm-gcc"265 or "clang". CHICKEN has also been successfully built with "zig cc",266 the C frontend of the "Zig" language toolchain.267268 Less frequently used settings are available by variables that can269 be passed on the "make" command line:270271 2.6. Uninstalling CHICKEN272273 To remove CHICKEN from your file-system, enter (probably as274 root):275276 make uninstall277278 (If you gave DESTDIR during installation, you have to pass279 the same setting to "make" when uninstalling)280281 2.7. What gets installed282283 These files will be installed under the prefix given during284 build and installation:285286 <PREFIX>287 |-- bin288 | |-- chicken289 | |-- chicken-install290 | |-- chicken-profile291 | |-- chicken-status292 | |-- chicken-uninstall293 | |-- libchicken.dll (Windows)294 | |-- csc295 | `-- csi296 |-- include297 | `-- chicken298 | |-- chicken-config.h299 | `-- chicken.h300 |-- lib301 | |-- chicken302 | | `-- 12303 | | |-- chicken.base.import.so304 | | |-- chicken.bitwise.import.so305 | | |-- chicken.bytevector.import.so306 | | |-- chicken.compiler.user-pass.import.so307 | | |-- chicken.condition.import.so308 | | |-- chicken.continuation.import.so309 | | |-- chicken.csi.import.so310 | | |-- chicken.errno.import.so311 | | |-- chicken.eval.import.so312 | | |-- chicken.file.import.so313 | | |-- chicken.file.posix.import.so314 | | |-- chicken.fixnum.import.so315 | | |-- chicken.flonum.import.so316 | | |-- chicken.foreign.import.so317 | | |-- chicken.format.import.so318 | | |-- chicken.gc.import.so319 | | |-- chicken.internal.import.so320 | | |-- chicken.io.import.so321 | | |-- chicken.irregex.import.so322 | | |-- chicken.keyword.import.so323 | | |-- chicken.load.import.so324 | | |-- chicken.locative.import.so325 | | |-- chicken.memory.import.so326 | | |-- chicken.memory.representation.import.so327 | | |-- chicken.pathname.import.so328 | | |-- chicken.platform.import.so329 | | |-- chicken.plist.import.so330 | | |-- chicken.port.import.so331 | | |-- chicken.pretty-print.import.so332 | | |-- chicken.process.import.so333 | | |-- chicken.process.signal.import.so334 | | |-- chicken.process-context.import.so335 | | |-- chicken.process-context.posix.import.so336 | | |-- chicken.random.import.so337 | | |-- chicken.repl.import.so338 | | |-- chicken.sort.import.so339 | | |-- chicken.string.import.so340 | | |-- chicken.read-syntax.import.so341 | | |-- chicken.syntax.import.so342 | | |-- chicken.tcp.import.so343 | | |-- chicken.time.import.so344 | | |-- chicken.time.posix.import.so345 | | |-- chicken.version.import.so346 | | |-- scheme.file.import.so347 | | |-- scheme.process-context.import.so348 | | |-- scheme.time.import.so349 | | |-- scheme.write.import.so350 | | |-- modules.db351 | | |-- srfi-4.import.so352 | | `-- types.db353 | |-- libchicken-static.a354 | |-- libchicken.dll.a (Windows)355 | |-- libchicken.dylib (Macintosh)356 | |-- libchicken.so -> libchicken.so.12 (Unix)357 | `-- libchicken.so.12 (Unix)358 `-- share359 |-- chicken360 | |-- doc361 | | |-- LICENSE362 | | |-- README363 | | |-- DEPRECATED364 | | |-- chicken.png365 | | |-- manual-html366 | | `-- *.html367 | |-- chicken.rc.o (Windows)368 | `-- setup.defaults369 `-- man370 `-- man1371 |-- chicken-install.1372 |-- chicken-profile.1373 |-- chicken-status.1374 |-- chicken-uninstall.1375 |-- chicken.1376 |-- csc.1377 `-- csi.1378379380 3. Usage381382 Documentation can be found in the directory383 PREFIX/share/chicken/doc in HTML format. The manual is384 maintained in a wiki at http://wiki.call-cc.org. Go there to385 read the most up to date documentation.386387388 4. Extensions389390 A large number of extension libraries for CHICKEN are391 available at http://wiki.call-cc.org/eggs. You can392 automatically download, compile and install extensions with393 the "chicken-install" program. See the CHICKEN User's Manual394 for more information.395396 A selection of 3rd party libraries, together with source and397 binary packages for tools helpful for development with CHICKEN398 are also available at:399 <http://www.call-with-current-continuation.org/tarballs/>.400401402 5. Platform issues403404 Android:405406 - The Android SDK and NDK are required. Make sure you have407 set up a project and have a suitable NDK toolchain408 available. You will have to override the make(1) variable409 C_COMPILER to contain the correct compiler; see410 docs/STANDALONE-TOOLCHAIN.html in your NDK root for notes411 on how to call the correct compiler. You will also need to412 override the ARCH variable to match the device you're413 targeting. The build will produce a libchicken.so that414 can then be integrated into your project as a prebuilt415 shared library. See the android section on416 http://wiki.call-cc.org/embedding for a complete example.417418 - It is possible to use eggs, by copying them into the right419 place and probably renaming the files. This is somewhat420 awkward and requires various hacks to make the421 loading/linking of eggs work. It may be easier to build422 the eggs you need manually and linking them statically to423 your executable.424425 - By default debug-logging is enabled and written to the426 Android log.427428 FreeBSD/NetBSD/OpenBSD:429430 - *BSD system users *must* use GNU make ("gmake") - the makefiles431 can not be processed by BSD make.432433 - On NetBSD it might be possible that compilation fails with a434 "virtual memory exhausted error". Try the following:435436 % unlimit datasize437438 - When using -deploy on NetBSD, currently the kernel only439 supports running the program through its absolute path,440 otherwise you will get an error message stating:441442 execname not specified in AUX vector: No such file or directory443444 Deployed binaries can also be run without an explicit path,445 through $PATH; only relative pathnames do not work.446447 - Using external libraries on NetBSD may also be easier, if448 you add the following definitions to `Makefile.bsd':449450 C_COMPILER_OPTIONS += -I/usr/pkg/lib451 LINKER_OPTIONS += -L/usr/pkg/lib -Wl,-rpath=/usr/pkg/lib452453 Note that this may cause build-problems, if you already have454 an existing CHICKEN installation in the /usr/pkg prefix.455456 Linux:457458 - If you want to build Linux binaries which use the "X32 ABI",459 you can pass ARCH=x32 on the Make command line.460461 - There have been reports where the library directory462 "/usr/lib64" could not be found at build-time on a Fedora463 12 system. If you build a 64-bit version of CHICKEN and464 the library directory is set incorrectly, you can override465 it by passing "LIBDIR=/usr/lib64" as an additional466 argument when you invoke "make".467468 Solaris:469470 - By default, CHICKEN is build with the GNU C compiler (`gcc').471 To use the SunPro C compiler (`cc') instead, override the472 used compiler like this:473474 CC=cc ./configure ...475476 - Older versions of Solaris have a bug in ld.so that causes477 trouble with dynamic loading. Patching Solaris fixes the478 problem. Solaris 7 needs patch 106950-18. Solaris 8 has an479 equivalent patch, 109147-16.480481 You can find out if you have these patches installed by482 running:483484 % showrev -p | grep 106950 # solaris 7485 % showrev -p | grep 109147 # solaris 8486487 Mac OS X:488489 - The build currently assumes the C toolchain is in the path,490 use the "xcode-select(1)" tool to make them available on the491 command line if you haven't already done so.492493 - CHICKEN will normally select a 32-bit or 64-bit build494 automatically when you use the normal build step:495496 make497498 Specifically, the defaults are:499500 10.4: 32-bit501 10.5: 32-bit502 10.6: 64-bit (32-bit on original Core Duo, circa early 2006)503 10.7: 64-bit504505 On 10.5, you can optionally build in 64-bit mode on machines506 released in late 2006 or later (i.e. with a Core 2 Duo or Xeon507 CPU), by specifying ARCH=x86-64:508509 make ARCH=x86-64510511 - Universal binaries: On 10.4 and 10.5 only, CHICKEN and its eggs512 can be built as universal binaries which will work on either513 Intel or PowerPC. Most users will not want to do this.514515 For 10.4 universal build:516 make ARCH=universal517518 For 10.5 universal build:519 export MACOSX_DEPLOYMENT_TARGET=10.4520 make C_COMPILER=gcc-4.0 ARCH=universal521522 For 10.6 and later, universal builds are not supported.523524 - On 10.3 and earlier, you must first install `dlcompat'525 which can be found at http://distfiles.macports.org/dlcompat/.526527 iOS:528529 - Make sure the "XCODE_PATH" setting is correct (see530 Makefile.ios), it defaults to "/Applications/Xcode.app".531532 - The paths for the the various build tools changed between533 Xcode 4 and 5. The makefile used for iOS builds of CHICKEN534 assume Xcode 5 is used. If you are using Xcode 4, override535 the XCODE_TOOLPATH and C_COMPILER make-variables providing536 the correct paths, see Makefile.ios for suggestions.537538 - The iOS build is static (iOS doesn't support dynamic539 loading of executable code). Only the runtime library540 (libchicken.a) is of interest. To use it, integrate541 libchicken.a in your Xcode project and use a normal MacOS542 build to compile your Scheme sources into C files, adding543 them to you project.544545 - Core library units must by accessed via "(declare (uses546 ...))" and "(import ...)", "require", "require-library",547 "require-extension" and "use" will not work, due to the548 reasons mentioned above.549550 - As dynamic loading is not supported, eggs can not be used551 as usual, you will have to compile them manually and552 integrate what you need into your project.553554 - If you want to build for the iPhone Simulator, override555 the ARCH and XCODE_SDK variables accordingly, see also in556 Makefile.ios for suggestions.557558 Windows:559560 - On Windows, native builds using the "MingW" toolchain and561 Cygwin are supported (Microsoft Visual Studio is *NOT*).562 Makefiles for MingW are provided (`Makefile.MingW').563 GNU make and a POSIX sh(1) are required to build the system.564 Please also read the notes below.565566 - Since there are various distributions of the MingW toolchain567 we recommend to use "w64devkit" by Chrstopher Wellons:568569 https://github.com/skeeto/w64devkit570571 This toolset is very complete, includes GNU make and a572 POSIX shell and is the development environment we use to573 test CHICKEN. Other distributions of MingW may work but574 are not tested by us.575576 - When installing under the MingW platform, PREFIX must be an577 absolute path name (i.e. it must include the drive letter) and578 must use forward slashes (no backward slashes), for example579580 ./configure --prefix C:/chicken/581582 - Under MingW, the "csc" compiler driver and "chicken-install"583 expect the compiler executable and the usual UNIX tools are584 in the PATH, so make sure to run them inside a shell that585 provides the necessary stuff.586587 - Cygwin will not be able to find the chicken shared libraries588 until Windows is rebooted.589590 - During "make check" you may see these intermittent errors:591592 ld.exe: cannot open output file a.out: Permission denied593594 When this happens, the virusscanner is holding open595 the file of the previous test while the compiler is596 preparing the next test.597 To work around this in Windows Defender (the default),598 disable "realtime protection" under tools->options.599600 AIX:601602 - CHICKEN is built with the GNU C compiler (`gcc'). IBM's XL603 C compiler is not supported at this time.604605 - AIX users *must* use GNU make ("gmake") - the makefiles can not be606 processed with IBM's version of make.607608 - Deployment doesn't work. See manual/Deployment for more details.609610 - The AIX linker may occasionally show warnings of the form:611612 ld: 0711-783 WARNING: TOC overflow. TOC size: 66656613 Maximum size: 65536614 Extra instructions are being generated for each reference to a TOC615 symbol if the symbol is in the TOC overflow area.616617 Such messages indicate that lookups for some symbols in the618 effected library/executable may be somewhat slower at runtime as an619 auxiliary symbol table is needed to accommodate all of the symbols.620621 - The AIX assembler may show warnings of the form:622623 /tmp//ccycPGzK.s: line 527244: 1252-171 The displacement must be624 greater than or equal to -32768 and less than or equal to 32767.625626 This is a known issue between the GNU toolchain and IBM's assembler:627628 http://gcc.gnu.org/bugzilla/show_bug.cgi?id=4587629630 The problem arises because the PPC architecture cannot perform jumps631 to addresses that differ more than what a 16-bit integer can632 represent. Adding support for IBM's XL C compiler may resolve this633 issue.634635 Instructing gcc to optimize the size of generated code (-Os)636 mitigates this to some degree, but very large C files may still be637 uncompilable. This is known to affect the html-tags egg.638639 Haiku:640641 - The default GCC compiler is too old to support the -fwrapv642 option. You can either remove the flag from Makefile.haiku,643 use a newer GCC, or supply your own C_COMPILER_OPTIONS on644 the Make command line.645646 - The default Haiku BFS file system only supports timestamps647 with a granularity of one second. This may cause trouble648 with pregenerated release or development snapshot tarballs649 due to the way files are pre-translated to C. You'll either650 need to have CHICKEN installed, or touch the651 build-version.c file before building.652653654 6. Bootstrapping655656 To build a bootstrapping compiler yourself, get the most657 recent development snapshot tarball from658 http://code.call-cc.org, unpack it, build and install everything.659 Then change to the directory containing the git code and run:660661 ./configure --chicken <path-to-existing-chicken>662 make boot-chicken663664 This will produce a statically linked binary with the name665 "chicken-boot[.exe]" that can be given as the value of the666 "--chicken" configuration option. Note that the path to an667 existing `chicken' binary must be given to use it for668 compiling the Scheme code of the runtime-system and compiler.669670 "scripts/bootstrap.sh" automates this process; use this script671 if you are unsure how to build from the repository sources. It672 downloads the necessary development snapshot with wget(1) and673 builds the boot-chicken that you can use to compile the674 development sources. The invocation is:675676 ./scripts/bootstrap.sh ...677678 You can add additional parameters if you like to customize the679 build, but this should not be necessary. Note that your current680 working directory must be the root directory of the CHICKEN681 git(1) repository. Once the boot-chicken is built, proceed by682 invoking make(1) as described above (in 2.2, Building from Git),683 with the additional parameter:684685 make CHICKEN=./chicken-boot ...686687 or run "configure" again:688689 ./configure --chicken ./chicken-boot ...690 make691692693 7. Emacs support694695 See http://wiki.call-cc.org/emacs for tips and links to emacs696 extensions for Scheme and CHICKEN programming.697698699 8. What's next?700701 If you find any bugs, or want to report a problem, please send702 a detailed bug report.703704 If you have any more questions or problems (even the slightest705 problems, or the most stupid questions), then please subscribe706 to the "chicken-users"707 (http://lists.nongnu.org/mailman/listinfo/chicken-users)708 mailing list and ask for help. It will be answered.