/[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.7 by mvo, Mon Apr 8 17:09:07 2002 UTC revision 1.1.2.8 by mvo, Thu Oct 3 15:31:50 2002 UTC
# Line 60  generate a file of calls to @code{scm_c_ Line 60  generate a file of calls to @code{scm_c_
60  @code{#include} into an initialization function.  @code{#include} into an initialization function.
61    
62  @menu  @menu
63  * How guile-snarf works::          Using @code{guile-snarf}, with example.  * How guile-snarf works::           Using @code{guile-snarf}, with example.
64  * Macros guile-snarf recognizes::  How to mark up code for @code{guile-snarf}.  * Macros guile-snarf recognizes::   How to mark up code for @code{guile-snarf}.
65    * Writing your own snarfing macros:: How to define new things to snarf.
66  @end menu  @end menu
67    
68  @c ---------------------------------------------------------------------------  @c ---------------------------------------------------------------------------
# Line 70  generate a file of calls to @code{scm_c_ Line 71  generate a file of calls to @code{scm_c_
71  @cindex guile-snarf invocation  @cindex guile-snarf invocation
72  @cindex guile-snarf example  @cindex guile-snarf example
73    
74  Usage: guile-snarf [-o OUTFILE] INFILE [CPP-OPTIONS ...]  Usage: guile-snarf [-o @var{outfile}] [@var{cpp-args} ...]
75    
76  What @code{guile-snarf} does:  The @code{guile-snarf} program will extract initialization actions to
77    @var{outfile} or to standard output when no @var{outfile} has been
78    specified or when @var{outfile} is @code{-}.  The C preprocessor is
79    called with @var{cpp-args} (which usually include an input file) and
80    the output is filtered to extract the initialization actions.
81    
82  Process INFILE using the C pre-processor and some other programs.  If there are errors during processing, @var{outfile} is deleted and the
83  Write output to a file named OUTFILE or to the standard output when no  program exits with non-zero status.
 OUTFILE has been specified or when OUTFILE is @code{-}.  
   
 If there are errors during processing, delete OUTFILE and exit with  
 non-zero status.  
   
 If env var CPP is set, use its value instead of the C pre-processor  
 determined at Guile configure-time.  
84    
85  During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is  During snarfing, the pre-processor macro @code{SCM_MAGIC_SNARFER} is
86  defined.  You can use this to avoid including snarfer output files  defined.  You could use this to avoid including snarfer output files
87  that don't yet exist by writing code like this:  that don't yet exist by writing code like this:
88  @example  
89  #ifndef SCM_MAGIC_SNARFER  @smallexample
90  #include "foo.x"  #ifndef SCM_MAGIC_SNARFER
91    #include "foo.x"
92  #endif  #endif
93  @end example  @end smallexample
94    
95    If the environment variable @code{CPP} is set, use its value instead of the
96    C pre-processor determined at Guile configure-time.
97    
98  @xref{Macros guile-snarf recognizes}, for a list of the special (some would  @xref{Macros guile-snarf recognizes}, for a list of the special (some would
99  say magic) cpp macros you can use, including the list of deprecated macros.  say magic) cpp macros you can use, including the list of deprecated macros.
# Line 108  SCM_DEFINE (clear_image, "clear-image", Line 110  SCM_DEFINE (clear_image, "clear-image",
110              "Clear the image.")              "Clear the image.")
111  #define FUNC_NAME s_clear_image  #define FUNC_NAME s_clear_image
112  @{  @{
113    /* C code to clear the image... */    /* C code to clear the image in @code{image_smob}... */
114  @}  @}
115  #undef FUNC_NAME  #undef FUNC_NAME
116    
# Line 122  init_image_type () Line 124  init_image_type ()
124    
125  The @code{SCM_DEFINE} declaration says that the C function  The @code{SCM_DEFINE} declaration says that the C function
126  @code{clear_image} implements a Scheme subr called @code{clear-image},  @code{clear_image} implements a Scheme subr called @code{clear-image},
127  which takes one required argument (type @code{SCM} named  which takes one required argument (of type @code{SCM} and named
128  @code{image_smob}), no optional arguments, and no tail argument.  @code{image_smob}), no optional arguments, and no rest argument.
129  @xref{Doc Snarfing}, for info on the docstring.  @xref{Doc Snarfing}, for info on the docstring.
130    
131  This works in concert with @code{FUNC_NAME} to also define a static  This works in concert with @code{FUNC_NAME} to also define a static
# Line 146  declarations, and writes to @file{image- Line 148  declarations, and writes to @file{image-
148  scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);  scm_c_define_gsubr (s_clear_image, 1, 0, 0, (SCM (*)() ) clear_image);
149  @end example  @end example
150    
151  When compiled normally, @code{SCM_DEFINE} is a macro which expands to a  When compiled normally, @code{SCM_DEFINE} is a macro which expands to
152  declaration of the @code{s_clear_image} string.  a declaration of the @code{s_clear_image} string and the function
153    header for @code{clear_image}.
154    
155  Note that the output file name matches the @code{#include} from the  Note that the output file name matches the @code{#include} from the
156  input file.  Also, you still need to provide all the same information  input file.  Also, you still need to provide all the same information
# Line 168  snarfcppopts = $(DEFS) $(INCLUDES) $(CPP Line 171  snarfcppopts = $(DEFS) $(INCLUDES) $(CPP
171  This tells make to run @code{guile-snarf} to produce each needed  This tells make to run @code{guile-snarf} to produce each needed
172  @file{.x} file from the corresponding @file{.c} file.  @file{.x} file from the corresponding @file{.c} file.
173    
174  Aside from the required argument INFILE, @code{guile-snarf} passes its  The program @code{guile-snarf} passes its command-line arguments
175  command-line arguments directly to the C preprocessor, which it uses to  directly to the C preprocessor, which it uses to extract the
176  extract the information it needs from the source code. this means you can pass  information it needs from the source code. this means you can pass
177  normal compilation flags to @code{guile-snarf} to define preprocessor symbols,  normal compilation flags to @code{guile-snarf} to define preprocessor
178  add header file directories, and so on.  symbols, add header file directories, and so on.
179    
180  @c ---------------------------------------------------------------------------  @c ---------------------------------------------------------------------------
181  @node Macros guile-snarf recognizes  @node Macros guile-snarf recognizes
# Line 221  ARGLIST is an argument list (in parenthe Line 224  ARGLIST is an argument list (in parenthe
224  is a expression suitable for initializing a new variable.  is a expression suitable for initializing a new variable.
225    
226  For procedures, you can use @code{SCM_DEFINE} for most purposes.  Use  For procedures, you can use @code{SCM_DEFINE} for most purposes.  Use
227  @code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't want  @code{SCM_PROC} along with @code{SCM_REGISTER_PROC} when you don't
228  to be bothered with docstrings.  Use @code{SCM_GPROC} for generic  want to be bothered with docstrings.  Use @code{SCM_GPROC} for generic
229  functions (@pxref{GOOPS,,,goops}).  All procedures are declared  functions (@pxref{GOOPS,,,goops}).  All procedures are declared with
230  @code{static} with return type @code{SCM}.  return type @code{SCM}.
231    
232  For everything else, use the appropriate macro (@code{SCM_SYMBOL} for  For everything else, use the appropriate macro (@code{SCM_SYMBOL} for
233  symbols, and so on).  The "_GLOBAL_" variants omit @code{static}  symbols, and so on).  Without "_GLOBAL_", the declarations are
234  declaration.  @code{static}.
235    
236  All these macros should be used at top-level, outside function bodies.  All these macros should be used at top-level, outside function bodies.
237  Also, it's a good idea to define @var{FUNC_NAME} immediately after using  Also, it's a good idea to define @var{FUNC_NAME} immediately after using
238  @code{SCM_DEFINE} (and similar), and then the function body, and then  @code{SCM_DEFINE} (and similar), and then the function body, and then
239  @code{#undef FUNC_NAME}.  @code{#undef FUNC_NAME}.
240    
 @c Here is the list of deprecated macros:  
   
 @c @c reminder: sync w/ libguile/guile-snarf.in var `deprecated_list'  
 @c @example  
 @c  SCM_CONST_LONG  
 @c  SCM_VCELL  
 @c  SCM_VCELL_INIT  
 @c  SCM_GLOBAL_VCELL  
 @c  SCM_GLOBAL_VCELL_INIT  
 @c @end example  
   
 @c Some versions of guile (and guile-snarf) will continue to recognize them but  
 @c at some point they will no longer work.  You can pass either @code{-d} or  
 @c @code{-D} option to have guile-snarf warn or signal error, respectively, if  
 @c any of these are found in the input file.  
   
241  @xref{How guile-snarf works}, and also libguile source, for examples.  @xref{How guile-snarf works}, and also libguile source, for examples.
242  @xref{Subrs}, for details on argument passing and how to write C  @xref{Subrs}, for details on argument passing and how to write C
243  functions.  functions.
244    
245  @c ---------------------------------------------------------------------------  @c ---------------------------------------------------------------------------
246    @node Writing your own snarfing macros
247    @subsubsection Writing your own snarfing macros
248    
249    When you want to use the general snarfing machanism, but none of the
250    provided macros fits your need, you can use the macro
251    @code{SCM_SNARF_INIT}.
252    
253    For example, the @code{SCM_SYMBOL} macro can be defined like this:
254    
255    @example
256    #define SCM_SYMBOL(c_name, scheme_name) \
257    static SCM c_name \
258    SCM_SNARF_INIT(c_name = scm_permanent_object (scm_str2symbol (scheme_name)))
259    @end example
260    
261    @defmac SCM_SNARF_INIT (code)
262    When processed normally, @code{SCM_SNARF_INIT} expands to nothing;
263    when processed by the snarfer, it causes @var{code} to be included in
264    the initialization action file, followed by a semicolon.
265    @end defmac
266    
267    @c ---------------------------------------------------------------------------
268  @node Doc Snarfing  @node Doc Snarfing
269  @subsection Doc Snarfing  @subsection Doc Snarfing
270    

Legend:
Removed from v.1.1.2.7  
changed lines
  Added in v.1.1.2.8

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