doc/ref/tools.texi

   1 @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
 248 @section Executable Modules
 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
 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/
 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
 288 The rest of this section describes the packaging that goes into creating an
 289 executable module.  Feel free to skip to the next chapter.
 290
 291 @subsection Writing Executable Modules
 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
 313 (define-module (scripts PROGRAM)
 314   :export (PROGRAM))
 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
 323 (define main PROGRAM)
 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
 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 !#
 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