AutoGen: Quick Start

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 7.2 Quick Start

Since it is generally easier to start with a simple example than it is to look at the options that AutoGen uses itself, here is a very simple AutoOpts example. You can copy this example out of the Info file and into a source file to try it. You can then embellish it into what you really need. For more extensive examples, you can also examine the help output and option definitions for the commands `columns`, `getdefs` and `autogen` itself.

For our simple example, assume you have a program named `check` that takes two options:

1. A list of directories to check over for whatever it is `check` does. You want this option available as a POSIX-style flag option and a GNU long option. You want to allow as many of these as the user wishes.
2. An option to show or not show the definition tree being used. Only one occurrence is to be allowed, specifying one or the other.

First, specify your program attributes and its options to AutoOpts, as with the following example.

    AutoGen Definitions options;
    prog-name     = check;
    prog-title    = "Checkout Automated Options";
    long-opts;
    test_main;

    flag = {
        name      = check_dirs;
        value     = L;        /* flag style option character */
        arg_type  = string;   /* option argument indication  */
        max       = NOLIMIT;  /* occurrence limit (none)     */
        stack_arg;            /* save opt args in a stack    */
        descrip   = "Checkout directory list";
    };

    flag = {
        name      = show_defs;
        descrip   = "Show the definition tree";
        disable   = dont;     /* mark as enable/disable type */
                              /* option.  Disable as `dont-' */
    };

Then perform the following steps:

1. `autogen checkopt.def`
2. `cc -o check -DTEST_CHECK_OPTS -g checkopt.c -L $prefix/lib -lopts`

And now, `./check --help` yields:

    check - Checkout Automated Options
    USAGE:  check [-<flag> [<val>]]... [--<name>[{=| }<val>]]...
      Flg Arg Option-Name    Description
       -L YES check-dirs     Checkout directory list
                                    - may appear without limit
          no  show-defs      Show the definition tree
                                    - disabled as --dont-show-defs
       -? no  help           Display usage information and exit
       -! no  more-help      Extended usage information passed thru pager

    Options may be specified by doubled markers and their name
    or by a single marker and the flag character/option value.

Normally, however, you would compile ``checkopt.c'` as in:

    cc -o checkopt.o -I$prefix/include -c checkopt.c

and link ``checkopt.o'` with the rest of your program. The main program causes the options to be processed by calling `optionProcess` (see section 7.4.28.3 optionProcess):

    main( int argc, char** argv )
    {
      {
        int optct = optionProcess( &checkOptions, argc, argv );
        argc -= optct;
        argv += optct;
      }

The options are tested and used as in the following fragment. "`ENABLED_OPT`" is used instead of "`HAVE_OPT`" for the `show-defs` option because it is an enabled/disabled option type:

      if (  ENABLED_OPT( SHOW_DEFS )
         && HAVE_OPT( CHECK_DIRS )) {
        int    dirct = STACKCT_OPT( CHECK_DIRS );
        char** dirs  = STACKLST_OPT( CHECK_DIRS );
        while (dirct-- > 0) {
          char* dir = *dirs++;
          ...

A lot of magic happens to make this happen. The rest of this chapter will describe the myriad of option attributes supported by AutoOpts. However, keep in mind that, in general, you won't need much more than what was described in this "quick start" section.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Bruce Korb on February 23, 2004 using texi2html