author | Mike Sullivan <Mike.Sullivan@Oracle.COM> |
Mon, 29 Sep 2014 11:02:50 -0700 | |
changeset 2120 | 9923c3ab55b8 |
parent 181 | 87e11e685b1f |
permissions | -rw-r--r-- |
173
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
1 |
'\" t |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
2 |
.\" |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
3 |
.\" Copyright (c) 2009, 2011, Oracle and/or its affiliates. All rights reserved. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
4 |
.\" |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
5 |
.\" This man page created by Oracle to provide a reference to the |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
6 |
.\" Info format documentation for guile provided with the distribution. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
7 |
.\" |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
8 |
.TH guile-snarf 1 "26 May 2008" |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
9 |
.SH NAME |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
10 |
guile-snarf \- a tool designed to help guile users to collect subr |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
11 |
information from distributed c files |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
12 |
.SH SYNOPSIS |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
13 |
/usr/bin/guile-snarf [-o outfile] [cpp-args ...] |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
14 |
.SH DESCRIPTION |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
15 |
When writing C code for use with Guile, you typically define a set of |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
16 |
C functions, and then make some of them visible to the Scheme world by |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
17 |
calling the scm_c_define_gsubr function; a C function published in this |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
18 |
way is called a subr. If you have many subrs to publish, it can sometimes |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
19 |
be annoying to keep the list of calls to scm_c_define_gsubr in sync with |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
20 |
the list of function definitions. Frequently, a programmer will define |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
21 |
a new subr in C, recompile the application, and then discover that the |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
22 |
Scheme interpreter cannot see the subr, because of a missed call to |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
23 |
scm_c_define_gsubr. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
24 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
25 |
Guile provides the guile-snarf command to manage this problem. Using this |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
26 |
tool, you can keep all the information needed to define the subr alongside |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
27 |
the function definition itself; guile-snarf will extract this information |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
28 |
from your source code, and automatically generate a file of calls to |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
29 |
scm_c_define_gsubr which you can #include into an initialization function. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
30 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
31 |
The guile-snarf program will extract initialization actions to outfile or |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
32 |
to standard output when no outfile has been specified or when outfile |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
33 |
is -. The C preprocessor is called with cpp-args (which usually include |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
34 |
an input file) and the output is filtered to extract the initialization |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
35 |
actions. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
36 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
37 |
If there are errors during processing, outfile is deleted and the program |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
38 |
exits with non-zero status. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
39 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
40 |
During snarfing, the pre-processor macro SCM_MAGIC_SNARFER is defined. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
41 |
You could use this to avoid including snarfer output files that don't yet |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
42 |
exist by writing code like this: |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
43 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
44 |
#ifndef SCM_MAGIC_SNARFER |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
45 |
#include "foo.x" |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
46 |
#endif |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
47 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
48 |
If the environment variable CPP is set, use its value instead of the C |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
49 |
pre-processor determined at Guile configure-time. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
50 |
.SH EXAMPLES |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
51 |
For example, here is how you might define a new subr called clear-image, |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
52 |
implemented by the C function clear_image: |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
53 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
54 |
#include <libguile.h> |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
55 |
|
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
56 |
SCM_DEFINE (clear_image, "clear-image", 1, 0, 0, |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
57 |
(SCM image_smob), |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
58 |
"Clear the image.") |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
59 |
|
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
60 |
#define FUNC_NAME s_clear_image |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
61 |
{ |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
62 |
/* C code to clear the image in image_smob... */ |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
63 |
|
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
64 |
} |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
65 |
#undef FUNC_NAME |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
66 |
|
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
67 |
void |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
68 |
init_image_type () |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
69 |
{ |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
70 |
#include "image-type.x" |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
71 |
} |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
72 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
73 |
The SCM_DEFINE declaration says that the C function clear_image implements |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
74 |
a Scheme subr called clear-image, which takes one required argument (of |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
75 |
type SCM and named image_smob), no optional arguments, and no rest argument. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
76 |
See Doc Snarfing, for info on the docstring. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
77 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
78 |
This works in concert with FUNC_NAME to also define a static array of |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
79 |
characters named s_clear_image, initialized to the string "clear-image". |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
80 |
The body of clear_image may use the array in error messages, instead of |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
81 |
writing out the literal string; this may save string space on some systems. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
82 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
83 |
Assuming the text above lives in a file named image-type.c, you will need |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
84 |
to execute the following command to prepare this file for compilation: |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
85 |
|
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
86 |
.I guile-snarf -o image-type.x image-type.c |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
87 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
88 |
This scans image-type.c for SCM_DEFINE declarations, and writes to |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
89 |
image-type.x the output: |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
90 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
91 |
scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image); |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
92 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
93 |
When compiled normally, SCM_DEFINE is a macro which expands to a |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
94 |
declaration of the s_clear_image string and the function header for |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
95 |
clear_image. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
96 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
97 |
Note that the output file name matches the #include from the input file. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
98 |
Also, you still need to provide all the same information you would if you |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
99 |
were using scm_c_define_gsubr yourself, but you can place the information |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
100 |
near the function definition itself, so it is less likely to become |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
101 |
incorrect or out-of-date. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
102 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
103 |
If you have many files that guile-snarf must process, you should consider |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
104 |
using a fragment like the following in your Makefile: |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
105 |
|
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
106 |
snarfcppopts = $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
107 |
.SUFFIXES: .x |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
108 |
.c.x: |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
109 |
guile-snarf -o $ $< $(snarfcppopts) |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
110 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
111 |
This tells make to run guile-snarf to produce each needed .x file from the |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
112 |
corresponding .c file. |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
113 |
.LP |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
114 |
The program guile-snarf passes its command-line arguments directly to the |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
115 |
C preprocessor, which it uses to extract the information it needs from |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
116 |
the source code. this means you can pass normal compilation flags to |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
117 |
guile-snarf to define preprocessor symbols, add header file directories, |
69315e61a221
7034838 migrate guile to userland
Kevin Crowe <Kevin.Crowe@oracle.com>
parents:
diff
changeset
|
118 |
and so on. |