Quoting Text for Autoconf

Main
AutoGen
Pages

Home
Announce
FAQ
docs
XML Defs
testimonials
downloads

Automated
Options

AutoOpts
Comparison
Man example
Redistribute
Licensing
local use
using getopt

GCC's
Fixincludes

fixincludes

Automated
FSM

description
example
usagefsm

Addons
addon

Autoconf
Config
Tests

create form
M4 Quoting

Automated
XDR

xdr project

i Autoconf is primarily a collection of M4 macros that are used to permute your supplied text into the desired result. This alleviates the need for you to type in all the repetitive text necessary for doing configure tests and it also makes it possible to fix bugs and change implementation without going back and fixing all the scripts that use the algorithms.

This page describes the derivation of the problem. I found it very helpful to know what the issues were that led to the current situation.

The issue with quoting evolved mostly as follows:

  • To work, M4 needs to be able to determine where the start and end of text are for each of its macro arguments. It does this by collecting text between the "(", "," and ")" characters.
  • Sometimes, however, you need these characters as part of the macro argument string. Therefore, M4 adds the notion of quoting a string. In vanilla M4, you can quote a string by surrounding the text with "`" and "'" characters.

  • In order to include these characters, they must be quoted. But since they are also the quote characters, they must be balanced within the quoted string. You must make sure they are properly ordered and nested. M4 will keep track of the depth and preserve the nested quotation characters.

  • Autoconf has a problem with this. In programming, these two quoting characters are used often and used for different purposes. Consequently, they will rarely happen to match. M4 provides a feature that Autoconf takes advantage of: changequote().

    With that special built-in macro, you can change the quoting characters to another pair of tokens that may, in fact, be several characters long. Autoconf did not take advantage of that, it changed it to "[" and "]" instead.

  • That mostly works in the programming world. That is because square brackets are generally used in pairs and so they behave as properly nested quotes in Autoconf's m4 files. The problems are the "mostly balanced" part, of course, and they will disappear on you if they are not quoted when they are evaluated. Ick.

Autoconf's solution for this is ``quadrigraphs''. These are very ugly four-character improbable sequences that get replaced in a final pass through sed(1) to emit the configure program. The reason Autoconf chose to do this instead of merely having users change quotes around the macro arguments was because the macro arguments are allowed to and encouraged to use Autoconf macros within them. If you change quotes around an Autoconf macro, M4 will become confused because the macro was written on the assumption that it knew what the current quoting phrases are (viz., "[" and "]").

As a consequence, you, the Autoconf macro developer should, in general, do everything you can to write code that either does not contain square brackets, or only contains them in balanced pairs.

If that is not possible for some circumstance, you may either:

  • Replace the square bracket characters that cause the imbalance with quadrigraphs. You should have AutoGen leave the text alone because the quote phrases are now balanced again, or
  • Have AutoGen blindly replace all Autoconf-problematic characters with quadrigraphs. Who cares if it's ugly. Don't look at it. Just beware, quoted arguments to contained Autoconf macros will have those quoting square brackets replaced, too. That is certain to confuse any Autoconf macros that exist within arguments to other macros.

Well, that's pretty much it. You are now an expert on Autoconf's use of M4 quoting. Your final exam consists of creating and using an autoconf macro yourself. To do this, you can:

  1. Use the conftest macro generation page,
  2. Copy and use or modify a macro from the Autoconf macro archive, or
  3. Write an Autoconf macro directly.

Whichever, please let me () know if you found this page useful.


top  Viewable With Any Browser  SourceForge Logo   Support This Project   Valid XHTML 1.0!


AutoGen, AutoOpts, columns, getdefs, AutoFSM, AutoXDR and these web pages copyright (c) 1999-2012 Bruce Korb, all rights reserved.
Last modified: Fri Aug 21 13:28:14 PDT 2015