GNU Automake For version 1.16.3, 19 November 2020 David MacKenzie Tom Tromey Alexandre Duret-Lutz Ralf Wildenhues Stefano Lattarini This manual is for GNU Automake (version 1.16.3, 19 November 2020), a program that creates GNU standards-compliant Makefiles from template files. Copyright c 1995{2020 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled \GNU Free Documentation License." i Table of Contents 1 Introduction ::::::::::::::::::::::::::::::::::::: 1 2 An Introduction to the Autotools:::::::::::::: 1 2.1 Introducing the GNU Build System ::::::::::::::::::::::::::::: 1 2.2 Use Cases for the GNU Build System ::::::::::::::::::::::::::: 2 2.2.1 Basic Installation :::::::::::::::::::::::::::::::::::::::::: 2 2.2.2 Standard Makefile Targets :::::::::::::::::::::::::::::::: 4 2.2.3 Standard Directory Variables :::::::::::::::::::::::::::::: 4 2.2.4 Standard Configuration Variables :::::::::::::::::::::::::: 5 2.2.5 Overriding Default Configuration Setting with config.site :: 6 2.2.6 Parallel Build Trees (a.k.a. VPATH Builds) :::::::::::::::: 6 2.2.7 Two-Part Installation :::::::::::::::::::::::::::::::::::::: 8 2.2.8 Cross-Compilation ::::::::::::::::::::::::::::::::::::::::: 9 2.2.9 Renaming Programs at Install Time :::::::::::::::::::::: 10 2.2.10 Building Binary Packages Using DESTDIR :::::::::::::: 10 2.2.11 Preparing Distributions:::::::::::::::::::::::::::::::::: 11 2.2.12 Automatic Dependency Tracking::::::::::::::::::::::::: 11 2.2.13 Nested Packages ::::::::::::::::::::::::::::::::::::::::: 12 2.3 How Autotools Help ::::::::::::::::::::::::::::::::::::::::::: 13 2.4 A Small Hello World :::::::::::::::::::::::::::::::::::::::::: 13 2.4.1 Creating amhello-1.0.tar.gz:::::::::::::::::::::::::::: 13 2.4.2 amhello's configure.ac Setup Explained :::::::::::::::: 16 2.4.3 amhello's Makefile.am Setup Explained:::::::::::::::::: 17 3 General ideas ::::::::::::::::::::::::::::::::::: 18 3.1 General Operation::::::::::::::::::::::::::::::::::::::::::::: 18 3.2 Strictness ::::::::::::::::::::::::::::::::::::::::::::::::::::: 19 3.3 The Uniform Naming Scheme:::::::::::::::::::::::::::::::::: 21 3.4 Staying below the command line length limit::::::::::::::::::: 22 3.5 How derived variables are named :::::::::::::::::::::::::::::: 23 3.6 Variables reserved for the user ::::::::::::::::::::::::::::::::: 23 3.7 Programs automake might require ::::::::::::::::::::::::::::: 24 4 Some example packages:::::::::::::::::::::::: 25 4.1 A simple example, start to finish::::::::::::::::::::::::::::::: 25 4.2 Building true and false :::::::::::::::::::::::::::::::::::::::: 26 5 Creating a Makefile.in::::::::::::::::::::::::: 27 ii 6 Scanning configure.ac, using aclocal::::::::: 30 6.1 Configuration requirements :::::::::::::::::::::::::::::::::::: 30 6.2 Other things Automake recognizes ::::::::::::::::::::::::::::: 32 6.3 Auto-generating aclocal.m4 :::::::::::::::::::::::::::::::::::: 36 6.3.1 aclocal Options ::::::::::::::::::::::::::::::::::::::::::: 36 6.3.2 Macro Search Path ::::::::::::::::::::::::::::::::::::::: 38 6.3.3 Writing your own aclocal macros :::::::::::::::::::::::::: 40 6.3.4 Handling Local Macros ::::::::::::::::::::::::::::::::::: 41 6.3.5 Serial Numbers ::::::::::::::::::::::::::::::::::::::::::: 42 6.3.6 The Future of aclocal ::::::::::::::::::::::::::::::::::: 44 6.4 Autoconf macros supplied with Automake ::::::::::::::::::::: 45 6.4.1 Public Macros :::::::::::::::::::::::::::::::::::::::::::: 45 6.4.2 Obsolete Macros :::::::::::::::::::::::::::::::::::::::::: 47 6.4.3 Private Macros ::::::::::::::::::::::::::::::::::::::::::: 47 7 Directories :::::::::::::::::::::::::::::::::::::: 48 7.1 Recursing subdirectories ::::::::::::::::::::::::::::::::::::::: 48 7.2 Conditional Subdirectories ::::::::::::::::::::::::::::::::::::: 49 7.2.1 SUBDIRS vs. DIST_SUBDIRS ::::::::::::::::::::::::::::::: 50 7.2.2 Subdirectories with AM_CONDITIONAL :::::::::::::::::::::: 50 7.2.3 Subdirectories with AC_SUBST ::::::::::::::::::::::::::::: 51 7.2.4 Unconfigured Subdirectories :::::::::::::::::::::::::::::: 51 7.3 An Alternative Approach to Subdirectories :::::::::::::::::::: 52 7.4 Nesting Packages :::::::::::::::::::::::::::::::::::::::::::::: 53 8 Building Programs and Libraries ::::::::::::: 54 8.1 Building a program :::::::::::::::::::::::::::::::::::::::::::: 54 8.1.1 Defining program sources ::::::::::::::::::::::::::::::::: 55 8.1.2 Linking the program :::::::::::::::::::::::::::::::::::::: 55 8.1.3 Conditional compilation of sources :::::::::::::::::::::::: 56 8.1.4 Conditional compilation of programs :::::::::::::::::::::: 58 8.2 Building a library ::::::::::::::::::::::::::::::::::::::::::::: 58 8.3 Building a Shared Library ::::::::::::::::::::::::::::::::::::: 59 8.3.1 The Libtool Concept:::::::::::::::::::::::::::::::::::::: 59 8.3.2 Building Libtool Libraries::::::::::::::::::::::::::::::::: 60 8.3.3 Building Libtool Libraries Conditionally :::::::::::::::::: 60 8.3.4 Libtool Libraries with Conditional Sources :::::::::::::::: 61 8.3.5 Libtool Convenience Libraries::::::::::::::::::::::::::::: 62 8.3.6 Libtool Modules :::::::::::::::::::::::::::::::::::::::::: 63 8.3.7 _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS :::::::::::::::::: 64 8.3.8 LTLIBOBJS and LTALLOCA ::::::::::::::::::::::::::::::::: 64 8.3.9 Common Issues Related to Libtool's Use :::::::::::::::::: 64 8.3.9.1 Error: `required file `./ltmain.sh' not found' ::: 64 8.3.9.2 Objects `created with both libtool and without' :: 65 8.4 Program and Library Variables :::::::::::::::::::::::::::::::: 65 8.5 Default _SOURCES ::::::::::::::::::::::::::::::::::::::::::::: 69 8.6 Special handling for LIBOBJS and ALLOCA :::::::::::::::::::::: 70 iii 8.7 Variables used when building a program ::::::::::::::::::::::: 72 8.8 Yacc and Lex support ::::::::::::::::::::::::::::::::::::::::: 73 8.9 C++ Support ::::::::::::::::::::::::::::::::::::::::::::::::: 75 8.10 Objective C Support ::::::::::::::::::::::::::::::::::::::::: 76 8.11 Objective C++ Support :::::::::::::::::::::::::::::::::::::: 76 8.12 Unified Parallel C Support ::::::::::::::::::::::::::::::::::: 76 8.13 Assembly Support :::::::::::::::::::::::::::::::::::::::::::: 77 8.14 Fortran 77 Support ::::::::::::::::::::::::::::::::::::::::::: 77 8.14.1 Preprocessing Fortran 77 :::::::::::::::::::::::::::::::: 78 8.14.2 Compiling Fortran 77 Files :::::::::::::::::::::::::::::: 78 8.14.3 Mixing Fortran 77 With C and C++::::::::::::::::::::: 78 8.14.3.1 How the Linker is Chosen ::::::::::::::::::::::::::: 79 8.15 Fortran 9x Support::::::::::::::::::::::::::::::::::::::::::: 80 8.15.1 Compiling Fortran 9x Files :::::::::::::::::::::::::::::: 80 8.16 Compiling Java sources using gcj ::::::::::::::::::::::::::::: 80 8.17 Vala Support ::::::::::::::::::::::::::::::::::::::::::::::::: 81 8.18 Support for Other Languages ::::::::::::::::::::::::::::::::: 81 8.19 Automatic dependency tracking :::::::::::::::::::::::::::::: 82 8.20 Support for executable extensions::::::::::::::::::::::::::::: 82 9 Other Derived Objects :::::::::::::::::::::::: 83 9.1 Executable Scripts::::::::::::::::::::::::::::::::::::::::::::: 83 9.2 Header files ::::::::::::::::::::::::::::::::::::::::::::::::::: 84 9.3 Architecture-independent data files :::::::::::::::::::::::::::: 85 9.4 Built Sources :::::::::::::::::::::::::::::::::::::::::::::::::: 85 9.4.1 Built Sources Example:::::::::::::::::::::::::::::::::::: 86 10 Other GNU Tools::::::::::::::::::::::::::::: 89 10.1 Emacs Lisp :::::::::::::::::::::::::::::::::::::::::::::::::: 89 10.2 Gettext :::::::::::::::::::::::::::::::::::::::::::::::::::::: 89 10.3 Libtool ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 90 10.4 Java bytecode compilation (deprecated)::::::::::::::::::::::: 90 10.5 Python::::::::::::::::::::::::::::::::::::::::::::::::::::::: 91 11 Building documentation :::::::::::::::::::::: 92 11.1 Texinfo::::::::::::::::::::::::::::::::::::::::::::::::::::::: 92 11.2 Man Pages ::::::::::::::::::::::::::::::::::::::::::::::::::: 95 12 What Gets Installed :::::::::::::::::::::::::: 96 12.1 Basics of Installation ::::::::::::::::::::::::::::::::::::::::: 96 12.2 The Two Parts of Install ::::::::::::::::::::::::::::::::::::: 96 12.3 Extending Installation :::::::::::::::::::::::::::::::::::::::: 97 12.4 Staged Installs ::::::::::::::::::::::::::::::::::::::::::::::: 97 12.5 Install Rules for the User ::::::::::::::::::::::::::::::::::::: 97 13 What Gets Cleaned::::::::::::::::::::::::::: 98 iv 14 What Goes in a Distribution :::::::::::::::: 98 14.1 Basics of Distribution :::::::::::::::::::::::::::::::::::::::: 98 14.2 Fine-grained Distribution Control::::::::::::::::::::::::::::: 99 14.3 The dist Hook::::::::::::::::::::::::::::::::::::::::::::::: 100 14.4 Checking the Distribution ::::::::::::::::::::::::::::::::::: 100 14.5 The Types of Distributions :::::::::::::::::::::::::::::::::: 103 15 Support for test suites :::::::::::::::::::::: 104 15.1 Generalities about Testing::::::::::::::::::::::::::::::::::: 104 15.2 Simple Tests :::::::::::::::::::::::::::::::::::::::::::::::: 105 15.2.1 Scripts-based Testsuites :::::::::::::::::::::::::::::::: 105 15.2.2 Older (and discouraged) serial test harness:::::::::::::: 107 15.2.3 Parallel Test Harness :::::::::::::::::::::::::::::::::::