Commit | Line | Data |
---|---|---|
abae3014 | 1 | @page |
fc17ed5b TTN |
2 | @node Miscellaneous Tools |
3 | @chapter Miscellaneous Tools | |
4 | ||
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! | |
9 | ||
10 | @menu | |
11 | * Snarfing:: Grepping the source in various ways. | |
12 | * Executable Modules:: Modules callable via guile-tools. | |
13 | @end menu | |
14 | ||
15 | @c --------------------------------------------------------------------------- | |
16 | @node Snarfing | |
17 | @section Snarfing | |
18 | @cindex snarfing | |
19 | ||
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.'' | |
26 | ||
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 | |
30 | time). | |
31 | ||
32 | @menu | |
33 | * Init Snarfing with guile-snarf:: Exposing C subrs and friends to Scheme. | |
34 | * Doc Snarfing:: Generating GDFv2 or texi from source. | |
35 | @end menu | |
36 | ||
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 | |
44 | ||
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}. | |
54 | ||
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. | |
61 | ||
62 | @menu | |
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 | @end menu | |
66 | ||
67 | @c --------------------------------------------------------------------------- | |
68 | @node How guile-snarf works | |
69 | @subsubsection How guile-snarf works | |
70 | @cindex guile-snarf invocation | |
71 | @cindex guile-snarf example | |
72 | ||
73 | Usage: @code{guile-snarf} [CPP-OPTIONS ...] SOURCE.c | |
74 | ||
75 | @code{guile-snarf} uses cpp to process SOURCE.c, writing C language | |
76 | initialization calls to standard output, based on special (some would say | |
77 | magic) cpp macros found in the input (@pxref{Macros guile-snarf recognizes}). | |
78 | ||
79 | For example, here is how you might define a new subr called | |
80 | @code{clear-image}, implemented by the C function @code{clear_image}: | |
81 | ||
82 | @example | |
83 | @group | |
84 | #include <libguile.h> | |
85 | ||
86 | SCM_DEFINE (clear_image, "clear-image", 1, 0, 0, | |
87 | (SCM image_smob), | |
88 | "Clear the image.") | |
89 | #define FUNC_NAME s_clear_image | |
90 | @{ | |
91 | /* C code to clear the image... */ | |
92 | @} | |
93 | #undef FUNC_NAME | |
94 | ||
95 | void | |
96 | init_image_type () | |
97 | @{ | |
98 | #include "image-type.x" | |
99 | @} | |
100 | @end group | |
101 | @end example | |
102 | ||
103 | The @code{SCM_DEFINE} declaration says that the C function | |
104 | @code{clear_image} implements a Scheme subr called @code{clear-image}, | |
105 | which takes one required argument (type @code{SCM} named | |
106 | @code{image_smob}), no optional arguments, and no tail argument. | |
107 | @xref{Doc Snarfing}, for info on the docstring. | |
108 | ||
109 | This works in concert with @code{FUNC_NAME} to also define a static | |
110 | array of characters named @code{s_clear_image}, initialized to the | |
111 | string "clear-image". The body of @code{clear_image} may use the array | |
112 | in error messages, instead of writing out the literal string; this may | |
113 | save string space on some systems. | |
114 | ||
115 | Assuming the text above lives in a file named @file{image-type.c}, you will | |
116 | need to execute the following command to prepare this file for compilation: | |
117 | ||
118 | @example | |
119 | guile-snarf image-type.c > image-type.x | |
120 | @end example | |
121 | ||
122 | This scans @file{image-type.c} for @code{SCM_DEFINE} | |
123 | declarations, and writes to @file{image-type.x} the output: | |
124 | ||
125 | @example | |
126 | scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image); | |
127 | @end example | |
128 | ||
129 | When compiled normally, @code{SCM_DEFINE} is a macro which expands to a | |
130 | declaration of the @code{s_clear_image} string. | |
131 | ||
132 | Note that the output file name matches the @code{#include} from the | |
133 | input file. Also, you still need to provide all the same information | |
134 | you would if you were using @code{scm_c_define_gsubr} yourself, but you | |
135 | can place the information near the function definition itself, so it is | |
136 | less likely to become incorrect or out-of-date. | |
137 | ||
138 | If you have many files that @code{guile-snarf} must process, you should | |
139 | consider using a rule like the following in your Makefile: | |
140 | ||
141 | @example | |
142 | .SUFFIXES: .x | |
143 | .c.x: | |
144 | guile-snarf $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< > $@@ | |
145 | @end example | |
146 | ||
147 | This tells make to run @code{guile-snarf} to produce each needed | |
148 | @file{.x} file from the corresponding @file{.c} file. | |
149 | ||
150 | @code{guile-snarf} passes all its command-line arguments directly to the | |
151 | C preprocessor, which it uses to extract the information it needs from | |
152 | the source code. this means you can pass normal compilation flags to | |
153 | @code{guile-snarf} to define preprocessor symbols, add header file | |
154 | directories, and so on. | |
155 | ||
156 | @c --------------------------------------------------------------------------- | |
157 | @node Macros guile-snarf recognizes | |
158 | @subsubsection Macros guile-snarf recognizes | |
159 | @cindex guile-snarf recognized macros | |
160 | ||
161 | Here are the macros you can use in your source code from which | |
162 | @code{guile-snarf} can construct initialization code: | |
163 | ||
164 | @example | |
165 | /* procedures */ | |
166 | SCM_DEFINE (FNAME, PRIMNAME, REQ, OPT, VAR, ARGLIST, DOCSTRING) | |
167 | ||
168 | SCM_PROC (RANAME, STR, REQ, OPT, VAR, CFN) | |
169 | SCM_REGISTER_PROC (RANAME, STR, REQ, OPT, VAR, CFN) | |
170 | ||
171 | SCM_GPROC (RANAME, STR, REQ, OPT, VAR, CFN, GF) | |
172 | ||
173 | /* everything else */ | |
174 | SCM_SYMBOL (c_name, scheme_name) | |
175 | SCM_GLOBAL_SYMBOL (c_name, scheme_name) | |
176 | ||
177 | SCM_KEYWORD (c_name, scheme_name) | |
178 | SCM_GLOBAL_KEYWORD (c_name, scheme_name) | |
179 | ||
180 | SCM_VARIABLE (c_name, scheme_name) | |
181 | SCM_GLOBAL_VARIABLE (c_name, scheme_name) | |
182 | ||
183 | SCM_VARIABLE_INIT (c_name, scheme_name, init_val) | |
184 | SCM_GLOBAL_VARIABLE_INIT (c_name, scheme_name, init_val) | |
185 | @end example | |
186 | ||
187 | @c i like things dense, but maybe someone else will reformat this | |
188 | @c into an easier-to-read list. also, all-upcase to me is a form | |
189 | @c of quoting, so @var{} is not necessary there. --ttn | |
190 | REQ and OPT are numbers indicating required and optional argument | |
191 | counts, respectively; VAR is a number that, if non-zero, means the | |
192 | function will accept any remaining arguments as a list; DOCSTRING is a | |
193 | string (use @code{\n\} at eol for multi-line); FNAME is a C-language | |
194 | identifier, CFN and GF and @var{c_name} likewise; PRIMNAME is a string | |
195 | denoting the name available to Scheme code, STR and @var{scheme_name} | |
196 | likewise; RANAME is the name of the static string (must match that | |
197 | declared by the associated definition of cpp macro @var{FUNC_NAME}); | |
198 | ARGLIST is an argument list (in parentheses); and lastly, @var{init_val} | |
199 | is a expression suitable for initializing a new variable. | |
200 | ||
201 | For procedures, you can use @code{SCM_DEFINE} for most purposes. Use | |
202 | @code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't want | |
203 | to be bothered with docstrings. Use @code{SCM_GPROC} for generic | |
204 | functions (@pxref{GOOPS,,,goops}). All procedures are declared | |
205 | @code{static} with return type @code{SCM}. | |
206 | ||
207 | For everything else, use the appropriate macro (@code{SCM_SYMBOL} for | |
208 | symbols, and so on). The "_GLOBAL_" variants omit @code{static} | |
209 | declaration. | |
210 | ||
211 | All these macros should be used at top-level, outside function bodies. | |
212 | Also, it's a good idea to define @var{FUNC_NAME} immediately after using | |
213 | @code{SCM_DEFINE} (and similar), and then the function body, and then | |
214 | @code{#undef FUNC_NAME}. | |
215 | ||
216 | @xref{How guile-snarf works}, and also libguile source, for examples. | |
217 | @xref{Subrs}, for details on argument passing and how to write C | |
218 | functions. | |
219 | ||
220 | @c --------------------------------------------------------------------------- | |
221 | @node Doc Snarfing | |
222 | @subsection Doc Snarfing | |
223 | ||
224 | In addition to init snarfing (@pxref{Init Snarfing with guile-snarf}), | |
225 | the libguile sources are also subject to doc snarfing, by programs that | |
226 | are included in the distribution (but not installed at this time). The | |
227 | output is the file @file{guile-procedures.txt} which is installed, and | |
228 | subsequently used by module @code{(ice-9 documentation)}. | |
229 | ||
230 | Here is a list of what does what according to @file{libguile/Makefile.am}: | |
231 | ||
232 | @itemize | |
233 | @item guile-snarf-docs runs cpp defining SCM_MAGIC_SNARF_DOCS | |
234 | @item guile_filter_doc_snarfage parses guile-snarf-docs output to produce .doc | |
235 | @item ../scripts/snarf-check-and-output-texi makes guile.texi | |
236 | @item ../scripts/snarf-check-and-output-texi makes guile-procedures.txt | |
237 | @item guile-func-name-check checks source snarf-syntax integrity (optional?) | |
238 | @item guile-doc-snarf calls guile-snarf-docs (to make .doc) and guile-snarf | |
239 | @end itemize | |
240 | ||
241 | Note that for guile-1.4, a completely different approach was used! All this | |
242 | is rather byzantine, so for now @emph{NO} doc snarfing programs are installed. | |
243 | ||
244 | [fixme: Document further once doc snarfing is tamed somewhat. --ttn] | |
245 | ||
246 | @c --------------------------------------------------------------------------- | |
abae3014 | 247 | @node Executable Modules |
fc17ed5b | 248 | @section Executable Modules |
abae3014 TTN |
249 | @cindex guile-tools |
250 | @cindex modules, executable | |
251 | @cindex executable modules | |
252 | @cindex scripts | |
253 | ||
254 | When Guile is installed, in addition to the @code{(ice-9 FOO)} modules, | |
255 | a set of @dfn{executable modules} @code{(scripts BAR)} is also installed. | |
256 | Each is a regular Scheme module that has some additional packaging so | |
257 | that it can be called as a program in its own right, from the shell. For this | |
258 | reason, we sometimes use the term @dfn{script} in this context to mean the | |
259 | same thing. | |
260 | ||
fc17ed5b TTN |
261 | @c wow look at this hole^! variable-width font users eat your heart out. |
262 | ||
abae3014 TTN |
263 | As a convenience, the @code{guile-tools} wrapper program is installed along w/ |
264 | @code{guile}; it knows where a particular module is installed and calls it | |
265 | passing its args to the program. The result is that you need not augment your | |
266 | PATH. Usage is straightforward: | |
267 | ||
268 | @example | |
269 | guile-tools --help | |
270 | guile-tools --version | |
271 | guile-tools [OPTION] PROGRAM [ARGS ...] | |
272 | ||
273 | If PROGRAM is "list" or omitted, display contents of scripts dir, otherwise | |
274 | PROGRAM is run w/ ARGS. Options (only one of which may be used at a time): | |
275 | --scriptsdir DIR -- Look in DIR for scripts | |
276 | --guileversion VERS -- Look in $pkgdatadir/VERS/scripts for scripts | |
277 | --source -- Display PROGRAM source (ignore ARGS) to stdout | |
278 | @end example | |
279 | ||
280 | The modules are self-documenting. For example, to see the documentation for | |
281 | @code{lint}, use one (or both) of the shell commands: | |
282 | ||
283 | @example | |
284 | guile-tools display-commentary '(scripts lint)' | |
285 | guile-tools --source lint | |
286 | @end example | |
287 | ||
fc17ed5b | 288 | The rest of this section describes the packaging that goes into creating an |
abae3014 TTN |
289 | executable module. Feel free to skip to the next chapter. |
290 | ||
fc17ed5b | 291 | @subsection Writing Executable Modules |
abae3014 TTN |
292 | |
293 | @c adapted from scripts/README | |
294 | ||
295 | See template file @code{PROGRAM} for a quick start. | |
296 | ||
297 | Programs must follow the @dfn{executable module} convention, documented here: | |
298 | ||
299 | @itemize | |
300 | ||
301 | @item | |
302 | The file name must not end in ".scm". | |
303 | ||
304 | @item | |
305 | The file must be executable (chmod +x). | |
306 | ||
307 | @item | |
308 | The module name must be "(scripts PROGRAM)". A procedure named PROGRAM w/ | |
309 | signature "(PROGRAM . args)" must be exported. Basically, use some variant | |
310 | of the form: | |
311 | ||
312 | @example | |
fc17ed5b TTN |
313 | (define-module (scripts PROGRAM) |
314 | :export (PROGRAM)) | |
abae3014 TTN |
315 | @end example |
316 | ||
317 | Feel free to export other definitions useful in the module context. | |
318 | ||
319 | @item | |
320 | There must be the alias: | |
321 | ||
322 | @example | |
fc17ed5b | 323 | (define main PROGRAM) |
abae3014 TTN |
324 | @end example |
325 | ||
326 | However, `main' must NOT be exported. | |
327 | ||
328 | @item | |
329 | The beginning of the file must use the following invocation sequence: | |
330 | ||
331 | @example | |
fc17ed5b TTN |
332 | #!/bin/sh |
333 | main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')' | |
334 | exec $@{GUILE-guile@} -l $0 -c "(apply $main (cdr (command-line)))" "$@@" | |
335 | !# | |
abae3014 TTN |
336 | @end example |
337 | ||
338 | @end itemize | |
339 | ||
340 | Following these conventions allows the program file to be used as module | |
341 | @code{(scripts PROGRAM)} in addition to as a standalone executable. Please | |
342 | also include a helpful Commentary section w/ some usage info. | |
343 | ||
344 | @c tools.texi ends here |