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