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}.
67 @c ---------------------------------------------------------------------------
68 @node How guile-snarf works
69 @subsubsection How guile-snarf works
70 @cindex guile-snarf invocation
71 @cindex guile-snarf example
73 Usage: guile-snarf [-d | -D] [-o OUTFILE] INFILE [CPP-OPTIONS ...]
75 What @code{guile-snarf} does:
77 Process INFILE using the C pre-processor and some other programs.
78 Write output to a file named OUTFILE or to the standard output when no
79 OUTFILE has been specified or when OUTFILE is @code{-}. When writing
80 to a file, ignore lines from the input matching the following grep(1)
87 If there are errors during processing, delete OUTFILE and exit with
90 Optional arg "-d" means grep INFILE for deprecated macros and
91 issue a warning if any are found. Alternatively, "-D" means
92 do the same thing but signal error and exit with non-zero status.
94 If env var CPP is set, use its value instead of the C pre-processor
95 determined at Guile configure-time.
97 During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
100 @xref{Macros guile-snarf recognizes}, for a list of the special (some would
101 say magic) cpp macros you can use, including the list of deprecated macros.
103 For example, here is how you might define a new subr called
104 @code{clear-image}, implemented by the C function @code{clear_image}:
108 #include <libguile.h>
110 SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
113 #define FUNC_NAME s_clear_image
115 /* C code to clear the image... */
122 #include "image-type.x"
127 The @code{SCM_DEFINE} declaration says that the C function
128 @code{clear_image} implements a Scheme subr called @code{clear-image},
129 which takes one required argument (type @code{SCM} named
130 @code{image_smob}), no optional arguments, and no tail argument.
131 @xref{Doc Snarfing}, for info on the docstring.
133 This works in concert with @code{FUNC_NAME} to also define a static
134 array of characters named @code{s_clear_image}, initialized to the
135 string "clear-image". The body of @code{clear_image} may use the array
136 in error messages, instead of writing out the literal string; this may
137 save string space on some systems.
139 Assuming the text above lives in a file named @file{image-type.c}, you will
140 need to execute the following command to prepare this file for compilation:
143 guile-snarf image-type.c
146 This scans @file{image-type.c} for @code{SCM_DEFINE}
147 declarations, and writes to @file{image-type.x} the output:
150 scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
153 When compiled normally, @code{SCM_DEFINE} is a macro which expands to a
154 declaration of the @code{s_clear_image} string.
156 Note that the output file name matches the @code{#include} from the
157 input file. Also, you still need to provide all the same information
158 you would if you were using @code{scm_c_define_gsubr} yourself, but you
159 can place the information near the function definition itself, so it is
160 less likely to become incorrect or out-of-date.
162 If you have many files that @code{guile-snarf} must process, you should
163 consider using a fragment like the following in your Makefile:
166 snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
169 guile-snarf -o $@ $< $(snarfcppopts)
172 This tells make to run @code{guile-snarf} to produce each needed
173 @file{.x} file from the corresponding @file{.c} file.
175 Aside from the required argument INFILE, @code{guile-snarf} passes its
176 command-line arguments directly to the C preprocessor, which it uses to
177 extract the information it needs from the source code. this means you can pass
178 normal compilation flags to @code{guile-snarf} to define preprocessor symbols,
179 add header file directories, and so on.
181 @c ---------------------------------------------------------------------------
182 @node Macros guile-snarf recognizes
183 @subsubsection Macros guile-snarf recognizes
184 @cindex guile-snarf recognized macros
185 @cindex guile-snarf deprecated macros
187 Here are the macros you can use in your source code from which
188 @code{guile-snarf} can construct initialization code:
192 SCM_DEFINE (FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING)
194 SCM_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
195 SCM_REGISTER_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
197 SCM_GPROC (RANAME, STR, REQ, OPT, VAR, CFN, GF)
199 /* everything else */
200 SCM_SYMBOL (c_name, scheme_name)
201 SCM_GLOBAL_SYMBOL (c_name, scheme_name)
203 SCM_KEYWORD (c_name, scheme_name)
204 SCM_GLOBAL_KEYWORD (c_name, scheme_name)
206 SCM_VARIABLE (c_name, scheme_name)
207 SCM_GLOBAL_VARIABLE (c_name, scheme_name)
209 SCM_VARIABLE_INIT (c_name, scheme_name, init_val)
210 SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, init_val)
213 @c i like things dense, but maybe someone else will reformat this
214 @c into an easier-to-read list. also, all-upcase to me is a form
215 @c of quoting, so @var{} is not necessary there. --ttn
216 REQ and OPT are numbers indicating required and optional argument
217 counts, respectively; VAR is a number that, if non-zero, means the
218 function will accept any remaining arguments as a list; DOCSTRING is a
219 string (use @code{\n\} at eol for multi-line); FNAME is a C-language
220 identifier, CFN and GF and @var{c_name} likewise; PRIMNAME is a string
221 denoting the name available to Scheme code, STR and @var{scheme_name}
222 likewise; RANAME is the name of the static string (must match that
223 declared by the associated definition of cpp macro @var{FUNC_NAME});
224 ARGLIST is an argument list (in parentheses); and lastly, @var{init_val}
225 is a expression suitable for initializing a new variable.
227 For procedures, you can use @code{SCM_DEFINE} for most purposes. Use
228 @code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't want
229 to be bothered with docstrings. Use @code{SCM_GPROC} for generic
230 functions (@pxref{GOOPS,,,goops}). All procedures are declared
231 @code{static} with return type @code{SCM}.
233 For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
234 symbols, and so on). The "_GLOBAL_" variants omit @code{static}
237 All these macros should be used at top-level, outside function bodies.
238 Also, it's a good idea to define @var{FUNC_NAME} immediately after using
239 @code{SCM_DEFINE} (and similar), and then the function body, and then
240 @code{#undef FUNC_NAME}.
242 Here is the list of deprecated macros:
244 @c reminder: sync w/ libguile/guile-snarf.in var `deprecated_list'
250 SCM_GLOBAL_VCELL_INIT
253 Some versions of guile (and guile-snarf) will continue to recognize them but
254 at some point they will no longer work. You can pass either @code{-d} or
255 @code{-D} option to have guile-snarf warn or signal error, respectively, if
256 any of these are found in the input file.
258 @xref{How guile-snarf works}, and also libguile source, for examples.
259 @xref{Subrs}, for details on argument passing and how to write C
262 @c ---------------------------------------------------------------------------
264 @subsection Doc Snarfing
266 In addition to init snarfing (@pxref{Init Snarfing with guile-snarf}),
267 the libguile sources are also subject to doc snarfing, by programs that
268 are included in the distribution (but not installed at this time). The
269 output is the file @file{guile-procedures.txt} which is installed, and
270 subsequently used by module @code{(ice-9 documentation)}.
272 Here is a list of what does what according to @file{libguile/Makefile.am}:
275 @item guile-snarf-docs runs cpp defining SCM_MAGIC_SNARF_DOCS
276 @item guile_filter_doc_snarfage parses guile-snarf-docs output to produce .doc
277 @item ../scripts/snarf-check-and-output-texi makes guile.texi
278 @item ../scripts/snarf-check-and-output-texi makes guile-procedures.txt
279 @item guile-func-name-check checks source snarf-syntax integrity (optional?)
280 @item guile-doc-snarf calls guile-snarf-docs (to make .doc) and guile-snarf
283 Note that for guile-1.4, a completely different approach was used! All this
284 is rather byzantine, so for now @emph{NO} doc snarfing programs are installed.
286 [fixme: Document further once doc snarfing is tamed somewhat. --ttn]
288 @c ---------------------------------------------------------------------------
289 @node Executable Modules
290 @section Executable Modules
292 @cindex modules, executable
293 @cindex executable modules
296 When Guile is installed, in addition to the @code{(ice-9 FOO)} modules,
297 a set of @dfn{executable modules} @code{(scripts BAR)} is also installed.
298 Each is a regular Scheme module that has some additional packaging so
299 that it can be called as a program in its own right, from the shell. For this
300 reason, we sometimes use the term @dfn{script} in this context to mean the
303 @c wow look at this hole^! variable-width font users eat your heart out.
305 As a convenience, the @code{guile-tools} wrapper program is installed along w/
306 @code{guile}; it knows where a particular module is installed and calls it
307 passing its args to the program. The result is that you need not augment your
308 PATH. Usage is straightforward:
312 guile-tools --version
313 guile-tools [OPTION] PROGRAM [ARGS ...]
315 If PROGRAM is "list" or omitted, display contents of scripts dir, otherwise
316 PROGRAM is run w/ ARGS. Options (only one of which may be used at a time):
317 --scriptsdir DIR -- Look in DIR for scripts
318 --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts
319 --source -- Display PROGRAM source (ignore ARGS) to stdout
322 The modules are self-documenting. For example, to see the documentation for
323 @code{lint}, use one (or both) of the shell commands:
326 guile-tools display-commentary '(scripts lint)'
327 guile-tools --source lint
330 The rest of this section describes the packaging that goes into creating an
331 executable module. Feel free to skip to the next chapter.
333 @subsection Writing Executable Modules
335 @c adapted from scripts/README
337 See template file @code{PROGRAM} for a quick start.
339 Programs must follow the @dfn{executable module} convention, documented here:
344 The file name must not end in ".scm".
347 The file must be executable (chmod +x).
350 The module name must be "(scripts PROGRAM)". A procedure named PROGRAM w/
351 signature "(PROGRAM . args)" must be exported. Basically, use some variant
355 (define-module (scripts PROGRAM)
359 Feel free to export other definitions useful in the module context.
362 There must be the alias:
365 (define main PROGRAM)
368 However, `main' must NOT be exported.
371 The beginning of the file must use the following invocation sequence:
375 main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')'
376 exec $@{GUILE-guile@} -l $0 -c "(apply $main (cdr (command-line)))" "$@@"
382 Following these conventions allows the program file to be used as module
383 @code{(scripts PROGRAM)} in addition to as a standalone executable. Please
384 also include a helpful Commentary section w/ some usage info.
386 @c tools.texi ends here