The Gerbil Universal Binary and Tools
If you look at the Gerbil installation bin directory, you will see someghing like the following:
$ ll -h /usr/local/gerbil/bin/
total 11M
-rwxrwxr-x 1 vyzo vyzo 19K Sep 24 10:20 gambuild-C
-rwxrwxr-x 1 vyzo vyzo 11M Sep 24 10:23 gerbil
-rwxrwxr-x 1 vyzo vyzo 151K Sep 24 10:20 gsc
lrwxrwxrwx 1 vyzo vyzo 6 Sep 24 10:23 gxc -> gerbil
lrwxrwxrwx 1 vyzo vyzo 6 Sep 24 14:43 gxensemble -> gerbil
lrwxrwxrwx 1 vyzo vyzo 6 Sep 24 10:23 gxi -> gerbil
lrwxrwxrwx 1 vyzo vyzo 6 Sep 24 14:43 gxpkg -> gerbil
lrwxrwxrwx 1 vyzo vyzo 6 Sep 24 14:43 gxprof -> gerbil
lrwxrwxrwx 1 vyzo vyzo 6 Sep 24 14:43 gxtags -> gerbil
lrwxrwxrwx 1 vyzo vyzo 6 Sep 24 14:43 gxtest -> gerbil
As you notice all the programs distributed with Gerbil link to a
single universal binary, gerbil. We call this program
affectionately Bach after the great composer of timeless music.
The gerbil binary includes all modules from the core system compiled
in and has specialized main functions for the interpreter and
compiler.
It also fronts for all tooling, which is implemented with dynamic
loading of dynamically compiled executable modules depending on the
linked executable name. Some of the tooling functionality is actually
explicitly lifted at top level: things like the build tool and
dependency management commands of the gxpkg tool.
Here we give an overview of all commands and tools supported by Bach.
Using Bach
The Gerbil universal binary has the following usage:
$ gerbil help
Usage: gerbil [option ...] arguments ...
Options:
-h|--help display this help message exit
-v|--version display the system version and exit
Arguments:
<cmd> cmd-arg ... execute a builtin tool command
arg ... drop to the gerbil interpreter
Commands:
new create a new project template (gxpkg new)
build build a gerbil package (gxpkg build)
deps manage dependencies for a package (gxpkg deps)
clean clean build artifactacts for a package (gxpkg clean)
env eval a shell expression in the local package environment (gxpkg env)
pkg invoke the gerbil package manager (gxpkg)
test run tests (gxtest)
tags create emacs tags (gxtags)
prof profile a dynamic executable module (gxprof)
ensemble invoke the gerbil actor ensemble manager (gxensemble)
interactive invoke the gerbil interpreter (gxi)
compile invoke the gerbil compiler (gxc)
help <cmd> display help for a tool command
Try gerbil help <cmd> for help on tool command usage
gxi
The Gerbil interpreter is gxi, but can also be invoked with gerbil interactve.
It has the following usage:
$ gxi -h
Usage: gxi [options ...] arguments ...
Options:
-h|--help|help display this help message exit
-v||--version|version display the system version and exit
-l|--lang module set the current interpretation language; must precede any evaluation
-e|--eval <expr> evaluate an expression
Arguments:
- enter the repl
:module import library module; if it exports a main function, apply it with the remaining arguments
file load file; if it defines a main function, apply it with the remaining arguments
When no arguments or options other than --lang are supplied, enters the interactive repl
gxc
The Gerbil compiler is gxc, but can also be invoked with gerbil compile.
It has the following usage:
$ gxc -h
gxc [options...] <file> ...
Options:
-h,--help display this help message and exit
-d <dir> set compiler output directory; defaults to $GERBIL_PATH/lib
-exe compile an executable
-o <file> set executable output file
-O optimize gerbil source
-full-program-optimization perform full program optimization
-static link the executable's external library dependencies statically
-s keep intermediate .scm files
-S don't invoke gsc
-v be verbose during compilation
-g compile with debug symbols; c code is compiled with -g
-no-ssxi don't generate .ssxi modules for cross-module optimization
-include-gambit-sharp include _gambit# with necessary cond expand features
-prelude <sexpr> add [-prelude <sexpr>] to gsc options
-cc-options <string> add [-cc-options <string>] to gsc options
-ld-options <string> add [-ld-options <string>] to gsc options
-gsc-flag <opt> add [<opt>] to gsc options
-gsc-option <opt> <string> add [<opt> <string>] to gsc options
gerbil new
$ gerbil help new
Usage: gxpkg new [command-option ...]
create a new package template in the current directory
Command Options:
-p --package <package> the package prefix for your project; defaults to the current username [default: vyzo]
-n --name <name> the package name; defaults to the current directory name [default: gerbil]
-l --link <link> link this package with a public package name; for example: github.com/your-user/your-package [default: #f]
gerbil build
$ gerbil help build
Usage: gxpkg build [command-option ...] <pkg> ...
rebuild one or more packages and their dependents
Command Options:
-l --local do the action in the local package context, unless GERBIL_PATH is set
-R --release build released (static) executables
-O --optimized build full program optimized executables
Arguments:
pkg package to build; all for all packages, omit to build in current directory
gerbil clean
$ gerbil help clean
Usage: gxpkg clean [command-option ...] <pkg> ...
clean compilation artefacts from one or more packages
Command Options:
-l --local do the action in the local package context, unless GERBIL_PATH is set
Arguments:
pkg package to clean; all for all packages, omit to clean in current directory
gerbil env
$ gerbil help env
Usage: gxpkg env <command> <command-args> ...
execute a command within the local package context
Arguments:
command the command to execute
command-args the command arguments
gerbil pkg
$ gerbil help pkg
gxpkg: The Gerbil Package Manager
Usage: gxpkg <command> command-arg ...
Commands:
new create a new package template in the current directory
build rebuild one or more packages and their dependents
clean clean compilation artefacts from one or more packages
deps manage dependencies for the current project
link link a local development package
unlink unlink one or more local development packages
install install one or more packages
uninstall uninstall one or more packages
update update one or more packages
list list installed packages
retag retag installed packages
search search the package directory
dir manage the directory list
env execute a command within the local package context
help display help; help <command> for command help
gerbil test
$ gerbil help test
gxtest: run Gerbil tests in the command line
Usage: gxtest [option ...] <args> ...
Options:
-v run in verbose mode where all test execution progress is displayed in stdout.
-r --run <run> only run test suites whose name matches a given regex [default: #f]
-D <features> define one or more conditional expansion feature (comma separated) for enabling tests that require external services [default: #f]
-h --help display help
Arguments:
args test files or directories to execute tests in; appending /... to a directory will recursively execute or tests in it. If no arguments are passed, all tests in the current directory are executed.
gerbil tags
$ gerbil help tags
gxtags: generate emacs tags for Gerbil code
Usage: gxtags [option ...] <input> ...
Options:
-a append to existing tag file
-o <output> explicit name of file for tag table [default: TAGS]
-h --help display help
Arguments:
input source file or directory
gerbil prof
$ gerbil help prof
gxprof: The Gerbil profiler
Usage: gxprof [option ...] [<module>] <module-args> ...
Options:
-o --output <output> gxprof output file [default: gxprof.out]
--heartbeat <heartbeat> heartbeat interval for sampling, in seconds [default: .001]
-k --ignore-kernel-frames ignore kernel functions in the analysis
-h --help display help
Arguments:
module dynamic executable module to run; analyze an existing output file if omitted [default: #f]
module-args arguments to pass to the executable module's main
gerbil ensemble
$ gerbil help ensemble
gxensemble: the Gerbil Actor Ensemble Manager
Usage: gxensemble <command> command-arg ...
Commands:
run run a server in the ensemble
registry runs the ensemble registry
load loads code in a running server
eval evals code in a running server
repl provides a repl for a running server
ping pings a server or actor in the server
lookup looks up a server by id or role
list list server state
shutdown shuts down an actor, server, or the entire ensemble including the registry
admin ensemble administrative operations
ca ensemble CA operations
package package ensemble state to ship an actor server environment
help display help; help <command> for command help