This document explains how to build a statically-linked
gauche binary, that can run stand-alone (that is, you don't need to
install Gauche runtime separately---everything is in one executable).

This is still an experimental feature.  The building process isn't
streamlined: You may need manual tweak depending on your configuration.
Also there's no easy way yet to statically link external Gauche
extensions such as Gauche-gl.  We'll gradually address these issues.


[1. Build a static library]

Static library isn't built by default.
After building Gauche in usual way (e.g. configure + make),
go to $(TOP_SRCDIR) and run 'make static'.  It creates
libgauche-static-X.Y.a  where X.Y is the ABI version.

IMPORTANT: The static library includes all objects under ext/.
If you enable dbm.gdbm module, there'll be object files that
depends on gdbm, which will be covered by GPL.  On some systems
(e.g. Linux), ndbm and odbm interface are also provided by gdbm
package and falls under the same license.

If you need the final binary GPL-free for some reason,
run 'make static' with setting environment variable
LIBGAUCHE_STATIC_EXCLUDES.  For example:

  LIBGAUCHE_STATIC_EXCLUDES=dbm.gdbm,dbm.ndbm,dbm.odbm make static

This still includes gdbm-related object files, but there's
no dependency from the core features, so if you create final
binary they'll be excluded.


[2. Bundle your script source]

Copy the created libgauche-static-X.Y.a to your source directory,
and run build-standalone subcommand:

  gosh build-standalone -o command yourscript.scm 

This looks header files (gauche.h etc.) and the static library
file (libgauche-static-X.Y.a) from the installed Gauche's paths.
If those are not in the installation location (especially
libgauche-static-X.Y.a, which isn't installed by default),
you need to tell the commane where to look for.

  gosh build-standalone -I/path/to/headers -L/path/to/library \
         -o command yourscript.scm

The resulting binary doesn't depend on neither Gauche DSOs nor
installed Gauche libraries.  You can copy just the binary onto
the target platform.

Note: It still depends on the system libraries (e.g. -lpthread)
and they are needed on the target platform.

Since the result binary includes entire Gauche bundled libraries,
it tends to be large (around 12MB on Linux/x86_64).

The examples/standalone directory contains a sample script.
After building the static library, run make there and you'll
get sample-repl.


[3. Using Gauche API from statically linked C applications]

If you want to call Gauche API from statically linked C app,
you need slightly different initialization than the usual.
Instead of calling GC_INIT() and Scm_Init(), you should do
the following:

  (1) include gauche/static.h along gauche.h

    #include <gauche.h>
    #include <gauche/static.h>

  (2) call SCM_INIT_STATIC() from main(), instead of GC_INIT()
      and Scm_INIT().

    int main() {
      :
      SCM_INIT_STATIC();
      :
    }




