Posts: Autoconf

Diversions in Autoconf (actually, in M4sugar)

Have you ever wondered how Autoconf reorganizes certain parts of your script regardless of the order in which you invoke the macros in your configure.ac script? For example, how come you can define --with-* and --enable-* flags anywhere in your script and these are all magically moved to the option-processing section of the final shell script? After all, Autoconf is just a collection of M4 macros, and a macro preprocessor's only work is to expand macros in the input with predefined output texts. Isn't it?

Enter M4sugar's diversions. Diversions are a mechanism that allows M4 macros to output code to different text blocks, which are later concatenated in a specific order to form the final script.

Let's consider an example (based on a few M4 macros to detect the ATF bindings from your own configure scripts). Suppose you want to define a macro FROB_ARG to provide a --with-frob argument whose argument must be either "yes" or "no". Also suppose you want to have another macro FROB_CHECK to detect whether libfrob exists. Lastly, you want the user to be able to use these two independently: when FROB_CHECK is used without invoking FROB_ARG first, you want it to unconditionally look for the library; otherwise, if FROB_ARG has been used, you want to honor its value.

We could define these macros as follows:

AC_DEFUN([FROB_ARG], [
    AC_ARG_WITH([frob],
                [AS_HELP_STRING([--with-frob=yes|no], [enable frob])],
                [with_frob=${withval}, [with_frob=yes]) 
])

AC_DEFUN([FROB_CHECK], [
    m4_divert_text([DEFAULTS], [with_frob=yes])

    if test "${with_frob}" = yes; then
        ... code to search for libfrob ... 
    elif test "${with_frob}" = no; then
        :  # Nothing to do. 
    else
        AC_MSG_ERROR([--with-frob must be yes or not]) 
    fi
])

Note the m4_divert_text call above: this macro invocation tells M4sugar to store the given text (with_frob=yes) in the DEFAULTS diversion. When the script is later generated, this text will appear at the beginning of the script before the command-line options are processed, completely separated from the shell logic that consumes this value later on.

With this we ensure that the with_frob shell variable is always defined regardless of the call to the FROB_ARG macro. If this macro is called, with_frob will be defined during the processing of the options and will override the value of the variable defined in the DEFAULTS section. However, if the macro has not been called, the variable will keep its default value for the duration of the script.

Of course, this example is fictitious and could be simplified in other ways. But, as you can see in the referred change and in the Autoconf code itself, diversions are extensively used for trickier purposes. In fact, Autoconf uses diversions to topologically sort macro dependencies in your script and output them in a specific order to satisfy cross-dependencies.

Isn't that cool?  I can't cease to be amazed, but I also don't dare to look at how this works internally for my own sanity...

September 6, 2011 · Tags: atf, autoconf, m4
Continue reading (about 3 minutes)