Menu
▾
▴
[Openocd-svn] r1921 - trunk/doc/manual/primer
|
From: <zw...@ma...> - 2009-05-27 12:27:36
|
Author: zwelch Date: 2009-05-27 12:27:32 +0200 (Wed, 27 May 2009) New Revision: 1921 Added: trunk/doc/manual/primer/autotools.txt Log: Add draft of Autotools Primer to The Manual. Added: trunk/doc/manual/primer/autotools.txt =================================================================== --- trunk/doc/manual/primer/autotools.txt 2009-05-27 07:49:58 UTC (rev 1920) +++ trunk/doc/manual/primer/autotools.txt 2009-05-27 10:27:32 UTC (rev 1921) @@ -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. + + */ Property changes on: trunk/doc/manual/primer/autotools.txt ___________________________________________________________________ Name: svn:eol-style + native |
