= What's in here? This directory contains sources of `spigot` extension module, as an example of Gauche extension. This extension isn't built by default. You can build it _after installing Gauche_. See below. The sources include: [horizontal] `package.scm`:: package metainformation `configure`:: configure script `Makefile.in`:: template makefile `spigot.h`:: common declaration within the spigot module `spigot.c`:: main logic `spigotlib.scm`:: Scheme binding of the module `math/spigot.scm`:: Scheme module definition `test.scm`:: unit test This is a typical construction of a simple extension. Note that you can generate the skeletons of these files automatically, by `gauche-package` script: [source,console] ---- % gauche-package generate spigot ---- It is a good way to start writing a fresh extension; but now we already have the sources, so let's move on. To build the extension, you have to generate `Makefile` by running the configure script. [source,console] ---- % ./configure ---- The configure script automatically finds installed Gauche, and picks the right options to compile and link. Now, `make` builds the extension, `make check` runs the test, and `make install` installs the extension in the Gauche's standard location. [source,console] ---- % make % make check % make install ---- == What's going on? Let's see each step in details. === Configure The `configure` script is like GNU autotool's `configure`, but written in Gauche. It generates `Makefile` from `Makefile.in`, tailored for the compiling platform. The default `configure` file is very simple, for most information can be taken from `package.scm` and installed Gauche. You can add your own customization much like aototool's `configure.ac`. Check the Gauche reference manual for the details. Running `configure` also creates `spigot.gpd`, where `gpd` stands for Gauche Package Description. It includes metainformation from `package.scm` and the build information. The file will be installed into the Gauche library directory (`.packages` subdirectory under `(gauche-site-library-directory)`) and `gauche-package` command refers to it. === Build By default, `make` invokes just a single command, `gauche-package compile`. It takes source files and builds a dynamically-loadable file (`+*.so+` on Unix platforms, `+*.dll+` on Windows), taking care of necessary include files and libraries related to Gauche. The basic usage is as follows: ``` gauche-package compile [-v] module-name source ... ``` The _-v_ option is to display actual compiler/linker command line. It's optional, but helps to see what's going on under the hood. Each _source_ file may be a C source, a Scheme source, or an object file. If it is a C file, it is compiled with the C compile that has built Gauche itself, with the necessary options. If it is a Scheme file, it is precompiled (see link:../../doc/HOWTO-precompile.adoc[Precompile Scheme code]). Then, all the object files will be linked into a single DSO file, e.g. `module-name.so`. The Scheme source is first converted to an intermediate C source (in the example, `spigotlib.c` is generated from `spigotlib.scm`), then compiled to an object file. When your extension module has multiple Scheme files, you don't need to list all Scheme filles here. Only the ones that contain _C stub definitions_, which bridge Scheme and C world, need to be precompiled. Pure-Scheme files can just be installed as is. (The command can also take `*.stub` files, which is an old way to define C-Scheme bridge. Its use is deprecated.) === Test `Make check` simply rungs `gosh` on the test script `test.scm`. The test script loads the extension with `(use math.spigot)`, and perform typical tests. === Install The template makefile uses `gauche-install` command, which has some advantages over typical `install` script. === Cleanup Makefile uses `gauche-package compile` command again, but with `--clean` option this time. Since `gauche-package compile` knows which files it generates, it's easy for it to remove those generated files. If you add other build steps that procedures extra files, you need to edit `Makefile.in` to add cleanup command for those files.