AutoGen's Frequently Asked Questions


XML Defs


Man example
local use
using getopt






Project GNU
Home Page


xdr project


This is a collection of issues that have come up and some approaches to solving them. As I collect more, I'll add some organization, too.

1.How can I keep the option version consistent with configure?
2.Are there any Finite State Machine examples?
3.Does it work on OS/X?
4.Is there a sample project that uses AutoGen and/or AutoOpts?
5.Can I call optionProcess a second time with different arguments? It seems the parser works only once.
6.How can I best manage a daemon configuration? The configuration is very complicated and I don't want folks going in and editing it willy nilly. Besides, the configuration files are on an embedded application, so we discourage direct access to the system anyway.
7.Are option name words separated with '-' or '_'?
8.Why doesn't AutoOpts handle floating point option arguments?
9.How can I create varied combinations and permutations?

After banging my head on a wall with C++ templates and related compiler incompatibilities I found AutoGen. I have done RTFM...but I haven't found a straightforward way to generate combinations/permutations.

An example: implementing routines for graphics composition where parameters can be either bitmaps or constant colors.

process( bitmap*, bitmap*, bitmap*, bitmap* ); // Bitmap only form
process( color, bitmap*, color, color ); // mixed bitmaps and colors
process( color, color, color, color ); // all colors

You could do this in the definition file [by laboriously enumerating the various possibilities, but that does not seem to buy you anything.]

Any tips?

How can I keep the option version consistent with configure?

There are several possible approaches. Well, lots of approaches, but I'll enumerate a few here:
  1. AutoGen definitions can derive their string value from the output of a shell script. Therefore, you can grep and sed the `' file.

  2. `configure' (`') is just a shell script, too. It can run a script whose purpose is to echo out the version, so both `configure' and AutoGen can easily use the same script.

  3. You can make an `' template and generate `' from AutoGen. This would mean, however, you could not run configure before this.

  4. You can make a `' file and create `version.def' when you run configure. Likewise, this would mean you would have to configure the product before generating any files that needed the version from `version.def'.

Are there any Finite State Machine examples?

There is the FSM example page itself, but AutoGen also uses three finite state machines:
agen5/cgi.def  produces cgi-fsm.c and cgi-fsm.h. These are used to scan CGI script values for conversion into AutoGen definitions.
pseudo.def  produces pseudo-fsm.h, which is used in the file loadPseudo.c. That FSM does not produce any code. The table produced is used to parse the pseudo macro at the start of a template.
defParse.def  produces defParse-fsm.c and defParse-fsm.h. This code drives the parsing of the definition files.

Does it work on OS/X?

It should now. Further, the fink project has a package for it.

Is there a sample project that uses AutoGen and/or AutoOpts?

There is now a sample project, blocksort. This sample integrates the redistributable libopts library source.

For most users, this is likely too much work. For simple, locally built projects, this is likely to be sufficient:

In your project directory create the option definition file: ``projopts.def'', per instructions in the manual.
Add to (or Makefile):

  projopts.c projopts.h : opts-stamp
  opts-stamp : projopts.def
      autogen projopts.def && touch $@

  project.1 : projopts.def
      autogen -Tagman-cmd.tpl -b project projopts.def

  projinvoke.texi : projopts.def project
      autogen -Taginfo.tpl -bprojinvoke -DLEVEL=section projopts.def

And add ``-I${prefix}/include'' to your compiles and ``-L${prefix}/lib -lopts'' to your link, where ``${prefix}'' is the autogen installation prefix.

If you use autoconf and automake, this can be done in an automated fashion. Place the distributed file "autoopts.m4" in your configure directory. In your file, invoke the AG_PATH_AUTOOPTS macro. Now back to your Use the following substitution values for your compile and link commands.


Can I call optionProcess a second time with different arguments?

You can parse the options multiple times. First, before calling optionProcess, call optionSaveState. Then, before calling optionProcess the second time, call optionRestore.

How can I best manage a daemon configuration?

Write two programs that use the same set of options. One is your daemon program and the other handles changes to its configuration. It's main routine needs to do three or four things:
  • call optionProcess() to process both the config file and any command line options.
  • call optionSaveFile() to save the new version of the config file.
  • (optionally) it may need to copy the new file version into place
  • If all is well, then tell the daemon process to reload its configuration.

Are option name words separated with '-' or '_'?

Either. Option names are case insensitive and the word separators can be any of the three characters '-', '_' and even '^'. (I worked at Tandem for a while.) Consequently, all of these are equivalent:
Of course, the leading hyphens must be hyphens.

Why doesn't AutoOpts handle floating point option arguments?

Because handling it yourself is trivial, handling it in a fully integrated fashion is hard and I don't use floating point myself.

That's the short answer. Here are the details for the first two parts:

  1. Write your own callback routine.

    flag = {
        name      = something;
        value     = s;
        arg-type  = string;
        arg-name  = float;
        descrip   = "floating point argument";
        doc = "Example of an option with a floating point arg.";
        flag-code = <<-  EOF
                extern double val;
                sscanf( pOptDesc->pzLastArg, "%f", &val );
                if (validations_fail) {
                    fprintf( stderr, "bad float for 'something'\n" );
                    USAGE( EXIT_FAILURE );
            EOF ;
  2. Provide a patch to extend the arg-type handling. :-)

    You would probably need to fiddle with the various opt*.tpl files and the documentation templates (agman-cmd.tpl and agtexi-cmd.tpl) and you would need to add a bit flag to the option descriptor flag bits and worry about how to save the data (save.c) and even how to keep the data (since floating point numbers do not fit in void*/char* buckets).

    This would be a fair bit of work, but it would be very nice to have. I don't use floating point myself (or it would already be done). The do-it-yourself solution is pretty easy, but, if you do do this and get it working (or even mostly working), I'll accept the patch and add first-class support for floating point option arguments.

How can I create varied combinations and permutations?

cat > process.tpl <<_EOF_
[+ autogen5 template h +]
[+ FOR arg1     in "bitmap*" color \+]
[+   FOR arg2   in "bitmap*" color \+]
[+     FOR arg3 IN "bitmap*" color

+]process( [+arg1+], [+arg2+], [+arg3+] );
[+     ENDFOR \+]
[+   ENDFOR   \+]
[+ ENDFOR     \+]
autogen -b process --no-defin -Tprocess.tpl

And you wind up with this process.h file:

process( bitmap*, bitmap*, bitmap* );
process( bitmap*, bitmap*, color );
process( bitmap*, color, bitmap* );
process( bitmap*, color, color );
process( color, bitmap*, bitmap* );
process( color, bitmap*, color );
process( color, color, bitmap* );
process( color, color, color );

I'll also take a guess that you would want a similar nested set of loops for the method implementation code that would convert their color args to bit maps and invoke the canonical method:

process(bitmap*, bitmap*, bitmap*)
That implementation code can be generated, too.

process(color a, bitmap* b, color c) {
  return process( color2bits(a), b, color2bits(c));

top  Viewable With Any Browser  Valid XHTML 1.0!

AutoGen, AutoOpts, columns, getdefs, AutoFSM, AutoXDR and these web pages copyright (c) 1999-2012 Bruce Korb, all rights reserved.

Return to GNU's home page.

Please send FSF & GNU inquiries & questions to There are also other ways to contact the FSF.

Please send comments on these web pages to, send other questions to

This article, Copyright © 2000-2002 by Bruce Korb

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. Last modified: Sat Aug 30 11:01:39 PDT 2014