/[guile]/guile/guile-core/doc/ref/tools.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/tools.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1.2.1 by ttn, Wed Mar 6 20:55:12 2002 UTC revision 1.1.2.2 by ttn, Fri Mar 8 21:30:20 2002 UTC
# Line 1  Line 1 
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
# Line 13  that it can be called as a program in it Line 258  that it can be called as a program in it
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
# Line 38  guile-tools display-commentary '(scripts Line 285  guile-tools display-commentary '(scripts
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    
# Line 63  signature "(PROGRAM . args)" must be exp Line 310  signature "(PROGRAM . args)" must be exp
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.
# Line 73  Feel free to export other definitions us Line 320  Feel free to export other definitions us
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.
# Line 82  However, `main' must NOT be exported. Line 329  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

Legend:
Removed from v.1.1.2.1  
changed lines
  Added in v.1.1.2.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26