Add draft of Autotools Primer to The Manual.
git-svn-id: svn://svn.berlios.de/openocd/trunk@1921 b42882b7-edfa-0310-969c-e2dbd0fdcd60__archive__
zwelch
parent
dd86b54e6e
commit
eedfcb2cbe
|
|
@ -0,0 +1,167 @@
|
|||
/** @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>svn update</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 Subversion. 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
|
||||
Subversion 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.
|
||||
|
||||
*/
|
||||
Loading…
Reference in New Issue