doc/manual/primer/autotools.txt

   1 /** @page primerautotools OpenOCD Autotools Primer
   2
   3 This page provides an overview to OpenOCD's use of the GNU autotool suite:
   4 - @ref primerautoconf
   5 - @ref primerautomake
   6 - @ref primerlibtool
   7
   8 Most developers do not need to concern themselves with these tools, as
   9 the @ref primerbootstrap script runs these tools in the required sequence.
  10
  11 @section primerbootstrap Autotools Bootstrap
  12
  13 The @c bootstrap script should be used by developers to run the
  14 autotools in the correct sequence.
  15
  16 When run after a fresh checkout, this script generates the build files
  17 required to compile the project, producing the project configure script.
  18 After running @c configure, the @ref primermaintainermode settings will
  19 handle most situations that require running these tools again.  In some
  20 cases, a fresh bootstrap may be still required.
  21
  22 @subsection primerbootstrapcures Problems Solved By Bootstrap
  23
  24 For example, the build system can fail in unexpected ways after running
  25 <code>git pull</code>.  Here, the <code>make maintainer-clean</code>
  26 should be used to remove all of the files generated by the @c bootstrap
  27 script and subsequent build processes.
  28
  29 In this particular case, one may also need to remove stray files by hand
  30 after running this command to ensure everything is rebuilt properly.
  31 This step should be necessary only if the @c maintainer-clean was run
  32 @b after altering the build system files with git. If it is run
  33 @b before any updates, the build system should never leave artifacts
  34 in the tree.
  35
  36 Without such precautions, changes can be introduced that leave the tree
  37 timestamps in an inconsistent state, producing strange compile errors
  38 that are resolve after such diligence.
  39
  40 @subsection primermaintainerclean Autotools Cleaning
  41
  42 Normally, all files generated by the bootstrap script, configure
  43 process, and build system should be removed after running <code>make
  44 maintainer-clean</code>.  Automatically generated files that remain
  45 after this should be listed in @c MAINTAINERCLEANFILES,
  46 @c DISTCLEANFILES, or @c CLEANFILES, depending on which stage of the
  47 build process they are produced.
  48
  49 @section primerautoconf Autoconf Configuration Script
  50
  51 The @c autoconf program generates the @c configure script from
  52 @c configure.in, using serious Perl voodoo.  The resulting script is
  53 included in the project distribution packages and run by users to
  54 configure the build process for their system.
  55
  56 @subsection primermaintainermode Maintainer Mode
  57
  58 After a fresh checkout, @c bootstrap, and a simple @c configure, you may
  59 experience errors when running @c make that some files cannot be found
  60 (e.g. @c version.texi), and a second @c make will "mysteriously" solve
  61 the problems.  The isssue is well-known and expected, if unfortunate.
  62
  63 The OpenOCD project requires that all developers building from  the
  64 git repository use the @c --enable-maintainer-mode option when
  65 running the @c configure script.  This option ensures that certain files
  66 are created during the build process that would normally be packaged in
  67 the distribution tarball.  The @c bootstrap script will remind you of
  68 this requirement when it runs.
  69
  70 In addition to solving these problems, this option enables Makefile
  71 rules (provided by automake) that allow the normal @c make process to
  72 rebuild the autotools outputs, included the automake-generated Makefiles
  73 themselves.  This avoids the heavy-handed approach of running the
  74 @c bootstrap script after changing one of these files.
  75
  76 @section primerautomake Automake Makefiles
  77
  78 The @c automake program generates @c Makefile.in files (from @c
  79 Makefile.am files).  These files are later processed by the configure
  80 script produced by @c autoconf.
  81
  82 @subsection primerautomakenewfiles Creating Makefile.am Files
  83
  84 This section shows how to add a @c Makefile.am in a new directory (or
  85 one that lacks one).
  86 -# The new directory must be listed in the @c SUBDIRS variable in the
  87 parent directory's Makefile.am:
  88 @code
  89 $ echo 'SUBDIRS += directory' >>../Makefile.am
  90 @endcode
  91 -# Create an bare-bones Makefile.am file in directory that needs it:
  92 @code
  93 $ echo "MAINTAINERCLEANFILES = Makefile.in" >Makefile.am
  94 @endcode
  95 -# The @c configure.in script must be updated, so it generates the required
  96 Makefile when the @a configure script is run by the user:
  97 @verbatim
  98 AC_OUTPUT([
  99                 ...
 100                 path/to/new/Makefile
 101         ])
 102 @endverbatim
 103
 104 Note: these instructions are @b not meant to be used literally, rather
 105 they are shown for demonstration purposes.
 106
 107 The default MAINTAINERCLEANFILES rule ensures that the
 108 automake-generated @c Makefile.in file will be removed when developers
 109 run <code>make maintainer-clean</code>.  Additional rules may be added
 110 after this; however, the project should bootstrap and tear down cleanly
 111 after taking these minimal steps, with the new directory being visited
 112 during the @c make sequence.
 113
 114 @subsection primerautomaketweaks Updating Makefile.am Files
 115
 116 Adding, removing, and renaming files from the project tree usually
 117 requires updating the autotools inputs. This section will help describe
 118 how to do this as questions arise.
 119
 120 @section primerlibtool Libtool and Libraries
 121
 122 The @c libtool program provides the means of generating libraries in a
 123 portable and painless manner (relatively speaking).
 124
 125 This section will contain an answer to "what does libtool give OpenOCD?"
 126 and "what do developers need to consider in new code?"
 127
 128 @section primerautotoolsmation Autotools Automation
 129
 130 This section outlines three ways the autotools provides automation to
 131 assist with testing and distribution:
 132 - @ref primerautocheck -- automatic unit and smoke tests
 133 - @ref primerautodistcheck -- automatic distribution and packaging tests
 134
 135 @subsection primerautocheck make check
 136
 137 The <code>make check</code> command will run the OpenOCD test suite,
 138 once it has been integrated as such.  This section will contain
 139 information about how to extend the testing build system components to
 140 implement new checks.
 141
 142 @subsection primerautodistcheck make distcheck
 143
 144 The <code>make distcheck</code> command produces an archive of the
 145 project deliverables (using <code>make dist</code>) and verifies its
 146 integrity for distribution by attemptng to use the package in the same
 147 manner as a user.
 148
 149 These checks includes the following steps:
 150 -# Unpack the project archive into its expected directory.
 151 -# Configure and build the project in a temporary out-of-tree directory.
 152 -# Run <code>make check</code> to ensure the distributed code passes all tests.
 153 -# Run <code>make install</code> into a temporary installation directory.
 154 -# Check that <code>make uninstall</code> removes all files that were installed.
 155 -# Check that <code>make distclean</code> removes all files created
 156 during all other steps (except the first).
 157
 158 If all of these steps complete successfully, the @c make process will
 159 output a friendly message indicating the archive is ready to be
 160 distributed.
 161
 162  */
 163 /** @file
 164
 165 This file contains the @ref primerautotools page.
 166
 167  */