Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
b8b06598 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011 |
2da09c3f MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
abae3014 | 7 | @page |
fc17ed5b TTN |
8 | @node Miscellaneous Tools |
9 | @chapter Miscellaneous Tools | |
10 | ||
11 | Programming is more fun with a good tools. This chapter describes snarfing | |
b8b06598 | 12 | tools, and the @code{guild} program which can be used to invoke the rest |
fc17ed5b TTN |
13 | of the tools (which are self-documenting). Some of these are used in Guile |
14 | development, too. Imagine that! | |
15 | ||
16 | @menu | |
17 | * Snarfing:: Grepping the source in various ways. | |
b8b06598 | 18 | * Executable Modules:: Modules callable via guild. |
fc17ed5b TTN |
19 | @end menu |
20 | ||
21 | @c --------------------------------------------------------------------------- | |
22 | @node Snarfing | |
23 | @section Snarfing | |
24 | @cindex snarfing | |
25 | ||
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.'' | |
32 | ||
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 | |
36 | time). | |
37 | ||
38 | @menu | |
39 | * Init Snarfing with guile-snarf:: Exposing C subrs and friends to Scheme. | |
40 | * Doc Snarfing:: Generating GDFv2 or texi from source. | |
41 | @end menu | |
42 | ||
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 | |
50 | ||
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}. | |
60 | ||
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. | |
67 | ||
68 | @menu | |
878caca5 MV |
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. | |
fc17ed5b TTN |
72 | @end menu |
73 | ||
74 | @c --------------------------------------------------------------------------- | |
75 | @node How guile-snarf works | |
76 | @subsubsection How guile-snarf works | |
77 | @cindex guile-snarf invocation | |
78 | @cindex guile-snarf example | |
79 | ||
878caca5 | 80 | Usage: guile-snarf [-o @var{outfile}] [@var{cpp-args} ...] |
fc17ed5b | 81 | |
878caca5 MV |
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. | |
d5e1d82d | 87 | |
878caca5 MV |
88 | If there are errors during processing, @var{outfile} is deleted and the |
89 | program exits with non-zero status. | |
d5e1d82d | 90 | |
878caca5 MV |
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: | |
d5e1d82d | 94 | |
878caca5 MV |
95 | @smallexample |
96 | #ifndef SCM_MAGIC_SNARFER | |
97 | #include "foo.x" | |
98 | #endif | |
99 | @end smallexample | |
d5e1d82d | 100 | |
878caca5 MV |
101 | If the environment variable @code{CPP} is set, use its value instead of the |
102 | C pre-processor determined at Guile configure-time. | |
033aa07c | 103 | |
d5e1d82d | 104 | @xref{Macros guile-snarf recognizes}, for a list of the special (some would |
b5bb4262 | 105 | say magic) cpp macros you can use, including the list of deprecated macros. |
fc17ed5b TTN |
106 | |
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}: | |
109 | ||
110 | @example | |
111 | @group | |
112 | #include <libguile.h> | |
113 | ||
114 | SCM_DEFINE (clear_image, "clear-image", 1, 0, 0, | |
115 | (SCM image_smob), | |
116 | "Clear the image.") | |
117 | #define FUNC_NAME s_clear_image | |
118 | @{ | |
878caca5 | 119 | /* C code to clear the image in @code{image_smob}... */ |
fc17ed5b TTN |
120 | @} |
121 | #undef FUNC_NAME | |
122 | ||
123 | void | |
124 | init_image_type () | |
125 | @{ | |
126 | #include "image-type.x" | |
127 | @} | |
128 | @end group | |
129 | @end example | |
130 | ||
131 | The @code{SCM_DEFINE} declaration says that the C function | |
132 | @code{clear_image} implements a Scheme subr called @code{clear-image}, | |
878caca5 MV |
133 | which takes one required argument (of type @code{SCM} and named |
134 | @code{image_smob}), no optional arguments, and no rest argument. | |
fc17ed5b TTN |
135 | @xref{Doc Snarfing}, for info on the docstring. |
136 | ||
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. | |
142 | ||
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: | |
145 | ||
146 | @example | |
878caca5 | 147 | guile-snarf -o image-type.x image-type.c |
fc17ed5b TTN |
148 | @end example |
149 | ||
150 | This scans @file{image-type.c} for @code{SCM_DEFINE} | |
151 | declarations, and writes to @file{image-type.x} the output: | |
152 | ||
153 | @example | |
154 | scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image); | |
155 | @end example | |
156 | ||
878caca5 MV |
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}. | |
fc17ed5b TTN |
160 | |
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. | |
166 | ||
167 | If you have many files that @code{guile-snarf} must process, you should | |
d5e1d82d | 168 | consider using a fragment like the following in your Makefile: |
fc17ed5b TTN |
169 | |
170 | @example | |
d5e1d82d | 171 | snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) |
fc17ed5b TTN |
172 | .SUFFIXES: .x |
173 | .c.x: | |
41e7d0f5 | 174 | guile-snarf -o $@@ $< $(snarfcppopts) |
fc17ed5b TTN |
175 | @end example |
176 | ||
177 | This tells make to run @code{guile-snarf} to produce each needed | |
178 | @file{.x} file from the corresponding @file{.c} file. | |
179 | ||
878caca5 MV |
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. | |
fc17ed5b TTN |
185 | |
186 | @c --------------------------------------------------------------------------- | |
187 | @node Macros guile-snarf recognizes | |
188 | @subsubsection Macros guile-snarf recognizes | |
189 | @cindex guile-snarf recognized macros | |
b5bb4262 | 190 | @cindex guile-snarf deprecated macros |
fc17ed5b TTN |
191 | |
192 | Here are the macros you can use in your source code from which | |
193 | @code{guile-snarf} can construct initialization code: | |
194 | ||
195 | @example | |
196 | /* procedures */ | |
197 | SCM_DEFINE (FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING) | |
198 | ||
199 | SCM_PROC (RANAME, STR, REQ, OPT, VAR, CFN) | |
200 | SCM_REGISTER_PROC (RANAME, STR, REQ, OPT, VAR, CFN) | |
201 | ||
202 | SCM_GPROC (RANAME, STR, REQ, OPT, VAR, CFN, GF) | |
203 | ||
204 | /* everything else */ | |
205 | SCM_SYMBOL (c_name, scheme_name) | |
206 | SCM_GLOBAL_SYMBOL (c_name, scheme_name) | |
207 | ||
208 | SCM_KEYWORD (c_name, scheme_name) | |
209 | SCM_GLOBAL_KEYWORD (c_name, scheme_name) | |
210 | ||
211 | SCM_VARIABLE (c_name, scheme_name) | |
212 | SCM_GLOBAL_VARIABLE (c_name, scheme_name) | |
213 | ||
214 | SCM_VARIABLE_INIT (c_name, scheme_name, init_val) | |
215 | SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, init_val) | |
216 | @end example | |
217 | ||
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. | |
231 | ||
232 | For procedures, you can use @code{SCM_DEFINE} for most purposes. Use | |
878caca5 MV |
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 | |
eb12b401 NJ |
235 | functions (@pxref{Creating Generic Functions}). All procedures are |
236 | declared with return type @code{SCM}. | |
fc17ed5b TTN |
237 | |
238 | For everything else, use the appropriate macro (@code{SCM_SYMBOL} for | |
878caca5 MV |
239 | symbols, and so on). Without "_GLOBAL_", the declarations are |
240 | @code{static}. | |
fc17ed5b TTN |
241 | |
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}. | |
246 | ||
878caca5 MV |
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 | |
249 | functions. | |
250 | ||
251 | @c --------------------------------------------------------------------------- | |
252 | @node Writing your own snarfing macros | |
253 | @subsubsection Writing your own snarfing macros | |
254 | ||
ecb87335 | 255 | When you want to use the general snarfing mechanism, but none of the |
878caca5 MV |
256 | provided macros fits your need, you can use the macro |
257 | @code{SCM_SNARF_INIT}. | |
258 | ||
259 | For example, the @code{SCM_SYMBOL} macro can be defined like this: | |
d5e1d82d TTN |
260 | |
261 | @example | |
878caca5 MV |
262 | #define SCM_SYMBOL(c_name, scheme_name) \ |
263 | static SCM c_name \ | |
264 | SCM_SNARF_INIT(c_name = scm_permanent_object (scm_str2symbol (scheme_name))) | |
d5e1d82d TTN |
265 | @end example |
266 | ||
878caca5 MV |
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. | |
271 | @end defmac | |
d5e1d82d | 272 | |
fc17ed5b TTN |
273 | @c --------------------------------------------------------------------------- |
274 | @node Doc Snarfing | |
275 | @subsection Doc Snarfing | |
276 | ||
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)}. | |
282 | ||
283 | Here is a list of what does what according to @file{libguile/Makefile.am}: | |
284 | ||
285 | @itemize | |
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?) | |
fc17ed5b TTN |
291 | @end itemize |
292 | ||
293 | Note that for guile-1.4, a completely different approach was used! All this | |
294 | is rather byzantine, so for now @emph{NO} doc snarfing programs are installed. | |
295 | ||
296 | [fixme: Document further once doc snarfing is tamed somewhat. --ttn] | |
297 | ||
298 | @c --------------------------------------------------------------------------- | |
abae3014 | 299 | @node Executable Modules |
fc17ed5b | 300 | @section Executable Modules |
b8b06598 | 301 | @cindex guild |
abae3014 TTN |
302 | @cindex guile-tools |
303 | @cindex modules, executable | |
304 | @cindex executable modules | |
305 | @cindex scripts | |
306 | ||
c6e05396 | 307 | When Guile is installed, in addition to the @code{(ice-9 FOO)} modules, a set |
b8b06598 | 308 | of @dfn{guild modules} @code{(scripts BAR)} is also installed. Each is |
c6e05396 | 309 | a regular Scheme module that has some additional packaging so that it can be |
b8b06598 | 310 | used by guild, from the shell. For this reason, we sometimes use the |
c6e05396 | 311 | term @dfn{script} in this context to mean the same thing. |
fc17ed5b | 312 | |
e108c961 | 313 | As a convenience, the @code{guild} wrapper program is installed along with |
abae3014 TTN |
314 | @code{guile}; it knows where a particular module is installed and calls it |
315 | passing its args to the program. The result is that you need not augment your | |
e108c961 | 316 | @code{PATH}. Usage is straightforward: |
abae3014 TTN |
317 | |
318 | @example | |
b8b06598 AW |
319 | guild --help |
320 | guild --version | |
321 | guild [OPTION] PROGRAM [ARGS ...] | |
abae3014 TTN |
322 | |
323 | If PROGRAM is "list" or omitted, display contents of scripts dir, otherwise | |
324 | PROGRAM is run w/ ARGS. Options (only one of which may be used at a time): | |
325 | --scriptsdir DIR -- Look in DIR for scripts | |
326 | --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts | |
327 | --source -- Display PROGRAM source (ignore ARGS) to stdout | |
328 | @end example | |
329 | ||
330 | The modules are self-documenting. For example, to see the documentation for | |
331 | @code{lint}, use one (or both) of the shell commands: | |
332 | ||
333 | @example | |
b8b06598 AW |
334 | guild display-commentary '(scripts lint)' |
335 | guild --source lint | |
abae3014 TTN |
336 | @end example |
337 | ||
fc17ed5b | 338 | The rest of this section describes the packaging that goes into creating an |
abae3014 TTN |
339 | executable module. Feel free to skip to the next chapter. |
340 | ||
fc17ed5b | 341 | @subsection Writing Executable Modules |
abae3014 TTN |
342 | |
343 | @c adapted from scripts/README | |
344 | ||
345 | See template file @code{PROGRAM} for a quick start. | |
346 | ||
b8b06598 | 347 | Programs must follow the @dfn{guild} convention, documented here: |
abae3014 TTN |
348 | |
349 | @itemize | |
350 | ||
abae3014 TTN |
351 | @item |
352 | The module name must be "(scripts PROGRAM)". A procedure named PROGRAM w/ | |
353 | signature "(PROGRAM . args)" must be exported. Basically, use some variant | |
354 | of the form: | |
355 | ||
356 | @example | |
fc17ed5b | 357 | (define-module (scripts PROGRAM) |
8d9cb14e | 358 | #:export (PROGRAM)) |
abae3014 TTN |
359 | @end example |
360 | ||
361 | Feel free to export other definitions useful in the module context. | |
362 | ||
363 | @item | |
364 | There must be the alias: | |
365 | ||
366 | @example | |
fc17ed5b | 367 | (define main PROGRAM) |
abae3014 TTN |
368 | @end example |
369 | ||
370 | However, `main' must NOT be exported. | |
371 | ||
abae3014 TTN |
372 | @end itemize |
373 | ||
374 | Following these conventions allows the program file to be used as module | |
b8b06598 | 375 | @code{(scripts PROGRAM)} in addition to being invoked by guild. Please |
abae3014 TTN |
376 | also include a helpful Commentary section w/ some usage info. |
377 | ||
378 | @c tools.texi ends here |