1 |
@page |
@page |
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 --------------------------------------------------------------------------- |
247 |
@node Executable Modules |
@node Executable Modules |
248 |
@chapter Executable Modules |
@section Executable Modules |
249 |
@cindex guile-tools |
@cindex guile-tools |
250 |
@cindex modules, executable |
@cindex modules, executable |
251 |
@cindex executable modules |
@cindex executable modules |
258 |
reason, we sometimes use the term @dfn{script} in this context to mean the |
reason, we sometimes use the term @dfn{script} in this context to mean the |
259 |
same thing. |
same thing. |
260 |
|
|
261 |
|
@c wow look at this hole^! variable-width font users eat your heart out. |
262 |
|
|
263 |
As a convenience, the @code{guile-tools} wrapper program is installed along w/ |
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 |
@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 |
passing its args to the program. The result is that you need not augment your |
285 |
guile-tools --source lint |
guile-tools --source lint |
286 |
@end example |
@end example |
287 |
|
|
288 |
The rest of this chapter describes the packaging that goes into creating an |
The rest of this section describes the packaging that goes into creating an |
289 |
executable module. Feel free to skip to the next chapter. |
executable module. Feel free to skip to the next chapter. |
290 |
|
|
291 |
@section Writing Executable Modules |
@subsection Writing Executable Modules |
292 |
|
|
293 |
@c adapted from scripts/README |
@c adapted from scripts/README |
294 |
|
|
310 |
of the form: |
of the form: |
311 |
|
|
312 |
@example |
@example |
313 |
(define-module (scripts PROGRAM) |
(define-module (scripts PROGRAM) |
314 |
:export (PROGRAM)) |
:export (PROGRAM)) |
315 |
@end example |
@end example |
316 |
|
|
317 |
Feel free to export other definitions useful in the module context. |
Feel free to export other definitions useful in the module context. |
320 |
There must be the alias: |
There must be the alias: |
321 |
|
|
322 |
@example |
@example |
323 |
(define main PROGRAM) |
(define main PROGRAM) |
324 |
@end example |
@end example |
325 |
|
|
326 |
However, `main' must NOT be exported. |
However, `main' must NOT be exported. |
329 |
The beginning of the file must use the following invocation sequence: |
The beginning of the file must use the following invocation sequence: |
330 |
|
|
331 |
@example |
@example |
332 |
#!/bin/sh |
#!/bin/sh |
333 |
main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')' |
main='(module-ref (resolve-module '\''(scripts PROGRAM)) '\'main')' |
334 |
exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@" |
exec $@{GUILE-guile@} -l $0 -c "(apply $main (cdr (command-line)))" "$@@" |
335 |
!# |
!# |
336 |
@end example |
@end example |
337 |
|
|
338 |
@end itemize |
@end itemize |