3.9 Building standalone executables

When you want to distribute your Gauche scripts or applications, the users need to install Gauche runtime on their machine. Although it is always the case for any language implementations—you need Java runtime to run Java applications, or C runtime to run C applications—it may be an extra effort to ask users to install not-so-standard language runtimes.

To ease distribution of Gauche applications, you can create a stand-alone executable. It statically links entire Gauche system so that it runs by just copying the executable file.

Quick recipe

To generate a standalone executable, just give your script file to the tools/build-standalone script, which is installed as a part of Gauche.

gosh tools/build-standalone yourscript.scm

It will create an executable file yourscript (or yourscript.exe on Windows) in the current directory.

To specify the output name different from the script name, give -o option:

gosh tools/build-standalone -o yourcommand yourscript.scm

When your script needs supporting library files, you should list those files as well:

gosh tools/build-standalone yourscript.scm lib/library1.scm lib/library2.scm

The library file paths need to be relative to the respective load path. See the explanation of -I option below.

Catches

There are a few things you should be aware of.

• The size of the binary tend to be large, since it contains the entire Gauche system regardless of whether your application use it or not. You can strip down the size if you need to, but you need to rebuild Gauche library to do so. See doc/HOWTO-standalone.txt in the source tree for the details.
• The generated binary still depends on external dynamically linked libraries, such as libpthread. The exact dependency may differ how Gauche is configured, and can be checked by running system-provided tools, such as ldd on most Unix systems and MinGW or otool -L on OSX, on the generated standalone binaries. You may want to ensure the users have required libraries.
• Currently we don’t yet have a convenient way to statically link extension libraries. We’re working on it.
• If Gauche is configured to use gdbm, it is linked to the standalone binary by default, hence the binary itself is covered by GPL. In case if you need to distribute binaries under BSD license, you need to give -D GAUCHE_STATIC_EXCLUDE_GDBM flag to tools/build-standalone. It makes tools/build-standalone not to link gdbm (and your script won’t be able to use it).
• If you build Gauche with mbedTLS support (if you have libmbedtls on your machine, Gauche include its support by default), the resulting standalone binary also depends on libmbedtls DSO files. If you’re not sure mbedTLS DSO files are available on target machines, you can exclude rfc.tls.mbed module by giving -D GAUCHE_STATIC_EXCLUDE_MBED flag to tools/build-standalone.

Using build-standalone

Program: gosh tools/build-standalone [options] script-file [library-file …] ¶

Create a stand-alone binary to execute a Gauche program in script-file. It is executed as if it is run as gosh script-file, with a few differences.

The main thing is that since script-file is no longer loaded from file, code that references paths relative to script-file won’t work. One example is (add-load-path dir :relative) (see Loading Scheme file). Auxiliary library files required by script-file must be explicitly listed as library-file …, so that they are bundled together into the executable.

The following command-line options are recognized.

Command Option: -o outfile ¶

Specifies output executable filename. When omitted, the basename of script-file without extension is used. (Or, on Windows, swapping extension with .exe).

Command Option: -D var[=val] ¶

Add C preprocessor definitions while compiling the generated C code. An important use case of this option is to exclude gdbm dependency from the generated binaries, by specifying -D GAUCHE_STATIC_EXCLUDE_GDBM. Note that you need a whitespace between -D and var.

This option can be specified multiple times.

Command Option: -I load-path ¶

Specifies the load path where library-file … are searched. The names given to library-file must match how they are loaded or used. If such paths are not relative to the directory you run tools/build-standalone, you have to tell where to find those libraries with this option.

For example, suppose you have this structure:

project/src/
    +----- main.scm
    |          (use myscript.util)
    +----- myscript/util.scm
               (define-module myscript.util ...)

If you run tools/build-standalone in the directory as src, you can just say this:

gosh tools/build-standalone main.scm myscript/util.scm

But if you run it under project, you need to say this:

gosh tools/build-standalone -I src src/main.scm myscript/util.scm

Another example; you have a separate library directory:

project/
    +----- src/main.scm
    |          (use myscript.util)
    +----- lib/myscript/util.scm
               (define-module myscript.util ...)

If you run tools/build-standalone in src, you say this:

gosh tools/build-standalone -I ../lib main.scm myscript/util.scm

Or, if you run it in project, you say this:

gosh tools/build-standalone -I lib src/main.scm myscript/util.scm

This option can be specified multiple times.

Command Option: --header-dir dir ¶

Command Option: --library-dir dir ¶

These tells tools/build-standalone where to find Gauche C headers and static libraries.

If you’ve installed Gauche on your system, tools/build-standalone automatically finds these from the installed directory and you don’t need to worry about them. Use these option only when you need to use Gauche runtime that’s not installed.