trip logs / gnuovla


Trip Log 2017-03-31 h15

Today I continue the thrust started in yesterday's trip log with more programming plus documentation pointers.  In this case, the programming and documentation concern infrastructure for the configuration of some Emacs Lisp packages that I maintain, namely EDB and ZOW.  Configuration is an important part of a package's deployment, and the GNU Project (which I take much inspiration from) has quite a bit to say on the topic.  The infrastructure for GNU-ish configuration is the so-called “Autotools” suite, and the bit I did was to write and document a pair of “m4 macro libraries” for eventual use via GNU Autoconf.  These libraries are named "ax_prog_emacs" and "ax_elisp".  Here is a (simplified) diagram that shows how they fit into the big picture: 

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                                                         ┃
┃ ax_prog_emacs.m4 ──┐                                    ┃
┃                    │                                    ┃
┃ ax_elisp.m4 ───────┴────┬───────────────────────┐       ┃
┃                         │                       │       ┃
┃                         v                       v       ┃
┃                        EDB                     ZOW      ┃
┃                    configure.ac            configure.ac ┃
┃                         │                       │       ┃
┃ GNU Autoconf ───────────┼───────────────────────┤       ┃
┃                         │                       │       ┃
┃                         v                       v       ┃
┃                        EDB                     ZOW      ┃
┃                     configure               configure   ┃
┃                                                         ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Here, "configure.ac" and "configure" are filenames.  To make a release, I generate "configure" from "configure.ac", using GNU Autoconf to incorporate the definitions in "ax_prog_emacs" and "ax_elisp".  The libraries' documentation is (like yesterday) embedded in the source code.  Here are the documentation excerpts: 

# SYNOPSIS
#
#   AX_PROG_EMACS
#
# DESCRIPTION
#
#   This macro allows the end user to specify a particular Emacs executable
#   via a configure script command-line arg. For example:
#
#     ./configure EMACS=$HOME/build/GNU/emacs/src/emacs
#
#   It also arranges to mention env var EMACS in the './configure --help'
#   output. See info node "(autoconf) Generic Programs" for details.
#
#   More precisely...
#
#   If env var EMACS is set, try to use its value directly, but avoid
#   getting fooled by value 't' (set by older Emacsen for subprocesses). If
#   no joy from the environment, search for "emacs" via AC_CHECK_PROG. If
#   still no joy, display "Emacs not found; required!" and make configure
#   exit failurefully. Otherwise, set shell var EMACS and AC_SUBST it, too.

and

# SYNOPSIS
#
#   AX_ELISP_CONFIG_FILE(FILENAME)
#   AX_ELISP_CHECK(SYMBOL,DESCRIPTION,BODY,SUCCESS-EXPR)
#   AX_ELISP_CHECK_FEATURE(SYMBOL)
#   AX_ELISP_CHECK_FBOUNDP(SYMBOL,[FEATURE [...]])
#   AX_ELISP_CHECK_BOUNDP(SYMBOL,[FEATURE [...]])
#
# DESCRIPTION
#
#   This is a simple library to check the Emacs reality by way of Emacs Lisp
#   forms evaluated under $EMACS --batch -Q. This means you MUST have the
#   shell variable EMACS set to a valid Emacs executable prior to the first
#   call to any of the AX_ELISP_CHECK et al macros. Those work by saving
#   their results to the file defined by calling AX_ELISP_CONFIG_FILE so you
#   MUST call that prior, too. For example:
#
#     dnl Arrange to save config answers in $top_builddir/lisp/config.el.
#     AX_ELISP_CONFIG_FILE([lisp/config.el])
#
#     dnl Set shell variable EMACS and AC_SUBST it, too.
#     dnl (NB: This is a separate Autoconf Archive macro.)
#     AX_PROG_EMACS
#
#   In the following detailed descriptions, SYMBOL stands for an Emacs Lisp
#   symbol, which may contain hyphens, e.g., 'define-error' or 'org-src'.
#   Likewise, FEATURE is an Emacs Lisp symbol (naming a feature). BODY and
#   SUCCESS-EXPR are Emacs Lisp forms, zero or more for BODY and exactly one
#   for SUCCESS-EXPR. In these forms you must take care to avoid apostrophe
#   (U+27). Instead of 'foo, write (quote foo).
#
#   * AX_ELISP_CONFIG_FILE(FILENAME)
#
#   This arranges for future AX_ELISP_CHECK (et al) calls to save their
#   results in FILENAME. May be called multiple times. FILENAME should be
#   relative to the top build dir.
#
#   * AX_ELISP_CHECK(SYMBOL,DESCRIPTION,BODY,SUCCESS-EXPR)
#
#   This is the general macro that the other AX_ELISP_CHECK* macros use. It
#   constructs a short Emacs Lisp file comprising BODY and evaluates it via
#   $EMACS --batch -Q. The exit value of this script depends on the result
#   of evaluating SUCCESS-EXPR: non-nil is success and nil is failure. On
#   success, append SYMBOL on a line of its own to the config file. This
#   macro uses AC_CACHE_CHECK and passes DESCRIPTION to it.
#
#   * AX_ELISP_CHECK_FEATURE(FEATURE)
#
#   This checks if (require (quote FEATURE)) is successful. If so, add
#   featurep-FEATURE to the config file (NB the "featurep-" prefix).
#
#   * AX_ELISP_CHECK_FBOUNDP(SYMBOL,[FEATURE [...]])
#
#   This checks if (fboundp (quote SYMBOL)) is successful. If so, append
#   SYMBOL to the config file. Optional 2nd arg is a space-separated list of
#   features to require prior to the fboundp check.
#
#   * AX_ELISP_CHECK_BOUNDP(SYMBOL,[FEATURE [...]])
#
#   This checks if (boundp (quote SYMBOL)) is successful. If so, append
#   SYMBOL to the config file. Optional 2nd arg is a space-separated list of
#   features to require prior to the boundp check.

The names of the libraries both begin with "ax_" because the eventual goal is to contribute them to the GNU Autoconf Archive.  I've already made inquiries towards that goal.  In a future trip log entry, I will go into detail about what the macros do, and how they are used. 

To recap, this trip log entry demonstrates (in a small way) my skill in writing maintainance-oriented software and documentation, transparency of intent and goodwill to the Free Software community, and some light-hearted momentum in the self-marketing space.  Are you a potential employer?  Are you impressed?  :-D  Well, maybe next time... 


Copyright (C) 2017 Thien-Thi Nguyen