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 if specified, or STEM.x if
79 INFILE looks like STEM.c and no OUTFILE is specified. Ignore
80 lines from the input matching grep(1) regular expression:
86 If there are errors during processing, delete OUTFILE and exit with
89 Optional arg "-d" means grep INFILE for deprecated macros and
90 issue a warning if any are found. Alternatively, "-D" means
91 do the same thing but signal error and exit with non-zero status.
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, including the list of deprecated macros.
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
181 @cindex guile-snarf deprecated macros
183 Here are the macros you can use in your source code from which
184 @code{guile-snarf} can construct initialization code:
188 SCM_DEFINE (FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING)
190 SCM_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
191 SCM_REGISTER_PROC (RANAME, STR, REQ, OPT, VAR, CFN)
193 SCM_GPROC (RANAME, STR, REQ, OPT, VAR, CFN, GF)
195 /* everything else */
196 SCM_SYMBOL (c_name, scheme_name)
197 SCM_GLOBAL_SYMBOL (c_name, scheme_name)
199 SCM_KEYWORD (c_name, scheme_name)
200 SCM_GLOBAL_KEYWORD (c_name, scheme_name)
202 SCM_VARIABLE (c_name, scheme_name)
203 SCM_GLOBAL_VARIABLE (c_name, scheme_name)
205 SCM_VARIABLE_INIT (c_name, scheme_name, init_val)
206 SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, init_val)
209 @c i like things dense, but maybe someone else will reformat this
210 @c into an easier-to-read list. also, all-upcase to me is a form
211 @c of quoting, so @var{} is not necessary there. --ttn
212 REQ and OPT are numbers indicating required and optional argument
213 counts, respectively; VAR is a number that, if non-zero, means the
214 function will accept any remaining arguments as a list; DOCSTRING is a
215 string (use @code{\n\} at eol for multi-line); FNAME is a C-language
216 identifier, CFN and GF and @var{c_name} likewise; PRIMNAME is a string
217 denoting the name available to Scheme code, STR and @var{scheme_name}
218 likewise; RANAME is the name of the static string (must match that
219 declared by the associated definition of cpp macro @var{FUNC_NAME});
220 ARGLIST is an argument list (in parentheses); and lastly, @var{init_val}
221 is a expression suitable for initializing a new variable.
223 For procedures, you can use @code{SCM_DEFINE} for most purposes. Use
224 @code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't want
225 to be bothered with docstrings. Use @code{SCM_GPROC} for generic
226 functions (@pxref{GOOPS,,,goops}). All procedures are declared
227 @code{static} with return type @code{SCM}.
229 For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
230 symbols, and so on). The "_GLOBAL_" variants omit @code{static}
233 All these macros should be used at top-level, outside function bodies.
234 Also, it's a good idea to define @var{FUNC_NAME} immediately after using
235 @code{SCM_DEFINE} (and similar), and then the function body, and then
236 @code{#undef FUNC_NAME}.
238 Here is the list of deprecated macros:
240 @c reminder: sync w/ libguile/guile-snarf.in var `deprecated_list'
246 SCM_GLOBAL_VCELL_INIT
249 Some versions of guile (and guile-snarf) will continue to recognize them but
250 at some point they will no longer work. You can pass either @code{-d} or
251 @code{-D} option to have guile-snarf warn or signal error, respectively, if
252 any of these are found in the input file.
254 @xref{How guile-snarf works}, and also libguile source, for examples.
255 @xref{Subrs}, for details on argument passing and how to write C
258 @c ---------------------------------------------------------------------------
260 @subsection Doc Snarfing
262 In addition to init snarfing (@pxref{Init Snarfing with guile-snarf}),
263 the libguile sources are also subject to doc snarfing, by programs that
264 are included in the distribution (but not installed at this time). The
265 output is the file @file{guile-procedures.txt} which is installed, and
266 subsequently used by module @code{(ice-9 documentation)}.
268 Here is a list of what does what according to @file{libguile/Makefile.am}:
271 @item guile-snarf-docs runs cpp defining SCM_MAGIC_SNARF_DOCS
272 @item guile_filter_doc_snarfage parses guile-snarf-docs output to produce .doc
273 @item ../scripts/snarf-check-and-output-texi makes guile.texi
274 @item ../scripts/snarf-check-and-output-texi makes guile-procedures.txt
275 @item guile-func-name-check checks source snarf-syntax integrity (optional?)
276 @item guile-doc-snarf calls guile-snarf-docs (to make .doc) and guile-snarf
279 Note that for guile-1.4, a completely different approach was used! All this
280 is rather byzantine, so for now @emph{NO} doc snarfing programs are installed.
282 [fixme: Document further once doc snarfing is tamed somewhat. --ttn]
284 @c ---------------------------------------------------------------------------
285 @node Executable Modules
286 @section Executable Modules
288 @cindex modules, executable
289 @cindex executable modules
292 When Guile is installed, in addition to the @code{(ice-9 FOO)} modules,
293 a set of @dfn{executable modules} @code{(scripts BAR)} is also installed.
294 Each is a regular Scheme module that has some additional packaging so
295 that it can be called as a program in its own right, from the shell. For this
296 reason, we sometimes use the term @dfn{script} in this context to mean the
299 @c wow look at this hole^! variable-width font users eat your heart out.
301 As a convenience, the @code{guile-tools} wrapper program is installed along w/
302 @code{guile}; it knows where a particular module is installed and calls it
303 passing its args to the program. The result is that you need not augment your
304 PATH. Usage is straightforward:
308 guile-tools --version
309 guile-tools [OPTION] PROGRAM [ARGS ...]
311 If PROGRAM is "list" or omitted, display contents of scripts dir, otherwise
312 PROGRAM is run w/ ARGS. Options (only one of which may be used at a time):
313 --scriptsdir DIR -- Look in DIR for scripts
314 --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts
315 --source -- Display PROGRAM source (ignore ARGS) to stdout
318 The modules are self-documenting. For example, to see the documentation for
319 @code{lint}, use one (or both) of the shell commands:
322 guile-tools display-commentary '(scripts lint)'
323 guile-tools --source lint
326 The rest of this section describes the packaging that goes into creating an
327 executable module. Feel free to skip to the next chapter.
329 @subsection Writing Executable Modules
331 @c adapted from scripts/README
333 See template file @code{PROGRAM} for a quick start.
335 Programs must follow the @dfn{executable module} convention, documented here:
340 The file name must not end in ".scm".
343 The file must be executable (chmod +x).
346 The module name must be "(scripts PROGRAM)". A procedure named PROGRAM w/
347 signature "(PROGRAM . args)" must be exported. Basically, use some variant
351 (define-module (scripts PROGRAM)
355 Feel free to export other definitions useful in the module context.
358 There must be the alias:
361 (define main PROGRAM)
364 However, `main' must NOT be exported.
367 The beginning of the file must use the following invocation sequence:
371 main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')'
372 exec $@{GUILE-guile@} -l $0 -c "(apply $main (cdr (command-line)))" "$@@"
378 Following these conventions allows the program file to be used as module
379 @code{(scripts PROGRAM)} in addition to as a standalone executable. Please
380 also include a helpful Commentary section w/ some usage info.
382 @c tools.texi ends here