                      Compiling and Installing Gauche

$Id: INSTALL.in,v 1.3 2007-03-16 09:21:28 shirok Exp $
Note: The Gauche system is a work in progress and frequently updated.
Check out the latest information on the site:
  http://practical-scheme.net/gauche/


Quick Start
---------------------------------------------------


   % ./configure [--enable-threads=pthreads]
   % make
   % make test
   % make install

Things will be installed under /usr/local/bin, /usr/local/lib/gauche,
and /usr/local/share/gauche.
If you want to use multithread support, pass --enable-threads=pthreads
option to configure.  It is supported on several platforms.

If you have installed Gauche 0.5 or later, and want to install
new version of Gauche with the same configuration option,
you can use the following command instead of 'configure'.
    % gauche-config --reconfigure | sh
When the option '--reconfigure' is given, Gauche-config prints out
the command line when it is configured.   Pass the output to
shell and you can reconfigure with the same options.


Choosing Character Encoding
---------------------------------------------------


By default, Gauche is compiled with utf-8 as a native character encoding.
You can give a --enable-multibyte=ENCODING option to switch the native
encoding.   Note that if you want to use ISO8859-1 GR characters in
the program text, you have to specify no multibyte encoding, or
Gauche takes such characters as the first byte of multibyte charaters.

  ./configure --enable-multibyte=utf-8   ;; UTF-8 (default)
  ./configure --enable-multibyte=euc-jp  ;; EUC-JP
  ./configure --enable-multibyte=sjis    ;; Shift JIS
  ./configure --enable-multibyte=no      ;; No multibyte string


Gauche can recognize and converts typical japanese character
encodings, but delegates other conversion work to iconv library
(when available).   If your system does not have iconv installed,
you can specify the location of your external
iconv library by --with-iconv option.

  ./configure --with-iconv=DIR


For example, if your say --with-iconv=/usr/local, Gauche looks
for the header iconv.h from /usr/local/include and the library
libiconv from /usr/local/lib.
In case if your iconv library is named other than libiconv, say,
libmyconv, you can also specify --with-iconv-lib=myconv to tell
Gauche to link against the library.

You can obtain Bruno Haible's libiconv library from here:
http://www.gnu.org/software/libiconv/


Local library paths
---------------------------------------------------


If you want to use some libraries installed in non-standard location
to build Gauche, you can use the following option to specify the
locations.

  --with-local=PATH:PATH2:...

This addts PATH/include, PATH2/include, ... to the include paths,
and PATH/lib, PATH2/lib, ... to the library search paths.

For example, if you want to use gdbm library in /usr/local,
you can say:

  --with-local=/usr/local


IPv6 support
---------------------------------------------------


Gauche has experimental support for IPv6.
It is turned off by default,
but you can include it by giving the following configure option.

  --enable-ipv6

Of course your OS has to have the support of IPv6.
The current implementation is tested on FreeBSD.
See the gauche.net section of the reference manual for details.


Selecting SLIB location
---------------------------------------------------


SLIB is a portable Scheme library containing various useful functions,
entirely written in Scheme.  Gauche can use SLIB features if you have
it on your system.

The configure script tries to find where SLIB is installed.  It looks
for some typical directories like /usr/local/slib or /usr/share/slib.
If you installed your SLIB in some non-standard location, you can tell
it to the configure script as follows:

   ./configure --with-slib=PATH

where PATH is the path you installed your SLIB.

Gauche works without SLIB, anyway.  If you're not interested, you
don't need to care about this.

SLIB needs a catalog file to be created in the Gauche library
directory before use.  If Gauche finds SLIB during installation,
the install procedure creates the catalog file.
If you install slib after installing Gauche, it tries to create
the catalog file when you use slib first time, and you may get
an error if you don't have a permission to write into the
Gauche library directory.   Run gosh in the right permission
and evaluate something like the following will solve the problem.

  (use slib)
  (require 'logical)


Run-time library path
---------------------------------------------------


In some cases, your have to run Gauche under the environment
you don't have much control.  One of such cases is when you
want to run CGI script on the ISP's machine.  It may become
a problem that your build of Gauche depends on some dynamically
loaded libraries that are installed in non-standard location.

For example, suppose you install a new libiconv.so in /home/yours/lib
on the ISP's server and compile Gauche with --with-iconv=/home/yours/lib.
You have set up correct environment variables such as LD_LIBRARY_PATH,
so you can invoke Gauche interpreter gosh without a problem.  Now,
you write a CGI script.   Unfortunately, the ISP's web server
doesn't set LD_LIBRARY_PATH as you desired, and your script never
runs on the server, for the interpreter can't find libiconv.so
in the system default path.

Some compilers have an option that writes exact path of shared
libraries that the binary depends on.  A configure option --with-rpath
utilizes the feature.  When an option --with-rpath=DIR is given,
configure sets up a build process so that the shared libraries
are looked from DIR.   This works only on gcc, however.


Customizing install location
---------------------------------------------------


Call configure with those parameters to specify where to install.

   % ./configure --prefix=$PREFIX  --exec-prefix=$EXEC_PREFIX


If --prefix option is omitted, /usr/local is assumed as PREFIX.
If --exec-prefix option is omitted, EXEC_PREFIX is set the same as PREFIX.


The files are installed in those locations:

  $EXEC_PREFIX/bin/*
     The interpreter (gosh) and configuration script (gauche-config).

  $EXEC_PREFIX/lib/*
     Library (libgauche.a).

  $PREFIX/share/gauche/VERSION/include/*
     Header files required to create applications using libgauche.

  $PREFIX/share/gauche/VERSION/lib/*
     Machine-independent Scheme files.

  $PREFIX/share/info/*
     info files.

  $EXEC_PREFIX/lib/gauche/VERSION/ARCHITECTURE/*
     Machine-dependent files (.so files, gosh, gauche-config, and libgauche.a)

  $PREFIX/share/gauche/site/lib/*
  $EXEC_PREFIX/lib/gauche/site/VERSION/ARCHITECTURE/*
     These are default locations where user installed machine-indenpedent/
     dependent files will go.


Optimization options
---------------------------------------------------


You can pass extra options at make time, using make macro OPTFLAGS.
'Configure' sets a default, but if you want to explore different
options, just run 'make' as follows:

  make OPTFLAGS="--some-compiler-option --other-option"


Uninstallation
---------------------------------------------------


You can remove installed Gauche software by running

  make uninstall

on top of the source tree.


Machine-dependent information
---------------------------------------------------


* MacOS X - For 10.2.x and earlier, you need to install the dlcompat
       library (libdl) from Fink project (http://fink.sourceforge.net)
       before configuring Gauche.   You don't need it if you have OSX
       10.3 or later.   If the dlcompat library is installed in non-standard
       location, you have to tell configure the place by --with-local.
       Besides, GC now requires pthreads on MacOS X, so you need
       --enable-threads=pthreads.

       For example, if you have dlfcn.h in $HOME/include and libdl.a
       in $HOME/lib, you should do:

         ./configure --with-local=$HOME --enable-threads=pthreads

* IRIX with 64bit binary - If you want to compile for 64bit ABI instead
       of the default 32bit ABI, run configure like this:

         CC="cc -64" AS="as -64" ./configure

* Linux/Crusoe TM5800 - It is reported that recent Linux kernel thinks
       TM5800 as i686-compatible, and compilation of Gauche fails at
       gc where the i686's prefetch instruction is used.   A quick fix
       is to edit gc/Makefile AFTER configure, to remove the following
       flag:

         -DUSE_I686_PREFETCH

       Then make it.

