You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

168 lines
6.8 KiB

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