Debian Codegraph @

examples/spigot/README.adoc

raw
1 = What's in here?
2
3 This directory contains sources of `spigot` extension module,
4 as an example of Gauche extension.
5
6 This extension isn't built by default. You can build it
7 _after installing Gauche_. See below.
8
9 The sources include:
10
11 [horizontal]
12 `package.scm`:: package metainformation
13 `configure`:: configure script
14 `Makefile.in`:: template makefile
15 `spigot.h`:: common declaration within the spigot module
16 `spigot.c`:: main logic
17 `spigotlib.scm`:: Scheme binding of the module
18 `math/spigot.scm`:: Scheme module definition
19 `test.scm`:: unit test
20
21 This is a typical construction of a simple extension. Note that
22 you can generate the skeletons of these files automatically,
23 by `gauche-package` script:
24
25 [source,console]
26 ----
27 % gauche-package generate spigot
28 ----
29
30 It is a good way to start writing a fresh extension; but now
31 we already have the sources, so let's move on.
32
33 To build the extension, you have to generate `Makefile` by
34 running the configure script.
35
36 [source,console]
37 ----
38 % ./configure
39 ----
40
41 The configure script automatically finds installed Gauche,
42 and picks the right options to compile and link.
43 Now, `make` builds the extension, `make check` runs
44 the test, and `make install` installs the extension
45 in the Gauche's standard location.
46
47 [source,console]
48 ----
49 % make
50 % make check
51 % make install
52 ----
53
54
55 == What's going on?
56
57 Let's see each step in details.
58
59 === Configure
60
61 The `configure` script is like GNU autotool's `configure`,
62 but written in Gauche. It generates `Makefile` from
63 `Makefile.in`, tailored for the compiling platform.
64
65 The default `configure` file is very simple, for most
66 information can be taken from `package.scm` and
67 installed Gauche. You can add your own customization
68 much like aototool's `configure.ac`. Check the
69 Gauche reference manual for the details.
70
71 Running `configure` also creates `spigot.gpd`, where `gpd` stands
72 for Gauche Package Description. It includes metainformation from
73 `package.scm` and the build information. The file will be
74 installed into the Gauche library directory
75 (`.packages` subdirectory under `(gauche-site-library-directory)`)
76 and `gauche-package` command refers to it.
77
78 === Build
79
80 By default, `make` invokes just a single command, `gauche-package compile`.
81 It takes source files and builds a dynamically-loadable file
82 (`+*.so+` on Unix platforms, `+*.dll+` on Windows), taking care of
83 necessary include files and libraries related to Gauche.
84
85 The basic usage is as follows:
86
87 ```
88 gauche-package compile [-v] module-name source ...
89 ```
90
91 The _-v_ option is to display actual compiler/linker command line.
92 It's optional, but helps to see what's going on under the hood.
93
94 Each _source_ file may be a C source, a Scheme source, or an object
95 file. If it is a C file, it is compiled with the C compile
96 that has built Gauche itself, with the necessary options.
97 If it is a Scheme file, it is precompiled
98 (see link:../../doc/HOWTO-precompile.adoc[Precompile Scheme code]).
99 Then, all the object files will be linked into
100 a single DSO file, e.g. `module-name.so`.
101
102 The Scheme source is first converted to an intermediate C source
103 (in the example, `spigotlib.c` is generated from `spigotlib.scm`),
104 then compiled to an object file.
105
106 When your extension module has multiple Scheme files, you don't
107 need to list all Scheme filles here. Only the ones that contain
108 _C stub definitions_, which bridge Scheme and C world, need
109 to be precompiled. Pure-Scheme files can just be installed as is.
110
111 (The command can also take `*.stub` files, which is an old way
112 to define C-Scheme bridge. Its use is deprecated.)
113
114 === Test
115
116 `Make check` simply rungs `gosh` on the test script `test.scm`.
117 The test script loads the extension with `(use math.spigot)`, and
118 perform typical tests.
119
120
121 === Install
122
123 The template makefile uses `gauche-install` command, which has
124 some advantages over typical `install` script.
125
126 === Cleanup
127
128 Makefile uses `gauche-package compile` command again, but with
129 `--clean` option this time. Since `gauche-package compile`
130 knows which files it generates, it's easy for it to remove
131 those generated files.
132
133 If you add other build steps that procedures extra files,
134 you need to edit `Makefile.in` to add cleanup command
135 for those files.