configure: remove AM_MAINTAINER_MODE, effectively always enabling all the rules
[openocd.git] / 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 @section primerautomake Automake Makefiles
57
58 The @c automake program generates @c Makefile.in files (from @c
59 Makefile.am files).  These files are later processed by the configure
60 script produced by @c autoconf.
61
62 @subsection primerautomakenewfiles Creating Makefile.am Files
63
64 This section shows how to add a @c Makefile.am in a new directory (or
65 one that lacks one).
66 -# The new directory must be listed in the @c SUBDIRS variable in the
67 parent directory's Makefile.am:
68 @code
69 $ echo 'SUBDIRS += directory' >>../Makefile.am
70 @endcode
71 -# Create an bare-bones Makefile.am file in directory that needs it:
72 @code
73 $ echo "MAINTAINERCLEANFILES = Makefile.in" >Makefile.am
74 @endcode
75 -# The @c configure.in script must be updated, so it generates the required
76 Makefile when the @a configure script is run by the user:
77 @verbatim
78 AC_OUTPUT([
79                 ...
80                 path/to/new/Makefile
81         ])
82 @endverbatim
83
84 Note: these instructions are @b not meant to be used literally, rather
85 they are shown for demonstration purposes.
86
87 The default MAINTAINERCLEANFILES rule ensures that the
88 automake-generated @c Makefile.in file will be removed when developers
89 run <code>make maintainer-clean</code>.  Additional rules may be added
90 after this; however, the project should bootstrap and tear down cleanly
91 after taking these minimal steps, with the new directory being visited
92 during the @c make sequence.
93
94 @subsection primerautomaketweaks Updating Makefile.am Files
95
96 Adding, removing, and renaming files from the project tree usually
97 requires updating the autotools inputs. This section will help describe
98 how to do this as questions arise.
99
100 @section primerlibtool Libtool and Libraries
101
102 The @c libtool program provides the means of generating libraries in a
103 portable and painless manner (relatively speaking).
104
105 This section will contain an answer to "what does libtool give OpenOCD?"
106 and "what do developers need to consider in new code?"
107
108 @section primerautotoolsmation Autotools Automation
109
110 This section outlines three ways the autotools provides automation to
111 assist with testing and distribution:
112 - @ref primerautocheck -- automatic unit and smoke tests
113 - @ref primerautodistcheck -- automatic distribution and packaging tests
114
115 @subsection primerautocheck make check
116
117 The <code>make check</code> command will run the OpenOCD test suite,
118 once it has been integrated as such.  This section will contain
119 information about how to extend the testing build system components to
120 implement new checks.
121
122 @subsection primerautodistcheck make distcheck
123
124 The <code>make distcheck</code> command produces an archive of the
125 project deliverables (using <code>make dist</code>) and verifies its
126 integrity for distribution by attemptng to use the package in the same
127 manner as a user.
128
129 These checks includes the following steps:
130 -# Unpack the project archive into its expected directory.
131 -# Configure and build the project in a temporary out-of-tree directory.
132 -# Run <code>make check</code> to ensure the distributed code passes all tests.
133 -# Run <code>make install</code> into a temporary installation directory.
134 -# Check that <code>make uninstall</code> removes all files that were installed.
135 -# Check that <code>make distclean</code> removes all files created
136 during all other steps (except the first).
137
138 If all of these steps complete successfully, the @c make process will
139 output a friendly message indicating the archive is ready to be
140 distributed.
141
142  */
143 /** @file
144
145 This file contains the @ref primerautotools page.
146
147  */