The Standard Library Build Tool
Building complex libraries and executables by invoking
gxc quickly gets tedious. When you reach that point of complexity and you need a build tool, you can use the
:std/make library module which provides a modest build tool that can handle reasonably complex project building.
The project source code
For illustration purposes, we'll make a hello world library module and an executable that uses it.
$ cat gerbil.pkg (package: example) $ cat util.ss (export #t) (def (hello who) (displayln "hello, " who)) $ cat hello.ss (import :example/util) (export main) (def (main . args) (for-each hello args))
The standard build script template
The recommended way to write a build script is to use the template provided by the standard library.
You can do this by importing
:std/build-script and using the
The macro defines a main function suitable for building packages either directly or through gpxkg. The syntax is
(defbuild-script build-spec . settings)
Using this, the build script for our project is the following:
$ cat build.ss #!/usr/bin/env gxi (import :std/build-script) (defbuild-script '("util" (exe: "hello")) optimize: #t debug: 'src)
And we can build by invoking the script:
$ chmod +x build.ss $ ./build.ss
Intermediate build scripts
Here is a full fledged build script that can handle building our library and executable.
It also supports dependency tracking for compiling in the correct order and incremental compilation that only compiles when relevant source modules are newer than compiled artifacts.
It is roughly equivalent to the script generated by
defbuild-script, without actions specific to
$ cat build.ss #!/usr/bin/env gxi (import :std/make) ;; the build specification (def build-spec '("util" (exe: "hello"))) ;; the source directory anchor (def srcdir (path-normalize (path-directory (this-source-file)))) ;; the main function of the script (def (main . args) (match args ;; this is the default (and, here, only) action, which builds the project ( (make srcdir: srcdir ; source anchor bindir: srcdir ; where to place executables; default is GERBIL_PATH/bin optimize: #t ; enable optimizations debug: 'src ; enable debugger introspection static: #f ; don't generate static compilation artifacts prefix: "example" ; this matches your package prefix build-spec)))) ; the actual build specification
To build our project:
$ chmod +x build.ss $ ./build.ss
After the initial dependency graph generation, we can build during development by reusing the dependency graph and simply invoking ./build.ss. You only need to generate a new dependency graph if your import sets change.
Building static executables
Static executables are simple to build:
- the executables are specified with the static-exe: build spec in place of exe:.
- the make invocation needs static: #t to be specified so that static compilation artifacts are built for modules.
However, there is a nuance: you usually don't want to build static executables with debug introspection as this will blow the executable size significantly.
Perhaps the simplest way to deal with the bloat issue is to have a separate step building the executables, while still compiling library modules with debug introspection for working in the repl.
The following build script breaks the build action into two steps, one for building library modules and another for building the executables:
#!/usr/bin/env gxi (import :std/make) ;; the library module build specification (def lib-build-spec '("util")) (def bin-build-spec '((static-exe: "hello"))) ;; the source directory anchor (def srcdir (path-normalize (path-directory (this-source-file)))) ;; the main function of the script (def (main . args) (match args (["lib"] ;; this action builds the library modules -- with static compilation artifacts (make srcdir: srcdir bindir: srcdir optimize: #t debug: 'src ; enable debugger introspection for library modules static: #t ; generate static compilation artifacts; required! prefix: "example" ;; build-deps: "build-deps" ; this value is the default lib-build-spec)) (["bin"] ;; this action builds the static executables -- no debug introspection (make srcdir: srcdir bindir: srcdir optimize: #t debug: #f ; no debug bloat for executables static: #t ; generate static compilation artifacts; required! prefix: "example" build-deps: "build-deps-bin" ; importantly, pick a file that differs from above bin-build-spec)) ;; this is the default action, builds libraries and executables ( (main "lib") (main "bin"))))
Note that the
build-deps: file is a cache that stores your project dependencies.
In large project, an up-to-date cache can save many seconds in build times.
When multiple projects share a same directory, they must be made to use separate
build-deps: file, or the caches will clash and be ineffective.
All but one of the projects must explicitly specify the
to point to its own distinct file.