// -*- coding: utf-8 -*-
:source-highlighter: pygments


= Compiling and Installing Gauche

NOTE: The Gauche system is a work in progress and frequently updated.
Check out the latest information on the site:
https://practical-scheme.net/gauche/

This document explains how to compile and install Gauche from a distributed
tarball.   To compile from cloned source tree from the repository,
you need some extra steps; See the file link:HACKING.adoc[] for the details.


== Prerequisites


Other than standard build tools on Unix environment, the following
tools and libraries are recommended to have.  You can build Gauche without
them, but some features won't be available.

- Makeinfo (version 5.0 or later) - used to build info document.
If the build platform doesn't have it, document building is skipped and info
document won't be installed.  (You need info document to use online document
browsing from REPL.)
- Gzip - also used during document building.
- Libiconv - Used for character encoding conversion.  See below.
- link:https://tls.mbed.org/[Mbed TLS] - Used for TLS/SSL connection.  See below.

There are other optional libraries, which will be explained below.

To build on Windows, you can use MSYS/MinGW.
See link:doc/HOWTO-mingw.adoc[] for the details.


== Quick Start

[source,console]
----
% ./configure
% make
% make check
% make install
----

Things will be installed under `/usr/local/bin`, `/usr/local/lib/gauche`,
and `/usr/local/share/gauche`.

If you have installed Gauche before, and want to install
new version of Gauche with the same configuration option,
you can use the following command instead of `configure`.

[source,console]
----
% 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.  It is a
convenient way to update Gauche.



== Thread Support

On most popular platforms, Gauche supports native threads.
The configure script tries to determine automatically whether thread
support can be enabled or not.  It shows at the end of the output
whether the support is enabled.

If you want to turn off the thread support even when the platform
allows it for some reason, or if the configure script misrecognizes the
platform and does not enable the support when it should be, you can use
the following configure options to turn off or turn on the support
explicitly.

[horizontal]
`--enable-threads=none`     :: turn off the thread support
`--enable-threads=pthreads` :: turn on the thread support (pthread)
`--enable-threads=win32`    :: turn on the thread support (windows)


== 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.

[horizontal]
`--enable-multibyte=utf-8`   :: UTF-8 (default)
`--enable-multibyte=euc-jp`  :: EUC-JP
`--enable-multibyte=sjis`    :: Shift JIS
`--enable-multibyte=no`      :: No multibyte string


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

[source,sh]
----
--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:
https://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.

[source,sh]
----
--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:

[source,sh]
----
--with-local=/usr/local
----


== IPv6 support

Gauche includes IPv6 support if the platform has it.  If you
don't want to include IPv6 support, give `--enable-ipv6=no` option.


== TLS/SSL support

Gauche includes secure socket connection support.  One uses
bundled link:http://axtls.sourceforge.net/[axTLS] library,
which is included automatically, and another
uses external link:https://tls.mbed.org/[mbedTLS] library,
which is compiled when we detect it
during configuration.  If you have a problem building those libraries,
you can selectively turn off each of them.

[horizontal]
`--with-tls=none`          :: do not include TLS/SSL support
`--with-tls=axtls`         :: include only axTLS support
`--with-tls=axtls,mbedtls` :: (default) include TLS/SSL support using
                            axTLS library (source is included in Gauche),
                            and mbedTLS library (installed on the system).
`--with-tls=axtls,mbedtls--internal` :: During the build, MbedTLS source is downloaded
                                and compiled with Gauche.  See below.

We recommend using Mbed TLS, for AxTLS has less support on ciphers
sometimes it fails to connect to a peer with a valid certificate.
See the manual entry of rfc.tls for the details.

If you give `mbedtls-internal` in place of `mbedtls`, the build process downloads
MbedTLS source and compile it into Gauche's extension library.  The resulting
binary doesn't depend on system's MbedTLS dynamic library, so you can move it
to the systems that don't have MbedTLS.   You need CMake to use this option.

Note that if you use `mbedtls-internal`, MbedTLS code is included in
`rfc--tls--mbed.so` and `libgauche-static-*.a`, so they are subject to the
MbedTLS license as well (Apache License 2.0).


== DBM database support

By default, Gauche looks for gdbm, ndbm and odbm (original dbm) libraries
on your system, and build support for available libraries.

If you want to exclude any of these support, list the libraries you
want to *inlucde* in `--with-dbm' configure option.  For example,
if you want to include ndbm but nothing else, specify `--with-dbm=ndbm'.
If you want to include none of them, specify `--with-dbm=no'.

== Selecting SLIB location

link:http://people.csail.mit.edu/jaffer/SLIB[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:

[source,sh]
----
./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.

[source,scheme]
----
(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.

[source,console]
----
% ./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-independent/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:

[source,sh]
----
make OPTFLAGS="--some-compiler-option --other-option"
----


== Uninstallation

You can remove installed Gauche software by running

[source,sh]
----
make uninstall
----

on top of the source tree.


== Cross compilation

Gauche supports autotools-standard cross compilation, that is,
you give `--build` and `--host` option to `configure` script and
just make (assuming you have appropriate cross development tools).
There are a couple of caveats, though.

- You have to have the same version of Gauche that you're trying to
  cross-compile on the build machine.
+
In normal build, Gauche uses freshly built `gosh` to compile
extension libraries (under `ext/`).  While cross compiling we can't run
freshly built `gosh` on the build machine, so we rely on the `gosh` already
installed on it.

- You may need `--with-libatomic-ops=no` option for `./configure`
+
The option forces Gauche to use bundled `libatomic_ops` source instead
of system provided one.  We noticed that `./configure` may misunderstood
the build system's `libatmic_ops` as the host system's.

For example, the following command line is to cross build on your machine
for Windows (mingw-w64 32bit):

[source,sh]
----
./configure --build=`./config.guess` \
            --host=i686-w64-mingw32 \
            --with-libatomic-ops=no \
            --prefix=/usr/local
----

== Machine-dependent information


* MacOS X - 10.15 (Catalina) enhanced the security check, and doesn't allow
  to execute shell scripts extracted from an unsigned downloaded tarball.
  Run the following command after extractng tarball
  (Replace VERSION for Gauche's version).
  You can check if the tarball isn't tampered using asc signature file
  distributed from https://practical-scheme.net/vault/.
+
[source,sh]
----
xattr -r -d com.apple.quarantine Gauche-VERSION/
----

* IRIX with 64bit binary - If you want to compile for 64bit ABI instead
  of the default 32bit ABI, run configure like this:
+
[source,sh]
----
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.
  If you want to disable this machine-dependent heuristic optimization,
  run configure like this:
+
[source,sh]
----
./configure --disable-heuristic-optimization
----
