doc/ref/tools.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011, 2014
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @page
   8 @node Miscellaneous Tools
   9 @chapter Miscellaneous Tools
  10
  11 Programming is more fun with a good tools.  This chapter describes snarfing
  12 tools, and the @code{guild} program which can be used to invoke the rest
  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.
  18 * Executable Modules::          Modules callable via guild.
  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
  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.
  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
  80 Usage: guile-snarf [-o @var{outfile}] [@var{cpp-args} ...]
  81
  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.
  87
  88 If there are errors during processing, @var{outfile} is deleted and the
  89 program exits with non-zero status.
  90
  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:
  94
  95 @smallexample
  96 #ifndef SCM_MAGIC_SNARFER
  97 #include "foo.x"
  98 #endif
  99 @end smallexample
 100
 101 If the environment variable @code{CPP} is set, use its value instead of the
 102 C pre-processor determined at Guile configure-time.
 103
 104 @xref{Macros guile-snarf recognizes}, for a list of the special (some would
 105 say magic) cpp macros you can use, including the list of deprecated macros.
 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),
 116             "Clear the image.")
 117 #define FUNC_NAME s_clear_image
 118 @{
 119   /* C code to clear the image in @code{image}... */
 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},
 133 which takes one required argument (of type @code{SCM} and named
 134 @code{image}), no optional arguments, and no rest argument.  @xref{Doc
 135 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
 147 guile-snarf -o image-type.x image-type.c
 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
 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}.
 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
 168 consider using a fragment like the following in your Makefile:
 169
 170 @example
 171 snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS)
 172 .SUFFIXES: .x
 173 .c.x:
 174         guile-snarf -o $@@ $< $(snarfcppopts)
 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
 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.
 185
 186 @c ---------------------------------------------------------------------------
 187 @node Macros guile-snarf recognizes
 188 @subsubsection Macros guile-snarf recognizes
 189 @cindex guile-snarf recognized macros
 190 @cindex guile-snarf deprecated macros
 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
 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
 235 functions (@pxref{Creating Generic Functions}).  All procedures are
 236 declared with return type @code{SCM}.
 237
 238 For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
 239 symbols, and so on).  Without "_GLOBAL_", the declarations are
 240 @code{static}.
 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
 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
 255 When you want to use the general snarfing mechanism, but none of the
 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:
 260
 261 @example
 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)))
 265 @end example
 266
 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
 272
 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?)
 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 ---------------------------------------------------------------------------
 299 @node Executable Modules
 300 @section Executable Modules
 301 @cindex guild
 302 @cindex guile-tools
 303 @cindex modules, executable
 304 @cindex executable modules
 305 @cindex scripts
 306
 307 When Guile is installed, in addition to the @code{(ice-9 FOO)} modules, a set
 308 of @dfn{guild modules} @code{(scripts BAR)} is also installed.  Each is
 309 a regular Scheme module that has some additional packaging so that it can be
 310 used by guild, from the shell.  For this reason, we sometimes use the
 311 term @dfn{script} in this context to mean the same thing.
 312
 313 As a convenience, the @code{guild} wrapper program is installed along with
 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
 316 @code{PATH}.  Usage is straightforward:
 317
 318 @example
 319 guild --help
 320 guild --version
 321 guild [OPTION] PROGRAM [ARGS ...]
 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
 334 guild display-commentary '(scripts lint)'
 335 guild --source lint
 336 @end example
 337
 338 The rest of this section describes the packaging that goes into creating an
 339 executable module.  Feel free to skip to the next chapter.
 340
 341 @subsection Writing Executable Modules
 342
 343 @c adapted from scripts/README
 344
 345 See template file @code{PROGRAM} for a quick start.
 346
 347 Programs must follow the @dfn{guild} convention, documented here:
 348
 349 @itemize
 350
 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
 357 (define-module (scripts PROGRAM)
 358   #:export (PROGRAM))
 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
 367 (define main PROGRAM)
 368 @end example
 369
 370 However, `main' must NOT be exported.
 371
 372 @end itemize
 373
 374 Following these conventions allows the program file to be used as module
 375 @code{(scripts PROGRAM)} in addition to being invoked by guild.  Please
 376 also include a helpful Commentary section w/ some usage info.
 377
 378 @c tools.texi ends here