Skip to content

Latest commit

 

History

History
834 lines (706 loc) · 29.6 KB

INSTALL.adoc

File metadata and controls

834 lines (706 loc) · 29.6 KB

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 HACKING.adoc for the details.

Prerequisites

You need the standard build tools of the Unix environment, and GNU make.

Besides that, 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.

  • 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 doc/HOWTO-mingw.adoc for the details.

Quick Start

% ./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.

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

TLS/SSL support

Gauche relies on MbedTLS for secure connection support.

By default, configure checks if the MbedTLS library is installed on the system, and use it if it’s available. Otherwise, no TLS support is compiled. If you can’t install MbedTLS for some reason, or you want to bring the compiled binary to the target system that may not have MbedTLS library, you can specify to download MbedTLS source during build and compile it into Gauche binary.

--with-tls=none

do not include TLS/SSL support
--with-tls=mbedtls

include only mbedTLS support
--with-tls=mbedtls-internal

During the build, MbedTLS source is downloaded and compiled with Gauche. See below.

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

MbedTLS library can be compiled with or without multi-threading support. Gauche requires MbedTLS library to be compiled with multi-threading support. If the system’s library doesn’t have that support, use the option to build it into Gauche library.

If you use TLS, you need CA certificates bundle to validate server certificates. You may specify several options where to look for one.

--with-ca-bundle=check

Use heuristics to find CA bundle (default)
--with-ca-bundle=none

Do not set default CA bundle
--with-ca-bundle=system

Use system CA bundle. On MinGW, it accesses system CA store via Windows API. Otherwise, it checks several known paths used for popular systems.
--with-ca-bundle=<path>

Use given path as the CA bundle file

See the manual’s rfc.tls entry for the details.

Common command names

SRFI (Scheme Requrests for Implementation), where various aspects of Scheme spec are discussed, suggests some common names for Scheme-related commands if the implementation comforms certain specs. Those command names may be used by other implementation, so we don’t install them by default.

If you give --enable-shared-commands option, the following commands are installed:

scheme-r7rs, scheme-srfi-0, scheme-srfi-7

Aliases of gosh.

compile-r7rs

Alias of gauche-compile-r7rs.

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 and odbm but nothing else, specify --with-dbm=ndbm,odbm. If you want to include none of them, specify --with-dbm=no.

Character encoding conversion

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.

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

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

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-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:

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

Uninstallation

You can remove installed Gauche software by running

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):

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

    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:

    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:

    ./configure --disable-heuristic-optimization