For Gauche 0.9.9

Previous: , Up: Programming in Gauche   [Contents][Index]

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 build-standalone script, which is installed as a part of Gauche.

gosh 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 build-standalone -o yourcommand yourscript.scm

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

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


There are a few things you should be aware of.

Using build-standalone

Program: gosh 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 build-standalone, you have to tell where to find those libraries with this option.

For example, suppose you have this structure:

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

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

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

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

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

Another example; you have a separate library directory:

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

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

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

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

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

This option can be specified multiple times. Note that a whitespace is required between -I and load-path.

Command Option: --header-dir dir
Command Option: --library-dir dir

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

If you’ve installed Gauche on your system, 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.
