gEDA and Guile — finding Scheme API code in gEDA

The response to my previous post was overwhelmingly in favour of continuing and merging my work on gEDA extensibility using Guile Scheme, both here and on the gEDA mailing lists. Some people asked how they could help out, and so I'm going to write a series of blog posts with some information on how gEDA uses Scheme and some easy introductory tasks that would be useful.

1. Finding Scheme API code in gEDA
2. Compiling against multiple Guile versions
3. Safe handling of non-local exits
4. Dealing with deprecated libguile functions
5. Checking arguments to Scheme functions in C
6. How and when to use Scheme errors
7. Reducing boilerplate with "snarfing macros"
8. Opportunities to get involved

In this blog post, I'll explain where Guile is used in gEDA at the moment, both C code using libguile and Scheme code itself.

What is Scheme used for?

Currently, Guile is used for:

• Executing "configuration" files (actually initialisation files) written in Scheme, in all libgeda applications.
• Setting up the menus and keybindings in gschem. Key sequences and menu items call Scheme "thunks" (functions of no arguments), which are mostly implemented in C. It's not currently feasible to create a meaningful new action in gschem without writing it mostly in C.
• Exporting netlists in gnetlist. A gnetlist backend generates particular on-disk netlist file format using a limited API that provides access to the compiled netlist.
• A few other things (mostly incomplete). For example, there is a very limited existing Scheme API spread between gschem and libgeda for taking actions on changes to pages and/or attributes.

It would be nice to do more things (like extending gschem with additional actions written in pure Scheme, or being able to modify the way that gnetlist compiles a netlist from input schematics).

Where is the Guile code in gEDA?

In the C sources, files which contain code using libguile usually begin with the prefix "g_". For example, "g_rc.c" contains definitions of functions used for configuration parameters, and "g_register.c" contains code for registering C functions and variables to be visible from Scheme. There are a bunch of exceptions to be aware of, which include:

• libgeda/src/s_clib.c contains some libguile code that permits component libraries to be defined as a set of Scheme functions.
• libgeda/src/s_menu.c contains some basic infrastructure for menu definitions in Scheme rc files that's past due to move into gschem.
• libgeda/src/s_menu.c has functions for converting gEDA colour map data to and from Scheme representations.
• Several gschem source files contain snippets of libguile code for firing hooks when the user carries out certain actions.
• gschem/src/x_menus.c implements menus defined in Scheme, and gschem/src/x_stroke.c provides support for assigning gestures to actions in Scheme (which capability I'm not sure I've ever used).

More generally, you can usually find code that uses libguile by searching for the "scm_" or "SCM_" prefix used by libguile functions, macros and variables.

Most of the application directories in the gEDA source tree have a "scheme" subdirectory where most of the ".scm" files with Scheme code live. There are also the system rc files for each application, which are also written in Scheme but for some reason live in "lib" subdirectories.

So that's a brief overview of where the Scheme-related code lives in gEDA. In my next post, I will talk about how to set up your build environment to be able to easily build against either Guile 1.8 or Guile 2.0.