168 lines
6.7 KiB
Plaintext
168 lines
6.7 KiB
Plaintext
/** @page primerautotools OpenOCD Autotools Primer
|
|
|
|
This page provides an overview to OpenOCD's use of the GNU autotool suite:
|
|
- @ref primerautoconf
|
|
- @ref primerautomake
|
|
- @ref primerlibtool
|
|
|
|
Most developers do not need to concern themselves with these tools, as
|
|
the @ref primerbootstrap script runs these tools in the required sequence.
|
|
|
|
@section primerbootstrap Autotools Bootstrap
|
|
|
|
The @c 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.
|
|
After running @c configure, the @ref primermaintainermode settings will
|
|
handle most situations that require running these tools again. In some
|
|
cases, a fresh bootstrap may be still required.
|
|
|
|
@subsection primerbootstrapcures Problems Solved By Bootstrap
|
|
|
|
For example, the build system can fail in unexpected ways after running
|
|
<code>git pull</code>. Here, the <code>make maintainer-clean</code>
|
|
should be used to remove all of the files generated by the @c 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 @c maintainer-clean was run
|
|
@b after altering the build system files with git. If it is run
|
|
@b 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.
|
|
|
|
@subsection primermaintainerclean Autotools Cleaning
|
|
|
|
Normally, all files generated by the bootstrap script, configure
|
|
process, and build system should be removed after running <code>make
|
|
maintainer-clean</code>. Automatically generated files that remain
|
|
after this should be listed in @c MAINTAINERCLEANFILES,
|
|
@c DISTCLEANFILES, or @c CLEANFILES, depending on which stage of the
|
|
build process they are produced.
|
|
|
|
@section primerautoconf Autoconf Configuration Script
|
|
|
|
The @c autoconf program generates the @c configure script from
|
|
@c 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.
|
|
|
|
@subsection primermaintainermode Maintainer Mode
|
|
|
|
After a fresh checkout, @c bootstrap, and a simple @c configure, you may
|
|
experience errors when running @c make that some files cannot be found
|
|
(e.g. @c version.texi), and a second @c make will "mysteriously" solve
|
|
the problems. The isssue is well-known and expected, if unfortunate.
|
|
|
|
The OpenOCD project requires that all developers building from the
|
|
git repository use the @c --enable-maintainer-mode option when
|
|
running the @c configure script. This option ensures that certain files
|
|
are created during the build process that would normally be packaged in
|
|
the distribution tarball. The @c bootstrap script will remind you of
|
|
this requirement when it runs.
|
|
|
|
In addition to solving these problems, this option enables Makefile
|
|
rules (provided by automake) that allow the normal @c make process to
|
|
rebuild the autotools outputs, included the automake-generated Makefiles
|
|
themselves. This avoids the heavy-handed approach of running the
|
|
@c bootstrap script after changing one of these files.
|
|
|
|
@section primerautomake Automake Makefiles
|
|
|
|
The @c automake program generates @c Makefile.in files (from @c
|
|
Makefile.am files). These files are later processed by the configure
|
|
script produced by @c autoconf.
|
|
|
|
@subsection primerautomakenewfiles Creating Makefile.am Files
|
|
|
|
This section shows how to add a @c Makefile.am in a new directory (or
|
|
one that lacks one).
|
|
-# The new directory must be listed in the @c SUBDIRS variable in the
|
|
parent directory's Makefile.am:
|
|
@code
|
|
$ echo 'SUBDIRS += directory' >>../Makefile.am
|
|
@endcode
|
|
-# Create an bare-bones Makefile.am file in directory that needs it:
|
|
@code
|
|
$ echo "MAINTAINERCLEANFILES = Makefile.in" >Makefile.am
|
|
@endcode
|
|
-# The @c configure.in script must be updated, so it generates the required
|
|
Makefile when the @a configure script is run by the user:
|
|
@verbatim
|
|
AC_OUTPUT([
|
|
...
|
|
path/to/new/Makefile
|
|
])
|
|
@endverbatim
|
|
|
|
Note: these instructions are @b not meant to be used literally, rather
|
|
they are shown for demonstration purposes.
|
|
|
|
The default MAINTAINERCLEANFILES rule ensures that the
|
|
automake-generated @c Makefile.in file will be removed when developers
|
|
run <code>make maintainer-clean</code>. 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 @c make sequence.
|
|
|
|
@subsection primerautomaketweaks 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.
|
|
|
|
@section primerlibtool Libtool and Libraries
|
|
|
|
The @c 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?"
|
|
|
|
@section primerautotoolsmation Autotools Automation
|
|
|
|
This section outlines three ways the autotools provides automation to
|
|
assist with testing and distribution:
|
|
- @ref primerautocheck -- automatic unit and smoke tests
|
|
- @ref primerautodistcheck -- automatic distribution and packaging tests
|
|
|
|
@subsection primerautocheck make check
|
|
|
|
The <code>make check</code> 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.
|
|
|
|
@subsection primerautodistcheck make distcheck
|
|
|
|
The <code>make distcheck</code> command produces an archive of the
|
|
project deliverables (using <code>make dist</code>) and verifies its
|
|
integrity for distribution by attemptng 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 <code>make check</code> to ensure the distributed code passes all tests.
|
|
-# Run <code>make install</code> into a temporary installation directory.
|
|
-# Check that <code>make uninstall</code> removes all files that were installed.
|
|
-# Check that <code>make distclean</code> removes all files created
|
|
during all other steps (except the first).
|
|
|
|
If all of these steps complete successfully, the @c make process will
|
|
output a friendly message indicating the archive is ready to be
|
|
distributed.
|
|
|
|
*/
|
|
/** @file
|
|
|
|
This file contains the @ref primerautotools page.
|
|
|
|
*/
|