2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @node Miscellaneous Tools
9 @chapter Miscellaneous Tools
11 Programming is more fun with a good tools. This chapter describes snarfing
12 tools, and the @code{guile-tools} program which can be used to invoke the rest
13 of the tools (which are self-documenting). Some of these are used in Guile
14 development, too. Imagine that!
17 * Snarfing:: Grepping the source in various ways.
18 * Executable Modules:: Modules callable via guile-tools.
21 @c ---------------------------------------------------------------------------
26 Because it's easier to maintain documentation, code, and other metainfo in one
27 source file than in many files, there have evolved many methods for grepping
28 source to lift and separate these kinds of info, in the process generating
29 docs or fragments of source or what have you. This is known generally as
30 @dfn{snarfing}, which comes from the verb ``to snarf'', here meaning ``to
31 unceremoniously extract information from a somewhat unwilling source.''
33 This section documents the installed program @code{guile-snarf} which does
34 @dfn{init snarfing}, and also touches upon guile's doc snarfing process which
35 is not yet finalized (i.e., doc snarfing programs are not installed at this
39 * Init Snarfing with guile-snarf:: Exposing C subrs and friends to Scheme.
40 * Doc Snarfing:: Generating GDFv2 or texi from source.
43 @c ---------------------------------------------------------------------------
44 @node Init Snarfing with guile-snarf
45 @subsection Init Snarfing with guile-snarf
46 @c NOTE: This node and two subnodes are adapted from ../sources/snarf.texi.
47 @cindex snarfing, init
48 @cindex primitive functions
49 @cindex subrs, defining
51 When writing C code for use with Guile, you typically define a set of C
52 functions, and then make some of them visible to the Scheme world by
53 calling the @code{scm_c_define_gsubr} function; a C function published in
54 this way is called a @dfn{subr}. If you have many subrs to publish, it
55 can sometimes be annoying to keep the list of calls to
56 @code{scm_c_define_gsubr} in sync with the list of function definitions.
57 Frequently, a programmer will define a new subr in C, recompile the
58 application, and then discover that the Scheme interpreter cannot see
59 the subr, because of a missed call to @code{scm_c_define_gsubr}.
61 Guile provides the @code{guile-snarf} command to manage this problem.
62 Using this tool, you can keep all the information needed to define the
63 subr alongside the function definition itself; @code{guile-snarf} will
64 extract this information from your source code, and automatically
65 generate a file of calls to @code{scm_c_define_gsubr} which you can
66 @code{#include} into an initialization function.
69 * How guile-snarf works:: Using @code{guile-snarf}, with example.
70 * Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}.
71 * Writing your own snarfing macros:: How to define new things to snarf.
74 @c ---------------------------------------------------------------------------
75 @node How guile-snarf works
76 @subsubsection How guile-snarf works
77 @cindex guile-snarf invocation
78 @cindex guile-snarf example
80 Usage: guile-snarf [-o @var{outfile}] [@var{cpp-args} ...]
82 The @code{guile-snarf} program will extract initialization actions to
83 @var{outfile} or to standard output when no @var{outfile} has been
84 specified or when @var{outfile} is @code{-}. The C preprocessor is
85 called with @var{cpp-args} (which usually include an input file) and
86 the output is filtered to extract the initialization actions.
88 If there are errors during processing, @var{outfile} is deleted and the
89 program exits with non-zero status.
91 During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
92 defined. You could use this to avoid including snarfer output files
93 that don't yet exist by writing code like this:
96 #ifndef SCM_MAGIC_SNARFER
101 If the environment variable @code{CPP} is set, use its value instead of the
102 C pre-processor determined at Guile configure-time.
104 @xref{Macros guile-snarf recognizes}, for a list of the special (some would
105 say magic) cpp macros you can use, including the list of deprecated macros.
107 For example, here is how you might define a new subr called
108 @code{clear-image}, implemented by the C function @code{clear_image}:
112 #include <libguile.h>
114 SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
117 #define FUNC_NAME s_clear_image
119 /* C code to clear the image in @code{image_smob}... */
126 #include "image-type.x"
131 The @code{SCM_DEFINE} declaration says that the C function
132 @code{clear_image} implements a Scheme subr called @code{clear-image},
133 which takes one required argument (of type @code{SCM} and named
134 @code{image_smob}), no optional arguments, and no rest argument.
135 @xref{Doc Snarfing}, for info on the docstring.
137 This works in concert with @code{FUNC_NAME} to also define a static
138 array of characters named @code{s_clear_image}, initialized to the
139 string "clear-image". The body of @code{clear_image} may use the array
140 in error messages, instead of writing out the literal string; this may
141 save string space on some systems.
143 Assuming the text above lives in a file named @file{image-type.c}, you will
144 need to execute the following command to prepare this file for compilation:
147 guile-snarf -o image-type.x image-type.c
150 This scans @file{image-type.c} for @code{SCM_DEFINE}
151 declarations, and writes to @file{image-type.x} the output:
154 scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
157 When compiled normally, @code{SCM_DEFINE} is a macro which expands to
158 a declaration of the @code{s_clear_image} string and the function
159 header for @code{clear_image}.
161 Note that the output file name matches the @code{#include} from the
162 input file. Also, you still need to provide all the same information
163 you would if you were using @code{scm_c_define_gsubr} yourself, but you
164 can place the information near the function definition itself, so it is
165 less likely to become incorrect or out-of-date.
167 If you have many files that @code{guile-snarf} must process, you should
168 consider using a fragment like the following in your Makefile:
171 snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
174 guile-snarf -o $@@ $< $(snarfcppopts)
177 This tells make to run @code{guile-snarf} to produce each needed
178 @file{.x} file from the corresponding @file{.c} file.
180 The program @code{guile-snarf} passes its command-line arguments
181 directly to the C preprocessor, which it uses to extract the
182 information it needs from the source code. this means you can pass
183 normal compilation flags to @code{guile-snarf} to define preprocessor
184 symbols, add header file directories, and so on.
186 @c ---------------------------------------------------------------------------
187 @node Macros guile-snarf recognizes
188 @subsubsection Macros guile-snarf recognizes
189 @cindex guile-snarf recognized macros
190 @cindex guile-snarf deprecated macros
192 Here are the macros you can use in your source code from which
193 @code{guile-snarf} can construct initialization code:
197 SCM_DEFINE (FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING)
199 SCM_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
200 SCM_REGISTER_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
202 SCM_GPROC (RANAME, STR, REQ, OPT, VAR, CFN, GF)
204 /* everything else */
205 SCM_SYMBOL (c_name, scheme_name)
206 SCM_GLOBAL_SYMBOL (c_name, scheme_name)
208 SCM_KEYWORD (c_name, scheme_name)
209 SCM_GLOBAL_KEYWORD (c_name, scheme_name)
211 SCM_VARIABLE (c_name, scheme_name)
212 SCM_GLOBAL_VARIABLE (c_name, scheme_name)
214 SCM_VARIABLE_INIT (c_name, scheme_name, init_val)
215 SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, init_val)
218 @c i like things dense, but maybe someone else will reformat this
219 @c into an easier-to-read list. also, all-upcase to me is a form
220 @c of quoting, so @var{} is not necessary there. --ttn
221 REQ and OPT are numbers indicating required and optional argument
222 counts, respectively; VAR is a number that, if non-zero, means the
223 function will accept any remaining arguments as a list; DOCSTRING is a
224 string (use @code{\n\} at eol for multi-line); FNAME is a C-language
225 identifier, CFN and GF and @var{c_name} likewise; PRIMNAME is a string
226 denoting the name available to Scheme code, STR and @var{scheme_name}
227 likewise; RANAME is the name of the static string (must match that
228 declared by the associated definition of cpp macro @var{FUNC_NAME});
229 ARGLIST is an argument list (in parentheses); and lastly, @var{init_val}
230 is a expression suitable for initializing a new variable.
232 For procedures, you can use @code{SCM_DEFINE} for most purposes. Use
233 @code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't
234 want to be bothered with docstrings. Use @code{SCM_GPROC} for generic
235 functions (@pxref{Creating Generic Functions,,, goops, GOOPS}). All
236 procedures are declared with return type @code{SCM}.
238 For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
239 symbols, and so on). Without "_GLOBAL_", the declarations are
242 All these macros should be used at top-level, outside function bodies.
243 Also, it's a good idea to define @var{FUNC_NAME} immediately after using
244 @code{SCM_DEFINE} (and similar), and then the function body, and then
245 @code{#undef FUNC_NAME}.
247 @xref{How guile-snarf works}, and also libguile source, for examples.
248 @xref{Subrs}, for details on argument passing and how to write C
251 @c ---------------------------------------------------------------------------
252 @node Writing your own snarfing macros
253 @subsubsection Writing your own snarfing macros
255 When you want to use the general snarfing machanism, but none of the
256 provided macros fits your need, you can use the macro
257 @code{SCM_SNARF_INIT}.
259 For example, the @code{SCM_SYMBOL} macro can be defined like this:
262 #define SCM_SYMBOL(c_name, scheme_name) \
264 SCM_SNARF_INIT(c_name = scm_permanent_object (scm_str2symbol (scheme_name)))
267 @defmac SCM_SNARF_INIT (code)
268 When processed normally, @code{SCM_SNARF_INIT} expands to nothing;
269 when processed by the snarfer, it causes @var{code} to be included in
270 the initialization action file, followed by a semicolon.
273 @c ---------------------------------------------------------------------------
275 @subsection Doc Snarfing
277 In addition to init snarfing (@pxref{Init Snarfing with guile-snarf}),
278 the libguile sources are also subject to doc snarfing, by programs that
279 are included in the distribution (but not installed at this time). The
280 output is the file @file{guile-procedures.txt} which is installed, and
281 subsequently used by module @code{(ice-9 documentation)}.
283 Here is a list of what does what according to @file{libguile/Makefile.am}:
286 @item guile-snarf-docs runs cpp defining SCM_MAGIC_SNARF_DOCS
287 @item guile_filter_doc_snarfage parses guile-snarf-docs output to produce .doc
288 @item ../scripts/snarf-check-and-output-texi makes guile.texi
289 @item ../scripts/snarf-check-and-output-texi makes guile-procedures.txt
290 @item guile-func-name-check checks source snarf-syntax integrity (optional?)
291 @item guile-doc-snarf calls guile-snarf-docs (to make .doc) and guile-snarf
294 Note that for guile-1.4, a completely different approach was used! All this
295 is rather byzantine, so for now @emph{NO} doc snarfing programs are installed.
297 [fixme: Document further once doc snarfing is tamed somewhat. --ttn]
299 @c ---------------------------------------------------------------------------
300 @node Executable Modules
301 @section Executable Modules
303 @cindex modules, executable
304 @cindex executable modules
307 When Guile is installed, in addition to the @code{(ice-9 FOO)} modules,
308 a set of @dfn{executable modules} @code{(scripts BAR)} is also installed.
309 Each is a regular Scheme module that has some additional packaging so
310 that it can be called as a program in its own right, from the shell. For this
311 reason, we sometimes use the term @dfn{script} in this context to mean the
314 @c wow look at this hole^! variable-width font users eat your heart out.
316 As a convenience, the @code{guile-tools} wrapper program is installed along w/
317 @code{guile}; it knows where a particular module is installed and calls it
318 passing its args to the program. The result is that you need not augment your
319 PATH. Usage is straightforward:
323 guile-tools --version
324 guile-tools [OPTION] PROGRAM [ARGS ...]
326 If PROGRAM is "list" or omitted, display contents of scripts dir, otherwise
327 PROGRAM is run w/ ARGS. Options (only one of which may be used at a time):
328 --scriptsdir DIR -- Look in DIR for scripts
329 --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts
330 --source -- Display PROGRAM source (ignore ARGS) to stdout
333 The modules are self-documenting. For example, to see the documentation for
334 @code{lint}, use one (or both) of the shell commands:
337 guile-tools display-commentary '(scripts lint)'
338 guile-tools --source lint
341 The rest of this section describes the packaging that goes into creating an
342 executable module. Feel free to skip to the next chapter.
344 @subsection Writing Executable Modules
346 @c adapted from scripts/README
348 See template file @code{PROGRAM} for a quick start.
350 Programs must follow the @dfn{executable module} convention, documented here:
355 The file name must not end in ".scm".
358 The file must be executable (chmod +x).
361 The module name must be "(scripts PROGRAM)". A procedure named PROGRAM w/
362 signature "(PROGRAM . args)" must be exported. Basically, use some variant
366 (define-module (scripts PROGRAM)
370 Feel free to export other definitions useful in the module context.
373 There must be the alias:
376 (define main PROGRAM)
379 However, `main' must NOT be exported.
382 The beginning of the file must use the following invocation sequence:
386 main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')'
387 exec $@{GUILE-guile@} -l $0 -c "(apply $main (cdr (command-line)))" "$@@"
393 Following these conventions allows the program file to be used as module
394 @code{(scripts PROGRAM)} in addition to as a standalone executable. Please
395 also include a helpful Commentary section w/ some usage info.
397 @c tools.texi ends here