| 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 |
| 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_smob), |
| 116 | "Clear the image.") |
| 117 | #define FUNC_NAME s_clear_image |
| 118 | @{ |
| 119 | /* C code to clear the image in @code{image_smob}... */ |
| 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_smob}), no optional arguments, and no rest argument. |
| 135 | @xref{Doc 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 |