readme

Scheme跨平台编译器

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

  version 3.4.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 mailing list. You
        can subscribe to the list from the Chicken homepage,
        http://www.call-with-current-continuation.org)


 2. Installation:

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

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

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

	Invoke "make" like this:

	  make PLATFORM=<platform> PREFIX=<destination>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	SYMBOLGC=1
	  Always enable garbage collection for unused symbols in the 
	  symbol table by default. This will result in slightly slower 
	  garbage collection, but minimizes the amount of garbage 
	  retained at runtime (which might be important for long 
	  running server applications). If you don't specify this 
	  option you can still enable symbol GC at runtime by passing 
	  the `-:w' runtime option when running the program.

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

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

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

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

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

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

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

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


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

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

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

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

	    make PLATFORM=<platform> confclean

	to remove old configuration files.


 3. Usage:

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


 4. Extension:

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

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

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

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

	
 5. Platform issues:

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

	- Some old Linux distributions ship with a buggy version of
	  the GNU C compiler (2.96). If the system is configured for
	  kernel recompilation, then an alternative GCC version is
	  available under the name `kgcc' (GCC 2.96 can not recompile
	  the kernel). CHICKEN's configuration script should normally
	  be able to handle this problem, but you have to remember to
	  compile your translated Scheme files with `kgcc' instead of
	  `gcc'.

	- Older versions of Solaris have a bug in ld.so that causes
	  trouble with dynamic loading.	 Patching Solaris fixes the
	  problem. Solaris 7 needs patch 106950-18. Solaris 8 has an
	  equivalent patch, 109147-16.

	  You can find out if you have these patches installed by
	  running:

	  % showrev -p | grep 106950	# solaris 7
	  % showrev -p | grep 109147	# solaris 8

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

	  % unlimit datasize

	- For Mac OS X, Chicken requires libdl, for loading compiled
	  code dynamically. This library is available on Mac OS X 10.4
	  (Tiger) by default. For older versions you can find it here:

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

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

	    make PLATFORM=macosx ARCH=universal

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

	    export MACOSX_DEPLOYMENT_TARGET=10.4
	    make PLATFORM=macosx ARCH=universal

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

	    make PLATFORM=macosx ARCH=x86-64

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

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

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

	- gcc 3.4 shows sometimes warnings of the form

	    easyffi.c: In function `f_11735':
	    easyffi.c:18697: warning: `noreturn' function does return
	
	  when compiling the system or compiled Scheme files. These
	  warnings are bogus and can be ignored.

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

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

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

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

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

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

 6. Emacs support:

	An emacs mode is provided in the file `hen.el'. To use it,
	copy it somewhere into a location you normally use for emacs
	extensions. If you want to add a specific location permanently
	to the list of paths emacs should search for extensions, add
	the following line to your `.emacs' file:

	  (setq load-path 
	    (cons
	      "<directory-where-your-emacs-lisp-files-live>" 
	      load-path))

	Add 

 	  (require 'hen)
	
	To make "hen-mode" available, and enter it by issuing the
	command M-x hen-mode.

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

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

	Or:

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

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

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

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


 7. What's next?

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

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


	Have fun!