This page provides an overview to OpenOCD's use of the GNU autotool suite:

Most developers do not need to concern themselves with these tools, as the Autotools Bootstrap script runs these tools in the required sequence.

Autotools Bootstrap

The bootstrap script should be used by developers to run the autotools in the correct sequence.

When run after a fresh checkout, this script generates the build files required to compile the project, producing the project configure script.

Problems Solved By Bootstrap

For example, the build system can fail in unexpected ways after running git pull. Here, the make maintainer-clean should be used to remove all of the files generated by the bootstrap script and subsequent build processes.

In this particular case, one may also need to remove stray files by hand after running this command to ensure everything is rebuilt properly. This step should be necessary only if the maintainer-clean was run after altering the build system files with git. If it is run before any updates, the build system should never leave artifacts in the tree.

Without such precautions, changes can be introduced that leave the tree timestamps in an inconsistent state, producing strange compile errors that are resolve after such diligence.

Autotools Cleaning

Normally, all files generated by the bootstrap script, configure process, and build system should be removed after running make maintainer-clean. Automatically generated files that remain after this should be listed in MAINTAINERCLEANFILES, DISTCLEANFILES, or CLEANFILES, depending on which stage of the build process they are produced.

Autoconf Configuration Script

The autoconf program generates the configure script from configure.in, using serious Perl voodoo. The resulting script is included in the project distribution packages and run by users to configure the build process for their system.

Automake Makefiles

The automake program generates Makefile.in files (from Makefile.am files). These files are later processed by the configure script produced by autoconf.

Creating Makefile.am Files

This section shows how to add a Makefile.am in a new directory (or one that lacks one).

The new directory must be listed in the SUBDIRS variable in the parent directory's Makefile.am:
$ echo 'SUBDIRS += directory' >>../Makefile.am
Create an bare-bones Makefile.am file in directory that needs it:
$ echo "MAINTAINERCLEANFILES = Makefile.in" >Makefile.am
The configure.in script must be updated, so it generates the required Makefile when the configure script is run by the user:
```
AC_OUTPUT([
        ...
        path/to/new/Makefile
    ])
```

Note: these instructions are not meant to be used literally, rather they are shown for demonstration purposes.

The default MAINTAINERCLEANFILES rule ensures that the automake-generated Makefile.in file will be removed when developers run make maintainer-clean. Additional rules may be added after this; however, the project should bootstrap and tear down cleanly after taking these minimal steps, with the new directory being visited during the make sequence.

Updating Makefile.am Files

Adding, removing, and renaming files from the project tree usually requires updating the autotools inputs. This section will help describe how to do this as questions arise.

Libtool and Libraries

The libtool program provides the means of generating libraries in a portable and painless manner (relatively speaking).

This section will contain an answer to "what does libtool give OpenOCD?" and "what do developers need to consider in new code?"

Autotools Automation

This section outlines three ways the autotools provides automation to assist with testing and distribution:

make check – automatic unit and smoke tests
make distcheck – automatic distribution and packaging tests

make check

The make check command will run the OpenOCD test suite, once it has been integrated as such. This section will contain information about how to extend the testing build system components to implement new checks.

make distcheck

The make distcheck command produces an archive of the project deliverables (using make dist) and verifies its integrity for distribution by attempting to use the package in the same manner as a user.

These checks includes the following steps:

Unpack the project archive into its expected directory.
Configure and build the project in a temporary out-of-tree directory.
Run make check to ensure the distributed code passes all tests.
Run make install into a temporary installation directory.
Check that make uninstall removes all files that were installed.
Check that make distclean removes all files created during all other steps (except the first).

If all of these steps complete successfully, the make process will output a friendly message indicating the archive is ready to be distributed.