13.1 Init Snarfing

Because it's easier to maintain documentation, code, and other metainfo in one source file than in many files, there have evolved many methods for grepping source to lift and separate these kinds of info, in the process generating docs or fragments of source or what have you. This is known generally as snarfing, which comes from the verb “to snarf”, here meaning “to unceremoniously extract information from a somewhat unwilling source.”

This section documents the program c2x which is used for init snarfing. See Doc Maintenance, on the other hand, for doc snarfing.

When writing C code for use with Guile, you typically define a set of C functions, and then make some of them visible to the Scheme world by calling the scm_make_gsubr function; a C function published in this way is called a subr. If you have many subrs to publish, it can sometimes be annoying to keep the list of calls to scm_make_gsubr in sync with the list of function definitions. Frequently, a programmer will define a new subr in C, recompile the application, and then discover that the Scheme interpreter cannot see the subr, because of a missed call to scm_make_gsubr.

Guile provides the c2x program¹ to manage this problem. Using this tool, you can keep all the information needed to define the subr alongside the function definition itself; c2x will extract this information from your source code, and automatically generate a file of calls to scm_make_gsubr which you can #include in an initialization function.

• How c2x works: Using c2x, with example.
• Macros c2x recognizes: How to mark up code for c2x.
• Customizing init snarfing: SCM_SNARF_HERE and SCM_SNARF_INIT.