6. Configuring and Installing

6.1 Configuring AutoGen

AutoGen is configured and built using Libtool, Automake and Autoconf. Consequently, you can install it whereever you wish using the various `--prefix' options. To the various configuration options supplied by these tools, AutoGen adds a few of its own:

`--disable-shell'

AutoGen is now capable of acting as a CGI forms server, See section 6.2 AutoGen as a CGI server. As such, it will gather its definitions using either `GET' or `POST' methods. All you need to do is have a template named `cgi.tpl' handy or specify a different one with a command line option.

However, doing this without disabling the server shell brings considerable risk. If you were to pass user input to a script that contained, say, the classic "``rm -rf /`'", you might have a problem. This configuration option will cause shell template commands to simply return the command string as the result. No mistakes. Much safer. Strongly recommended. The default is to have server shell scripting enabled.

Disabling the shell will have some build side effects, too.

• Many of the make check tests will fail, since they assume a working server shell.
• The getdefs and columns programs are not built. The options are distributed as definition files and they cannot be expanded with a shell-disabled AutoGen.
• Similarly, the documentation cannot be regenerated because the documentation templates depend on subshell functionality.

`--enable-debug'

Turning on AutoGen debugging enables very detailed inspection of the input definitions and monitoring shell script processing. These options are not particularly useful to anyone not directly involved in maintaining AutoGen. If you do choose to enable AutoGen debugging, be aware that the usage page was generated without these options, so when the build process reaches the documentation rebuild, there will be a failure. `cd' into the `agen5' build directory, `make' the `autogen.texi' file and all will be well thereafter.

`--with-regex-header'

`--with-header-path'

`--with-regex-lib'

These three work together to specify how to compile with and link to a particular POSIX regular expression library. The value for `--with-regex-header=value' must be the name of the relevant header file. The AutoGen sources will attempt to include that source with a #include <value> C preprocessing statement. The path from the `--with-header-path=path' will be added to CPPFLAGS as `-Ipath'. The lib-specs from `--with-regex-lib=lib-specs' will be added to LDFLAGS without any adornment.

6.2 AutoGen as a CGI server

AutoGen is now capable of acting as a CGI forms server. It behaves as a CGI server if the definitions input is from stdin and the environment variable REQUEST_METHOD is defined and set to either "GET" or "POST". If set to anything else, AutoGen will exit with a failure message. When set to one of those values, the CGI data will be converted to AutoGen definitions (see section 2. AutoGen Definitions File) and the template named "cgi.tpl" will be processed.

This works by including the name of the real template to process in the form data and having the "cgi.tpl" template include that template for processing. I do this for processing the form http://autogen.sourceforge.net/conftest.html. The "cgi.tpl" looks approximately like this:

<? AutoGen5 Template ?>
<?
IF (not (exist? "template"))                       ?><?
  form-error                                       ?><?

ELIF (=* (get "template") "/")                     ?><?
  form-error                                       ?><?

ELIF (define tpl-file (string-append "cgi-tpl/"
                      (get "template")))
     (access? tpl-file R_OK)                       ?><?
  INCLUDE (. tpl-file)                             ?><?

ELIF (set! tpl-file (string-append tpl-file ".tpl"))
     (access? tpl-file R_OK)                       ?><?
  INCLUDE (. tpl-file)                             ?><?

ELSE                                               ?><?
  form-error                                       ?><?
ENDIF                                              ?>

This forces the template to be found in the "cgi-tpl/" directory. Note also that there is no suffix specified in the pseudo macro (see section 3.1 Format of the Pseudo Macro). That tells AutoGen to emit the output to stdout.

The output is actually spooled until it is complete so that, in the case of an error, the output can be discarded and a proper error message can be written in its stead.

Please also note that it is advisable, especially for network accessible machines, to configure AutoGen (see section 6.1 Configuring AutoGen) with shell processing disabled (--disable-shell). That will make it impossible for any referenced template to hand data to a subshell for interpretation.

6.3 Signal Names

When AutoGen is first built, it tries to use psignal(3), sys_siglist, strsigno(3) and strsignal(3) from the host operating system. If your system does not supply these, the AutoGen distribution will. However, it will use the distributed mapping and this mapping is unlikely to match what your system uses. This can be fixed. Once you have installed autogen, the mapping can be rebuilt on the host operating system. To do so, you must perform the following steps:

1. Build and install AutoGen in a place where it will be found in your search path.

2. cd ${top_srcdir}/compat

3. autogen strsignal.def

4. Verify the results by examining the `strsignal.h' file produced.

5. Re-build and re-install AutoGen.

If you have any problems or peculiarities that cause this process to fail on your platform, please send me copies of the header files containing the signal names and numbers, along with the full path names of these files. I will endeavor to fix it. There is a shell script inside of `strsignal.def' that tries to hunt down the information.

6.4 Installing AutoGen

There are several files that get installed. The number depend whether or not both shared and archive libraries are to be installed. The following assumes that everything is installed relative to $prefix. You can, of course, use configure to place these files where you wish.

NB AutoGen does not contain any compiled-in path names. All support directories are located via option processing, the environment variable HOME or finding the directory where the executable came from.

The installed files are:

1. The executables in `bin' (autogen, getdefs and columns).

2. The AutoOpts link libraries as `lib/libopts.*'.

3. An include file in `include/options.h', needed for Automated Option Processing (see next chapter).

4. Several template files and a scheme script in `share/autogen', needed for Automated Option Processing (see section 7. Automated Option Processing), parsing definitions written with scheme syntax (see section 2.4 Dynamic Text), the templates for producing documentation for your program (see section 7.3.5 Man and Info doc Attributes), autoconf test macros, and AutoFSM.

5. Info-style help files as `info/autogen.info*'. These files document AutoGen, the option processing library AutoOpts, and several add-on components.

6. The three man pages for the three executables are installed in man/man1.

This program, library and supporting files can be installed with three commands:

• <src-dir>/configure [ <configure-options> ]
• make
• make install

However, you may wish to insert make check before the make install command.

If you do perform a make check and there are any failures, you will find the results in <module>/test/FAILURES. Needless to say, I would be interested in seeing the contents of those files and any associated messages. If you choose to go on and analyze one of these failures, you will need to invoke the test scripts individually. You may do so by specifying the test (or list of test) in the TESTS make variable, thus:

gmake TESTS=test-name.test check

I specify gmake because most makes will not let you override internal definitions with command line arguments. gmake does.

All of the AutoGen tests are written to honor the contents of the VERBOSE environment variable. Normally, any commentary generated during a test run is discarded unless the VERBOSE environment variable is set. So, to see what is happening during the test, you might invoke the following with bash or ksh:

VERBOSE=1 gmake TESTS="for.test forcomma.test" check

Or equivalently with csh:

env VERBOSE=1 gmake TESTS="for.test forcomma.test" check