2 @node Miscellaneous Tools
3 @chapter Miscellaneous Tools
5 Programming is more fun with a good tools. This chapter describes snarfing
6 tools, and the @code{guile-tools} program which can be used to invoke the rest
7 of the tools (which are self-documenting). Some of these are used in Guile
8 development, too. Imagine that!
11 * Snarfing:: Grepping the source in various ways.
12 * Executable Modules:: Modules callable via guile-tools.
15 @c ---------------------------------------------------------------------------
20 Because it's easier to maintain documentation, code, and other metainfo in one
21 source file than in many files, there have evolved many methods for grepping
22 source to lift and separate these kinds of info, in the process generating
23 docs or fragments of source or what have you. This is known generally as
24 @dfn{snarfing}, which comes from the verb ``to snarf'', here meaning ``to
25 unceremoniously extract information from a somewhat unwilling source.''
27 This section documents the installed program @code{guile-snarf} which does
28 @dfn{init snarfing}, and also touches upon guile's doc snarfing process which
29 is not yet finalized (i.e., doc snarfing programs are not installed at this
33 * Init Snarfing with guile-snarf:: Exposing C subrs and friends to Scheme.
34 * Doc Snarfing:: Generating GDFv2 or texi from source.
37 @c ---------------------------------------------------------------------------
38 @node Init Snarfing with guile-snarf
39 @subsection Init Snarfing with guile-snarf
40 @c NOTE: This node and two subnodes are adapted from ../sources/snarf.texi.
41 @cindex snarfing, init
42 @cindex primitive functions
43 @cindex subrs, defining
45 When writing C code for use with Guile, you typically define a set of C
46 functions, and then make some of them visible to the Scheme world by
47 calling the @code{scm_c_define_gsubr} function; a C function published in
48 this way is called a @dfn{subr}. If you have many subrs to publish, it
49 can sometimes be annoying to keep the list of calls to
50 @code{scm_c_define_gsubr} in sync with the list of function definitions.
51 Frequently, a programmer will define a new subr in C, recompile the
52 application, and then discover that the Scheme interpreter cannot see
53 the subr, because of a missed call to @code{scm_c_define_gsubr}.
55 Guile provides the @code{guile-snarf} command to manage this problem.
56 Using this tool, you can keep all the information needed to define the
57 subr alongside the function definition itself; @code{guile-snarf} will
58 extract this information from your source code, and automatically
59 generate a file of calls to @code{scm_c_define_gsubr} which you can
60 @code{#include} into an initialization function.
63 * How guile-snarf works:: Using @code{guile-snarf}, with example.
64 * Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}.
65 * guile-1.4 guile-snarf:: The old way, and how handle it.
68 @c ---------------------------------------------------------------------------
69 @node How guile-snarf works
70 @subsubsection How guile-snarf works
71 @cindex guile-snarf invocation
72 @cindex guile-snarf example
74 Usage: guile-snarf [--compat=1.4] [-o OUTFILE] INFILE [CPP-OPTIONS ...]
76 What @code{guile-snarf} does:
78 Process INFILE using the C pre-processor and some other programs.
79 Write output to a file, named OUTFILE if specified, or STEM.x if
80 INFILE looks like STEM.c and no OUTFILE is specified. Ignore
81 lines from the input matching grep(1) regular expression:
87 If there are errors during processing, delete OUTFILE and exit with
90 Optional arg "--compat=1.4" means emulate guile-1.4 guile-snarf.
91 This option is not fully tested (@pxref{guile-1.4 guile-snarf}).
93 If env var CPP is set, use its value instead of the C pre-processor
94 determined at Guile configure-time.
96 @xref{Macros guile-snarf recognizes}, for a list of the special (some would
97 say magic) cpp macros you can use.
99 For example, here is how you might define a new subr called
100 @code{clear-image}, implemented by the C function @code{clear_image}:
104 #include <libguile.h>
106 SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
109 #define FUNC_NAME s_clear_image
111 /* C code to clear the image... */
118 #include "image-type.x"
123 The @code{SCM_DEFINE} declaration says that the C function
124 @code{clear_image} implements a Scheme subr called @code{clear-image},
125 which takes one required argument (type @code{SCM} named
126 @code{image_smob}), no optional arguments, and no tail argument.
127 @xref{Doc Snarfing}, for info on the docstring.
129 This works in concert with @code{FUNC_NAME} to also define a static
130 array of characters named @code{s_clear_image}, initialized to the
131 string "clear-image". The body of @code{clear_image} may use the array
132 in error messages, instead of writing out the literal string; this may
133 save string space on some systems.
135 Assuming the text above lives in a file named @file{image-type.c}, you will
136 need to execute the following command to prepare this file for compilation:
139 guile-snarf image-type.c
142 This scans @file{image-type.c} for @code{SCM_DEFINE}
143 declarations, and writes to @file{image-type.x} the output:
146 scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
149 When compiled normally, @code{SCM_DEFINE} is a macro which expands to a
150 declaration of the @code{s_clear_image} string.
152 Note that the output file name matches the @code{#include} from the
153 input file. Also, you still need to provide all the same information
154 you would if you were using @code{scm_c_define_gsubr} yourself, but you
155 can place the information near the function definition itself, so it is
156 less likely to become incorrect or out-of-date.
158 If you have many files that @code{guile-snarf} must process, you should
159 consider using a fragment like the following in your Makefile:
162 snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
165 guile-snarf -o $@ $< $(snarfcppopts)
168 This tells make to run @code{guile-snarf} to produce each needed
169 @file{.x} file from the corresponding @file{.c} file.
171 Aside from the required argument INFILE, @code{guile-snarf} passes its
172 command-line arguments directly to the C preprocessor, which it uses to
173 extract the information it needs from the source code. this means you can pass
174 normal compilation flags to @code{guile-snarf} to define preprocessor symbols,
175 add header file directories, and so on.
177 @c ---------------------------------------------------------------------------
178 @node Macros guile-snarf recognizes
179 @subsubsection Macros guile-snarf recognizes
180 @cindex guile-snarf recognized macros
182 Here are the macros you can use in your source code from which
183 @code{guile-snarf} can construct initialization code:
187 SCM_DEFINE (FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING)
189 SCM_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
190 SCM_REGISTER_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
192 SCM_GPROC (RANAME, STR, REQ, OPT, VAR, CFN, GF)
194 /* everything else */
195 SCM_SYMBOL (c_name, scheme_name)
196 SCM_GLOBAL_SYMBOL (c_name, scheme_name)
198 SCM_KEYWORD (c_name, scheme_name)
199 SCM_GLOBAL_KEYWORD (c_name, scheme_name)
201 SCM_VARIABLE (c_name, scheme_name)
202 SCM_GLOBAL_VARIABLE (c_name, scheme_name)
204 SCM_VARIABLE_INIT (c_name, scheme_name, init_val)
205 SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, init_val)
208 @c i like things dense, but maybe someone else will reformat this
209 @c into an easier-to-read list. also, all-upcase to me is a form
210 @c of quoting, so @var{} is not necessary there. --ttn
211 REQ and OPT are numbers indicating required and optional argument
212 counts, respectively; VAR is a number that, if non-zero, means the
213 function will accept any remaining arguments as a list; DOCSTRING is a
214 string (use @code{\n\} at eol for multi-line); FNAME is a C-language
215 identifier, CFN and GF and @var{c_name} likewise; PRIMNAME is a string
216 denoting the name available to Scheme code, STR and @var{scheme_name}
217 likewise; RANAME is the name of the static string (must match that
218 declared by the associated definition of cpp macro @var{FUNC_NAME});
219 ARGLIST is an argument list (in parentheses); and lastly, @var{init_val}
220 is a expression suitable for initializing a new variable.
222 For procedures, you can use @code{SCM_DEFINE} for most purposes. Use
223 @code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't want
224 to be bothered with docstrings. Use @code{SCM_GPROC} for generic
225 functions (@pxref{GOOPS,,,goops}). All procedures are declared
226 @code{static} with return type @code{SCM}.
228 For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
229 symbols, and so on). The "_GLOBAL_" variants omit @code{static}
232 All these macros should be used at top-level, outside function bodies.
233 Also, it's a good idea to define @var{FUNC_NAME} immediately after using
234 @code{SCM_DEFINE} (and similar), and then the function body, and then
235 @code{#undef FUNC_NAME}.
237 @xref{How guile-snarf works}, and also libguile source, for examples.
238 @xref{Subrs}, for details on argument passing and how to write C
241 @xref{guile-1.4 guile-snarf}, if you have code that relies on the guile-snarf
242 shipped with guile-1.4 (guile-snarf shipped with guile-1.6 is different).
244 @c ---------------------------------------------------------------------------
245 @node guile-1.4 guile-snarf
246 @subsubsection guile-1.4 guile-snarf
247 @cindex guile-1.4 guile-snarf
248 @cindex guile-snarf, guile-1.4
250 The @code{guile-snarf} included with guile-1.4 differs in behavior and usage
251 from that included with guile-1.6 and later. This page explains the four
252 kinds of modifications code written with guile-1.4 guile-snarf in mind need to
253 undergo, in order to be completely compatible with guile-1.6 init snarfing
254 practice; and explains how to use @code{guile-snarf --compat=1.4}.
258 @item Some of the recognized macro names have changed.
260 Specifically, you need to rename:
263 @item SCM_VCELL to SCM_VARIABLE
264 @item SCM_GLOBAL_VCELL to SCM_GLOBAL_VARIABLE
265 @item SCM_VCELL_INIT to SCM_VARIABLE_INIT
266 @item SCM_GLOBAL_VCELL_INIT to SCM_GLOBAL_VARIABLE_INIT
269 @item The macro SCM_CONST_LONG is no longer recognized.
271 Proabably you can use SCM_GLOBAL_VARIABLE_INIT where you would have
272 formerly used SCM_CONST_LONG. [fixme: needs verification]
274 @item guile-snarf is no longer usable in a pipe.
276 With guile-1.4 guile-snarf you had capture its output to a file, check
277 the exit value of the guile-snarf process, and delete the file if that
278 value was false. These operations are now handled internally to
279 guile-snarf, providing you either specify the output file explicitly, or
280 use an input file name that ends in @code{.c} (in which case the output
281 filename is computed from the input filename by replacing @code{.c} with
286 If you have code that uses the old snarf macros (for example,
287 SCM_VCELL), but have installed the new guile-snarf, you can arrange for
288 the old macros to be still recognized by using the @code{--compat=1.4}
289 option. With this option, old macros are translated to their new
290 variants on input to the modern snarfing process. This means the .x
291 files produced will make use of @code{scm_c_define_gsubr} and friends,
292 which are ready to be compiled against the new libguile.
294 Thus, @code{--compat=1.4} does not provide @emph{full} emulation, only
295 input emulation. (The thinking is: If you have a new guile-snarf
296 installed, probably you have a new libguile installed, too, and would
297 prefer to get your old code to work with the new libguile.)
299 The makefile fragment to use would look something like:
303 guile-snarf --compat=1.4 -o $@ $<
306 After you've done a global search and replace on SCM_VCELL and friends,
307 you can remove @code{--compat=1.4} altogether (@pxref{How guile-snarf
310 @c ---------------------------------------------------------------------------
312 @subsection Doc Snarfing
314 In addition to init snarfing (@pxref{Init Snarfing with guile-snarf}),
315 the libguile sources are also subject to doc snarfing, by programs that
316 are included in the distribution (but not installed at this time). The
317 output is the file @file{guile-procedures.txt} which is installed, and
318 subsequently used by module @code{(ice-9 documentation)}.
320 Here is a list of what does what according to @file{libguile/Makefile.am}:
323 @item guile-snarf-docs runs cpp defining SCM_MAGIC_SNARF_DOCS
324 @item guile_filter_doc_snarfage parses guile-snarf-docs output to produce .doc
325 @item ../scripts/snarf-check-and-output-texi makes guile.texi
326 @item ../scripts/snarf-check-and-output-texi makes guile-procedures.txt
327 @item guile-func-name-check checks source snarf-syntax integrity (optional?)
328 @item guile-doc-snarf calls guile-snarf-docs (to make .doc) and guile-snarf
331 Note that for guile-1.4, a completely different approach was used! All this
332 is rather byzantine, so for now @emph{NO} doc snarfing programs are installed.
334 [fixme: Document further once doc snarfing is tamed somewhat. --ttn]
336 @c ---------------------------------------------------------------------------
337 @node Executable Modules
338 @section Executable Modules
340 @cindex modules, executable
341 @cindex executable modules
344 When Guile is installed, in addition to the @code{(ice-9 FOO)} modules,
345 a set of @dfn{executable modules} @code{(scripts BAR)} is also installed.
346 Each is a regular Scheme module that has some additional packaging so
347 that it can be called as a program in its own right, from the shell. For this
348 reason, we sometimes use the term @dfn{script} in this context to mean the
351 @c wow look at this hole^! variable-width font users eat your heart out.
353 As a convenience, the @code{guile-tools} wrapper program is installed along w/
354 @code{guile}; it knows where a particular module is installed and calls it
355 passing its args to the program. The result is that you need not augment your
356 PATH. Usage is straightforward:
360 guile-tools --version
361 guile-tools [OPTION] PROGRAM [ARGS ...]
363 If PROGRAM is "list" or omitted, display contents of scripts dir, otherwise
364 PROGRAM is run w/ ARGS. Options (only one of which may be used at a time):
365 --scriptsdir DIR -- Look in DIR for scripts
366 --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts
367 --source -- Display PROGRAM source (ignore ARGS) to stdout
370 The modules are self-documenting. For example, to see the documentation for
371 @code{lint}, use one (or both) of the shell commands:
374 guile-tools display-commentary '(scripts lint)'
375 guile-tools --source lint
378 The rest of this section describes the packaging that goes into creating an
379 executable module. Feel free to skip to the next chapter.
381 @subsection Writing Executable Modules
383 @c adapted from scripts/README
385 See template file @code{PROGRAM} for a quick start.
387 Programs must follow the @dfn{executable module} convention, documented here:
392 The file name must not end in ".scm".
395 The file must be executable (chmod +x).
398 The module name must be "(scripts PROGRAM)". A procedure named PROGRAM w/
399 signature "(PROGRAM . args)" must be exported. Basically, use some variant
403 (define-module (scripts PROGRAM)
407 Feel free to export other definitions useful in the module context.
410 There must be the alias:
413 (define main PROGRAM)
416 However, `main' must NOT be exported.
419 The beginning of the file must use the following invocation sequence:
423 main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')'
424 exec $@{GUILE-guile@} -l $0 -c "(apply $main (cdr (command-line)))" "$@@"
430 Following these conventions allows the program file to be used as module
431 @code{(scripts PROGRAM)} in addition to as a standalone executable. Please
432 also include a helpful Commentary section w/ some usage info.
434 @c tools.texi ends here