| This is automake.info, produced by makeinfo version 5.2 from |
| automake.texi. |
| |
| This manual is for GNU Automake (version 1.15, 31 December 2014), a |
| program that creates GNU standards-compliant Makefiles from template |
| files. |
| |
| Copyright © 1995-2014 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.” |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Automake: (automake). Making GNU standards-compliant Makefiles. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION Individual utilities |
| START-INFO-DIR-ENTRY |
| * aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4. |
| * automake-invocation: (automake)automake Invocation. Generating Makefile.in. |
| END-INFO-DIR-ENTRY |
| |
| |
| File: automake.info, Node: Top, Next: Introduction, Up: (dir) |
| |
| GNU Automake |
| ************ |
| |
| This manual is for GNU Automake (version 1.15, 31 December 2014), a |
| program that creates GNU standards-compliant Makefiles from template |
| files. |
| |
| Copyright © 1995-2014 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.” |
| |
| * Menu: |
| |
| * Introduction:: Automake’s purpose |
| * Autotools Introduction:: An Introduction to the Autotools |
| * Generalities:: General ideas |
| * Examples:: Some example packages |
| * automake Invocation:: Creating a Makefile.in |
| * configure:: Scanning configure.ac, using aclocal |
| * Directories:: Declaring subdirectories |
| * Programs:: Building programs and libraries |
| * Other Objects:: Other derived objects |
| * Other GNU Tools:: Other GNU Tools |
| * Documentation:: Building documentation |
| * Install:: What gets installed |
| * Clean:: What gets cleaned |
| * Dist:: What goes in a distribution |
| * Tests:: Support for test suites |
| * Rebuilding:: Automatic rebuilding of Makefile |
| * Options:: Changing Automake’s behavior |
| * Miscellaneous:: Miscellaneous rules |
| * Include:: Including extra files in an Automake template |
| * Conditionals:: Conditionals |
| * Silencing Make:: Obtain less verbose output from ‘make’ |
| * Gnits:: The effect of ‘--gnu’ and ‘--gnits’ |
| * Not Enough:: When Automake is not Enough |
| * Distributing:: Distributing the Makefile.in |
| * API Versioning:: About compatibility between Automake versions |
| * Upgrading:: Upgrading to a Newer Automake Version |
| * FAQ:: Frequently Asked Questions |
| * Copying This Manual:: How to make copies of this manual |
| * Indices:: Indices of variables, macros, and concepts |
| |
| — The Detailed Node Listing — |
| |
| An Introduction to the Autotools |
| |
| * GNU Build System:: Introducing the GNU Build System |
| * Use Cases:: Use Cases for the GNU Build System |
| * Why Autotools:: How Autotools Help |
| * Hello World:: A Small Hello World Package |
| |
| Use Cases for the GNU Build System |
| |
| * Basic Installation:: Common installation procedure |
| * Standard Targets:: A list of standard Makefile targets |
| * Standard Directory Variables:: A list of standard directory variables |
| * Standard Configuration Variables:: Using configuration variables |
| * config.site:: Using a config.site file |
| * VPATH Builds:: Parallel build trees |
| * Two-Part Install:: Installing data and programs separately |
| * Cross-Compilation:: Building for other architectures |
| * Renaming:: Renaming programs at install time |
| * DESTDIR:: Building binary packages with DESTDIR |
| * Preparing Distributions:: Rolling out tarballs |
| * Dependency Tracking:: Automatic dependency tracking |
| * Nested Packages:: The GNU Build Systems can be nested |
| |
| A Small Hello World |
| |
| * Creating amhello:: Create ‘amhello-1.0.tar.gz’ from scratch |
| * amhello's configure.ac Setup Explained:: |
| * amhello's Makefile.am Setup Explained:: |
| |
| General ideas |
| |
| * General Operation:: General operation of Automake |
| * Strictness:: Standards conformance checking |
| * Uniform:: The Uniform Naming Scheme |
| * Length Limitations:: Staying below the command line length limit |
| * Canonicalization:: How derived variables are named |
| * User Variables:: Variables reserved for the user |
| * Auxiliary Programs:: Programs automake might require |
| |
| Some example packages |
| |
| * Complete:: A simple example, start to finish |
| * true:: Building true and false |
| |
| Scanning ‘configure.ac’, using ‘aclocal’ |
| |
| * Requirements:: Configuration requirements |
| * Optional:: Other things Automake recognizes |
| * aclocal Invocation:: Auto-generating aclocal.m4 |
| * Macros:: Autoconf macros supplied with Automake |
| |
| Auto-generating aclocal.m4 |
| |
| * aclocal Options:: Options supported by aclocal |
| * Macro Search Path:: How aclocal finds .m4 files |
| * Extending aclocal:: Writing your own aclocal macros |
| * Local Macros:: Organizing local macros |
| * Serials:: Serial lines in Autoconf macros |
| * Future of aclocal:: aclocal’s scheduled death |
| |
| Autoconf macros supplied with Automake |
| |
| * Public Macros:: Macros that you can use. |
| * Private Macros:: Macros that you should not use. |
| |
| Directories |
| |
| * Subdirectories:: Building subdirectories recursively |
| * Conditional Subdirectories:: Conditionally not building directories |
| * Alternative:: Subdirectories without recursion |
| * Subpackages:: Nesting packages |
| |
| Conditional Subdirectories |
| |
| * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories |
| * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories |
| * Subdirectories with AC_SUBST:: Another way for conditional recursion |
| * Unconfigured Subdirectories:: Not even creating a ‘Makefile’ |
| |
| Building Programs and Libraries |
| |
| * A Program:: Building a program |
| * A Library:: Building a library |
| * A Shared Library:: Building a Libtool library |
| * Program and Library Variables:: Variables controlling program and |
| library builds |
| * Default _SOURCES:: Default source files |
| * LIBOBJS:: Special handling for LIBOBJS and ALLOCA |
| * Program Variables:: Variables used when building a program |
| * Yacc and Lex:: Yacc and Lex support |
| * C++ Support:: Compiling C++ sources |
| * Objective C Support:: Compiling Objective C sources |
| * Objective C++ Support:: Compiling Objective C++ sources |
| * Unified Parallel C Support:: Compiling Unified Parallel C sources |
| * Assembly Support:: Compiling assembly sources |
| * Fortran 77 Support:: Compiling Fortran 77 sources |
| * Fortran 9x Support:: Compiling Fortran 9x sources |
| * Java Support with gcj:: Compiling Java sources using gcj |
| * Vala Support:: Compiling Vala sources |
| * Support for Other Languages:: Compiling other languages |
| * Dependencies:: Automatic dependency tracking |
| * EXEEXT:: Support for executable extensions |
| |
| Building a program |
| |
| * Program Sources:: Defining program sources |
| * Linking:: Linking with libraries or extra objects |
| * Conditional Sources:: Handling conditional sources |
| * Conditional Programs:: Building a program conditionally |
| |
| Building a Shared Library |
| |
| * Libtool Concept:: Introducing Libtool |
| * Libtool Libraries:: Declaring Libtool Libraries |
| * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally |
| * Conditional Libtool Sources:: Choosing Library Sources Conditionally |
| * Libtool Convenience Libraries:: Building Convenience Libtool Libraries |
| * Libtool Modules:: Building Libtool Modules |
| * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS |
| * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA) |
| * Libtool Issues:: Common Issues Related to Libtool’s Use |
| |
| Common Issues Related to Libtool’s Use |
| |
| * Error required file ltmain.sh not found:: The need to run libtoolize |
| * Objects created both with libtool and without:: Avoid a specific build race |
| |
| Fortran 77 Support |
| |
| * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources |
| * Compiling Fortran 77 Files:: Compiling Fortran 77 sources |
| * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++ |
| |
| Mixing Fortran 77 With C and C++ |
| |
| * How the Linker is Chosen:: Automatic linker selection |
| |
| Fortran 9x Support |
| |
| * Compiling Fortran 9x Files:: Compiling Fortran 9x sources |
| |
| Other Derived Objects |
| |
| * Scripts:: Executable scripts |
| * Headers:: Header files |
| * Data:: Architecture-independent data files |
| * Sources:: Derived sources |
| |
| Built Sources |
| |
| * Built Sources Example:: Several ways to handle built sources. |
| |
| Other GNU Tools |
| |
| * Emacs Lisp:: Emacs Lisp |
| * gettext:: Gettext |
| * Libtool:: Libtool |
| * Java:: Java bytecode compilation (deprecated) |
| * Python:: Python |
| |
| Building documentation |
| |
| * Texinfo:: Texinfo |
| * Man Pages:: Man pages |
| |
| What Gets Installed |
| |
| * Basics of Installation:: What gets installed where |
| * The Two Parts of Install:: Installing data and programs separately |
| * Extending Installation:: Adding your own rules for installation |
| * Staged Installs:: Installation in a temporary location |
| * Install Rules for the User:: Useful additional rules |
| |
| What Goes in a Distribution |
| |
| * Basics of Distribution:: Files distributed by default |
| * Fine-grained Distribution Control:: ‘dist_’ and ‘nodist_’ prefixes |
| * The dist Hook:: A target for last-minute distribution changes |
| * Checking the Distribution:: ‘make distcheck’ explained |
| * The Types of Distributions:: A variety of formats and compression methods |
| |
| Support for test suites |
| |
| * Generalities about Testing:: Generic concepts and terminology about testing |
| * Simple Tests:: Listing test scripts in ‘TESTS’ |
| * Custom Test Drivers:: Writing and using custom test drivers |
| * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol |
| * DejaGnu Tests:: Interfacing with the ‘dejagnu’ testing framework |
| * Install Tests:: Running tests on installed packages |
| |
| Simple Tests |
| |
| * Scripts-based Testsuites:: Automake-specific concepts and terminology |
| * Serial Test Harness:: Older (and discouraged) serial test harness |
| * Parallel Test Harness:: Generic concurrent test harness |
| |
| Using the TAP test protocol |
| |
| * Introduction to TAP:: |
| * Use TAP with the Automake test harness:: |
| * Incompatibilities with other TAP parsers and drivers:: |
| * Links and external resources on TAP:: |
| |
| Custom Test Drivers |
| |
| * Overview of Custom Test Drivers Support:: |
| * Declaring Custom Test Drivers:: |
| * API for Custom Test Drivers:: |
| |
| API for Custom Test Drivers |
| |
| * Command-line arguments for test drivers:: |
| * Log files generation and test results recording:: |
| * Testsuite progress output:: |
| |
| Changing Automake’s Behavior |
| |
| * Options generalities:: Semantics of Automake option |
| * List of Automake options:: A comprehensive list of Automake options |
| |
| Miscellaneous Rules |
| |
| * Tags:: Interfacing to cscope, etags and mkid |
| * Suffixes:: Handling new file extensions |
| |
| Conditionals |
| |
| * Usage of Conditionals:: Declaring conditional content |
| * Limits of Conditionals:: Enclosing complete statements |
| |
| Silencing Make |
| |
| * Make verbosity:: Make is verbose by default |
| * Tricks For Silencing Make:: Standard and generic ways to silence make |
| * Automake Silent Rules:: How Automake can help in silencing make |
| |
| When Automake Isn’t Enough |
| |
| * Extending:: Adding new rules or overriding existing ones. |
| * Third-Party Makefiles:: Integrating Non-Automake ‘Makefile’s. |
| |
| Frequently Asked Questions about Automake |
| |
| * CVS:: CVS and generated files |
| * maintainer-mode:: missing and AM_MAINTAINER_MODE |
| * Wildcards:: Why doesn’t Automake support wildcards? |
| * Limitations on File Names:: Limitations on source and installed file names |
| * Errors with distclean:: Files left in build directory after distclean |
| * Flag Variables Ordering:: CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS |
| * Renamed Objects:: Why are object files sometimes renamed? |
| * Per-Object Flags:: How to simulate per-object flags? |
| * Multiple Outputs:: Writing rules for tools with many output files |
| * Hard-Coded Install Paths:: Installing to hard-coded locations |
| * Debugging Make Rules:: Strategies when things don’t work as expected |
| * Reporting Bugs:: Feedback on bugs and feature requests |
| |
| Copying This Manual |
| |
| * GNU Free Documentation License:: License for copying this manual |
| |
| Indices |
| |
| * Macro Index:: Index of Autoconf macros |
| * Variable Index:: Index of Makefile variables |
| * General Index:: General index |
| |
| |
| |
| File: automake.info, Node: Introduction, Next: Autotools Introduction, Prev: Top, Up: Top |
| |
| 1 Introduction |
| ************** |
| |
| Automake is a tool for automatically generating ‘Makefile.in’s from |
| files called ‘Makefile.am’. Each ‘Makefile.am’ is basically a series of |
| ‘make’ variable definitions(1), with rules being thrown in occasionally. |
| The generated ‘Makefile.in’s are compliant with the GNU Makefile |
| standards. |
| |
| The GNU Makefile Standards Document (*note (standards)Makefile |
| Conventions::) is long, complicated, and subject to change. The goal of |
| Automake is to remove the burden of Makefile maintenance from the back |
| of the individual GNU maintainer (and put it on the back of the Automake |
| maintainers). |
| |
| The typical Automake input file is simply a series of variable |
| definitions. Each such file is processed to create a ‘Makefile.in’. |
| |
| Automake does constrain a project in certain ways; for instance, it |
| assumes that the project uses Autoconf (*note Introduction: |
| (autoconf)Top.), and enforces certain restrictions on the ‘configure.ac’ |
| contents. |
| |
| Automake requires ‘perl’ in order to generate the ‘Makefile.in’s. |
| However, the distributions created by Automake are fully GNU |
| standards-compliant, and do not require ‘perl’ in order to be built. |
| |
| For more information on bug reports, *Note Reporting Bugs::. |
| |
| ---------- Footnotes ---------- |
| |
| (1) These variables are also called "make macros" in Make |
| terminology, however in this manual we reserve the term "macro" for |
| Autoconf’s macros. |
| |
| |
| File: automake.info, Node: Autotools Introduction, Next: Generalities, Prev: Introduction, Up: Top |
| |
| 2 An Introduction to the Autotools |
| ********************************** |
| |
| If you are new to Automake, maybe you know that it is part of a set of |
| tools called _The Autotools_. Maybe you’ve already delved into a |
| package full of files named ‘configure’, ‘configure.ac’, ‘Makefile.in’, |
| ‘Makefile.am’, ‘aclocal.m4’, …, some of them claiming to be _generated |
| by_ Autoconf or Automake. But the exact purpose of these files and |
| their relations is probably fuzzy. The goal of this chapter is to |
| introduce you to this machinery, to show you how it works and how |
| powerful it is. If you’ve never installed or seen such a package, do |
| not worry: this chapter will walk you through it. |
| |
| If you need some teaching material, more illustrations, or a less |
| ‘automake’-centered continuation, some slides for this introduction are |
| available in Alexandre Duret-Lutz’s Autotools Tutorial |
| (http://www.lrde.epita.fr/~adl/autotools.html). This chapter is the |
| written version of the first part of his tutorial. |
| |
| * Menu: |
| |
| * GNU Build System:: Introducing the GNU Build System |
| * Use Cases:: Use Cases for the GNU Build System |
| * Why Autotools:: How Autotools Help |
| * Hello World:: A Small Hello World Package |
| |
| |
| File: automake.info, Node: GNU Build System, Next: Use Cases, Up: Autotools Introduction |
| |
| 2.1 Introducing the GNU Build System |
| ==================================== |
| |
| It is a truth universally acknowledged, that as a developer in |
| possession of a new package, you must be in want of a build system. |
| |
| In the Unix world, such a build system is traditionally achieved |
| using the command ‘make’ (*note Overview: (make)Top.). You express the |
| recipe to build your package in a ‘Makefile’. This file is a set of |
| rules to build the files in the package. For instance the program |
| ‘prog’ may be built by running the linker on the files ‘main.o’, |
| ‘foo.o’, and ‘bar.o’; the file ‘main.o’ may be built by running the |
| compiler on ‘main.c’; etc. Each time ‘make’ is run, it reads |
| ‘Makefile’, checks the existence and modification time of the files |
| mentioned, decides what files need to be built (or rebuilt), and runs |
| the associated commands. |
| |
| When a package needs to be built on a different platform than the one |
| it was developed on, its ‘Makefile’ usually needs to be adjusted. For |
| instance the compiler may have another name or require more options. In |
| 1991, David J. MacKenzie got tired of customizing ‘Makefile’ for the 20 |
| platforms he had to deal with. Instead, he handcrafted a little shell |
| script called ‘configure’ to automatically adjust the ‘Makefile’ (*note |
| Genesis: (autoconf)Genesis.). Compiling his package was now as simple |
| as running ‘./configure && make’. |
| |
| Today this process has been standardized in the GNU project. The GNU |
| Coding Standards (*note The Release Process: (standards)Managing |
| Releases.) explains how each package of the GNU project should have a |
| ‘configure’ script, and the minimal interface it should have. The |
| ‘Makefile’ too should follow some established conventions. The result? |
| A unified build system that makes all packages almost indistinguishable |
| by the installer. In its simplest scenario, all the installer has to do |
| is to unpack the package, run ‘./configure && make && make install’, and |
| repeat with the next package to install. |
| |
| We call this build system the "GNU Build System", since it was grown |
| out of the GNU project. However it is used by a vast number of other |
| packages: following any existing convention has its advantages. |
| |
| The Autotools are tools that will create a GNU Build System for your |
| package. Autoconf mostly focuses on ‘configure’ and Automake on |
| ‘Makefile’s. It is entirely possible to create a GNU Build System |
| without the help of these tools. However it is rather burdensome and |
| error-prone. We will discuss this again after some illustration of the |
| GNU Build System in action. |
| |
| |
| File: automake.info, Node: Use Cases, Next: Why Autotools, Prev: GNU Build System, Up: Autotools Introduction |
| |
| 2.2 Use Cases for the GNU Build System |
| ====================================== |
| |
| In this section we explore several use cases for the GNU Build System. |
| You can replay all of these examples on the ‘amhello-1.0.tar.gz’ package |
| distributed with Automake. If Automake is installed on your system, you |
| should find a copy of this file in |
| ‘PREFIX/share/doc/automake/amhello-1.0.tar.gz’, where PREFIX is the |
| installation prefix specified during configuration (PREFIX defaults to |
| ‘/usr/local’, however if Automake was installed by some GNU/Linux |
| distribution it most likely has been set to ‘/usr’). If you do not have |
| a copy of Automake installed, you can find a copy of this file inside |
| the ‘doc/’ directory of the Automake package. |
| |
| Some of the following use cases present features that are in fact |
| extensions to the GNU Build System. Read: they are not specified by the |
| GNU Coding Standards, but they are nonetheless part of the build system |
| created by the Autotools. To keep things simple, we do not point out |
| the difference. Our objective is to show you many of the features that |
| the build system created by the Autotools will offer to you. |
| |
| * Menu: |
| |
| * Basic Installation:: Common installation procedure |
| * Standard Targets:: A list of standard Makefile targets |
| * Standard Directory Variables:: A list of standard directory variables |
| * Standard Configuration Variables:: Using configuration variables |
| * config.site:: Using a config.site file |
| * VPATH Builds:: Parallel build trees |
| * Two-Part Install:: Installing data and programs separately |
| * Cross-Compilation:: Building for other architectures |
| * Renaming:: Renaming programs at install time |
| * DESTDIR:: Building binary packages with DESTDIR |
| * Preparing Distributions:: Rolling out tarballs |
| * Dependency Tracking:: Automatic dependency tracking |
| * Nested Packages:: The GNU Build Systems can be nested |
| |
| |
| File: automake.info, Node: Basic Installation, Next: Standard Targets, Up: Use Cases |
| |
| 2.2.1 Basic Installation |
| ------------------------ |
| |
| The most common installation procedure looks as follows. |
| |
| ~ % tar zxf amhello-1.0.tar.gz |
| ~ % cd amhello-1.0 |
| ~/amhello-1.0 % ./configure |
| … |
| config.status: creating Makefile |
| config.status: creating src/Makefile |
| … |
| ~/amhello-1.0 % make |
| … |
| ~/amhello-1.0 % make check |
| … |
| ~/amhello-1.0 % su |
| Password: |
| /home/adl/amhello-1.0 # make install |
| … |
| /home/adl/amhello-1.0 # exit |
| ~/amhello-1.0 % make installcheck |
| … |
| |
| The user first unpacks the package. Here, and in the following |
| examples, we will use the non-portable ‘tar zxf’ command for simplicity. |
| On a system without GNU ‘tar’ installed, this command should read |
| ‘gunzip -c amhello-1.0.tar.gz | tar xf -’. |
| |
| The user then enters the newly created directory to run the |
| ‘configure’ script. This script probes the system for various features, |
| and finally creates the ‘Makefile’s. In this toy example there are only |
| two ‘Makefile’s, but in real-world projects, there may be many more, |
| usually one ‘Makefile’ per directory. |
| |
| It is now possible to run ‘make’. This will construct all the |
| programs, libraries, and scripts that need to be constructed for the |
| package. In our example, this compiles the ‘hello’ program. All files |
| are constructed in place, in the source tree; we will see later how this |
| can be changed. |
| |
| ‘make check’ causes the package’s tests to be run. This step is not |
| mandatory, but it is often good to make sure the programs that have been |
| built behave as they should, before you decide to install them. Our |
| example does not contain any tests, so running ‘make check’ is a no-op. |
| |
| After everything has been built, and maybe tested, it is time to |
| install it on the system. That means copying the programs, libraries, |
| header files, scripts, and other data files from the source directory to |
| their final destination on the system. The command ‘make install’ will |
| do that. However, by default everything will be installed in |
| subdirectories of ‘/usr/local’: binaries will go into ‘/usr/local/bin’, |
| libraries will end up in ‘/usr/local/lib’, etc. This destination is |
| usually not writable by any user, so we assume that we have to become |
| root before we can run ‘make install’. In our example, running ‘make |
| install’ will copy the program ‘hello’ into ‘/usr/local/bin’ and |
| ‘README’ into ‘/usr/local/share/doc/amhello’. |
| |
| A last and optional step is to run ‘make installcheck’. This command |
| may run tests on the installed files. ‘make check’ tests the files in |
| the source tree, while ‘make installcheck’ tests their installed copies. |
| The tests run by the latter can be different from those run by the |
| former. For instance, there are tests that cannot be run in the source |
| tree. Conversely, some packages are set up so that ‘make installcheck’ |
| will run the very same tests as ‘make check’, only on different files |
| (non-installed vs. installed). It can make a difference, for instance |
| when the source tree’s layout is different from that of the |
| installation. Furthermore it may help to diagnose an incomplete |
| installation. |
| |
| Presently most packages do not have any ‘installcheck’ tests because |
| the existence of ‘installcheck’ is little known, and its usefulness is |
| neglected. Our little toy package is no better: ‘make installcheck’ |
| does nothing. |
| |
| |
| File: automake.info, Node: Standard Targets, Next: Standard Directory Variables, Prev: Basic Installation, Up: Use Cases |
| |
| 2.2.2 Standard ‘Makefile’ Targets |
| --------------------------------- |
| |
| So far we have come across four ways to run ‘make’ in the GNU Build |
| System: ‘make’, ‘make check’, ‘make install’, and ‘make installcheck’. |
| The words ‘check’, ‘install’, and ‘installcheck’, passed as arguments to |
| ‘make’, are called "targets". ‘make’ is a shorthand for ‘make all’, |
| ‘all’ being the default target in the GNU Build System. |
| |
| Here is a list of the most useful targets that the GNU Coding |
| Standards specify. |
| |
| ‘make all’ |
| Build programs, libraries, documentation, etc. (same as ‘make’). |
| ‘make install’ |
| Install what needs to be installed, copying the files from the |
| package’s tree to system-wide directories. |
| ‘make install-strip’ |
| Same as ‘make install’, then strip debugging symbols. Some users |
| like to trade space for useful bug reports... |
| ‘make uninstall’ |
| The opposite of ‘make install’: erase the installed files. (This |
| needs to be run from the same build tree that was installed.) |
| ‘make clean’ |
| Erase from the build tree the files built by ‘make all’. |
| ‘make distclean’ |
| Additionally erase anything ‘./configure’ created. |
| ‘make check’ |
| Run the test suite, if any. |
| ‘make installcheck’ |
| Check the installed programs or libraries, if supported. |
| ‘make dist’ |
| Recreate ‘PACKAGE-VERSION.tar.gz’ from all the source files. |
| |
| |
| File: automake.info, Node: Standard Directory Variables, Next: Standard Configuration Variables, Prev: Standard Targets, Up: Use Cases |
| |
| 2.2.3 Standard Directory Variables |
| ---------------------------------- |
| |
| The GNU Coding Standards also specify a hierarchy of variables to denote |
| installation directories. Some of these are: |
| |
| Directory variable Default value |
| ------------------------------------------------------- |
| ‘prefix’ ‘/usr/local’ |
| ‘exec_prefix’ ‘${prefix}’ |
| ‘bindir’ ‘${exec_prefix}/bin’ |
| ‘libdir’ ‘${exec_prefix}/lib’ |
| … |
| ‘includedir’ ‘${prefix}/include’ |
| ‘datarootdir’ ‘${prefix}/share’ |
| ‘datadir’ ‘${datarootdir}’ |
| ‘mandir’ ‘${datarootdir}/man’ |
| ‘infodir’ ‘${datarootdir}/info’ |
| ‘docdir’ ‘${datarootdir}/doc/${PACKAGE}’ |
| … |
| |
| Each of these directories has a role which is often obvious from its |
| name. In a package, any installable file will be installed in one of |
| these directories. For instance in ‘amhello-1.0’, the program ‘hello’ |
| is to be installed in BINDIR, the directory for binaries. The default |
| value for this directory is ‘/usr/local/bin’, but the user can supply a |
| different value when calling ‘configure’. Also the file ‘README’ will |
| be installed into DOCDIR, which defaults to |
| ‘/usr/local/share/doc/amhello’. |
| |
| As a user, if you wish to install a package on your own account, you |
| could proceed as follows: |
| |
| ~/amhello-1.0 % ./configure --prefix ~/usr |
| … |
| ~/amhello-1.0 % make |
| … |
| ~/amhello-1.0 % make install |
| … |
| |
| This would install ‘~/usr/bin/hello’ and |
| ‘~/usr/share/doc/amhello/README’. |
| |
| The list of all such directory options is shown by ‘./configure |
| --help’. |
| |
| |
| File: automake.info, Node: Standard Configuration Variables, Next: config.site, Prev: Standard Directory Variables, Up: Use Cases |
| |
| 2.2.4 Standard Configuration Variables |
| -------------------------------------- |
| |
| The GNU Coding Standards also define a set of standard configuration |
| variables used during the build. Here are some: |
| |
| ‘CC’ |
| C compiler command |
| ‘CFLAGS’ |
| C compiler flags |
| ‘CXX’ |
| C++ compiler command |
| ‘CXXFLAGS’ |
| C++ compiler flags |
| ‘LDFLAGS’ |
| linker flags |
| ‘CPPFLAGS’ |
| C/C++ preprocessor flags |
| … |
| |
| ‘configure’ usually does a good job at setting appropriate values for |
| these variables, but there are cases where you may want to override |
| them. For instance you may have several versions of a compiler |
| installed and would like to use another one, you may have header files |
| installed outside the default search path of the compiler, or even |
| libraries out of the way of the linker. |
| |
| Here is how one would call ‘configure’ to force it to use ‘gcc-3’ as |
| C compiler, use header files from ‘~/usr/include’ when compiling, and |
| libraries from ‘~/usr/lib’ when linking. |
| |
| ~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \ |
| CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib |
| |
| Again, a full list of these variables appears in the output of |
| ‘./configure --help’. |
| |
| |
| File: automake.info, Node: config.site, Next: VPATH Builds, Prev: Standard Configuration Variables, Up: Use Cases |
| |
| 2.2.5 Overriding Default Configuration Setting with ‘config.site’ |
| ----------------------------------------------------------------- |
| |
| When installing several packages using the same setup, it can be |
| convenient to create a file to capture common settings. If a file named |
| ‘PREFIX/share/config.site’ exists, ‘configure’ will source it at the |
| beginning of its execution. |
| |
| Recall the command from the previous section: |
| |
| ~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \ |
| CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib |
| |
| Assuming we are installing many package in ‘~/usr’, and will always |
| want to use these definitions of ‘CC’, ‘CPPFLAGS’, and ‘LDFLAGS’, we can |
| automate this by creating the following ‘~/usr/share/config.site’ file: |
| |
| test -z "$CC" && CC=gcc-3 |
| test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include |
| test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib |
| |
| Now, any time a ‘configure’ script is using the ‘~/usr’ prefix, it |
| will execute the above ‘config.site’ and define these three variables. |
| |
| ~/amhello-1.0 % ./configure --prefix ~/usr |
| configure: loading site script /home/adl/usr/share/config.site |
| … |
| |
| *Note Setting Site Defaults: (autoconf)Site Defaults, for more |
| information about this feature. |
| |
| |
| File: automake.info, Node: VPATH Builds, Next: Two-Part Install, Prev: config.site, Up: Use Cases |
| |
| 2.2.6 Parallel Build Trees (a.k.a. VPATH Builds) |
| ------------------------------------------------ |
| |
| The GNU Build System distinguishes two trees: the source tree, and the |
| build tree. |
| |
| The source tree is rooted in the directory containing ‘configure’. |
| It contains all the sources files (those that are distributed), and may |
| be arranged using several subdirectories. |
| |
| The build tree is rooted in the directory in which ‘configure’ was |
| run, and is populated with all object files, programs, libraries, and |
| other derived files built from the sources (and hence not distributed). |
| The build tree usually has the same subdirectory layout as the source |
| tree; its subdirectories are created automatically by the build system. |
| |
| If ‘configure’ is executed in its own directory, the source and build |
| trees are combined: derived files are constructed in the same |
| directories as their sources. This was the case in our first |
| installation example (*note Basic Installation::). |
| |
| A common request from users is that they want to confine all derived |
| files to a single directory, to keep their source directories |
| uncluttered. Here is how we could run ‘configure’ to build everything |
| in a subdirectory called ‘build/’. |
| |
| ~ % tar zxf ~/amhello-1.0.tar.gz |
| ~ % cd amhello-1.0 |
| ~/amhello-1.0 % mkdir build && cd build |
| ~/amhello-1.0/build % ../configure |
| … |
| ~/amhello-1.0/build % make |
| … |
| |
| These setups, where source and build trees are different, are often |
| called "parallel builds" or "VPATH builds". The expression _parallel |
| build_ is misleading: the word _parallel_ is a reference to the way the |
| build tree shadows the source tree, it is not about some concurrency in |
| the way build commands are run. For this reason we refer to such setups |
| using the name _VPATH builds_ in the following. _VPATH_ is the name of |
| the ‘make’ feature used by the ‘Makefile’s to allow these builds (*note |
| ‘VPATH’ Search Path for All Prerequisites: (make)General Search.). |
| |
| VPATH builds have other interesting uses. One is to build the same |
| sources with multiple configurations. For instance: |
| |
| ~ % tar zxf ~/amhello-1.0.tar.gz |
| ~ % cd amhello-1.0 |
| ~/amhello-1.0 % mkdir debug optim && cd debug |
| ~/amhello-1.0/debug % ../configure CFLAGS='-g -O0' |
| … |
| ~/amhello-1.0/debug % make |
| … |
| ~/amhello-1.0/debug % cd ../optim |
| ~/amhello-1.0/optim % ../configure CFLAGS='-O3 -fomit-frame-pointer' |
| … |
| ~/amhello-1.0/optim % make |
| … |
| |
| With network file systems, a similar approach can be used to build |
| the same sources on different machines. For instance, suppose that the |
| sources are installed on a directory shared by two hosts: ‘HOST1’ and |
| ‘HOST2’, which may be different platforms. |
| |
| ~ % cd /nfs/src |
| /nfs/src % tar zxf ~/amhello-1.0.tar.gz |
| |
| On the first host, you could create a local build directory: |
| [HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh |
| [HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure |
| ... |
| [HOST1] /tmp/amh % make && sudo make install |
| ... |
| |
| (Here we assume that the installer has configured ‘sudo’ so it can |
| execute ‘make install’ with root privileges; it is more convenient than |
| using ‘su’ like in *note Basic Installation::). |
| |
| On the second host, you would do exactly the same, possibly at the |
| same time: |
| [HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh |
| [HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure |
| ... |
| [HOST2] /tmp/amh % make && sudo make install |
| ... |
| |
| In this scenario, nothing forbids the ‘/nfs/src/amhello-1.0’ |
| directory from being read-only. In fact VPATH builds are also a means |
| of building packages from a read-only medium such as a CD-ROM. (The FSF |
| used to sell CD-ROM with unpacked source code, before the GNU project |
| grew so big.) |
| |
| |
| File: automake.info, Node: Two-Part Install, Next: Cross-Compilation, Prev: VPATH Builds, Up: Use Cases |
| |
| 2.2.7 Two-Part Installation |
| --------------------------- |
| |
| In our last example (*note VPATH Builds::), a source tree was shared by |
| two hosts, but compilation and installation were done separately on each |
| host. |
| |
| The GNU Build System also supports networked setups where part of the |
| installed files should be shared amongst multiple hosts. It does so by |
| distinguishing architecture-dependent files from |
| architecture-independent files, and providing two ‘Makefile’ targets to |
| install each of these classes of files. |
| |
| These targets are ‘install-exec’ for architecture-dependent files and |
| ‘install-data’ for architecture-independent files. The command we used |
| up to now, ‘make install’, can be thought of as a shorthand for ‘make |
| install-exec install-data’. |
| |
| From the GNU Build System point of view, the distinction between |
| architecture-dependent files and architecture-independent files is based |
| exclusively on the directory variable used to specify their installation |
| destination. In the list of directory variables we provided earlier |
| (*note Standard Directory Variables::), all the variables based on |
| EXEC-PREFIX designate architecture-dependent directories whose files |
| will be installed by ‘make install-exec’. The others designate |
| architecture-independent directories and will serve files installed by |
| ‘make install-data’. *Note The Two Parts of Install::, for more |
| details. |
| |
| Here is how we could revisit our two-host installation example, |
| assuming that (1) we want to install the package directly in ‘/usr’, and |
| (2) the directory ‘/usr/share’ is shared by the two hosts. |
| |
| On the first host we would run |
| [HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh |
| [HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure --prefix /usr |
| ... |
| [HOST1] /tmp/amh % make && sudo make install |
| ... |
| |
| On the second host, however, we need only install the |
| architecture-specific files. |
| [HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh |
| [HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure --prefix /usr |
| ... |
| [HOST2] /tmp/amh % make && sudo make install-exec |
| ... |
| |
| In packages that have installation checks, it would make sense to run |
| ‘make installcheck’ (*note Basic Installation::) to verify that the |
| package works correctly despite the apparent partial installation. |
| |
| |
| File: automake.info, Node: Cross-Compilation, Next: Renaming, Prev: Two-Part Install, Up: Use Cases |
| |
| 2.2.8 Cross-Compilation |
| ----------------------- |
| |
| To "cross-compile" is to build on one platform a binary that will run on |
| another platform. When speaking of cross-compilation, it is important |
| to distinguish between the "build platform" on which the compilation is |
| performed, and the "host platform" on which the resulting executable is |
| expected to run. The following ‘configure’ options are used to specify |
| each of them: |
| |
| ‘--build=BUILD’ |
| The system on which the package is built. |
| ‘--host=HOST’ |
| The system where built programs and libraries will run. |
| |
| When the ‘--host’ is used, ‘configure’ will search for the |
| cross-compiling suite for this platform. Cross-compilation tools |
| commonly have their target architecture as prefix of their name. For |
| instance my cross-compiler for MinGW32 has its binaries called |
| ‘i586-mingw32msvc-gcc’, ‘i586-mingw32msvc-ld’, ‘i586-mingw32msvc-as’, |
| etc. |
| |
| Here is how we could build ‘amhello-1.0’ for ‘i586-mingw32msvc’ on a |
| GNU/Linux PC. |
| |
| ~/amhello-1.0 % ./configure --build i686-pc-linux-gnu --host i586-mingw32msvc |
| checking for a BSD-compatible install... /usr/bin/install -c |
| checking whether build environment is sane... yes |
| checking for gawk... gawk |
| checking whether make sets $(MAKE)... yes |
| checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip |
| checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc |
| checking for C compiler default output file name... a.exe |
| checking whether the C compiler works... yes |
| checking whether we are cross compiling... yes |
| checking for suffix of executables... .exe |
| checking for suffix of object files... o |
| checking whether we are using the GNU C compiler... yes |
| checking whether i586-mingw32msvc-gcc accepts -g... yes |
| checking for i586-mingw32msvc-gcc option to accept ANSI C... |
| … |
| ~/amhello-1.0 % make |
| … |
| ~/amhello-1.0 % cd src; file hello.exe |
| hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable |
| |
| The ‘--host’ and ‘--build’ options are usually all we need for |
| cross-compiling. The only exception is if the package being built is |
| itself a cross-compiler: we need a third option to specify its target |
| architecture. |
| |
| ‘--target=TARGET’ |
| When building compiler tools: the system for which the tools will |
| create output. |
| |
| For instance when installing GCC, the GNU Compiler Collection, we can |
| use ‘--target=TARGET’ to specify that we want to build GCC as a |
| cross-compiler for TARGET. Mixing ‘--build’ and ‘--target’, we can |
| actually cross-compile a cross-compiler; such a three-way |
| cross-compilation is known as a "Canadian cross". |
| |
| *Note Specifying the System Type: (autoconf)Specifying Names, for |
| more information about these ‘configure’ options. |
| |
| |
| File: automake.info, Node: Renaming, Next: DESTDIR, Prev: Cross-Compilation, Up: Use Cases |
| |
| 2.2.9 Renaming Programs at Install Time |
| --------------------------------------- |
| |
| The GNU Build System provides means to automatically rename executables |
| and manpages before they are installed (*note Man Pages::). This is |
| especially convenient when installing a GNU package on a system that |
| already has a proprietary implementation you do not want to overwrite. |
| For instance, you may want to install GNU ‘tar’ as ‘gtar’ so you can |
| distinguish it from your vendor’s ‘tar’. |
| |
| This can be done using one of these three ‘configure’ options. |
| |
| ‘--program-prefix=PREFIX’ |
| Prepend PREFIX to installed program names. |
| ‘--program-suffix=SUFFIX’ |
| Append SUFFIX to installed program names. |
| ‘--program-transform-name=PROGRAM’ |
| Run ‘sed PROGRAM’ on installed program names. |
| |
| The following commands would install ‘hello’ as |
| ‘/usr/local/bin/test-hello’, for instance. |
| |
| ~/amhello-1.0 % ./configure --program-prefix test- |
| … |
| ~/amhello-1.0 % make |
| … |
| ~/amhello-1.0 % sudo make install |
| … |
| |
| |
| File: automake.info, Node: DESTDIR, Next: Preparing Distributions, Prev: Renaming, Up: Use Cases |
| |
| 2.2.10 Building Binary Packages Using DESTDIR |
| --------------------------------------------- |
| |
| The GNU Build System’s ‘make install’ and ‘make uninstall’ interface |
| does not exactly fit the needs of a system administrator who has to |
| deploy and upgrade packages on lots of hosts. In other words, the GNU |
| Build System does not replace a package manager. |
| |
| Such package managers usually need to know which files have been |
| installed by a package, so a mere ‘make install’ is inappropriate. |
| |
| The ‘DESTDIR’ variable can be used to perform a staged installation. |
| The package should be configured as if it was going to be installed in |
| its final location (e.g., ‘--prefix /usr’), but when running ‘make |
| install’, the ‘DESTDIR’ should be set to the absolute name of a |
| directory into which the installation will be diverted. From this |
| directory it is easy to review which files are being installed where, |
| and finally copy them to their final location by some means. |
| |
| For instance here is how we could create a binary package containing |
| a snapshot of all the files to be installed. |
| |
| ~/amhello-1.0 % ./configure --prefix /usr |
| … |
| ~/amhello-1.0 % make |
| … |
| ~/amhello-1.0 % make DESTDIR=$HOME/inst install |
| … |
| ~/amhello-1.0 % cd ~/inst |
| ~/inst % find . -type f -print > ../files.lst |
| ~/inst % tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst` |
| ./usr/bin/hello |
| ./usr/share/doc/amhello/README |
| |
| After this example, ‘amhello-1.0-i686.tar.gz’ is ready to be |
| uncompressed in ‘/’ on many hosts. (Using ‘`cat ../files.lst`’ instead |
| of ‘.’ as argument for ‘tar’ avoids entries for each subdirectory in the |
| archive: we would not like ‘tar’ to restore the modification time of |
| ‘/’, ‘/usr/’, etc.) |
| |
| Note that when building packages for several architectures, it might |
| be convenient to use ‘make install-data’ and ‘make install-exec’ (*note |
| Two-Part Install::) to gather architecture-independent files in a single |
| package. |
| |
| *Note Install::, for more information. |
| |
| |
| File: automake.info, Node: Preparing Distributions, Next: Dependency Tracking, Prev: DESTDIR, Up: Use Cases |
| |
| 2.2.11 Preparing Distributions |
| ------------------------------ |
| |
| We have already mentioned ‘make dist’. This target collects all your |
| source files and the necessary parts of the build system to create a |
| tarball named ‘PACKAGE-VERSION.tar.gz’. |
| |
| Another, more useful command is ‘make distcheck’. The ‘distcheck’ |
| target constructs ‘PACKAGE-VERSION.tar.gz’ just as well as ‘dist’, but |
| it additionally ensures most of the use cases presented so far work: |
| |
| • It attempts a full compilation of the package (*note Basic |
| Installation::), unpacking the newly constructed tarball, running |
| ‘make’, ‘make check’, ‘make install’, as well as ‘make |
| installcheck’, and even ‘make dist’, |
| • it tests VPATH builds with read-only source tree (*note VPATH |
| Builds::), |
| • it makes sure ‘make clean’, ‘make distclean’, and ‘make uninstall’ |
| do not omit any file (*note Standard Targets::), |
| • and it checks that ‘DESTDIR’ installations work (*note DESTDIR::). |
| |
| All of these actions are performed in a temporary directory, so that |
| no root privileges are required. Please note that the exact location |
| and the exact structure of such a subdirectory (where the extracted |
| sources are placed, how the temporary build and install directories are |
| named and how deeply they are nested, etc.) is to be considered an |
| implementation detail, which can change at any time; so do not rely on |
| it. |
| |
| Releasing a package that fails ‘make distcheck’ means that one of the |
| scenarios we presented will not work and some users will be |
| disappointed. Therefore it is a good practice to release a package only |
| after a successful ‘make distcheck’. This of course does not imply that |
| the package will be flawless, but at least it will prevent some of the |
| embarrassing errors you may find in packages released by people who have |
| never heard about ‘distcheck’ (like ‘DESTDIR’ not working because of a |
| typo, or a distributed file being erased by ‘make clean’, or even |
| ‘VPATH’ builds not working). |
| |
| *Note Creating amhello::, to recreate ‘amhello-1.0.tar.gz’ using |
| ‘make distcheck’. *Note Checking the Distribution::, for more |
| information about ‘distcheck’. |
| |
| |
| File: automake.info, Node: Dependency Tracking, Next: Nested Packages, Prev: Preparing Distributions, Up: Use Cases |
| |
| 2.2.12 Automatic Dependency Tracking |
| ------------------------------------ |
| |
| Dependency tracking is performed as a side-effect of compilation. Each |
| time the build system compiles a source file, it computes its list of |
| dependencies (in C these are the header files included by the source |
| being compiled). Later, any time ‘make’ is run and a dependency appears |
| to have changed, the dependent files will be rebuilt. |
| |
| Automake generates code for automatic dependency tracking by default, |
| unless the developer chooses to override it; for more information, *note |
| Dependencies::. |
| |
| When ‘configure’ is executed, you can see it probing each compiler |
| for the dependency mechanism it supports (several mechanisms can be |
| used): |
| |
| ~/amhello-1.0 % ./configure --prefix /usr |
| … |
| checking dependency style of gcc... gcc3 |
| … |
| |
| Because dependencies are only computed as a side-effect of the |
| compilation, no dependency information exists the first time a package |
| is built. This is OK because all the files need to be built anyway: |
| ‘make’ does not have to decide which files need to be rebuilt. In fact, |
| dependency tracking is completely useless for one-time builds and there |
| is a ‘configure’ option to disable this: |
| |
| ‘--disable-dependency-tracking’ |
| Speed up one-time builds. |
| |
| Some compilers do not offer any practical way to derive the list of |
| dependencies as a side-effect of the compilation, requiring a separate |
| run (maybe of another tool) to compute these dependencies. The |
| performance penalty implied by these methods is important enough to |
| disable them by default. The option ‘--enable-dependency-tracking’ must |
| be passed to ‘configure’ to activate them. |
| |
| ‘--enable-dependency-tracking’ |
| Do not reject slow dependency extractors. |
| |
| *Note Dependency Tracking Evolution: (automake-history)Dependency |
| Tracking Evolution, for some discussion about the different dependency |
| tracking schemes used by Automake over the years. |
| |
| |
| File: automake.info, Node: Nested Packages, Prev: Dependency Tracking, Up: Use Cases |
| |
| 2.2.13 Nested Packages |
| ---------------------- |
| |
| Although nesting packages isn’t something we would recommend to someone |
| who is discovering the Autotools, it is a nice feature worthy of mention |
| in this small advertising tour. |
| |
| Autoconfiscated packages (that means packages whose build system have |
| been created by Autoconf and friends) can be nested to arbitrary depth. |
| |
| A typical setup is that package A will distribute one of the |
| libraries it needs in a subdirectory. This library B is a complete |
| package with its own GNU Build System. The ‘configure’ script of A will |
| run the ‘configure’ script of B as part of its execution, building and |
| installing A will also build and install B. Generating a distribution |
| for A will also include B. |
| |
| It is possible to gather several packages like this. GCC is a heavy |
| user of this feature. This gives installers a single package to |
| configure, build and install, while it allows developers to work on |
| subpackages independently. |
| |
| When configuring nested packages, the ‘configure’ options given to |
| the top-level ‘configure’ are passed recursively to nested ‘configure’s. |
| A package that does not understand an option will ignore it, assuming it |
| is meaningful to some other package. |
| |
| The command ‘configure --help=recursive’ can be used to display the |
| options supported by all the included packages. |
| |
| *Note Subpackages::, for an example setup. |
| |
| |
| File: automake.info, Node: Why Autotools, Next: Hello World, Prev: Use Cases, Up: Autotools Introduction |
| |
| 2.3 How Autotools Help |
| ====================== |
| |
| There are several reasons why you may not want to implement the GNU |
| Build System yourself (read: write a ‘configure’ script and ‘Makefile’s |
| yourself). |
| |
| • As we have seen, the GNU Build System has a lot of features (*note |
| Use Cases::). Some users may expect features you have not |
| implemented because you did not need them. |
| • Implementing these features portably is difficult and exhausting. |
| Think of writing portable shell scripts, and portable ‘Makefile’s, |
| for systems you may not have handy. *Note Portable Shell |
| Programming: (autoconf)Portable Shell, to convince yourself. |
| • You will have to upgrade your setup to follow changes to the GNU |
| Coding Standards. |
| |
| The GNU Autotools take all this burden off your back and provide: |
| |
| • Tools to create a portable, complete, and self-contained GNU Build |
| System, from simple instructions. _Self-contained_ meaning the |
| resulting build system does not require the GNU Autotools. |
| • A central place where fixes and improvements are made: a bug-fix |
| for a portability issue will benefit every package. |
| |
| Yet there also exist reasons why you may want NOT to use the |
| Autotools... For instance you may be already using (or used to) another |
| incompatible build system. Autotools will only be useful if you do |
| accept the concepts of the GNU Build System. People who have their own |
| idea of how a build system should work will feel frustrated by the |
| Autotools. |
| |
| |
| File: automake.info, Node: Hello World, Prev: Why Autotools, Up: Autotools Introduction |
| |
| 2.4 A Small Hello World |
| ======================= |
| |
| In this section we recreate the ‘amhello-1.0’ package from scratch. The |
| first subsection shows how to call the Autotools to instantiate the GNU |
| Build System, while the second explains the meaning of the |
| ‘configure.ac’ and ‘Makefile.am’ files read by the Autotools. |
| |
| * Menu: |
| |
| * Creating amhello:: Create ‘amhello-1.0.tar.gz’ from scratch |
| * amhello's configure.ac Setup Explained:: |
| * amhello's Makefile.am Setup Explained:: |
| |
| |
| File: automake.info, Node: Creating amhello, Next: amhello's configure.ac Setup Explained, Up: Hello World |
| |
| 2.4.1 Creating ‘amhello-1.0.tar.gz’ |
| ----------------------------------- |
| |
| Here is how we can recreate ‘amhello-1.0.tar.gz’ from scratch. The |
| package is simple enough so that we will only need to write 5 files. |
| (You may copy them from the final ‘amhello-1.0.tar.gz’ that is |
| distributed with Automake if you do not want to write them.) |
| |
| Create the following files in an empty directory. |
| |
| • ‘src/main.c’ is the source file for the ‘hello’ program. We store |
| it in the ‘src/’ subdirectory, because later, when the package |
| evolves, it will ease the addition of a ‘man/’ directory for man |
| pages, a ‘data/’ directory for data files, etc. |
| ~/amhello % cat src/main.c |
| #include <config.h> |
| #include <stdio.h> |
| |
| int |
| main (void) |
| { |
| puts ("Hello World!"); |
| puts ("This is " PACKAGE_STRING "."); |
| return 0; |
| } |
| |
| • ‘README’ contains some very limited documentation for our little |
| package. |
| ~/amhello % cat README |
| This is a demonstration package for GNU Automake. |
| Type 'info Automake' to read the Automake manual. |
| |
| • ‘Makefile.am’ and ‘src/Makefile.am’ contain Automake instructions |
| for these two directories. |
| |
| ~/amhello % cat src/Makefile.am |
| bin_PROGRAMS = hello |
| hello_SOURCES = main.c |
| ~/amhello % cat Makefile.am |
| SUBDIRS = src |
| dist_doc_DATA = README |
| |
| • Finally, ‘configure.ac’ contains Autoconf instructions to create |
| the ‘configure’ script. |
| |
| ~/amhello % cat configure.ac |
| AC_INIT([amhello], [1.0], [bug-automake@gnu.org]) |
| AM_INIT_AUTOMAKE([-Wall -Werror foreign]) |
| AC_PROG_CC |
| AC_CONFIG_HEADERS([config.h]) |
| AC_CONFIG_FILES([ |
| Makefile |
| src/Makefile |
| ]) |
| AC_OUTPUT |
| |
| Once you have these five files, it is time to run the Autotools to |
| instantiate the build system. Do this using the ‘autoreconf’ command as |
| follows: |
| |
| ~/amhello % autoreconf --install |
| configure.ac: installing './install-sh' |
| configure.ac: installing './missing' |
| configure.ac: installing './compile' |
| src/Makefile.am: installing './depcomp' |
| |
| At this point the build system is complete. |
| |
| In addition to the three scripts mentioned in its output, you can see |
| that ‘autoreconf’ created four other files: ‘configure’, ‘config.h.in’, |
| ‘Makefile.in’, and ‘src/Makefile.in’. The latter three files are |
| templates that will be adapted to the system by ‘configure’ under the |
| names ‘config.h’, ‘Makefile’, and ‘src/Makefile’. Let’s do this: |
| |
| ~/amhello % ./configure |
| checking for a BSD-compatible install... /usr/bin/install -c |
| checking whether build environment is sane... yes |
| checking for gawk... no |
| checking for mawk... mawk |
| checking whether make sets $(MAKE)... yes |
| checking for gcc... gcc |
| checking for C compiler default output file name... a.out |
| checking whether the C compiler works... yes |
| checking whether we are cross compiling... no |
| checking for suffix of executables... |
| checking for suffix of object files... o |
| checking whether we are using the GNU C compiler... yes |
| checking whether gcc accepts -g... yes |
| checking for gcc option to accept ISO C89... none needed |
| checking for style of include used by make... GNU |
| checking dependency style of gcc... gcc3 |
| configure: creating ./config.status |
| config.status: creating Makefile |
| config.status: creating src/Makefile |
| config.status: creating config.h |
| config.status: executing depfiles commands |
| |
| You can see ‘Makefile’, ‘src/Makefile’, and ‘config.h’ being created |
| at the end after ‘configure’ has probed the system. It is now possible |
| to run all the targets we wish (*note Standard Targets::). For |
| instance: |
| |
| ~/amhello % make |
| … |
| ~/amhello % src/hello |
| Hello World! |
| This is amhello 1.0. |
| ~/amhello % make distcheck |
| … |
| ============================================= |
| amhello-1.0 archives ready for distribution: |
| amhello-1.0.tar.gz |
| ============================================= |
| |
| Note that running ‘autoreconf’ is only needed initially when the GNU |
| Build System does not exist. When you later change some instructions in |
| a ‘Makefile.am’ or ‘configure.ac’, the relevant part of the build system |
| will be regenerated automatically when you execute ‘make’. |
| |
| ‘autoreconf’ is a script that calls ‘autoconf’, ‘automake’, and a |
| bunch of other commands in the right order. If you are beginning with |
| these tools, it is not important to figure out in which order all of |
| these tools should be invoked and why. However, because Autoconf and |
| Automake have separate manuals, the important point to understand is |
| that ‘autoconf’ is in charge of creating ‘configure’ from |
| ‘configure.ac’, while ‘automake’ is in charge of creating ‘Makefile.in’s |
| from ‘Makefile.am’s and ‘configure.ac’. This should at least direct you |
| to the right manual when seeking answers. |
| |
| |
| File: automake.info, Node: amhello's configure.ac Setup Explained, Next: amhello's Makefile.am Setup Explained, Prev: Creating amhello, Up: Hello World |
| |
| 2.4.2 ‘amhello’’s ‘configure.ac’ Setup Explained |
| ------------------------------------------------ |
| |
| Let us begin with the contents of ‘configure.ac’. |
| |
| AC_INIT([amhello], [1.0], [bug-automake@gnu.org]) |
| AM_INIT_AUTOMAKE([-Wall -Werror foreign]) |
| AC_PROG_CC |
| AC_CONFIG_HEADERS([config.h]) |
| AC_CONFIG_FILES([ |
| Makefile |
| src/Makefile |
| ]) |
| AC_OUTPUT |
| |
| This file is read by both ‘autoconf’ (to create ‘configure’) and |
| ‘automake’ (to create the various ‘Makefile.in’s). It contains a series |
| of M4 macros that will be expanded as shell code to finally form the |
| ‘configure’ script. We will not elaborate on the syntax of this file, |
| because the Autoconf manual has a whole section about it (*note Writing |
| ‘configure.ac’: (autoconf)Writing Autoconf Input.). |
| |
| The macros prefixed with ‘AC_’ are Autoconf macros, documented in the |
| Autoconf manual (*note Autoconf Macro Index: (autoconf)Autoconf Macro |
| Index.). The macros that start with ‘AM_’ are Automake macros, |
| documented later in this manual (*note Macro Index::). |
| |
| The first two lines of ‘configure.ac’ initialize Autoconf and |
| Automake. ‘AC_INIT’ takes in as parameters the name of the package, its |
| version number, and a contact address for bug-reports about the package |
| (this address is output at the end of ‘./configure --help’, for |
| instance). When adapting this setup to your own package, by all means |
| please do not blindly copy Automake’s address: use the mailing list of |
| your package, or your own mail address. |
| |
| The argument to ‘AM_INIT_AUTOMAKE’ is a list of options for |
| ‘automake’ (*note Options::). ‘-Wall’ and ‘-Werror’ ask ‘automake’ to |
| turn on all warnings and report them as errors. We are speaking of |
| *Automake* warnings here, such as dubious instructions in ‘Makefile.am’. |
| This has absolutely nothing to do with how the compiler will be called, |
| even though it may support options with similar names. Using ‘-Wall |
| -Werror’ is a safe setting when starting to work on a package: you do |
| not want to miss any issues. Later you may decide to relax things a |
| bit. The ‘foreign’ option tells Automake that this package will not |
| follow the GNU Standards. GNU packages should always distribute |
| additional files such as ‘ChangeLog’, ‘AUTHORS’, etc. We do not want |
| ‘automake’ to complain about these missing files in our small example. |
| |
| The ‘AC_PROG_CC’ line causes the ‘configure’ script to search for a C |
| compiler and define the variable ‘CC’ with its name. The |
| ‘src/Makefile.in’ file generated by Automake uses the variable ‘CC’ to |
| build ‘hello’, so when ‘configure’ creates ‘src/Makefile’ from |
| ‘src/Makefile.in’, it will define ‘CC’ with the value it has found. If |
| Automake is asked to create a ‘Makefile.in’ that uses ‘CC’ but |
| ‘configure.ac’ does not define it, it will suggest you add a call to |
| ‘AC_PROG_CC’. |
| |
| The ‘AC_CONFIG_HEADERS([config.h])’ invocation causes the ‘configure’ |
| script to create a ‘config.h’ file gathering ‘#define’s defined by other |
| macros in ‘configure.ac’. In our case, the ‘AC_INIT’ macro already |
| defined a few of them. Here is an excerpt of ‘config.h’ after |
| ‘configure’ has run: |
| |
| … |
| /* Define to the address where bug reports for this package should be sent. */ |
| #define PACKAGE_BUGREPORT "bug-automake@gnu.org" |
| |
| /* Define to the full name and version of this package. */ |
| #define PACKAGE_STRING "amhello 1.0" |
| … |
| |
| As you probably noticed, ‘src/main.c’ includes ‘config.h’ so it can |
| use ‘PACKAGE_STRING’. In a real-world project, ‘config.h’ can grow |
| really big, with one ‘#define’ per feature probed on the system. |
| |
| The ‘AC_CONFIG_FILES’ macro declares the list of files that |
| ‘configure’ should create from their ‘*.in’ templates. Automake also |
| scans this list to find the ‘Makefile.am’ files it must process. (This |
| is important to remember: when adding a new directory to your project, |
| you should add its ‘Makefile’ to this list, otherwise Automake will |
| never process the new ‘Makefile.am’ you wrote in that directory.) |
| |
| Finally, the ‘AC_OUTPUT’ line is a closing command that actually |
| produces the part of the script in charge of creating the files |
| registered with ‘AC_CONFIG_HEADERS’ and ‘AC_CONFIG_FILES’. |
| |
| When starting a new project, we suggest you start with such a simple |
| ‘configure.ac’, and gradually add the other tests it requires. The |
| command ‘autoscan’ can also suggest a few of the tests your package may |
| need (*note Using ‘autoscan’ to Create ‘configure.ac’: |
| (autoconf)autoscan Invocation.). |
| |
| |
| File: automake.info, Node: amhello's Makefile.am Setup Explained, Prev: amhello's configure.ac Setup Explained, Up: Hello World |
| |
| 2.4.3 ‘amhello’’s ‘Makefile.am’ Setup Explained |
| ----------------------------------------------- |
| |
| We now turn to ‘src/Makefile.am’. This file contains Automake |
| instructions to build and install ‘hello’. |
| |
| bin_PROGRAMS = hello |
| hello_SOURCES = main.c |
| |
| A ‘Makefile.am’ has the same syntax as an ordinary ‘Makefile’. When |
| ‘automake’ processes a ‘Makefile.am’ it copies the entire file into the |
| output ‘Makefile.in’ (that will be later turned into ‘Makefile’ by |
| ‘configure’) but will react to certain variable definitions by |
| generating some build rules and other variables. Often ‘Makefile.am’s |
| contain only a list of variable definitions as above, but they can also |
| contain other variable and rule definitions that ‘automake’ will pass |
| along without interpretation. |
| |
| Variables that end with ‘_PROGRAMS’ are special variables that list |
| programs that the resulting ‘Makefile’ should build. In Automake speak, |
| this ‘_PROGRAMS’ suffix is called a "primary"; Automake recognizes other |
| primaries such as ‘_SCRIPTS’, ‘_DATA’, ‘_LIBRARIES’, etc. corresponding |
| to different types of files. |
| |
| The ‘bin’ part of the ‘bin_PROGRAMS’ tells ‘automake’ that the |
| resulting programs should be installed in BINDIR. Recall that the GNU |
| Build System uses a set of variables to denote destination directories |
| and allow users to customize these locations (*note Standard Directory |
| Variables::). Any such directory variable can be put in front of a |
| primary (omitting the ‘dir’ suffix) to tell ‘automake’ where to install |
| the listed files. |
| |
| Programs need to be built from source files, so for each program |
| ‘PROG’ listed in a ‘_PROGRAMS’ variable, ‘automake’ will look for |
| another variable named ‘PROG_SOURCES’ listing its source files. There |
| may be more than one source file: they will all be compiled and linked |
| together. |
| |
| Automake also knows that source files need to be distributed when |
| creating a tarball (unlike built programs). So a side-effect of this |
| ‘hello_SOURCES’ declaration is that ‘main.c’ will be part of the tarball |
| created by ‘make dist’. |
| |
| Finally here are some explanations regarding the top-level |
| ‘Makefile.am’. |
| |
| SUBDIRS = src |
| dist_doc_DATA = README |
| |
| ‘SUBDIRS’ is a special variable listing all directories that ‘make’ |
| should recurse into before processing the current directory. So this |
| line is responsible for ‘make’ building ‘src/hello’ even though we run |
| it from the top-level. This line also causes ‘make install’ to install |
| ‘src/hello’ before installing ‘README’ (not that this order matters). |
| |
| The line ‘dist_doc_DATA = README’ causes ‘README’ to be distributed |
| and installed in DOCDIR. Files listed with the ‘_DATA’ primary are not |
| automatically part of the tarball built with ‘make dist’, so we add the |
| ‘dist_’ prefix so they get distributed. However, for ‘README’ it would |
| not have been necessary: ‘automake’ automatically distributes any |
| ‘README’ file it encounters (the list of other files automatically |
| distributed is presented by ‘automake --help’). The only important |
| effect of this second line is therefore to install ‘README’ during ‘make |
| install’. |
| |
| One thing not covered in this example is accessing the installation |
| directory values (*note Standard Directory Variables::) from your |
| program code, that is, converting them into defined macros. For this, |
| *note (autoconf)Defining Directories::. |
| |
| |
| File: automake.info, Node: Generalities, Next: Examples, Prev: Autotools Introduction, Up: Top |
| |
| 3 General ideas |
| *************** |
| |
| The following sections cover a few basic ideas that will help you |
| understand how Automake works. |
| |
| * Menu: |
| |
| * General Operation:: General operation of Automake |
| * Strictness:: Standards conformance checking |
| * Uniform:: The Uniform Naming Scheme |
| * Length Limitations:: Staying below the command line length limit |
| * Canonicalization:: How derived variables are named |
| * User Variables:: Variables reserved for the user |
| * Auxiliary Programs:: Programs automake might require |
| |
| |
| File: automake.info, Node: General Operation, Next: Strictness, Up: Generalities |
| |
| 3.1 General Operation |
| ===================== |
| |
| Automake works by reading a ‘Makefile.am’ and generating a |
| ‘Makefile.in’. Certain variables and rules defined in the ‘Makefile.am’ |
| instruct Automake to generate more specialized code; for instance, a |
| ‘bin_PROGRAMS’ variable definition will cause rules for compiling and |
| linking programs to be generated. |
| |
| The variable definitions and rules in the ‘Makefile.am’ are copied |
| mostly verbatim into the generated file, with all variable definitions |
| preceding all rules. This allows you to add almost arbitrary code into |
| the generated ‘Makefile.in’. For instance, the Automake distribution |
| includes a non-standard rule for the ‘git-dist’ target, which the |
| Automake maintainer uses to make distributions from the source control |
| system. |
| |
| Note that most GNU make extensions are not recognized by Automake. |
| Using such extensions in a ‘Makefile.am’ will lead to errors or |
| confusing behavior. |
| |
| A special exception is that the GNU make append operator, ‘+=’, is |
| supported. This operator appends its right hand argument to the |
| variable specified on the left. Automake will translate the operator |
| into an ordinary ‘=’ operator; ‘+=’ will thus work with any make |
| program. |
| |
| Automake tries to keep comments grouped with any adjoining rules or |
| variable definitions. |
| |
| Generally, Automake is not particularly smart in the parsing of |
| unusual Makefile constructs, so you’re advised to avoid fancy constructs |
| or “creative” use of whitespace. For example, <TAB> characters cannot |
| be used between a target name and the following “‘:’” character, and |
| variable assignments shouldn’t be indented with <TAB> characters. Also, |
| using more complex macro in target names can cause trouble: |
| |
| % cat Makefile.am |
| $(FOO:=x): bar |
| % automake |
| Makefile.am:1: bad characters in variable name '$(FOO' |
| Makefile.am:1: ':='-style assignments are not portable |
| |
| A rule defined in ‘Makefile.am’ generally overrides any such rule of |
| a similar name that would be automatically generated by ‘automake’. |
| Although this is a supported feature, it is generally best to avoid |
| making use of it, as sometimes the generated rules are very particular. |
| |
| Similarly, a variable defined in ‘Makefile.am’ or ‘AC_SUBST’ed from |
| ‘configure.ac’ will override any definition of the variable that |
| ‘automake’ would ordinarily create. This feature is more often useful |
| than the ability to override a rule. Be warned that many of the |
| variables generated by ‘automake’ are considered to be for internal use |
| only, and their names might change in future releases. |
| |
| When examining a variable definition, Automake will recursively |
| examine variables referenced in the definition. For example, if |
| Automake is looking at the content of ‘foo_SOURCES’ in this snippet |
| |
| xs = a.c b.c |
| foo_SOURCES = c.c $(xs) |
| |
| it would use the files ‘a.c’, ‘b.c’, and ‘c.c’ as the contents of |
| ‘foo_SOURCES’. |
| |
| Automake also allows a form of comment that is _not_ copied into the |
| output; all lines beginning with ‘##’ (leading spaces allowed) are |
| completely ignored by Automake. |
| |
| It is customary to make the first line of ‘Makefile.am’ read: |
| |
| ## Process this file with automake to produce Makefile.in |
| |
| |
| File: automake.info, Node: Strictness, Next: Uniform, Prev: General Operation, Up: Generalities |
| |
| 3.2 Strictness |
| ============== |
| |
| While Automake is intended to be used by maintainers of GNU packages, it |
| does make some effort to accommodate those who wish to use it, but do |
| not want to use all the GNU conventions. |
| |
| To this end, Automake supports three levels of "strictness"—the |
| strictness indicating how stringently Automake should check standards |
| conformance. |
| |
| The valid strictness levels are: |
| |
| ‘foreign’ |
| Automake will check for only those things that are absolutely |
| required for proper operations. For instance, whereas GNU |
| standards dictate the existence of a ‘NEWS’ file, it will not be |
| required in this mode. This strictness will also turn off some |
| warnings by default (among them, portability warnings). The name |
| comes from the fact that Automake is intended to be used for GNU |
| programs; these relaxed rules are not the standard mode of |
| operation. |
| |
| ‘gnu’ |
| Automake will check—as much as possible—for compliance to the GNU |
| standards for packages. This is the default. |
| |
| ‘gnits’ |
| Automake will check for compliance to the as-yet-unwritten "Gnits |
| standards". These are based on the GNU standards, but are even |
| more detailed. Unless you are a Gnits standards contributor, it is |
| recommended that you avoid this option until such time as the Gnits |
| standard is actually published (which may never happen). |
| |
| *Note Gnits::, for more information on the precise implications of |
| the strictness level. |
| |
| |
| File: automake.info, Node: Uniform, Next: Length Limitations, Prev: Strictness, Up: Generalities |
| |
| 3.3 The Uniform Naming Scheme |
| ============================= |
| |
| Automake variables generally follow a "uniform naming scheme" that makes |
| it easy to decide how programs (and other derived objects) are built, |
| and how they are installed. This scheme also supports ‘configure’ time |
| determination of what should be built. |
| |
| At ‘make’ time, certain variables are used to determine which objects |
| are to be built. The variable names are made of several pieces that are |
| concatenated together. |
| |
| The piece that tells ‘automake’ what is being built is commonly |
| called the "primary". For instance, the primary ‘PROGRAMS’ holds a list |
| of programs that are to be compiled and linked. |
| |
| A different set of names is used to decide where the built objects |
| should be installed. These names are prefixes to the primary, and they |
| indicate which standard directory should be used as the installation |
| directory. The standard directory names are given in the GNU standards |
| (*note (standards)Directory Variables::). Automake extends this list |
| with ‘pkgdatadir’, ‘pkgincludedir’, ‘pkglibdir’, and ‘pkglibexecdir’; |
| these are the same as the non-‘pkg’ versions, but with ‘$(PACKAGE)’ |
| appended. For instance, ‘pkglibdir’ is defined as |
| ‘$(libdir)/$(PACKAGE)’. |
| |
| For each primary, there is one additional variable named by |
| prepending ‘EXTRA_’ to the primary name. This variable is used to list |
| objects that may or may not be built, depending on what ‘configure’ |
| decides. This variable is required because Automake must statically |
| know the entire list of objects that may be built in order to generate a |
| ‘Makefile.in’ that will work in all cases. |
| |
| For instance, ‘cpio’ decides at configure time which programs should |
| be built. Some of the programs are installed in ‘bindir’, and some are |
| installed in ‘sbindir’: |
| |
| EXTRA_PROGRAMS = mt rmt |
| bin_PROGRAMS = cpio pax |
| sbin_PROGRAMS = $(MORE_PROGRAMS) |
| |
| Defining a primary without a prefix as a variable, e.g., ‘PROGRAMS’, |
| is an error. |
| |
| Note that the common ‘dir’ suffix is left off when constructing the |
| variable names; thus one writes ‘bin_PROGRAMS’ and not |
| ‘bindir_PROGRAMS’. |
| |
| Not every sort of object can be installed in every directory. |
| Automake will flag those attempts it finds in error (but see below how |
| to override the check if you really need to). Automake will also |
| diagnose obvious misspellings in directory names. |
| |
| Sometimes the standard directories—even as augmented by Automake—are |
| not enough. In particular it is sometimes useful, for clarity, to |
| install objects in a subdirectory of some predefined directory. To this |
| end, Automake allows you to extend the list of possible installation |
| directories. A given prefix (e.g., ‘zar’) is valid if a variable of the |
| same name with ‘dir’ appended is defined (e.g., ‘zardir’). |
| |
| For instance, the following snippet will install ‘file.xml’ into |
| ‘$(datadir)/xml’. |
| |
| xmldir = $(datadir)/xml |
| xml_DATA = file.xml |
| |
| This feature can also be used to override the sanity checks Automake |
| performs to diagnose suspicious directory/primary couples (in the |
| unlikely case these checks are undesirable, and you really know what |
| you’re doing). For example, Automake would error out on this input: |
| |
| # Forbidden directory combinations, automake will error out on this. |
| pkglib_PROGRAMS = foo |
| doc_LIBRARIES = libquux.a |
| |
| but it will succeed with this: |
| |
| # Work around forbidden directory combinations. Do not use this |
| # without a very good reason! |
| my_execbindir = $(pkglibdir) |
| my_doclibdir = $(docdir) |
| my_execbin_PROGRAMS = foo |
| my_doclib_LIBRARIES = libquux.a |
| |
| The ‘exec’ substring of the ‘my_execbindir’ variable lets the files |
| be installed at the right time (*note The Two Parts of Install::). |
| |
| The special prefix ‘noinst_’ indicates that the objects in question |
| should be built but not installed at all. This is usually used for |
| objects required to build the rest of your package, for instance static |
| libraries (*note A Library::), or helper scripts. |
| |
| The special prefix ‘check_’ indicates that the objects in question |
| should not be built until the ‘make check’ command is run. Those |
| objects are not installed either. |
| |
| The current primary names are ‘PROGRAMS’, ‘LIBRARIES’, ‘LTLIBRARIES’, |
| ‘LISP’, ‘PYTHON’, ‘JAVA’, ‘SCRIPTS’, ‘DATA’, ‘HEADERS’, ‘MANS’, and |
| ‘TEXINFOS’. |
| |
| Some primaries also allow additional prefixes that control other |
| aspects of ‘automake’’s behavior. The currently defined prefixes are |
| ‘dist_’, ‘nodist_’, ‘nobase_’, and ‘notrans_’. These prefixes are |
| explained later (*note Program and Library Variables::) (*note Man |
| Pages::). |
| |
| |
| File: automake.info, Node: Length Limitations, Next: Canonicalization, Prev: Uniform, Up: Generalities |
| |
| 3.4 Staying below the command line length limit |
| =============================================== |
| |
| Traditionally, most unix-like systems have a length limitation for the |
| command line arguments and environment contents when creating new |
| processes (see for example |
| <http://www.in-ulm.de/~mascheck/various/argmax/> for an overview on this |
| issue), which of course also applies to commands spawned by ‘make’. |
| POSIX requires this limit to be at least 4096 bytes, and most modern |
| systems have quite high limits (or are unlimited). |
| |
| In order to create portable Makefiles that do not trip over these |
| limits, it is necessary to keep the length of file lists bounded. |
| Unfortunately, it is not possible to do so fully transparently within |
| Automake, so your help may be needed. Typically, you can split long |
| file lists manually and use different installation directory names for |
| each list. For example, |
| |
| data_DATA = file1 … fileN fileN+1 … file2N |
| |
| may also be written as |
| |
| data_DATA = file1 … fileN |
| data2dir = $(datadir) |
| data2_DATA = fileN+1 … file2N |
| |
| and will cause Automake to treat the two lists separately during ‘make |
| install’. See *note The Two Parts of Install:: for choosing directory |
| names that will keep the ordering of the two parts of installation Note |
| that ‘make dist’ may still only work on a host with a higher length |
| limit in this example. |
| |
| Automake itself employs a couple of strategies to avoid long command |
| lines. For example, when ‘${srcdir}/’ is prepended to file names, as |
| can happen with above ‘$(data_DATA)’ lists, it limits the amount of |
| arguments passed to external commands. |
| |
| Unfortunately, some system’s ‘make’ commands may prepend ‘VPATH’ |
| prefixes like ‘${srcdir}/’ to file names from the source tree |
| automatically (*note Automatic Rule Rewriting: (autoconf)Automatic Rule |
| Rewriting.). In this case, the user may have to switch to use GNU Make, |
| or refrain from using VPATH builds, in order to stay below the length |
| limit. |
| |
| For libraries and programs built from many sources, convenience |
| archives may be used as intermediates in order to limit the object list |
| length (*note Libtool Convenience Libraries::). |
| |
| |
| File: automake.info, Node: Canonicalization, Next: User Variables, Prev: Length Limitations, Up: Generalities |
| |
| 3.5 How derived variables are named |
| =================================== |
| |
| Sometimes a Makefile variable name is derived from some text the |
| maintainer supplies. For instance, a program name listed in ‘_PROGRAMS’ |
| is rewritten into the name of a ‘_SOURCES’ variable. In cases like |
| this, Automake canonicalizes the text, so that program names and the |
| like do not have to follow Makefile variable naming rules. All |
| characters in the name except for letters, numbers, the strudel (@), and |
| the underscore are turned into underscores when making variable |
| references. |
| |
| For example, if your program is named ‘sniff-glue’, the derived |
| variable name would be ‘sniff_glue_SOURCES’, not ‘sniff-glue_SOURCES’. |
| Similarly the sources for a library named ‘libmumble++.a’ should be |
| listed in the ‘libmumble___a_SOURCES’ variable. |
| |
| The strudel is an addition, to make the use of Autoconf substitutions |
| in variable names less obfuscating. |
| |
| |
| File: automake.info, Node: User Variables, Next: Auxiliary Programs, Prev: Canonicalization, Up: Generalities |
| |
| 3.6 Variables reserved for the user |
| =================================== |
| |
| Some ‘Makefile’ variables are reserved by the GNU Coding Standards for |
| the use of the “user”—the person building the package. For instance, |
| ‘CFLAGS’ is one such variable. |
| |
| Sometimes package developers are tempted to set user variables such |
| as ‘CFLAGS’ because it appears to make their job easier. However, the |
| package itself should never set a user variable, particularly not to |
| include switches that are required for proper compilation of the |
| package. Since these variables are documented as being for the package |
| builder, that person rightfully expects to be able to override any of |
| these variables at build time. |
| |
| To get around this problem, Automake introduces an automake-specific |
| shadow variable for each user flag variable. (Shadow variables are not |
| introduced for variables like ‘CC’, where they would make no sense.) |
| The shadow variable is named by prepending ‘AM_’ to the user variable’s |
| name. For instance, the shadow variable for ‘YFLAGS’ is ‘AM_YFLAGS’. |
| The package maintainer—that is, the author(s) of the ‘Makefile.am’ and |
| ‘configure.ac’ files—may adjust these shadow variables however |
| necessary. |
| |
| *Note Flag Variables Ordering::, for more discussion about these |
| variables and how they interact with per-target variables. |
| |
| |
| File: automake.info, Node: Auxiliary Programs, Prev: User Variables, Up: Generalities |
| |
| 3.7 Programs automake might require |
| =================================== |
| |
| Automake sometimes requires helper programs so that the generated |
| ‘Makefile’ can do its work properly. There are a fairly large number of |
| them, and we list them here. |
| |
| Although all of these files are distributed and installed with |
| Automake, a couple of them are maintained separately. The Automake |
| copies are updated before each release, but we mention the original |
| source in case you need more recent versions. |
| |
| ‘ar-lib’ |
| This is a wrapper primarily for the Microsoft lib archiver, to make |
| it more POSIX-like. |
| |
| ‘compile’ |
| This is a wrapper for compilers that do not accept options ‘-c’ and |
| ‘-o’ at the same time. It is only used when absolutely required. |
| Such compilers are rare, with the Microsoft C/C++ Compiler as the |
| most notable exception. This wrapper also makes the following |
| common options available for that compiler, while performing file |
| name translation where needed: ‘-I’, ‘-L’, ‘-l’, ‘-Wl,’ and |
| ‘-Xlinker’. |
| |
| ‘config.guess’ |
| ‘config.sub’ |
| These two programs compute the canonical triplets for the given |
| build, host, or target architecture. These programs are updated |
| regularly to support new architectures and fix probes broken by |
| changes in new kernel versions. Each new release of Automake comes |
| with up-to-date copies of these programs. If your copy of Automake |
| is getting old, you are encouraged to fetch the latest versions of |
| these files from <http://savannah.gnu.org/git/?group=config> before |
| making a release. |
| |
| ‘depcomp’ |
| This program understands how to run a compiler so that it will |
| generate not only the desired output but also dependency |
| information that is then used by the automatic dependency tracking |
| feature (*note Dependencies::). |
| |
| ‘install-sh’ |
| This is a replacement for the ‘install’ program that works on |
| platforms where ‘install’ is unavailable or unusable. |
| |
| ‘mdate-sh’ |
| This script is used to generate a ‘version.texi’ file. It examines |
| a file and prints some date information about it. |
| |
| ‘missing’ |
| This wraps a number of programs that are typically only required by |
| maintainers. If the program in question doesn’t exist, or seems to |
| old, ‘missing’ will print an informative warning before failing |
| out, to provide the user with more context and information. |
| |
| ‘mkinstalldirs’ |
| This script used to be a wrapper around ‘mkdir -p’, which is not |
| portable. Now we prefer to use ‘install-sh -d’ when ‘configure’ |
| finds that ‘mkdir -p’ does not work, this makes one less script to |
| distribute. |
| |
| For backward compatibility ‘mkinstalldirs’ is still used and |
| distributed when ‘automake’ finds it in a package. But it is no |
| longer installed automatically, and it should be safe to remove it. |
| |
| ‘py-compile’ |
| This is used to byte-compile Python scripts. |
| |
| ‘test-driver’ |
| This implements the default test driver offered by the parallel |
| testsuite harness. |
| |
| ‘texinfo.tex’ |
| Not a program, this file is required for ‘make dvi’, ‘make ps’ and |
| ‘make pdf’ to work when Texinfo sources are in the package. The |
| latest version can be downloaded from |
| <http://www.gnu.org/software/texinfo/>. |
| |
| ‘ylwrap’ |
| This program wraps ‘lex’ and ‘yacc’ to rename their output files. |
| It also ensures that, for instance, multiple ‘yacc’ instances can |
| be invoked in a single directory in parallel. |
| |
| |
| File: automake.info, Node: Examples, Next: automake Invocation, Prev: Generalities, Up: Top |
| |
| 4 Some example packages |
| *********************** |
| |
| This section contains two small examples. |
| |
| The first example (*note Complete::) assumes you have an existing |
| project already using Autoconf, with handcrafted ‘Makefile’s, and that |
| you want to convert it to using Automake. If you are discovering both |
| tools, it is probably better that you look at the Hello World example |
| presented earlier (*note Hello World::). |
| |
| The second example (*note true::) shows how two programs can be built |
| from the same file, using different compilation parameters. It contains |
| some technical digressions that are probably best skipped on first read. |
| |
| * Menu: |
| |
| * Complete:: A simple example, start to finish |
| * true:: Building true and false |
| |
| |
| File: automake.info, Node: Complete, Next: true, Up: Examples |
| |
| 4.1 A simple example, start to finish |
| ===================================== |
| |
| Let’s suppose you just finished writing ‘zardoz’, a program to make your |
| head float from vortex to vortex. You’ve been using Autoconf to provide |
| a portability framework, but your ‘Makefile.in’s have been ad-hoc. You |
| want to make them bulletproof, so you turn to Automake. |
| |
| The first step is to update your ‘configure.ac’ to include the |
| commands that ‘automake’ needs. The way to do this is to add an |
| ‘AM_INIT_AUTOMAKE’ call just after ‘AC_INIT’: |
| |
| AC_INIT([zardoz], [1.0]) |
| AM_INIT_AUTOMAKE |
| … |
| |
| Since your program doesn’t have any complicating factors (e.g., it |
| doesn’t use ‘gettext’, it doesn’t want to build a shared library), |
| you’re done with this part. That was easy! |
| |
| Now you must regenerate ‘configure’. But to do that, you’ll need to |
| tell ‘autoconf’ how to find the new macro you’ve used. The easiest way |
| to do this is to use the ‘aclocal’ program to generate your ‘aclocal.m4’ |
| for you. But wait… maybe you already have an ‘aclocal.m4’, because you |
| had to write some hairy macros for your program. The ‘aclocal’ program |
| lets you put your own macros into ‘acinclude.m4’, so simply rename and |
| then run: |
| |
| mv aclocal.m4 acinclude.m4 |
| aclocal |
| autoconf |
| |
| Now it is time to write your ‘Makefile.am’ for ‘zardoz’. Since |
| ‘zardoz’ is a user program, you want to install it where the rest of the |
| user programs go: ‘bindir’. Additionally, ‘zardoz’ has some Texinfo |
| documentation. Your ‘configure.ac’ script uses ‘AC_REPLACE_FUNCS’, so |
| you need to link against ‘$(LIBOBJS)’. So here’s what you’d write: |
| |
| bin_PROGRAMS = zardoz |
| zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c |
| zardoz_LDADD = $(LIBOBJS) |
| |
| info_TEXINFOS = zardoz.texi |
| |
| Now you can run ‘automake --add-missing’ to generate your |
| ‘Makefile.in’ and grab any auxiliary files you might need, and you’re |
| done! |
| |
| |
| File: automake.info, Node: true, Prev: Complete, Up: Examples |
| |
| 4.2 Building true and false |
| =========================== |
| |
| Here is another, trickier example. It shows how to generate two |
| programs (‘true’ and ‘false’) from the same source file (‘true.c’). The |
| difficult part is that each compilation of ‘true.c’ requires different |
| ‘cpp’ flags. |
| |
| bin_PROGRAMS = true false |
| false_SOURCES = |
| false_LDADD = false.o |
| |
| true.o: true.c |
| $(COMPILE) -DEXIT_CODE=0 -c true.c |
| |
| false.o: true.c |
| $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c |
| |
| Note that there is no ‘true_SOURCES’ definition. Automake will |
| implicitly assume that there is a source file named ‘true.c’ (*note |
| Default _SOURCES::), and define rules to compile ‘true.o’ and link |
| ‘true’. The ‘true.o: true.c’ rule supplied by the above ‘Makefile.am’, |
| will override the Automake generated rule to build ‘true.o’. |
| |
| ‘false_SOURCES’ is defined to be empty—that way no implicit value is |
| substituted. Because we have not listed the source of ‘false’, we have |
| to tell Automake how to link the program. This is the purpose of the |
| ‘false_LDADD’ line. A ‘false_DEPENDENCIES’ variable, holding the |
| dependencies of the ‘false’ target will be automatically generated by |
| Automake from the content of ‘false_LDADD’. |
| |
| The above rules won’t work if your compiler doesn’t accept both ‘-c’ |
| and ‘-o’. The simplest fix for this is to introduce a bogus dependency |
| (to avoid problems with a parallel ‘make’): |
| |
| true.o: true.c false.o |
| $(COMPILE) -DEXIT_CODE=0 -c true.c |
| |
| false.o: true.c |
| $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o |
| |
| As it turns out, there is also a much easier way to do this same |
| task. Some of the above technique is useful enough that we’ve kept the |
| example in the manual. However if you were to build ‘true’ and ‘false’ |
| in real life, you would probably use per-program compilation flags, like |
| so: |
| |
| bin_PROGRAMS = false true |
| |
| false_SOURCES = true.c |
| false_CPPFLAGS = -DEXIT_CODE=1 |
| |
| true_SOURCES = true.c |
| true_CPPFLAGS = -DEXIT_CODE=0 |
| |
| In this case Automake will cause ‘true.c’ to be compiled twice, with |
| different flags. In this instance, the names of the object files would |
| be chosen by automake; they would be ‘false-true.o’ and ‘true-true.o’. |
| (The name of the object files rarely matters.) |
| |
| |
| File: automake.info, Node: automake Invocation, Next: configure, Prev: Examples, Up: Top |
| |
| 5 Creating a ‘Makefile.in’ |
| ************************** |
| |
| To create all the ‘Makefile.in’s for a package, run the ‘automake’ |
| program in the top level directory, with no arguments. ‘automake’ will |
| automatically find each appropriate ‘Makefile.am’ (by scanning |
| ‘configure.ac’; *note configure::) and generate the corresponding |
| ‘Makefile.in’. Note that ‘automake’ has a rather simplistic view of |
| what constitutes a package; it assumes that a package has only one |
| ‘configure.ac’, at the top. If your package has multiple |
| ‘configure.ac’s, then you must run ‘automake’ in each directory holding |
| a ‘configure.ac’. (Alternatively, you may rely on Autoconf’s |
| ‘autoreconf’, which is able to recurse your package tree and run |
| ‘automake’ where appropriate.) |
| |
| You can optionally give ‘automake’ an argument; ‘.am’ is appended to |
| the argument and the result is used as the name of the input file. This |
| feature is generally only used to automatically rebuild an out-of-date |
| ‘Makefile.in’. Note that ‘automake’ must always be run from the topmost |
| directory of a project, even if being used to regenerate the |
| ‘Makefile.in’ in some subdirectory. This is necessary because |
| ‘automake’ must scan ‘configure.ac’, and because ‘automake’ uses the |
| knowledge that a ‘Makefile.in’ is in a subdirectory to change its |
| behavior in some cases. |
| |
| Automake will run ‘autoconf’ to scan ‘configure.ac’ and its |
| dependencies (i.e., ‘aclocal.m4’ and any included file), therefore |
| ‘autoconf’ must be in your ‘PATH’. If there is an ‘AUTOCONF’ variable |
| in your environment it will be used instead of ‘autoconf’, this allows |
| you to select a particular version of Autoconf. By the way, don’t |
| misunderstand this paragraph: ‘automake’ runs ‘autoconf’ to *scan* your |
| ‘configure.ac’, this won’t build ‘configure’ and you still have to run |
| ‘autoconf’ yourself for this purpose. |
| |
| ‘automake’ accepts the following options: |
| |
| ‘-a’ |
| ‘--add-missing’ |
| Automake requires certain common files to exist in certain |
| situations; for instance, ‘config.guess’ is required if |
| ‘configure.ac’ invokes ‘AC_CANONICAL_HOST’. Automake is |
| distributed with several of these files (*note Auxiliary |
| Programs::); this option will cause the missing ones to be |
| automatically added to the package, whenever possible. In general |
| if Automake tells you a file is missing, try using this option. By |
| default Automake tries to make a symbolic link pointing to its own |
| copy of the missing file; this can be changed with ‘--copy’. |
| |
| Many of the potentially-missing files are common scripts whose |
| location may be specified via the ‘AC_CONFIG_AUX_DIR’ macro. |
| Therefore, ‘AC_CONFIG_AUX_DIR’’s setting affects whether a file is |
| considered missing, and where the missing file is added (*note |
| Optional::). |
| |
| In some strictness modes, additional files are installed, see *note |
| Gnits:: for more information. |
| |
| ‘--libdir=DIR’ |
| Look for Automake data files in directory DIR instead of in the |
| installation directory. This is typically used for debugging. |
| |
| ‘--print-libdir’ |
| Print the path of the installation directory containing |
| Automake-provided scripts and data files (like e.g., ‘texinfo.texi’ |
| and ‘install-sh’). |
| |
| ‘-c’ |
| ‘--copy’ |
| When used with ‘--add-missing’, causes installed files to be |
| copied. The default is to make a symbolic link. |
| |
| ‘-f’ |
| ‘--force-missing’ |
| When used with ‘--add-missing’, causes standard files to be |
| reinstalled even if they already exist in the source tree. This |
| involves removing the file from the source tree before creating the |
| new symlink (or, with ‘--copy’, copying the new file). |
| |
| ‘--foreign’ |
| Set the global strictness to ‘foreign’. For more information, see |
| *note Strictness::. |
| |
| ‘--gnits’ |
| Set the global strictness to ‘gnits’. For more information, see |
| *note Gnits::. |
| |
| ‘--gnu’ |
| Set the global strictness to ‘gnu’. For more information, see |
| *note Gnits::. This is the default strictness. |
| |
| ‘--help’ |
| Print a summary of the command line options and exit. |
| |
| ‘-i’ |
| ‘--ignore-deps’ |
| This disables the dependency tracking feature in generated |
| ‘Makefile’s; see *note Dependencies::. |
| |
| ‘--include-deps’ |
| This enables the dependency tracking feature. This feature is |
| enabled by default. This option is provided for historical reasons |
| only and probably should not be used. |
| |
| ‘--no-force’ |
| Ordinarily ‘automake’ creates all ‘Makefile.in’s mentioned in |
| ‘configure.ac’. This option causes it to only update those |
| ‘Makefile.in’s that are out of date with respect to one of their |
| dependents. |
| |
| ‘-o DIR’ |
| ‘--output-dir=DIR’ |
| Put the generated ‘Makefile.in’ in the directory DIR. Ordinarily |
| each ‘Makefile.in’ is created in the directory of the corresponding |
| ‘Makefile.am’. This option is deprecated and will be removed in a |
| future release. |
| |
| ‘-v’ |
| ‘--verbose’ |
| Cause Automake to print information about which files are being |
| read or created. |
| |
| ‘--version’ |
| Print the version number of Automake and exit. |
| |
| ‘-W CATEGORY’ |
| ‘--warnings=CATEGORY’ |
| Output warnings falling in CATEGORY. CATEGORY can be one of: |
| ‘gnu’ |
| warnings related to the GNU Coding Standards (*note |
| (standards)Top::). |
| ‘obsolete’ |
| obsolete features or constructions |
| ‘override’ |
| user redefinitions of Automake rules or variables |
| ‘portability’ |
| portability issues (e.g., use of ‘make’ features that are |
| known to be not portable) |
| ‘extra-portability’ |
| extra portability issues related to obscure tools. One |
| example of such a tool is the Microsoft ‘lib’ archiver. |
| ‘syntax’ |
| weird syntax, unused variables, typos |
| ‘unsupported’ |
| unsupported or incomplete features |
| ‘all’ |
| all the warnings |
| ‘none’ |
| turn off all the warnings |
| ‘error’ |
| treat warnings as errors |
| |
| A category can be turned off by prefixing its name with ‘no-’. For |
| instance, ‘-Wno-syntax’ will hide the warnings about unused |
| variables. |
| |
| The categories output by default are ‘obsolete’, ‘syntax’ and |
| ‘unsupported’. Additionally, ‘gnu’ and ‘portability’ are enabled |
| in ‘--gnu’ and ‘--gnits’ strictness. |
| |
| Turning off ‘portability’ will also turn off ‘extra-portability’, |
| and similarly turning on ‘extra-portability’ will also turn on |
| ‘portability’. However, turning on ‘portability’ or turning off |
| ‘extra-portability’ will not affect the other category. |
| |
| The environment variable ‘WARNINGS’ can contain a comma separated |
| list of categories to enable. It will be taken into account before |
| the command-line switches, this way ‘-Wnone’ will also ignore any |
| warning category enabled by ‘WARNINGS’. This variable is also used |
| by other tools like ‘autoconf’; unknown categories are ignored for |
| this reason. |
| |
| If the environment variable ‘AUTOMAKE_JOBS’ contains a positive |
| number, it is taken as the maximum number of Perl threads to use in |
| ‘automake’ for generating multiple ‘Makefile.in’ files concurrently. |
| This is an experimental feature. |
| |
| |
| File: automake.info, Node: configure, Next: Directories, Prev: automake Invocation, Up: Top |
| |
| 6 Scanning ‘configure.ac’, using ‘aclocal’ |
| ****************************************** |
| |
| Automake scans the package’s ‘configure.ac’ to determine certain |
| information about the package. Some ‘autoconf’ macros are required and |
| some variables must be defined in ‘configure.ac’. Automake will also |
| use information from ‘configure.ac’ to further tailor its output. |
| |
| Automake also supplies some Autoconf macros to make the maintenance |
| easier. These macros can automatically be put into your ‘aclocal.m4’ |
| using the ‘aclocal’ program. |
| |
| * Menu: |
| |
| * Requirements:: Configuration requirements |
| * Optional:: Other things Automake recognizes |
| * aclocal Invocation:: Auto-generating aclocal.m4 |
| * Macros:: Autoconf macros supplied with Automake |
| |
| |
| File: automake.info, Node: Requirements, Next: Optional, Up: configure |
| |
| 6.1 Configuration requirements |
| ============================== |
| |
| The one real requirement of Automake is that your ‘configure.ac’ call |
| ‘AM_INIT_AUTOMAKE’. This macro does several things that are required |
| for proper Automake operation (*note Macros::). |
| |
| Here are the other macros that Automake requires but which are not |
| run by ‘AM_INIT_AUTOMAKE’: |
| |
| ‘AC_CONFIG_FILES’ |
| ‘AC_OUTPUT’ |
| These two macros are usually invoked as follows near the end of |
| ‘configure.ac’. |
| |
| … |
| AC_CONFIG_FILES([ |
| Makefile |
| doc/Makefile |
| src/Makefile |
| src/lib/Makefile |
| … |
| ]) |
| AC_OUTPUT |
| |
| Automake uses these to determine which files to create (*note |
| Creating Output Files: (autoconf)Output.). A listed file is |
| considered to be an Automake generated ‘Makefile’ if there exists a |
| file with the same name and the ‘.am’ extension appended. |
| Typically, ‘AC_CONFIG_FILES([foo/Makefile])’ will cause Automake to |
| generate ‘foo/Makefile.in’ if ‘foo/Makefile.am’ exists. |
| |
| When using ‘AC_CONFIG_FILES’ with multiple input files, as in |
| |
| AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in]) |
| |
| ‘automake’ will generate the first ‘.in’ input file for which a |
| ‘.am’ file exists. If no such file exists the output file is not |
| considered to be generated by Automake. |
| |
| Files created by ‘AC_CONFIG_FILES’, be they Automake ‘Makefile’s or |
| not, are all removed by ‘make distclean’. Their inputs are |
| automatically distributed, unless they are the output of prior |
| ‘AC_CONFIG_FILES’ commands. Finally, rebuild rules are generated |
| in the Automake ‘Makefile’ existing in the subdirectory of the |
| output file, if there is one, or in the top-level ‘Makefile’ |
| otherwise. |
| |
| The above machinery (cleaning, distributing, and rebuilding) works |
| fine if the ‘AC_CONFIG_FILES’ specifications contain only literals. |
| If part of the specification uses shell variables, ‘automake’ will |
| not be able to fulfill this setup, and you will have to complete |
| the missing bits by hand. For instance, on |
| |
| file=input |
| … |
| AC_CONFIG_FILES([output:$file],, [file=$file]) |
| |
| ‘automake’ will output rules to clean ‘output’, and rebuild it. |
| However the rebuild rule will not depend on ‘input’, and this file |
| will not be distributed either. (You must add ‘EXTRA_DIST = input’ |
| to your ‘Makefile.am’ if ‘input’ is a source file.) |
| |
| Similarly |
| |
| file=output |
| file2=out:in |
| … |
| AC_CONFIG_FILES([$file:input],, [file=$file]) |
| AC_CONFIG_FILES([$file2],, [file2=$file2]) |
| |
| will only cause ‘input’ to be distributed. No file will be cleaned |
| automatically (add ‘DISTCLEANFILES = output out’ yourself), and no |
| rebuild rule will be output. |
| |
| Obviously ‘automake’ cannot guess what value ‘$file’ is going to |
| hold later when ‘configure’ is run, and it cannot use the shell |
| variable ‘$file’ in a ‘Makefile’. However, if you make reference |
| to ‘$file’ as ‘${file}’ (i.e., in a way that is compatible with |
| ‘make’’s syntax) and furthermore use ‘AC_SUBST’ to ensure that |
| ‘${file}’ is meaningful in a ‘Makefile’, then ‘automake’ will be |
| able to use ‘${file}’ to generate all of these rules. For |
| instance, here is how the Automake package itself generates |
| versioned scripts for its test suite: |
| |
| AC_SUBST([APIVERSION], …) |
| … |
| AC_CONFIG_FILES( |
| [tests/aclocal-${APIVERSION}:tests/aclocal.in], |
| [chmod +x tests/aclocal-${APIVERSION}], |
| [APIVERSION=$APIVERSION]) |
| AC_CONFIG_FILES( |
| [tests/automake-${APIVERSION}:tests/automake.in], |
| [chmod +x tests/automake-${APIVERSION}]) |
| |
| Here cleaning, distributing, and rebuilding are done automatically, |
| because ‘${APIVERSION}’ is known at ‘make’-time. |
| |
| Note that you should not use shell variables to declare ‘Makefile’ |
| files for which ‘automake’ must create ‘Makefile.in’. Even |
| ‘AC_SUBST’ does not help here, because ‘automake’ needs to know the |
| file name when it runs in order to check whether ‘Makefile.am’ |
| exists. (In the very hairy case that your setup requires such use |
| of variables, you will have to tell Automake which ‘Makefile.in’s |
| to generate on the command-line.) |
| |
| It is possible to let ‘automake’ emit conditional rules for |
| ‘AC_CONFIG_FILES’ with the help of ‘AM_COND_IF’ (*note Optional::). |
| |
| To summarize: |
| • Use literals for ‘Makefile’s, and for other files whenever |
| possible. |
| • Use ‘$file’ (or ‘${file}’ without ‘AC_SUBST([file])’) for |
| files that ‘automake’ should ignore. |
| • Use ‘${file}’ and ‘AC_SUBST([file])’ for files that ‘automake’ |
| should not ignore. |
| |
| |
| File: automake.info, Node: Optional, Next: aclocal Invocation, Prev: Requirements, Up: configure |
| |
| 6.2 Other things Automake recognizes |
| ==================================== |
| |
| Every time Automake is run it calls Autoconf to trace ‘configure.ac’. |
| This way it can recognize the use of certain macros and tailor the |
| generated ‘Makefile.in’ appropriately. Currently recognized macros and |
| their effects are: |
| |
| ‘AC_CANONICAL_BUILD’ |
| ‘AC_CANONICAL_HOST’ |
| ‘AC_CANONICAL_TARGET’ |
| Automake will ensure that ‘config.guess’ and ‘config.sub’ exist. |
| Also, the ‘Makefile’ variables ‘build_triplet’, ‘host_triplet’ and |
| ‘target_triplet’ are introduced. See *note Getting the Canonical |
| System Type: (autoconf)Canonicalizing. |
| |
| ‘AC_CONFIG_AUX_DIR’ |
| Automake will look for various helper scripts, such as |
| ‘install-sh’, in the directory named in this macro invocation. |
| (The full list of scripts is: ‘ar-lib’, ‘config.guess’, |
| ‘config.sub’, ‘depcomp’, ‘compile’, ‘install-sh’, ‘ltmain.sh’, |
| ‘mdate-sh’, ‘missing’, ‘mkinstalldirs’, ‘py-compile’, |
| ‘test-driver’, ‘texinfo.tex’, ‘ylwrap’.) Not all scripts are |
| always searched for; some scripts will only be sought if the |
| generated ‘Makefile.in’ requires them. |
| |
| If ‘AC_CONFIG_AUX_DIR’ is not given, the scripts are looked for in |
| their standard locations. For ‘mdate-sh’, ‘texinfo.tex’, and |
| ‘ylwrap’, the standard location is the source directory |
| corresponding to the current ‘Makefile.am’. For the rest, the |
| standard location is the first one of ‘.’, ‘..’, or ‘../..’ |
| (relative to the top source directory) that provides any one of the |
| helper scripts. *Note Finding ‘configure’ Input: (autoconf)Input. |
| |
| Required files from ‘AC_CONFIG_AUX_DIR’ are automatically |
| distributed, even if there is no ‘Makefile.am’ in this directory. |
| |
| ‘AC_CONFIG_LIBOBJ_DIR’ |
| Automake will require the sources file declared with ‘AC_LIBSOURCE’ |
| (see below) in the directory specified by this macro. |
| |
| ‘AC_CONFIG_HEADERS’ |
| Automake will generate rules to rebuild these headers from the |
| corresponding templates (usually, the template for a ‘foo.h’ header |
| being ‘foo.h.in’). Older versions of Automake required the use of |
| ‘AM_CONFIG_HEADER’; this is no longer the case, and that macro has |
| indeed been removed. |
| |
| As with ‘AC_CONFIG_FILES’ (*note Requirements::), parts of the |
| specification using shell variables will be ignored as far as |
| cleaning, distributing, and rebuilding is concerned. |
| |
| ‘AC_CONFIG_LINKS’ |
| Automake will generate rules to remove ‘configure’ generated links |
| on ‘make distclean’ and to distribute named source files as part of |
| ‘make dist’. |
| |
| As for ‘AC_CONFIG_FILES’ (*note Requirements::), parts of the |
| specification using shell variables will be ignored as far as |
| cleaning and distributing is concerned. (There are no rebuild |
| rules for links.) |
| |
| ‘AC_LIBOBJ’ |
| ‘AC_LIBSOURCE’ |
| ‘AC_LIBSOURCES’ |
| Automake will automatically distribute any file listed in |
| ‘AC_LIBSOURCE’ or ‘AC_LIBSOURCES’. |
| |
| Note that the ‘AC_LIBOBJ’ macro calls ‘AC_LIBSOURCE’. So if an |
| Autoconf macro is documented to call ‘AC_LIBOBJ([file])’, then |
| ‘file.c’ will be distributed automatically by Automake. This |
| encompasses many macros like ‘AC_FUNC_ALLOCA’, ‘AC_FUNC_MEMCMP’, |
| ‘AC_REPLACE_FUNCS’, and others. |
| |
| By the way, direct assignments to ‘LIBOBJS’ are no longer |
| supported. You should always use ‘AC_LIBOBJ’ for this purpose. |
| *Note ‘AC_LIBOBJ’ vs. ‘LIBOBJS’: (autoconf)AC_LIBOBJ vs LIBOBJS. |
| |
| ‘AC_PROG_RANLIB’ |
| This is required if any libraries are built in the package. *Note |
| Particular Program Checks: (autoconf)Particular Programs. |
| |
| ‘AC_PROG_CXX’ |
| This is required if any C++ source is included. *Note Particular |
| Program Checks: (autoconf)Particular Programs. |
| |
| ‘AC_PROG_OBJC’ |
| This is required if any Objective C source is included. *Note |
| Particular Program Checks: (autoconf)Particular Programs. |
| |
| ‘AC_PROG_OBJCXX’ |
| This is required if any Objective C++ source is included. *Note |
| Particular Program Checks: (autoconf)Particular Programs. |
| |
| ‘AC_PROG_F77’ |
| This is required if any Fortran 77 source is included. *Note |
| Particular Program Checks: (autoconf)Particular Programs. |
| |
| ‘AC_F77_LIBRARY_LDFLAGS’ |
| This is required for programs and shared libraries that are a |
| mixture of languages that include Fortran 77 (*note Mixing Fortran |
| 77 With C and C++::). *Note Autoconf macros supplied with |
| Automake: Macros. |
| |
| ‘AC_FC_SRCEXT’ |
| Automake will add the flags computed by ‘AC_FC_SRCEXT’ to |
| compilation of files with the respective source extension (*note |
| Fortran Compiler Characteristics: (autoconf)Fortran Compiler.). |
| |
| ‘AC_PROG_FC’ |
| This is required if any Fortran 90/95 source is included. This |
| macro is distributed with Autoconf version 2.58 and later. *Note |
| Particular Program Checks: (autoconf)Particular Programs. |
| |
| ‘AC_PROG_LIBTOOL’ |
| Automake will turn on processing for ‘libtool’ (*note Introduction: |
| (libtool)Top.). |
| |
| ‘AC_PROG_YACC’ |
| If a Yacc source file is seen, then you must either use this macro |
| or define the variable ‘YACC’ in ‘configure.ac’. The former is |
| preferred (*note Particular Program Checks: (autoconf)Particular |
| Programs.). |
| |
| ‘AC_PROG_LEX’ |
| If a Lex source file is seen, then this macro must be used. *Note |
| Particular Program Checks: (autoconf)Particular Programs. |
| |
| ‘AC_REQUIRE_AUX_FILE’ |
| For each ‘AC_REQUIRE_AUX_FILE([FILE])’, ‘automake’ will ensure that |
| ‘FILE’ exists in the aux directory, and will complain otherwise. |
| It will also automatically distribute the file. This macro should |
| be used by third-party Autoconf macros that require some supporting |
| files in the aux directory specified with ‘AC_CONFIG_AUX_DIR’ |
| above. *Note Finding ‘configure’ Input: (autoconf)Input. |
| |
| ‘AC_SUBST’ |
| The first argument is automatically defined as a variable in each |
| generated ‘Makefile.in’, unless ‘AM_SUBST_NOTMAKE’ is also used for |
| this variable. *Note Setting Output Variables: (autoconf)Setting |
| Output Variables. |
| |
| For every substituted variable VAR, ‘automake’ will add a line ‘VAR |
| = VALUE’ to each ‘Makefile.in’ file. Many Autoconf macros invoke |
| ‘AC_SUBST’ to set output variables this way, e.g., ‘AC_PATH_XTRA’ |
| defines ‘X_CFLAGS’ and ‘X_LIBS’. Thus, you can access these |
| variables as ‘$(X_CFLAGS)’ and ‘$(X_LIBS)’ in any ‘Makefile.am’ if |
| ‘AC_PATH_XTRA’ is called. |
| |
| ‘AM_CONDITIONAL’ |
| This introduces an Automake conditional (*note Conditionals::). |
| |
| ‘AM_COND_IF’ |
| This macro allows ‘automake’ to detect subsequent access within |
| ‘configure.ac’ to a conditional previously introduced with |
| ‘AM_CONDITIONAL’, thus enabling conditional ‘AC_CONFIG_FILES’ |
| (*note Usage of Conditionals::). |
| |
| ‘AM_GNU_GETTEXT’ |
| This macro is required for packages that use GNU gettext (*note |
| gettext::). It is distributed with gettext. If Automake sees this |
| macro it ensures that the package meets some of gettext’s |
| requirements. |
| |
| ‘AM_GNU_GETTEXT_INTL_SUBDIR’ |
| This macro specifies that the ‘intl/’ subdirectory is to be built, |
| even if the ‘AM_GNU_GETTEXT’ macro was invoked with a first |
| argument of ‘external’. |
| |
| ‘AM_MAINTAINER_MODE([DEFAULT-MODE])’ |
| This macro adds an ‘--enable-maintainer-mode’ option to |
| ‘configure’. If this is used, ‘automake’ will cause |
| “maintainer-only” rules to be turned off by default in the |
| generated ‘Makefile.in’s, unless DEFAULT-MODE is ‘enable’. This |
| macro defines the ‘MAINTAINER_MODE’ conditional, which you can use |
| in your own ‘Makefile.am’. *Note maintainer-mode::. |
| |
| ‘AM_SUBST_NOTMAKE(VAR)’ |
| Prevent Automake from defining a variable VAR, even if it is |
| substituted by ‘config.status’. Normally, Automake defines a |
| ‘make’ variable for each ‘configure’ substitution, i.e., for each |
| ‘AC_SUBST([VAR])’. This macro prevents that definition from |
| Automake. If ‘AC_SUBST’ has not been called for this variable, |
| then ‘AM_SUBST_NOTMAKE’ has no effects. Preventing variable |
| definitions may be useful for substitution of multi-line values, |
| where ‘VAR = @VALUE@’ might yield unintended results. |
| |
| ‘m4_include’ |
| Files included by ‘configure.ac’ using this macro will be detected |
| by Automake and automatically distributed. They will also appear |
| as dependencies in ‘Makefile’ rules. |
| |
| ‘m4_include’ is seldom used by ‘configure.ac’ authors, but can |
| appear in ‘aclocal.m4’ when ‘aclocal’ detects that some required |
| macros come from files local to your package (as opposed to macros |
| installed in a system-wide directory, *note aclocal Invocation::). |
| |
| |
| File: automake.info, Node: aclocal Invocation, Next: Macros, Prev: Optional, Up: configure |
| |
| 6.3 Auto-generating aclocal.m4 |
| ============================== |
| |
| Automake includes a number of Autoconf macros that can be used in your |
| package (*note Macros::); some of them are actually required by Automake |
| in certain situations. These macros must be defined in your |
| ‘aclocal.m4’; otherwise they will not be seen by ‘autoconf’. |
| |
| The ‘aclocal’ program will automatically generate ‘aclocal.m4’ files |
| based on the contents of ‘configure.ac’. This provides a convenient way |
| to get Automake-provided macros, without having to search around. The |
| ‘aclocal’ mechanism allows other packages to supply their own macros |
| (*note Extending aclocal::). You can also use it to maintain your own |
| set of custom macros (*note Local Macros::). |
| |
| At startup, ‘aclocal’ scans all the ‘.m4’ files it can find, looking |
| for macro definitions (*note Macro Search Path::). Then it scans |
| ‘configure.ac’. Any mention of one of the macros found in the first |
| step causes that macro, and any macros it in turn requires, to be put |
| into ‘aclocal.m4’. |
| |
| _Putting_ the file that contains the macro definition into |
| ‘aclocal.m4’ is usually done by copying the entire text of this file, |
| including unused macro definitions as well as both ‘#’ and ‘dnl’ |
| comments. If you want to make a comment that will be completely ignored |
| by ‘aclocal’, use ‘##’ as the comment leader. |
| |
| When a file selected by ‘aclocal’ is located in a subdirectory |
| specified as a relative search path with ‘aclocal’’s ‘-I’ argument, |
| ‘aclocal’ assumes the file belongs to the package and uses ‘m4_include’ |
| instead of copying it into ‘aclocal.m4’. This makes the package |
| smaller, eases dependency tracking, and cause the file to be distributed |
| automatically. (*Note Local Macros::, for an example.) Any macro that |
| is found in a system-wide directory, or via an absolute search path will |
| be copied. So use ‘-I `pwd`/reldir’ instead of ‘-I reldir’ whenever |
| some relative directory should be considered outside the package. |
| |
| The contents of ‘acinclude.m4’, if this file exists, are also |
| automatically included in ‘aclocal.m4’. We recommend against using |
| ‘acinclude.m4’ in new packages (*note Local Macros::). |
| |
| While computing ‘aclocal.m4’, ‘aclocal’ runs ‘autom4te’ (*note Using |
| ‘Autom4te’: (autoconf)Using autom4te.) in order to trace the macros that |
| are really used, and omit from ‘aclocal.m4’ all macros that are |
| mentioned but otherwise unexpanded (this can happen when a macro is |
| called conditionally). ‘autom4te’ is expected to be in the ‘PATH’, just |
| as ‘autoconf’. Its location can be overridden using the ‘AUTOM4TE’ |
| environment variable. |
| |
| * Menu: |
| |
| * aclocal Options:: Options supported by aclocal |
| * Macro Search Path:: How aclocal finds .m4 files |
| * Extending aclocal:: Writing your own aclocal macros |
| * Local Macros:: Organizing local macros |
| * Serials:: Serial lines in Autoconf macros |
| * Future of aclocal:: aclocal’s scheduled death |
| |
| |
| File: automake.info, Node: aclocal Options, Next: Macro Search Path, Up: aclocal Invocation |
| |
| 6.3.1 aclocal Options |
| --------------------- |
| |
| ‘aclocal’ accepts the following options: |
| |
| ‘--automake-acdir=DIR’ |
| Look for the automake-provided macro files in DIR instead of in the |
| installation directory. This is typically used for debugging. |
| |
| ‘--system-acdir=DIR’ |
| Look for the system-wide third-party macro files (and the special |
| ‘dirlist’ file) in DIR instead of in the installation directory. |
| This is typically used for debugging. |
| |
| ‘--diff[=COMMAND]’ |
| Run COMMAND on M4 file that would be installed or overwritten by |
| ‘--install’. The default COMMAND is ‘diff -u’. This option |
| implies ‘--install’ and ‘--dry-run’. |
| |
| ‘--dry-run’ |
| Do not actually overwrite (or create) ‘aclocal.m4’ and M4 files |
| installed by ‘--install’. |
| |
| ‘--help’ |
| Print a summary of the command line options and exit. |
| |
| ‘-I DIR’ |
| Add the directory DIR to the list of directories searched for ‘.m4’ |
| files. |
| |
| ‘--install’ |
| Install system-wide third-party macros into the first directory |
| specified with ‘-I DIR’ instead of copying them in the output file. |
| Note that this will happen also if DIR is an absolute path. |
| |
| When this option is used, and only when this option is used, |
| ‘aclocal’ will also honor ‘#serial NUMBER’ lines that appear in |
| macros: an M4 file is ignored if there exists another M4 file with |
| the same basename and a greater serial number in the search path |
| (*note Serials::). |
| |
| ‘--force’ |
| Always overwrite the output file. The default is to overwrite the |
| output file only when really needed, i.e., when its contents |
| changes or if one of its dependencies is younger. |
| |
| This option forces the update of ‘aclocal.m4’ (or the file |
| specified with ‘--output’ below) and only this file, it has |
| absolutely no influence on files that may need to be installed by |
| ‘--install’. |
| |
| ‘--output=FILE’ |
| Cause the output to be put into FILE instead of ‘aclocal.m4’. |
| |
| ‘--print-ac-dir’ |
| Prints the name of the directory that ‘aclocal’ will search to find |
| third-party ‘.m4’ files. When this option is given, normal |
| processing is suppressed. This option was used _in the past_ by |
| third-party packages to determine where to install ‘.m4’ macro |
| files, but _this usage is today discouraged_, since it causes |
| ‘$(prefix)’ not to be thoroughly honored (which violates the GNU |
| Coding Standards), and a similar semantics can be better obtained |
| with the ‘ACLOCAL_PATH’ environment variable; *note Extending |
| aclocal::. |
| |
| ‘--verbose’ |
| Print the names of the files it examines. |
| |
| ‘--version’ |
| Print the version number of Automake and exit. |
| |
| ‘-W CATEGORY’ |
| ‘--warnings=CATEGORY’ |
| Output warnings falling in CATEGORY. CATEGORY can be one of: |
| ‘syntax’ |
| dubious syntactic constructs, underquoted macros, unused |
| macros, etc. |
| ‘unsupported’ |
| unknown macros |
| ‘all’ |
| all the warnings, this is the default |
| ‘none’ |
| turn off all the warnings |
| ‘error’ |
| treat warnings as errors |
| |
| All warnings are output by default. |
| |
| The environment variable ‘WARNINGS’ is honored in the same way as |
| it is for ‘automake’ (*note automake Invocation::). |
| |
| |
| File: automake.info, Node: Macro Search Path, Next: Extending aclocal, Prev: aclocal Options, Up: aclocal Invocation |
| |
| 6.3.2 Macro Search Path |
| ----------------------- |
| |
| By default, ‘aclocal’ searches for ‘.m4’ files in the following |
| directories, in this order: |
| |
| ‘ACDIR-APIVERSION’ |
| This is where the ‘.m4’ macros distributed with Automake itself are |
| stored. APIVERSION depends on the Automake release used; for |
| example, for Automake 1.11.x, APIVERSION = ‘1.11’. |
| |
| ‘ACDIR’ |
| This directory is intended for third party ‘.m4’ files, and is |
| configured when ‘automake’ itself is built. This is |
| ‘@datadir@/aclocal/’, which typically expands to |
| ‘${prefix}/share/aclocal/’. To find the compiled-in value of |
| ACDIR, use the ‘--print-ac-dir’ option (*note aclocal Options::). |
| |
| As an example, suppose that ‘automake-1.11.2’ was configured with |
| ‘--prefix=/usr/local’. Then, the search path would be: |
| |
| 1. ‘/usr/local/share/aclocal-1.11.2/’ |
| 2. ‘/usr/local/share/aclocal/’ |
| |
| The paths for the ACDIR and ACDIR-APIVERSION directories can be |
| changed respectively through aclocal options ‘--system-acdir’ and |
| ‘--automake-acdir’ (*note aclocal Options::). Note however that these |
| options are only intended for use by the internal Automake test suite, |
| or for debugging under highly unusual situations; they are not |
| ordinarily needed by end-users. |
| |
| As explained in (*note aclocal Options::), there are several options |
| that can be used to change or extend this search path. |
| |
| Modifying the Macro Search Path: ‘-I DIR’ |
| ......................................... |
| |
| Any extra directories specified using ‘-I’ options (*note aclocal |
| Options::) are _prepended_ to this search list. Thus, ‘aclocal -I /foo |
| -I /bar’ results in the following search path: |
| |
| 1. ‘/foo’ |
| 2. ‘/bar’ |
| 3. ACDIR-APIVERSION |
| 4. ACDIR |
| |
| Modifying the Macro Search Path: ‘dirlist’ |
| .......................................... |
| |
| There is a third mechanism for customizing the search path. If a |
| ‘dirlist’ file exists in ACDIR, then that file is assumed to contain a |
| list of directory patterns, one per line. ‘aclocal’ expands these |
| patterns to directory names, and adds them to the search list _after_ |
| all other directories. ‘dirlist’ entries may use shell wildcards such |
| as ‘*’, ‘?’, or ‘[...]’. |
| |
| For example, suppose ‘ACDIR/dirlist’ contains the following: |
| |
| /test1 |
| /test2 |
| /test3* |
| |
| and that ‘aclocal’ was called with the ‘-I /foo -I /bar’ options. Then, |
| the search path would be |
| |
| 1. ‘/foo’ |
| 2. ‘/bar’ |
| 3. ACDIR-APIVERSION |
| 4. ACDIR |
| 5. ‘/test1’ |
| 6. ‘/test2’ |
| |
| and all directories with path names starting with ‘/test3’. |
| |
| If the ‘--system-acdir=DIR’ option is used, then ‘aclocal’ will |
| search for the ‘dirlist’ file in DIR; but remember the warnings above |
| against the use of ‘--system-acdir’. |
| |
| ‘dirlist’ is useful in the following situation: suppose that |
| ‘automake’ version ‘1.11.2’ is installed with ‘--prefix=/usr’ by the |
| system vendor. Thus, the default search directories are |
| |
| 1. ‘/usr/share/aclocal-1.11/’ |
| 2. ‘/usr/share/aclocal/’ |
| |
| However, suppose further that many packages have been manually |
| installed on the system, with $prefix=/usr/local, as is typical. In |
| that case, many of these “extra” ‘.m4’ files are in |
| ‘/usr/local/share/aclocal’. The only way to force ‘/usr/bin/aclocal’ to |
| find these “extra” ‘.m4’ files is to always call ‘aclocal -I |
| /usr/local/share/aclocal’. This is inconvenient. With ‘dirlist’, one |
| may create a file ‘/usr/share/aclocal/dirlist’ containing only the |
| single line |
| |
| /usr/local/share/aclocal |
| |
| Now, the “default” search path on the affected system is |
| |
| 1. ‘/usr/share/aclocal-1.11/’ |
| 2. ‘/usr/share/aclocal/’ |
| 3. ‘/usr/local/share/aclocal/’ |
| |
| without the need for ‘-I’ options; ‘-I’ options can be reserved for |
| project-specific needs (‘my-source-dir/m4/’), rather than using it to |
| work around local system-dependent tool installation directories. |
| |
| Similarly, ‘dirlist’ can be handy if you have installed a local copy |
| of Automake in your account and want ‘aclocal’ to look for macros |
| installed at other places on the system. |
| |
| Modifying the Macro Search Path: ‘ACLOCAL_PATH’ |
| ............................................... |
| |
| The fourth and last mechanism to customize the macro search path is also |
| the simplest. Any directory included in the colon-separated environment |
| variable ‘ACLOCAL_PATH’ is added to the search path and takes precedence |
| over system directories (including those found via ‘dirlist’), with the |
| exception of the versioned directory ACDIR-APIVERSION (*note Macro |
| Search Path::). However, directories passed via ‘-I’ will take |
| precedence over directories in ‘ACLOCAL_PATH’. |
| |
| Also note that, if the ‘--install’ option is used, any ‘.m4’ file |
| containing a required macro that is found in a directory listed in |
| ‘ACLOCAL_PATH’ will be installed locally. In this case, serial numbers |
| in ‘.m4’ are honored too, *note Serials::. |
| |
| Conversely to ‘dirlist’, ‘ACLOCAL_PATH’ is useful if you are using a |
| global copy of Automake and want ‘aclocal’ to look for macros somewhere |
| under your home directory. |
| |
| Planned future incompatibilities |
| ................................ |
| |
| The order in which the directories in the macro search path are |
| currently looked up is confusing and/or suboptimal in various aspects, |
| and is probably going to be changed in the future Automake release. In |
| particular, directories in ‘ACLOCAL_PATH’ and ‘ACDIR’ might end up |
| taking precedence over ‘ACDIR-APIVERSION’, and directories in |
| ‘ACDIR/dirlist’ might end up taking precedence over ‘ACDIR’. _This is a |
| possible future incompatibility!_ |
| |
| |
| File: automake.info, Node: Extending aclocal, Next: Local Macros, Prev: Macro Search Path, Up: aclocal Invocation |
| |
| 6.3.3 Writing your own aclocal macros |
| ------------------------------------- |
| |
| The ‘aclocal’ program doesn’t have any built-in knowledge of any macros, |
| so it is easy to extend it with your own macros. |
| |
| This can be used by libraries that want to supply their own Autoconf |
| macros for use by other programs. For instance, the ‘gettext’ library |
| supplies a macro ‘AM_GNU_GETTEXT’ that should be used by any package |
| using ‘gettext’. When the library is installed, it installs this macro |
| so that ‘aclocal’ will find it. |
| |
| A macro file’s name should end in ‘.m4’. Such files should be |
| installed in ‘$(datadir)/aclocal’. This is as simple as writing: |
| |
| aclocaldir = $(datadir)/aclocal |
| aclocal_DATA = mymacro.m4 myothermacro.m4 |
| |
| Please do use ‘$(datadir)/aclocal’, and not something based on the |
| result of ‘aclocal --print-ac-dir’ (*note Hard-Coded Install Paths::, |
| for arguments). It might also be helpful to suggest to the user to add |
| the ‘$(datadir)/aclocal’ directory to his ‘ACLOCAL_PATH’ variable (*note |
| ACLOCAL_PATH::) so that ‘aclocal’ will find the ‘.m4’ files installed by |
| your package automatically. |
| |
| A file of macros should be a series of properly quoted ‘AC_DEFUN’’s |
| (*note (autoconf)Macro Definitions::). The ‘aclocal’ programs also |
| understands ‘AC_REQUIRE’ (*note (autoconf)Prerequisite Macros::), so it |
| is safe to put each macro in a separate file. Each file should have no |
| side effects but macro definitions. Especially, any call to ‘AC_PREREQ’ |
| should be done inside the defined macro, not at the beginning of the |
| file. |
| |
| Starting with Automake 1.8, ‘aclocal’ will warn about all underquoted |
| calls to ‘AC_DEFUN’. We realize this will annoy a lot of people, |
| because ‘aclocal’ was not so strict in the past and many third party |
| macros are underquoted; and we have to apologize for this temporary |
| inconvenience. The reason we have to be stricter is that a future |
| implementation of ‘aclocal’ (*note Future of aclocal::) will have to |
| temporarily include all of these third party ‘.m4’ files, maybe several |
| times, including even files that are not actually needed. Doing so |
| should alleviate many problems of the current implementation, however it |
| requires a stricter style from the macro authors. Hopefully it is easy |
| to revise the existing macros. For instance, |
| |
| # bad style |
| AC_PREREQ(2.68) |
| AC_DEFUN(AX_FOOBAR, |
| [AC_REQUIRE([AX_SOMETHING])dnl |
| AX_FOO |
| AX_BAR |
| ]) |
| |
| should be rewritten as |
| |
| AC_DEFUN([AX_FOOBAR], |
| [AC_PREREQ([2.68])dnl |
| AC_REQUIRE([AX_SOMETHING])dnl |
| AX_FOO |
| AX_BAR |
| ]) |
| |
| Wrapping the ‘AC_PREREQ’ call inside the macro ensures that Autoconf |
| 2.68 will not be required if ‘AX_FOOBAR’ is not actually used. Most |
| importantly, quoting the first argument of ‘AC_DEFUN’ allows the macro |
| to be redefined or included twice (otherwise this first argument would |
| be expanded during the second definition). For consistency we like to |
| quote even arguments such as ‘2.68’ that do not require it. |
| |
| If you have been directed here by the ‘aclocal’ diagnostic but are |
| not the maintainer of the implicated macro, you will want to contact the |
| maintainer of that macro. Please make sure you have the latest version |
| of the macro and that the problem hasn’t already been reported before |
| doing so: people tend to work faster when they aren’t flooded by mails. |
| |
| Another situation where ‘aclocal’ is commonly used is to manage |
| macros that are used locally by the package, *note Local Macros::. |
| |
| |
| File: automake.info, Node: Local Macros, Next: Serials, Prev: Extending aclocal, Up: aclocal Invocation |
| |
| 6.3.4 Handling Local Macros |
| --------------------------- |
| |
| Feature tests offered by Autoconf do not cover all needs. People often |
| have to supplement existing tests with their own macros, or with |
| third-party macros. |
| |
| There are two ways to organize custom macros in a package. |
| |
| The first possibility (the historical practice) is to list all your |
| macros in ‘acinclude.m4’. This file will be included in ‘aclocal.m4’ |
| when you run ‘aclocal’, and its macro(s) will henceforth be visible to |
| ‘autoconf’. However if it contains numerous macros, it will rapidly |
| become difficult to maintain, and it will be almost impossible to share |
| macros between packages. |
| |
| The second possibility, which we do recommend, is to write each macro |
| in its own file and gather all these files in a directory. This |
| directory is usually called ‘m4/’. Then it’s enough to update |
| ‘configure.ac’ by adding a proper call to ‘AC_CONFIG_MACRO_DIRS’: |
| |
| AC_CONFIG_MACRO_DIRS([m4]) |
| |
| ‘aclocal’ will then take care of automatically adding ‘m4/’ to its |
| search path for m4 files. |
| |
| When ‘aclocal’ is run, it will build an ‘aclocal.m4’ that |
| ‘m4_include’s any file from ‘m4/’ that defines a required macro. Macros |
| not found locally will still be searched in system-wide directories, as |
| explained in *note Macro Search Path::. |
| |
| Custom macros should be distributed for the same reason that |
| ‘configure.ac’ is: so that other people have all the sources of your |
| package if they want to work on it. Actually, this distribution happens |
| automatically because all ‘m4_include’d files are distributed. |
| |
| However there is no consensus on the distribution of third-party |
| macros that your package may use. Many libraries install their own |
| macro in the system-wide ‘aclocal’ directory (*note Extending |
| aclocal::). For instance, Guile ships with a file called ‘guile.m4’ |
| that contains the macro ‘GUILE_FLAGS’ that can be used to define setup |
| compiler and linker flags appropriate for using Guile. Using |
| ‘GUILE_FLAGS’ in ‘configure.ac’ will cause ‘aclocal’ to copy ‘guile.m4’ |
| into ‘aclocal.m4’, but as ‘guile.m4’ is not part of the project, it will |
| not be distributed. Technically, that means a user who needs to rebuild |
| ‘aclocal.m4’ will have to install Guile first. This is probably OK, if |
| Guile already is a requirement to build the package. However, if Guile |
| is only an optional feature, or if your package might run on |
| architectures where Guile cannot be installed, this requirement will |
| hinder development. An easy solution is to copy such third-party macros |
| in your local ‘m4/’ directory so they get distributed. |
| |
| Since Automake 1.10, ‘aclocal’ offers the option ‘--install’ to copy |
| these system-wide third-party macros in your local macro directory, |
| helping to solve the above problem. |
| |
| With this setup, system-wide macros will be copied to ‘m4/’ the first |
| time you run ‘aclocal’. Then the locally installed macros will have |
| precedence over the system-wide installed macros each time ‘aclocal’ is |
| run again. |
| |
| One reason why you should keep ‘--install’ in the flags even after |
| the first run is that when you later edit ‘configure.ac’ and depend on a |
| new macro, this macro will be installed in your ‘m4/’ automatically. |
| Another one is that serial numbers (*note Serials::) can be used to |
| update the macros in your source tree automatically when new system-wide |
| versions are installed. A serial number should be a single line of the |
| form |
| |
| #serial NNN |
| |
| where NNN contains only digits and dots. It should appear in the M4 |
| file before any macro definition. It is a good practice to maintain a |
| serial number for each macro you distribute, even if you do not use the |
| ‘--install’ option of ‘aclocal’: this allows other people to use it. |
| |
| |
| File: automake.info, Node: Serials, Next: Future of aclocal, Prev: Local Macros, Up: aclocal Invocation |
| |
| 6.3.5 Serial Numbers |
| -------------------- |
| |
| Because third-party macros defined in ‘*.m4’ files are naturally shared |
| between multiple projects, some people like to version them. This makes |
| it easier to tell which of two M4 files is newer. Since at least 1996, |
| the tradition is to use a ‘#serial’ line for this. |
| |
| A serial number should be a single line of the form |
| |
| # serial VERSION |
| |
| where VERSION is a version number containing only digits and dots. |
| Usually people use a single integer, and they increment it each time |
| they change the macro (hence the name of “serial”). Such a line should |
| appear in the M4 file before any macro definition. |
| |
| The ‘#’ must be the first character on the line, and it is OK to have |
| extra words after the version, as in |
| |
| #serial VERSION GARBAGE |
| |
| Normally these serial numbers are completely ignored by ‘aclocal’ and |
| ‘autoconf’, like any genuine comment. However when using ‘aclocal’’s |
| ‘--install’ feature, these serial numbers will modify the way ‘aclocal’ |
| selects the macros to install in the package: if two files with the same |
| basename exist in your search path, and if at least one of them uses a |
| ‘#serial’ line, ‘aclocal’ will ignore the file that has the older |
| ‘#serial’ line (or the file that has none). |
| |
| Note that a serial number applies to a whole M4 file, not to any |
| macro it contains. A file can contains multiple macros, but only one |
| serial. |
| |
| Here is a use case that illustrates the use of ‘--install’ and its |
| interaction with serial numbers. Let’s assume we maintain a package |
| called MyPackage, the ‘configure.ac’ of which requires a third-party |
| macro ‘AX_THIRD_PARTY’ defined in ‘/usr/share/aclocal/thirdparty.m4’ as |
| follows: |
| |
| # serial 1 |
| AC_DEFUN([AX_THIRD_PARTY], [...]) |
| |
| MyPackage uses an ‘m4/’ directory to store local macros as explained |
| in *note Local Macros::, and has |
| |
| AC_CONFIG_MACRO_DIRS([m4]) |
| |
| in its ‘configure.ac’. |
| |
| Initially the ‘m4/’ directory is empty. The first time we run |
| ‘aclocal --install’, it will notice that |
| |
| • ‘configure.ac’ uses ‘AX_THIRD_PARTY’ |
| • No local macros define ‘AX_THIRD_PARTY’ |
| • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with |
| serial 1. |
| |
| Because ‘/usr/share/aclocal/thirdparty.m4’ is a system-wide macro and |
| ‘aclocal’ was given the ‘--install’ option, it will copy this file in |
| ‘m4/thirdparty.m4’, and output an ‘aclocal.m4’ that contains |
| ‘m4_include([m4/thirdparty.m4])’. |
| |
| The next time ‘aclocal --install’ is run, something different |
| happens. ‘aclocal’ notices that |
| |
| • ‘configure.ac’ uses ‘AX_THIRD_PARTY’ |
| • ‘m4/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with serial 1. |
| • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with |
| serial 1. |
| |
| Because both files have the same serial number, ‘aclocal’ uses the first |
| it found in its search path order (*note Macro Search Path::). |
| ‘aclocal’ therefore ignores ‘/usr/share/aclocal/thirdparty.m4’ and |
| outputs an ‘aclocal.m4’ that contains ‘m4_include([m4/thirdparty.m4])’. |
| |
| Local directories specified with ‘-I’ are always searched before |
| system-wide directories, so a local file will always be preferred to the |
| system-wide file in case of equal serial numbers. |
| |
| Now suppose the system-wide third-party macro is changed. This can |
| happen if the package installing this macro is updated. Let’s suppose |
| the new macro has serial number 2. The next time ‘aclocal --install’ is |
| run the situation is the following: |
| |
| • ‘configure.ac’ uses ‘AX_THIRD_PARTY’ |
| • ‘m4/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with serial 1. |
| • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with |
| serial 2. |
| |
| When ‘aclocal’ sees a greater serial number, it immediately forgets |
| anything it knows from files that have the same basename and a smaller |
| serial number. So after it has found ‘/usr/share/aclocal/thirdparty.m4’ |
| with serial 2, ‘aclocal’ will proceed as if it had never seen |
| ‘m4/thirdparty.m4’. This brings us back to a situation similar to that |
| at the beginning of our example, where no local file defined the macro. |
| ‘aclocal’ will install the new version of the macro in |
| ‘m4/thirdparty.m4’, in this case overriding the old version. MyPackage |
| just had its macro updated as a side effect of running ‘aclocal’. |
| |
| If you are leery of letting ‘aclocal’ update your local macro, you |
| can run ‘aclocal --diff’ to review the changes ‘aclocal --install’ would |
| perform on these macros. |
| |
| Finally, note that the ‘--force’ option of ‘aclocal’ has absolutely |
| no effect on the files installed by ‘--install’. For instance, if you |
| have modified your local macros, do not expect ‘--install --force’ to |
| replace the local macros by their system-wide versions. If you want to |
| do so, simply erase the local macros you want to revert, and run |
| ‘aclocal --install’. |
| |
| |
| File: automake.info, Node: Future of aclocal, Prev: Serials, Up: aclocal Invocation |
| |
| 6.3.6 The Future of ‘aclocal’ |
| ----------------------------- |
| |
| ‘aclocal’ is expected to disappear. This feature really should not be |
| offered by Automake. Automake should focus on generating ‘Makefile’s; |
| dealing with M4 macros really is Autoconf’s job. The fact that some |
| people install Automake just to use ‘aclocal’, but do not use ‘automake’ |
| otherwise is an indication of how that feature is misplaced. |
| |
| The new implementation will probably be done slightly differently. |
| For instance, it could enforce the ‘m4/’-style layout discussed in *note |
| Local Macros::. |
| |
| We have no idea when and how this will happen. This has been |
| discussed several times in the past, but someone still has to commit to |
| that non-trivial task. |
| |
| From the user point of view, ‘aclocal’’s removal might turn out to be |
| painful. There is a simple precaution that you may take to make that |
| switch more seamless: never call ‘aclocal’ yourself. Keep this guy |
| under the exclusive control of ‘autoreconf’ and Automake’s rebuild |
| rules. Hopefully you won’t need to worry about things breaking, when |
| ‘aclocal’ disappears, because everything will have been taken care of. |
| If otherwise you used to call ‘aclocal’ directly yourself or from some |
| script, you will quickly notice the change. |
| |
| Many packages come with a script called ‘bootstrap.sh’ or |
| ‘autogen.sh’, that will just call ‘aclocal’, ‘libtoolize’, ‘gettextize’ |
| or ‘autopoint’, ‘autoconf’, ‘autoheader’, and ‘automake’ in the right |
| order. Actually this is precisely what ‘autoreconf’ can do for you. If |
| your package has such a ‘bootstrap.sh’ or ‘autogen.sh’ script, consider |
| using ‘autoreconf’. That should simplify its logic a lot (less things |
| to maintain, yum!), it’s even likely you will not need the script |
| anymore, and more to the point you will not call ‘aclocal’ directly |
| anymore. |
| |
| For the time being, third-party packages should continue to install |
| public macros into ‘/usr/share/aclocal/’. If ‘aclocal’ is replaced by |
| another tool it might make sense to rename the directory, but supporting |
| ‘/usr/share/aclocal/’ for backward compatibility should be really easy |
| provided all macros are properly written (*note Extending aclocal::). |
| |
| |
| File: automake.info, Node: Macros, Prev: aclocal Invocation, Up: configure |
| |
| 6.4 Autoconf macros supplied with Automake |
| ========================================== |
| |
| Automake ships with several Autoconf macros that you can use from your |
| ‘configure.ac’. When you use one of them it will be included by |
| ‘aclocal’ in ‘aclocal.m4’. |
| |
| * Menu: |
| |
| * Public Macros:: Macros that you can use. |
| * Obsolete Macros:: Macros that will soon be removed. |
| * Private Macros:: Macros that you should not use. |
| |
| |
| File: automake.info, Node: Public Macros, Next: Obsolete Macros, Up: Macros |
| |
| 6.4.1 Public Macros |
| ------------------- |
| |
| ‘AM_INIT_AUTOMAKE([OPTIONS])’ |
| Runs many macros required for proper operation of the generated |
| Makefiles. |
| |
| Today, ‘AM_INIT_AUTOMAKE’ is called with a single argument: a |
| space-separated list of Automake options that should be applied to |
| every ‘Makefile.am’ in the tree. The effect is as if each option |
| were listed in ‘AUTOMAKE_OPTIONS’ (*note Options::). |
| |
| This macro can also be called in another, _deprecated_ form: |
| ‘AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])’. In this form, |
| there are two required arguments: the package and the version |
| number. This usage is mostly obsolete because the PACKAGE and |
| VERSION can be obtained from Autoconf’s ‘AC_INIT’ macro. However, |
| differently from what happens for ‘AC_INIT’ invocations, this |
| ‘AM_INIT_AUTOMAKE’ invocation supports shell variables’ expansions |
| in the ‘PACKAGE’ and ‘VERSION’ arguments (which otherwise defaults, |
| respectively, to the ‘PACKAGE_TARNAME’ and ‘PACKAGE_VERSION’ |
| defined via the ‘AC_INIT’ invocation; *note The ‘AC_INIT’ macro: |
| (autoconf)AC_INIT.); and this can be still be useful in some |
| selected situations. Our hope is that future Autoconf versions |
| will improve their support for package versions defined dynamically |
| at configure runtime; when (and if) this happens, support for the |
| two-args ‘AM_INIT_AUTOMAKE’ invocation will likely be removed from |
| Automake. |
| |
| If your ‘configure.ac’ has: |
| |
| AC_INIT([src/foo.c]) |
| AM_INIT_AUTOMAKE([mumble], [1.5]) |
| |
| you should modernize it as follows: |
| |
| AC_INIT([mumble], [1.5]) |
| AC_CONFIG_SRCDIR([src/foo.c]) |
| AM_INIT_AUTOMAKE |
| |
| Note that if you’re upgrading your ‘configure.ac’ from an earlier |
| version of Automake, it is not always correct to simply move the |
| package and version arguments from ‘AM_INIT_AUTOMAKE’ directly to |
| ‘AC_INIT’, as in the example above. The first argument to |
| ‘AC_INIT’ should be the name of your package (e.g., ‘GNU |
| Automake’), not the tarball name (e.g., ‘automake’) that you used |
| to pass to ‘AM_INIT_AUTOMAKE’. Autoconf tries to derive a tarball |
| name from the package name, which should work for most but not all |
| package names. (If it doesn’t work for yours, you can use the |
| four-argument form of ‘AC_INIT’ to provide the tarball name |
| explicitly). |
| |
| By default this macro ‘AC_DEFINE’’s ‘PACKAGE’ and ‘VERSION’. This |
| can be avoided by passing the ‘no-define’ option (*note List of |
| Automake options::): |
| AM_INIT_AUTOMAKE([no-define ...]) |
| |
| ‘AM_PATH_LISPDIR’ |
| Searches for the program ‘emacs’, and, if found, sets the output |
| variable ‘lispdir’ to the full path to Emacs’ site-lisp directory. |
| |
| Note that this test assumes the ‘emacs’ found to be a version that |
| supports Emacs Lisp (such as GNU Emacs or XEmacs). Other emacsen |
| can cause this test to hang (some, like old versions of MicroEmacs, |
| start up in interactive mode, requiring ‘C-x C-c’ to exit, which is |
| hardly obvious for a non-emacs user). In most cases, however, you |
| should be able to use ‘C-c’ to kill the test. In order to avoid |
| problems, you can set ‘EMACS’ to “no” in the environment, or use |
| the ‘--with-lispdir’ option to ‘configure’ to explicitly set the |
| correct path (if you’re sure you have an ‘emacs’ that supports |
| Emacs Lisp). |
| |
| ‘AM_PROG_AR([ACT-IF-FAIL])’ |
| You must use this macro when you use the archiver in your project, |
| if you want support for unusual archivers such as Microsoft ‘lib’. |
| The content of the optional argument is executed if the archiver |
| interface is not recognized; the default action is to abort |
| configure with an error message. |
| |
| ‘AM_PROG_AS’ |
| Use this macro when you have assembly code in your project. This |
| will choose the assembler for you (by default the C compiler) and |
| set ‘CCAS’, and will also set ‘CCASFLAGS’ if required. |
| |
| ‘AM_PROG_CC_C_O’ |
| This is an obsolescent macro that checks that the C compiler |
| supports the ‘-c’ and ‘-o’ options together. Note that, since |
| Automake 1.14, the ‘AC_PROG_CC’ is rewritten to implement such |
| checks itself, and thus the explicit use of ‘AM_PROG_CC_C_O’ should |
| no longer be required. |
| |
| ‘AM_PROG_LEX’ |
| Like ‘AC_PROG_LEX’ (*note Particular Program Checks: |
| (autoconf)Particular Programs.), but uses the ‘missing’ script on |
| systems that do not have ‘lex’. HP-UX 10 is one such system. |
| |
| ‘AM_PROG_GCJ’ |
| This macro finds the ‘gcj’ program or causes an error. It sets |
| ‘GCJ’ and ‘GCJFLAGS’. ‘gcj’ is the Java front-end to the GNU |
| Compiler Collection. |
| |
| ‘AM_PROG_UPC([COMPILER-SEARCH-LIST])’ |
| Find a compiler for Unified Parallel C and define the ‘UPC’ |
| variable. The default COMPILER-SEARCH-LIST is ‘upcc upc’. This |
| macro will abort ‘configure’ if no Unified Parallel C compiler is |
| found. |
| |
| ‘AM_MISSING_PROG(NAME, PROGRAM)’ |
| Find a maintainer tool PROGRAM and define the NAME environment |
| variable with its location. If PROGRAM is not detected, then NAME |
| will instead invoke the ‘missing’ script, in order to give useful |
| advice to the user about the missing maintainer tool. *Note |
| maintainer-mode::, for more information on when the ‘missing’ |
| script is appropriate. |
| |
| ‘AM_SILENT_RULES’ |
| Control the machinery for less verbose build output (*note Automake |
| Silent Rules::). |
| |
| ‘AM_WITH_DMALLOC’ |
| Add support for the Dmalloc package (http://dmalloc.com/). If the |
| user runs ‘configure’ with ‘--with-dmalloc’, then define |
| ‘WITH_DMALLOC’ and add ‘-ldmalloc’ to ‘LIBS’. |
| |
| |
| File: automake.info, Node: Obsolete Macros, Next: Private Macros, Prev: Public Macros, Up: Macros |
| |
| 6.4.2 Obsolete Macros |
| --------------------- |
| |
| Although using some of the following macros was required in past |
| releases, you should not use any of them in new code. _All these macros |
| will be removed in the next major Automake version_; if you are still |
| using them, running ‘autoupdate’ should adjust your ‘configure.ac’ |
| automatically (*note Using ‘autoupdate’ to Modernize ‘configure.ac’: |
| (autoconf)autoupdate Invocation.). _Do it NOW!_ |
| |
| ‘AM_PROG_MKDIR_P’ |
| |
| From Automake 1.8 to 1.9.6 this macro used to define the output |
| variable ‘mkdir_p’ to one of ‘mkdir -p’, ‘install-sh -d’, or |
| ‘mkinstalldirs’. |
| |
| Nowadays Autoconf provides a similar functionality with |
| ‘AC_PROG_MKDIR_P’ (*note Particular Program Checks: |
| (autoconf)Particular Programs.), however this defines the output |
| variable ‘MKDIR_P’ instead. In case you are still using the |
| ‘AM_PROG_MKDIR_P’ macro in your ‘configure.ac’, or its provided |
| variable ‘$(mkdir_p)’ in your ‘Makefile.am’, you are advised to |
| switch ASAP to the more modern Autoconf-provided interface instead; |
| both the macro and the variable might be removed in a future major |
| Automake release. |
| |
| |
| File: automake.info, Node: Private Macros, Prev: Obsolete Macros, Up: Macros |
| |
| 6.4.3 Private Macros |
| -------------------- |
| |
| The following macros are private macros you should not call directly. |
| They are called by the other public macros when appropriate. Do not |
| rely on them, as they might be changed in a future version. Consider |
| them as implementation details; or better, do not consider them at all: |
| skip this section! |
| |
| ‘_AM_DEPENDENCIES’ |
| ‘AM_SET_DEPDIR’ |
| ‘AM_DEP_TRACK’ |
| ‘AM_OUTPUT_DEPENDENCY_COMMANDS’ |
| These macros are used to implement Automake’s automatic dependency |
| tracking scheme. They are called automatically by Automake when |
| required, and there should be no need to invoke them manually. |
| |
| ‘AM_MAKE_INCLUDE’ |
| This macro is used to discover how the user’s ‘make’ handles |
| ‘include’ statements. This macro is automatically invoked when |
| needed; there should be no need to invoke it manually. |
| |
| ‘AM_PROG_INSTALL_STRIP’ |
| This is used to find a version of ‘install’ that can be used to |
| strip a program at installation time. This macro is automatically |
| included when required. |
| |
| ‘AM_SANITY_CHECK’ |
| This checks to make sure that a file created in the build directory |
| is newer than a file in the source directory. This can fail on |
| systems where the clock is set incorrectly. This macro is |
| automatically run from ‘AM_INIT_AUTOMAKE’. |
| |
| |
| File: automake.info, Node: Directories, Next: Programs, Prev: configure, Up: Top |
| |
| 7 Directories |
| ************* |
| |
| For simple projects that distribute all files in the same directory it |
| is enough to have a single ‘Makefile.am’ that builds everything in |
| place. |
| |
| In larger projects, it is common to organize files in different |
| directories, in a tree. For example, there could be a directory for the |
| program’s source, one for the testsuite, and one for the documentation; |
| or, for very large projects, there could be one directory per program, |
| per library or per module. |
| |
| The traditional approach is to build these subdirectories |
| recursively, employing _make recursion_: each directory contains its own |
| ‘Makefile’, and when ‘make’ is run from the top-level directory, it |
| enters each subdirectory in turn, and invokes there a new ‘make’ |
| instance to build the directory’s contents. |
| |
| Because this approach is very widespread, Automake offers built-in |
| support for it. However, it is worth nothing that the use of make |
| recursion has its own serious issues and drawbacks, and that it’s well |
| possible to have packages with a multi directory layout that make little |
| or no use of such recursion (examples of such packages are GNU Bison and |
| GNU Automake itself); see also the *note Alternative:: section below. |
| |
| * Menu: |
| |
| * Subdirectories:: Building subdirectories recursively |
| * Conditional Subdirectories:: Conditionally not building directories |
| * Alternative:: Subdirectories without recursion |
| * Subpackages:: Nesting packages |
| |
| |
| File: automake.info, Node: Subdirectories, Next: Conditional Subdirectories, Up: Directories |
| |
| 7.1 Recursing subdirectories |
| ============================ |
| |
| In packages using make recursion, the top level ‘Makefile.am’ must tell |
| Automake which subdirectories are to be built. This is done via the |
| ‘SUBDIRS’ variable. |
| |
| The ‘SUBDIRS’ variable holds a list of subdirectories in which |
| building of various sorts can occur. The rules for many targets (e.g., |
| ‘all’) in the generated ‘Makefile’ will run commands both locally and in |
| all specified subdirectories. Note that the directories listed in |
| ‘SUBDIRS’ are not required to contain ‘Makefile.am’s; only ‘Makefile’s |
| (after configuration). This allows inclusion of libraries from packages |
| that do not use Automake (such as ‘gettext’; see also *note Third-Party |
| Makefiles::). |
| |
| In packages that use subdirectories, the top-level ‘Makefile.am’ is |
| often very short. For instance, here is the ‘Makefile.am’ from the GNU |
| Hello distribution: |
| |
| EXTRA_DIST = BUGS ChangeLog.O README-alpha |
| SUBDIRS = doc intl po src tests |
| |
| When Automake invokes ‘make’ in a subdirectory, it uses the value of |
| the ‘MAKE’ variable. It passes the value of the variable ‘AM_MAKEFLAGS’ |
| to the ‘make’ invocation; this can be set in ‘Makefile.am’ if there are |
| flags you must always pass to ‘make’. |
| |
| The directories mentioned in ‘SUBDIRS’ are usually direct children of |
| the current directory, each subdirectory containing its own |
| ‘Makefile.am’ with a ‘SUBDIRS’ pointing to deeper subdirectories. |
| Automake can be used to construct packages of arbitrary depth this way. |
| |
| By default, Automake generates ‘Makefiles’ that work depth-first in |
| postfix order: the subdirectories are built before the current |
| directory. However, it is possible to change this ordering. You can do |
| this by putting ‘.’ into ‘SUBDIRS’. For instance, putting ‘.’ first |
| will cause a prefix ordering of directories. |
| |
| Using |
| |
| SUBDIRS = lib src . test |
| |
| will cause ‘lib/’ to be built before ‘src/’, then the current directory |
| will be built, finally the ‘test/’ directory will be built. It is |
| customary to arrange test directories to be built after everything else |
| since they are meant to test what has been constructed. |
| |
| In addition to the built-in recursive targets defined by Automake |
| (‘all’, ‘check’, etc.), the developer can also define his own recursive |
| targets. That is done by passing the names of such targets as arguments |
| to the m4 macro ‘AM_EXTRA_RECURSIVE_TARGETS’ in ‘configure.ac’. |
| Automake generates rules to handle the recursion for such targets; and |
| the developer can define real actions for them by defining corresponding |
| ‘-local’ targets. |
| |
| % cat configure.ac |
| AC_INIT([pkg-name], [1.0] |
| AM_INIT_AUTOMAKE |
| AM_EXTRA_RECURSIVE_TARGETS([foo]) |
| AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile]) |
| AC_OUTPUT |
| % cat Makefile.am |
| SUBDIRS = sub |
| foo-local: |
| @echo This will be run by "make foo". |
| % cat sub/Makefile.am |
| SUBDIRS = src |
| % cat sub/src/Makefile.am |
| foo-local: |
| @echo This too will be run by a "make foo" issued either in |
| @echo the 'sub/src/' directory, the 'sub/' directory, or the |
| @echo top-level directory. |
| |
| |
| File: automake.info, Node: Conditional Subdirectories, Next: Alternative, Prev: Subdirectories, Up: Directories |
| |
| 7.2 Conditional Subdirectories |
| ============================== |
| |
| It is possible to define the ‘SUBDIRS’ variable conditionally if, like |
| in the case of GNU Inetutils, you want to only build a subset of the |
| entire package. |
| |
| To illustrate how this works, let’s assume we have two directories |
| ‘src/’ and ‘opt/’. ‘src/’ should always be built, but we want to decide |
| in ‘configure’ whether ‘opt/’ will be built or not. (For this example |
| we will assume that ‘opt/’ should be built when the variable ‘$want_opt’ |
| was set to ‘yes’.) |
| |
| Running ‘make’ should thus recurse into ‘src/’ always, and then maybe |
| in ‘opt/’. |
| |
| However ‘make dist’ should always recurse into both ‘src/’ and |
| ‘opt/’. Because ‘opt/’ should be distributed even if it is not needed |
| in the current configuration. This means ‘opt/Makefile’ should be |
| created _unconditionally_. |
| |
| There are two ways to setup a project like this. You can use |
| Automake conditionals (*note Conditionals::) or use Autoconf ‘AC_SUBST’ |
| variables (*note Setting Output Variables: (autoconf)Setting Output |
| Variables.). Using Automake conditionals is the preferred solution. |
| Before we illustrate these two possibilities, let’s introduce |
| ‘DIST_SUBDIRS’. |
| |
| * Menu: |
| |
| * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories |
| * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories |
| * Subdirectories with AC_SUBST:: Another way for conditional recursion |
| * Unconfigured Subdirectories:: Not even creating a ‘Makefile’ |
| |
| |
| File: automake.info, Node: SUBDIRS vs DIST_SUBDIRS, Next: Subdirectories with AM_CONDITIONAL, Up: Conditional Subdirectories |
| |
| 7.2.1 ‘SUBDIRS’ vs. ‘DIST_SUBDIRS’ |
| ---------------------------------- |
| |
| Automake considers two sets of directories, defined by the variables |
| ‘SUBDIRS’ and ‘DIST_SUBDIRS’. |
| |
| ‘SUBDIRS’ contains the subdirectories of the current directory that |
| must be built (*note Subdirectories::). It must be defined manually; |
| Automake will never guess a directory is to be built. As we will see in |
| the next two sections, it is possible to define it conditionally so that |
| some directory will be omitted from the build. |
| |
| ‘DIST_SUBDIRS’ is used in rules that need to recurse in all |
| directories, even those that have been conditionally left out of the |
| build. Recall our example where we may not want to build subdirectory |
| ‘opt/’, but yet we want to distribute it? This is where ‘DIST_SUBDIRS’ |
| comes into play: ‘opt’ may not appear in ‘SUBDIRS’, but it must appear |
| in ‘DIST_SUBDIRS’. |
| |
| Precisely, ‘DIST_SUBDIRS’ is used by ‘make maintainer-clean’, ‘make |
| distclean’ and ‘make dist’. All other recursive rules use ‘SUBDIRS’. |
| |
| If ‘SUBDIRS’ is defined conditionally using Automake conditionals, |
| Automake will define ‘DIST_SUBDIRS’ automatically from the possible |
| values of ‘SUBDIRS’ in all conditions. |
| |
| If ‘SUBDIRS’ contains ‘AC_SUBST’ variables, ‘DIST_SUBDIRS’ will not |
| be defined correctly because Automake does not know the possible values |
| of these variables. In this case ‘DIST_SUBDIRS’ needs to be defined |
| manually. |
| |
| |
| File: automake.info, Node: Subdirectories with AM_CONDITIONAL, Next: Subdirectories with AC_SUBST, Prev: SUBDIRS vs DIST_SUBDIRS, Up: Conditional Subdirectories |
| |
| 7.2.2 Subdirectories with ‘AM_CONDITIONAL’ |
| ------------------------------------------ |
| |
| ‘configure’ should output the ‘Makefile’ for each directory and define a |
| condition into which ‘opt/’ should be built. |
| |
| … |
| AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes]) |
| AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile]) |
| … |
| |
| Then ‘SUBDIRS’ can be defined in the top-level ‘Makefile.am’ as |
| follows. |
| |
| if COND_OPT |
| MAYBE_OPT = opt |
| endif |
| SUBDIRS = src $(MAYBE_OPT) |
| |
| As you can see, running ‘make’ will rightly recurse into ‘src/’ and |
| maybe ‘opt/’. |
| |
| As you can’t see, running ‘make dist’ will recurse into both ‘src/’ |
| and ‘opt/’ directories because ‘make dist’, unlike ‘make all’, doesn’t |
| use the ‘SUBDIRS’ variable. It uses the ‘DIST_SUBDIRS’ variable. |
| |
| In this case Automake will define ‘DIST_SUBDIRS = src opt’ |
| automatically because it knows that ‘MAYBE_OPT’ can contain ‘opt’ in |
| some condition. |
| |
| |
| File: automake.info, Node: Subdirectories with AC_SUBST, Next: Unconfigured Subdirectories, Prev: Subdirectories with AM_CONDITIONAL, Up: Conditional Subdirectories |
| |
| 7.2.3 Subdirectories with ‘AC_SUBST’ |
| ------------------------------------ |
| |
| Another possibility is to define ‘MAYBE_OPT’ from ‘./configure’ using |
| ‘AC_SUBST’: |
| |
| … |
| if test "$want_opt" = yes; then |
| MAYBE_OPT=opt |
| else |
| MAYBE_OPT= |
| fi |
| AC_SUBST([MAYBE_OPT]) |
| AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile]) |
| … |
| |
| In this case the top-level ‘Makefile.am’ should look as follows. |
| |
| SUBDIRS = src $(MAYBE_OPT) |
| DIST_SUBDIRS = src opt |
| |
| The drawback is that since Automake cannot guess what the possible |
| values of ‘MAYBE_OPT’ are, it is necessary to define ‘DIST_SUBDIRS’. |
| |
| |
| File: automake.info, Node: Unconfigured Subdirectories, Prev: Subdirectories with AC_SUBST, Up: Conditional Subdirectories |
| |
| 7.2.4 Unconfigured Subdirectories |
| --------------------------------- |
| |
| The semantics of ‘DIST_SUBDIRS’ are often misunderstood by some users |
| that try to _configure and build_ subdirectories conditionally. Here by |
| configuring we mean creating the ‘Makefile’ (it might also involve |
| running a nested ‘configure’ script: this is a costly operation that |
| explains why people want to do it conditionally, but only the ‘Makefile’ |
| is relevant to the discussion). |
| |
| The above examples all assume that every ‘Makefile’ is created, even |
| in directories that are not going to be built. The simple reason is |
| that we want ‘make dist’ to distribute even the directories that are not |
| being built (e.g., platform-dependent code), hence ‘make dist’ must |
| recurse into the subdirectory, hence this directory must be configured |
| and appear in ‘DIST_SUBDIRS’. |
| |
| Building packages that do not configure every subdirectory is a |
| tricky business, and we do not recommend it to the novice as it is easy |
| to produce an incomplete tarball by mistake. We will not discuss this |
| topic in depth here, yet for the adventurous here are a few rules to |
| remember. |
| |
| • ‘SUBDIRS’ should always be a subset of ‘DIST_SUBDIRS’. |
| |
| It makes little sense to have a directory in ‘SUBDIRS’ that is not |
| in ‘DIST_SUBDIRS’. Think of the former as a way to tell which |
| directories listed in the latter should be built. |
| • Any directory listed in ‘DIST_SUBDIRS’ and ‘SUBDIRS’ must be |
| configured. |
| |
| I.e., the ‘Makefile’ must exists or the recursive ‘make’ rules will |
| not be able to process the directory. |
| • Any configured directory must be listed in ‘DIST_SUBDIRS’. |
| |
| So that the cleaning rules remove the generated ‘Makefile’s. It |
| would be correct to see ‘DIST_SUBDIRS’ as a variable that lists all |
| the directories that have been configured. |
| |
| In order to prevent recursion in some unconfigured directory you must |
| therefore ensure that this directory does not appear in ‘DIST_SUBDIRS’ |
| (and ‘SUBDIRS’). For instance, if you define ‘SUBDIRS’ conditionally |
| using ‘AC_SUBST’ and do not define ‘DIST_SUBDIRS’ explicitly, it will be |
| default to ‘$(SUBDIRS)’; another possibility is to force ‘DIST_SUBDIRS = |
| $(SUBDIRS)’. |
| |
| Of course, directories that are omitted from ‘DIST_SUBDIRS’ will not |
| be distributed unless you make other arrangements for this to happen |
| (for instance, always running ‘make dist’ in a configuration where all |
| directories are known to appear in ‘DIST_SUBDIRS’; or writing a |
| ‘dist-hook’ target to distribute these directories). |
| |
| In few packages, unconfigured directories are not even expected to be |
| distributed. Although these packages do not require the aforementioned |
| extra arrangements, there is another pitfall. If the name of a |
| directory appears in ‘SUBDIRS’ or ‘DIST_SUBDIRS’, ‘automake’ will make |
| sure the directory exists. Consequently ‘automake’ cannot be run on |
| such a distribution when one directory has been omitted. One way to |
| avoid this check is to use the ‘AC_SUBST’ method to declare conditional |
| directories; since ‘automake’ does not know the values of ‘AC_SUBST’ |
| variables it cannot ensure the corresponding directory exists. |
| |
| |
| File: automake.info, Node: Alternative, Next: Subpackages, Prev: Conditional Subdirectories, Up: Directories |
| |
| 7.3 An Alternative Approach to Subdirectories |
| ============================================= |
| |
| If you’ve ever read Peter Miller’s excellent paper, Recursive Make |
| Considered Harmful (http://miller.emu.id.au/pmiller/books/rmch/), the |
| preceding sections on the use of make recursion will probably come as |
| unwelcome advice. For those who haven’t read the paper, Miller’s main |
| thesis is that recursive ‘make’ invocations are both slow and |
| error-prone. |
| |
| Automake provides sufficient cross-directory support (1) to enable |
| you to write a single ‘Makefile.am’ for a complex multi-directory |
| package. |
| |
| By default an installable file specified in a subdirectory will have |
| its directory name stripped before installation. For instance, in this |
| example, the header file will be installed as ‘$(includedir)/stdio.h’: |
| |
| include_HEADERS = inc/stdio.h |
| |
| However, the ‘nobase_’ prefix can be used to circumvent this path |
| stripping. In this example, the header file will be installed as |
| ‘$(includedir)/sys/types.h’: |
| |
| nobase_include_HEADERS = sys/types.h |
| |
| ‘nobase_’ should be specified first when used in conjunction with |
| either ‘dist_’ or ‘nodist_’ (*note Fine-grained Distribution Control::). |
| For instance: |
| |
| nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg |
| |
| Finally, note that a variable using the ‘nobase_’ prefix can often be |
| replaced by several variables, one for each destination directory (*note |
| Uniform::). For instance, the last example could be rewritten as |
| follows: |
| |
| imagesdir = $(pkgdatadir)/images |
| soundsdir = $(pkgdatadir)/sounds |
| dist_images_DATA = images/vortex.pgm |
| dist_sounds_DATA = sounds/whirl.ogg |
| |
| This latter syntax makes it possible to change one destination directory |
| without changing the layout of the source tree. |
| |
| Currently, ‘nobase_*_LTLIBRARIES’ are the only exception to this |
| rule, in that there is no particular installation order guarantee for an |
| otherwise equivalent set of variables without ‘nobase_’ prefix. |
| |
| ---------- Footnotes ---------- |
| |
| (1) We believe. This work is new and there are probably warts. |
| *Note Introduction::, for information on reporting bugs. |
| |
| |
| File: automake.info, Node: Subpackages, Prev: Alternative, Up: Directories |
| |
| 7.4 Nesting Packages |
| ==================== |
| |
| In the GNU Build System, packages can be nested to arbitrary depth. |
| This means that a package can embed other packages with their own |
| ‘configure’, ‘Makefile’s, etc. |
| |
| These other packages should just appear as subdirectories of their |
| parent package. They must be listed in ‘SUBDIRS’ like other ordinary |
| directories. However the subpackage’s ‘Makefile’s should be output by |
| its own ‘configure’ script, not by the parent’s ‘configure’. This is |
| achieved using the ‘AC_CONFIG_SUBDIRS’ Autoconf macro (*note |
| AC_CONFIG_SUBDIRS: (autoconf)Subdirectories.). |
| |
| Here is an example package for an ‘arm’ program that links with a |
| ‘hand’ library that is a nested package in subdirectory ‘hand/’. |
| |
| ‘arm’’s ‘configure.ac’: |
| |
| AC_INIT([arm], [1.0]) |
| AC_CONFIG_AUX_DIR([.]) |
| AM_INIT_AUTOMAKE |
| AC_PROG_CC |
| AC_CONFIG_FILES([Makefile]) |
| # Call hand's ./configure script recursively. |
| AC_CONFIG_SUBDIRS([hand]) |
| AC_OUTPUT |
| |
| ‘arm’’s ‘Makefile.am’: |
| |
| # Build the library in the hand subdirectory first. |
| SUBDIRS = hand |
| |
| # Include hand's header when compiling this directory. |
| AM_CPPFLAGS = -I$(srcdir)/hand |
| |
| bin_PROGRAMS = arm |
| arm_SOURCES = arm.c |
| # link with the hand library. |
| arm_LDADD = hand/libhand.a |
| |
| Now here is ‘hand’’s ‘hand/configure.ac’: |
| |
| AC_INIT([hand], [1.2]) |
| AC_CONFIG_AUX_DIR([.]) |
| AM_INIT_AUTOMAKE |
| AC_PROG_CC |
| AM_PROG_AR |
| AC_PROG_RANLIB |
| AC_CONFIG_FILES([Makefile]) |
| AC_OUTPUT |
| |
| and its ‘hand/Makefile.am’: |
| |
| lib_LIBRARIES = libhand.a |
| libhand_a_SOURCES = hand.c |
| |
| When ‘make dist’ is run from the top-level directory it will create |
| an archive ‘arm-1.0.tar.gz’ that contains the ‘arm’ code as well as the |
| ‘hand’ subdirectory. This package can be built and installed like any |
| ordinary package, with the usual ‘./configure && make && make install’ |
| sequence (the ‘hand’ subpackage will be built and installed by the |
| process). |
| |
| When ‘make dist’ is run from the hand directory, it will create a |
| self-contained ‘hand-1.2.tar.gz’ archive. So although it appears to be |
| embedded in another package, it can still be used separately. |
| |
| The purpose of the ‘AC_CONFIG_AUX_DIR([.])’ instruction is to force |
| Automake and Autoconf to search for auxiliary scripts in the current |
| directory. For instance, this means that there will be two copies of |
| ‘install-sh’: one in the top-level of the ‘arm’ package, and another one |
| in the ‘hand/’ subdirectory for the ‘hand’ package. |
| |
| The historical default is to search for these auxiliary scripts in |
| the parent directory and the grandparent directory. So if the |
| ‘AC_CONFIG_AUX_DIR([.])’ line was removed from ‘hand/configure.ac’, that |
| subpackage would share the auxiliary script of the ‘arm’ package. This |
| may looks like a gain in size (a few kilobytes), but it is actually a |
| loss of modularity as the ‘hand’ subpackage is no longer self-contained |
| (‘make dist’ in the subdirectory will not work anymore). |
| |
| Packages that do not use Automake need more work to be integrated |
| this way. *Note Third-Party Makefiles::. |
| |
| |
| File: automake.info, Node: Programs, Next: Other Objects, Prev: Directories, Up: Top |
| |
| 8 Building Programs and Libraries |
| ********************************* |
| |
| A large part of Automake’s functionality is dedicated to making it easy |
| to build programs and libraries. |
| |
| * Menu: |
| |
| * A Program:: Building a program |
| * A Library:: Building a library |
| * A Shared Library:: Building a Libtool library |
| * Program and Library Variables:: Variables controlling program and |
| library builds |
| * Default _SOURCES:: Default source files |
| * LIBOBJS:: Special handling for LIBOBJS and ALLOCA |
| * Program Variables:: Variables used when building a program |
| * Yacc and Lex:: Yacc and Lex support |
| * C++ Support:: Compiling C++ sources |
| * Objective C Support:: Compiling Objective C sources |
| * Objective C++ Support:: Compiling Objective C++ sources |
| * Unified Parallel C Support:: Compiling Unified Parallel C sources |
| * Assembly Support:: Compiling assembly sources |
| * Fortran 77 Support:: Compiling Fortran 77 sources |
| * Fortran 9x Support:: Compiling Fortran 9x sources |
| * Java Support with gcj:: Compiling Java sources using gcj |
| * Vala Support:: Compiling Vala sources |
| * Support for Other Languages:: Compiling other languages |
| * Dependencies:: Automatic dependency tracking |
| * EXEEXT:: Support for executable extensions |
| |
| |
| File: automake.info, Node: A Program, Next: A Library, Up: Programs |
| |
| 8.1 Building a program |
| ====================== |
| |
| In order to build a program, you need to tell Automake which sources are |
| part of it, and which libraries it should be linked with. |
| |
| This section also covers conditional compilation of sources or |
| programs. Most of the comments about these also apply to libraries |
| (*note A Library::) and libtool libraries (*note A Shared Library::). |
| |
| * Menu: |
| |
| * Program Sources:: Defining program sources |
| * Linking:: Linking with libraries or extra objects |
| * Conditional Sources:: Handling conditional sources |
| * Conditional Programs:: Building a program conditionally |
| |
| |
| File: automake.info, Node: Program Sources, Next: Linking, Up: A Program |
| |
| 8.1.1 Defining program sources |
| ------------------------------ |
| |
| In a directory containing source that gets built into a program (as |
| opposed to a library or a script), the ‘PROGRAMS’ primary is used. |
| Programs can be installed in ‘bindir’, ‘sbindir’, ‘libexecdir’, |
| ‘pkglibexecdir’, or not at all (‘noinst_’). They can also be built only |
| for ‘make check’, in which case the prefix is ‘check_’. |
| |
| For instance: |
| |
| bin_PROGRAMS = hello |
| |
| In this simple case, the resulting ‘Makefile.in’ will contain code to |
| generate a program named ‘hello’. |
| |
| Associated with each program are several assisting variables that are |
| named after the program. These variables are all optional, and have |
| reasonable defaults. Each variable, its use, and default is spelled out |
| below; we use the “hello” example throughout. |
| |
| The variable ‘hello_SOURCES’ is used to specify which source files |
| get built into an executable: |
| |
| hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h |
| |
| This causes each mentioned ‘.c’ file to be compiled into the |
| corresponding ‘.o’. Then all are linked to produce ‘hello’. |
| |
| If ‘hello_SOURCES’ is not specified, then it defaults to the single |
| file ‘hello.c’ (*note Default _SOURCES::). |
| |
| Multiple programs can be built in a single directory. Multiple |
| programs can share a single source file, which must be listed in each |
| ‘_SOURCES’ definition. |
| |
| Header files listed in a ‘_SOURCES’ definition will be included in |
| the distribution but otherwise ignored. In case it isn’t obvious, you |
| should not include the header file generated by ‘configure’ in a |
| ‘_SOURCES’ variable; this file should not be distributed. Lex (‘.l’) |
| and Yacc (‘.y’) files can also be listed; see *note Yacc and Lex::. |
| |
| |
| File: automake.info, Node: Linking, Next: Conditional Sources, Prev: Program Sources, Up: A Program |
| |
| 8.1.2 Linking the program |
| ------------------------- |
| |
| If you need to link against libraries that are not found by ‘configure’, |
| you can use ‘LDADD’ to do so. This variable is used to specify |
| additional objects or libraries to link with; it is inappropriate for |
| specifying specific linker flags, you should use ‘AM_LDFLAGS’ for this |
| purpose. |
| |
| Sometimes, multiple programs are built in one directory but do not |
| share the same link-time requirements. In this case, you can use the |
| ‘PROG_LDADD’ variable (where PROG is the name of the program as it |
| appears in some ‘_PROGRAMS’ variable, and usually written in lowercase) |
| to override ‘LDADD’. If this variable exists for a given program, then |
| that program is not linked using ‘LDADD’. |
| |
| For instance, in GNU cpio, ‘pax’, ‘cpio’ and ‘mt’ are linked against |
| the library ‘libcpio.a’. However, ‘rmt’ is built in the same directory, |
| and has no such link requirement. Also, ‘mt’ and ‘rmt’ are only built |
| on certain architectures. Here is what cpio’s ‘src/Makefile.am’ looks |
| like (abridged): |
| |
| bin_PROGRAMS = cpio pax $(MT) |
| libexec_PROGRAMS = $(RMT) |
| EXTRA_PROGRAMS = mt rmt |
| |
| LDADD = ../lib/libcpio.a $(INTLLIBS) |
| rmt_LDADD = |
| |
| cpio_SOURCES = … |
| pax_SOURCES = … |
| mt_SOURCES = … |
| rmt_SOURCES = … |
| |
| ‘PROG_LDADD’ is inappropriate for passing program-specific linker |
| flags (except for ‘-l’, ‘-L’, ‘-dlopen’ and ‘-dlpreopen’). So, use the |
| ‘PROG_LDFLAGS’ variable for this purpose. |
| |
| It is also occasionally useful to have a program depend on some other |
| target that is not actually part of that program. This can be done |
| using either the ‘PROG_DEPENDENCIES’ or the ‘EXTRA_PROG_DEPENDENCIES’ |
| variable. Each program depends on the contents both variables, but no |
| further interpretation is done. |
| |
| Since these dependencies are associated to the link rule used to |
| create the programs they should normally list files used by the link |
| command. That is ‘*.$(OBJEXT)’, ‘*.a’, or ‘*.la’ files. In rare cases |
| you may need to add other kinds of files such as linker scripts, but |
| _listing a source file in ‘_DEPENDENCIES’ is wrong_. If some source |
| file needs to be built before all the components of a program are built, |
| consider using the ‘BUILT_SOURCES’ variable instead (*note Sources::). |
| |
| If ‘PROG_DEPENDENCIES’ is not supplied, it is computed by Automake. |
| The automatically-assigned value is the contents of ‘PROG_LDADD’, with |
| most configure substitutions, ‘-l’, ‘-L’, ‘-dlopen’ and ‘-dlpreopen’ |
| options removed. The configure substitutions that are left in are only |
| ‘$(LIBOBJS)’ and ‘$(ALLOCA)’; these are left because it is known that |
| they will not cause an invalid value for ‘PROG_DEPENDENCIES’ to be |
| generated. |
| |
| *note Conditional Sources:: shows a situation where ‘_DEPENDENCIES’ |
| may be used. |
| |
| The ‘EXTRA_PROG_DEPENDENCIES’ may be useful for cases where you |
| merely want to augment the ‘automake’-generated ‘PROG_DEPENDENCIES’ |
| rather than replacing it. |
| |
| We recommend that you avoid using ‘-l’ options in ‘LDADD’ or |
| ‘PROG_LDADD’ when referring to libraries built by your package. |
| Instead, write the file name of the library explicitly as in the above |
| ‘cpio’ example. Use ‘-l’ only to list third-party libraries. If you |
| follow this rule, the default value of ‘PROG_DEPENDENCIES’ will list all |
| your local libraries and omit the other ones. |
| |
| |
| File: automake.info, Node: Conditional Sources, Next: Conditional Programs, Prev: Linking, Up: A Program |
| |
| 8.1.3 Conditional compilation of sources |
| ---------------------------------------- |
| |
| You can’t put a configure substitution (e.g., ‘@FOO@’ or ‘$(FOO)’ where |
| ‘FOO’ is defined via ‘AC_SUBST’) into a ‘_SOURCES’ variable. The reason |
| for this is a bit hard to explain, but suffice to say that it simply |
| won’t work. Automake will give an error if you try to do this. |
| |
| Fortunately there are two other ways to achieve the same result. One |
| is to use configure substitutions in ‘_LDADD’ variables, the other is to |
| use an Automake conditional. |
| |
| Conditional Compilation using ‘_LDADD’ Substitutions |
| .................................................... |
| |
| Automake must know all the source files that could possibly go into a |
| program, even if not all the files are built in every circumstance. Any |
| files that are only conditionally built should be listed in the |
| appropriate ‘EXTRA_’ variable. For instance, if ‘hello-linux.c’ or |
| ‘hello-generic.c’ were conditionally included in ‘hello’, the |
| ‘Makefile.am’ would contain: |
| |
| bin_PROGRAMS = hello |
| hello_SOURCES = hello-common.c |
| EXTRA_hello_SOURCES = hello-linux.c hello-generic.c |
| hello_LDADD = $(HELLO_SYSTEM) |
| hello_DEPENDENCIES = $(HELLO_SYSTEM) |
| |
| You can then setup the ‘$(HELLO_SYSTEM)’ substitution from |
| ‘configure.ac’: |
| |
| … |
| case $host in |
| *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;; |
| *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;; |
| esac |
| AC_SUBST([HELLO_SYSTEM]) |
| … |
| |
| In this case, the variable ‘HELLO_SYSTEM’ should be replaced by |
| either ‘hello-linux.o’ or ‘hello-generic.o’, and added to both |
| ‘hello_DEPENDENCIES’ and ‘hello_LDADD’ in order to be built and linked |
| in. |
| |
| Conditional Compilation using Automake Conditionals |
| ................................................... |
| |
| An often simpler way to compile source files conditionally is to use |
| Automake conditionals. For instance, you could use this ‘Makefile.am’ |
| construct to build the same ‘hello’ example: |
| |
| bin_PROGRAMS = hello |
| if LINUX |
| hello_SOURCES = hello-linux.c hello-common.c |
| else |
| hello_SOURCES = hello-generic.c hello-common.c |
| endif |
| |
| In this case, ‘configure.ac’ should setup the ‘LINUX’ conditional |
| using ‘AM_CONDITIONAL’ (*note Conditionals::). |
| |
| When using conditionals like this you don’t need to use the ‘EXTRA_’ |
| variable, because Automake will examine the contents of each variable to |
| construct the complete list of source files. |
| |
| If your program uses a lot of files, you will probably prefer a |
| conditional ‘+=’. |
| |
| bin_PROGRAMS = hello |
| hello_SOURCES = hello-common.c |
| if LINUX |
| hello_SOURCES += hello-linux.c |
| else |
| hello_SOURCES += hello-generic.c |
| endif |
| |
| |
| File: automake.info, Node: Conditional Programs, Prev: Conditional Sources, Up: A Program |
| |
| 8.1.4 Conditional compilation of programs |
| ----------------------------------------- |
| |
| Sometimes it is useful to determine the programs that are to be built at |
| configure time. For instance, GNU ‘cpio’ only builds ‘mt’ and ‘rmt’ |
| under special circumstances. The means to achieve conditional |
| compilation of programs are the same you can use to compile source files |
| conditionally: substitutions or conditionals. |
| |
| Conditional Programs using ‘configure’ Substitutions |
| .................................................... |
| |
| In this case, you must notify Automake of all the programs that can |
| possibly be built, but at the same time cause the generated |
| ‘Makefile.in’ to use the programs specified by ‘configure’. This is |
| done by having ‘configure’ substitute values into each ‘_PROGRAMS’ |
| definition, while listing all optionally built programs in |
| ‘EXTRA_PROGRAMS’. |
| |
| bin_PROGRAMS = cpio pax $(MT) |
| libexec_PROGRAMS = $(RMT) |
| EXTRA_PROGRAMS = mt rmt |
| |
| As explained in *note EXEEXT::, Automake will rewrite ‘bin_PROGRAMS’, |
| ‘libexec_PROGRAMS’, and ‘EXTRA_PROGRAMS’, appending ‘$(EXEEXT)’ to each |
| binary. Obviously it cannot rewrite values obtained at run-time through |
| ‘configure’ substitutions, therefore you should take care of appending |
| ‘$(EXEEXT)’ yourself, as in ‘AC_SUBST([MT], ['mt${EXEEXT}'])’. |
| |
| Conditional Programs using Automake Conditionals |
| ................................................ |
| |
| You can also use Automake conditionals (*note Conditionals::) to select |
| programs to be built. In this case you don’t have to worry about |
| ‘$(EXEEXT)’ or ‘EXTRA_PROGRAMS’. |
| |
| bin_PROGRAMS = cpio pax |
| if WANT_MT |
| bin_PROGRAMS += mt |
| endif |
| if WANT_RMT |
| libexec_PROGRAMS = rmt |
| endif |
| |
| |
| File: automake.info, Node: A Library, Next: A Shared Library, Prev: A Program, Up: Programs |
| |
| 8.2 Building a library |
| ====================== |
| |
| Building a library is much like building a program. In this case, the |
| name of the primary is ‘LIBRARIES’. Libraries can be installed in |
| ‘libdir’ or ‘pkglibdir’. |
| |
| *Note A Shared Library::, for information on how to build shared |
| libraries using libtool and the ‘LTLIBRARIES’ primary. |
| |
| Each ‘_LIBRARIES’ variable is a list of the libraries to be built. |
| For instance, to create a library named ‘libcpio.a’, but not install it, |
| you would write: |
| |
| noinst_LIBRARIES = libcpio.a |
| libcpio_a_SOURCES = … |
| |
| The sources that go into a library are determined exactly as they are |
| for programs, via the ‘_SOURCES’ variables. Note that the library name |
| is canonicalized (*note Canonicalization::), so the ‘_SOURCES’ variable |
| corresponding to ‘libcpio.a’ is ‘libcpio_a_SOURCES’, not |
| ‘libcpio.a_SOURCES’. |
| |
| Extra objects can be added to a library using the ‘LIBRARY_LIBADD’ |
| variable. This should be used for objects determined by ‘configure’. |
| Again from ‘cpio’: |
| |
| libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA) |
| |
| In addition, sources for extra objects that will not exist until |
| configure-time must be added to the ‘BUILT_SOURCES’ variable (*note |
| Sources::). |
| |
| Building a static library is done by compiling all object files, then |
| by invoking ‘$(AR) $(ARFLAGS)’ followed by the name of the library and |
| the list of objects, and finally by calling ‘$(RANLIB)’ on that library. |
| You should call ‘AC_PROG_RANLIB’ from your ‘configure.ac’ to define |
| ‘RANLIB’ (Automake will complain otherwise). You should also call |
| ‘AM_PROG_AR’ to define ‘AR’, in order to support unusual archivers such |
| as Microsoft lib. ‘ARFLAGS’ will default to ‘cru’; you can override |
| this variable by setting it in your ‘Makefile.am’ or by ‘AC_SUBST’ing it |
| from your ‘configure.ac’. You can override the ‘AR’ variable by |
| defining a per-library ‘maude_AR’ variable (*note Program and Library |
| Variables::). |
| |
| Be careful when selecting library components conditionally. Because |
| building an empty library is not portable, you should ensure that any |
| library always contains at least one object. |
| |
| To use a static library when building a program, add it to ‘LDADD’ |
| for this program. In the following example, the program ‘cpio’ is |
| statically linked with the library ‘libcpio.a’. |
| |
| noinst_LIBRARIES = libcpio.a |
| libcpio_a_SOURCES = … |
| |
| bin_PROGRAMS = cpio |
| cpio_SOURCES = cpio.c … |
| cpio_LDADD = libcpio.a |
| |
| |
| File: automake.info, Node: A Shared Library, Next: Program and Library Variables, Prev: A Library, Up: Programs |
| |
| 8.3 Building a Shared Library |
| ============================= |
| |
| Building shared libraries portably is a relatively complex matter. For |
| this reason, GNU Libtool (*note Introduction: (libtool)Top.) was created |
| to help build shared libraries in a platform-independent way. |
| |
| * Menu: |
| |
| * Libtool Concept:: Introducing Libtool |
| * Libtool Libraries:: Declaring Libtool Libraries |
| * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally |
| * Conditional Libtool Sources:: Choosing Library Sources Conditionally |
| * Libtool Convenience Libraries:: Building Convenience Libtool Libraries |
| * Libtool Modules:: Building Libtool Modules |
| * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS |
| * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA) |
| * Libtool Issues:: Common Issues Related to Libtool’s Use |
| |
| |
| File: automake.info, Node: Libtool Concept, Next: Libtool Libraries, Up: A Shared Library |
| |
| 8.3.1 The Libtool Concept |
| ------------------------- |
| |
| Libtool abstracts shared and static libraries into a unified concept |
| henceforth called "libtool libraries". Libtool libraries are files |
| using the ‘.la’ suffix, and can designate a static library, a shared |
| library, or maybe both. Their exact nature cannot be determined until |
| ‘./configure’ is run: not all platforms support all kinds of libraries, |
| and users can explicitly select which libraries should be built. |
| (However the package’s maintainers can tune the default, *note The |
| ‘AC_PROG_LIBTOOL’ macro: (libtool)AC_PROG_LIBTOOL.) |
| |
| Because object files for shared and static libraries must be compiled |
| differently, libtool is also used during compilation. Object files |
| built by libtool are called "libtool objects": these are files using the |
| ‘.lo’ suffix. Libtool libraries are built from these libtool objects. |
| |
| You should not assume anything about the structure of ‘.la’ or ‘.lo’ |
| files and how libtool constructs them: this is libtool’s concern, and |
| the last thing one wants is to learn about libtool’s guts. However the |
| existence of these files matters, because they are used as targets and |
| dependencies in ‘Makefile’s rules when building libtool libraries. |
| There are situations where you may have to refer to these, for instance |
| when expressing dependencies for building source files conditionally |
| (*note Conditional Libtool Sources::). |
| |
| People considering writing a plug-in system, with dynamically loaded |
| modules, should look into ‘libltdl’: libtool’s dlopening library (*note |
| Using libltdl: (libtool)Using libltdl.). This offers a portable |
| dlopening facility to load libtool libraries dynamically, and can also |
| achieve static linking where unavoidable. |
| |
| Before we discuss how to use libtool with Automake in details, it |
| should be noted that the libtool manual also has a section about how to |
| use Automake with libtool (*note Using Automake with Libtool: |
| (libtool)Using Automake.). |
| |
| |
| File: automake.info, Node: Libtool Libraries, Next: Conditional Libtool Libraries, Prev: Libtool Concept, Up: A Shared Library |
| |
| 8.3.2 Building Libtool Libraries |
| -------------------------------- |
| |
| Automake uses libtool to build libraries declared with the ‘LTLIBRARIES’ |
| primary. Each ‘_LTLIBRARIES’ variable is a list of libtool libraries to |
| build. For instance, to create a libtool library named ‘libgettext.la’, |
| and install it in ‘libdir’, write: |
| |
| lib_LTLIBRARIES = libgettext.la |
| libgettext_la_SOURCES = gettext.c gettext.h … |
| |
| Automake predefines the variable ‘pkglibdir’, so you can use |
| ‘pkglib_LTLIBRARIES’ to install libraries in ‘$(libdir)/@PACKAGE@/’. |
| |
| If ‘gettext.h’ is a public header file that needs to be installed in |
| order for people to use the library, it should be declared using a |
| ‘_HEADERS’ variable, not in ‘libgettext_la_SOURCES’. Headers listed in |
| the latter should be internal headers that are not part of the public |
| interface. |
| |
| lib_LTLIBRARIES = libgettext.la |
| libgettext_la_SOURCES = gettext.c … |
| include_HEADERS = gettext.h … |
| |
| A package can build and install such a library along with other |
| programs that use it. This dependency should be specified using |
| ‘LDADD’. The following example builds a program named ‘hello’ that is |
| linked with ‘libgettext.la’. |
| |
| lib_LTLIBRARIES = libgettext.la |
| libgettext_la_SOURCES = gettext.c … |
| |
| bin_PROGRAMS = hello |
| hello_SOURCES = hello.c … |
| hello_LDADD = libgettext.la |
| |
| Whether ‘hello’ is statically or dynamically linked with ‘libgettext.la’ |
| is not yet known: this will depend on the configuration of libtool and |
| the capabilities of the host. |
| |
| |
| File: automake.info, Node: Conditional Libtool Libraries, Next: Conditional Libtool Sources, Prev: Libtool Libraries, Up: A Shared Library |
| |
| 8.3.3 Building Libtool Libraries Conditionally |
| ---------------------------------------------- |
| |
| Like conditional programs (*note Conditional Programs::), there are two |
| main ways to build conditional libraries: using Automake conditionals or |
| using Autoconf ‘AC_SUBST’itutions. |
| |
| The important implementation detail you have to be aware of is that |
| the place where a library will be installed matters to libtool: it needs |
| to be indicated _at link-time_ using the ‘-rpath’ option. |
| |
| For libraries whose destination directory is known when Automake |
| runs, Automake will automatically supply the appropriate ‘-rpath’ option |
| to libtool. This is the case for libraries listed explicitly in some |
| installable ‘_LTLIBRARIES’ variables such as ‘lib_LTLIBRARIES’. |
| |
| However, for libraries determined at configure time (and thus |
| mentioned in ‘EXTRA_LTLIBRARIES’), Automake does not know the final |
| installation directory. For such libraries you must add the ‘-rpath’ |
| option to the appropriate ‘_LDFLAGS’ variable by hand. |
| |
| The examples below illustrate the differences between these two |
| methods. |
| |
| Here is an example where ‘WANTEDLIBS’ is an ‘AC_SUBST’ed variable set |
| at ‘./configure’-time to either ‘libfoo.la’, ‘libbar.la’, both, or none. |
| Although ‘$(WANTEDLIBS)’ appears in the ‘lib_LTLIBRARIES’, Automake |
| cannot guess it relates to ‘libfoo.la’ or ‘libbar.la’ at the time it |
| creates the link rule for these two libraries. Therefore the ‘-rpath’ |
| argument must be explicitly supplied. |
| |
| EXTRA_LTLIBRARIES = libfoo.la libbar.la |
| lib_LTLIBRARIES = $(WANTEDLIBS) |
| libfoo_la_SOURCES = foo.c … |
| libfoo_la_LDFLAGS = -rpath '$(libdir)' |
| libbar_la_SOURCES = bar.c … |
| libbar_la_LDFLAGS = -rpath '$(libdir)' |
| |
| Here is how the same ‘Makefile.am’ would look using Automake |
| conditionals named ‘WANT_LIBFOO’ and ‘WANT_LIBBAR’. Now Automake is |
| able to compute the ‘-rpath’ setting itself, because it’s clear that |
| both libraries will end up in ‘$(libdir)’ if they are installed. |
| |
| lib_LTLIBRARIES = |
| if WANT_LIBFOO |
| lib_LTLIBRARIES += libfoo.la |
| endif |
| if WANT_LIBBAR |
| lib_LTLIBRARIES += libbar.la |
| endif |
| libfoo_la_SOURCES = foo.c … |
| libbar_la_SOURCES = bar.c … |
| |
| |
| File: automake.info, Node: Conditional Libtool Sources, Next: Libtool Convenience Libraries, Prev: Conditional Libtool Libraries, Up: A Shared Library |
| |
| 8.3.4 Libtool Libraries with Conditional Sources |
| ------------------------------------------------ |
| |
| Conditional compilation of sources in a library can be achieved in the |
| same way as conditional compilation of sources in a program (*note |
| Conditional Sources::). The only difference is that ‘_LIBADD’ should be |
| used instead of ‘_LDADD’ and that it should mention libtool objects |
| (‘.lo’ files). |
| |
| So, to mimic the ‘hello’ example from *note Conditional Sources::, we |
| could build a ‘libhello.la’ library using either ‘hello-linux.c’ or |
| ‘hello-generic.c’ with the following ‘Makefile.am’. |
| |
| lib_LTLIBRARIES = libhello.la |
| libhello_la_SOURCES = hello-common.c |
| EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c |
| libhello_la_LIBADD = $(HELLO_SYSTEM) |
| libhello_la_DEPENDENCIES = $(HELLO_SYSTEM) |
| |
| And make sure ‘configure’ defines ‘HELLO_SYSTEM’ as either |
| ‘hello-linux.lo’ or ‘hello-generic.lo’. |
| |
| Or we could simply use an Automake conditional as follows. |
| |
| lib_LTLIBRARIES = libhello.la |
| libhello_la_SOURCES = hello-common.c |
| if LINUX |
| libhello_la_SOURCES += hello-linux.c |
| else |
| libhello_la_SOURCES += hello-generic.c |
| endif |
| |
| |
| File: automake.info, Node: Libtool Convenience Libraries, Next: Libtool Modules, Prev: Conditional Libtool Sources, Up: A Shared Library |
| |
| 8.3.5 Libtool Convenience Libraries |
| ----------------------------------- |
| |
| Sometimes you want to build libtool libraries that should not be |
| installed. These are called "libtool convenience libraries" and are |
| typically used to encapsulate many sublibraries, later gathered into one |
| big installed library. |
| |
| Libtool convenience libraries are declared by directory-less |
| variables such as ‘noinst_LTLIBRARIES’, ‘check_LTLIBRARIES’, or even |
| ‘EXTRA_LTLIBRARIES’. Unlike installed libtool libraries they do not |
| need an ‘-rpath’ flag at link time (actually this is the only |
| difference). |
| |
| Convenience libraries listed in ‘noinst_LTLIBRARIES’ are always |
| built. Those listed in ‘check_LTLIBRARIES’ are built only upon ‘make |
| check’. Finally, libraries listed in ‘EXTRA_LTLIBRARIES’ are never |
| built explicitly: Automake outputs rules to build them, but if the |
| library does not appear as a Makefile dependency anywhere it won’t be |
| built (this is why ‘EXTRA_LTLIBRARIES’ is used for conditional |
| compilation). |
| |
| Here is a sample setup merging libtool convenience libraries from |
| subdirectories into one main ‘libtop.la’ library. |
| |
| # -- Top-level Makefile.am -- |
| SUBDIRS = sub1 sub2 … |
| lib_LTLIBRARIES = libtop.la |
| libtop_la_SOURCES = |
| libtop_la_LIBADD = \ |
| sub1/libsub1.la \ |
| sub2/libsub2.la \ |
| … |
| |
| # -- sub1/Makefile.am -- |
| noinst_LTLIBRARIES = libsub1.la |
| libsub1_la_SOURCES = … |
| |
| # -- sub2/Makefile.am -- |
| # showing nested convenience libraries |
| SUBDIRS = sub2.1 sub2.2 … |
| noinst_LTLIBRARIES = libsub2.la |
| libsub2_la_SOURCES = |
| libsub2_la_LIBADD = \ |
| sub21/libsub21.la \ |
| sub22/libsub22.la \ |
| … |
| |
| When using such setup, beware that ‘automake’ will assume ‘libtop.la’ |
| is to be linked with the C linker. This is because ‘libtop_la_SOURCES’ |
| is empty, so ‘automake’ picks C as default language. If |
| ‘libtop_la_SOURCES’ was not empty, ‘automake’ would select the linker as |
| explained in *note How the Linker is Chosen::. |
| |
| If one of the sublibraries contains non-C source, it is important |
| that the appropriate linker be chosen. One way to achieve this is to |
| pretend that there is such a non-C file among the sources of the |
| library, thus forcing ‘automake’ to select the appropriate linker. Here |
| is the top-level ‘Makefile’ of our example updated to force C++ linking. |
| |
| SUBDIRS = sub1 sub2 … |
| lib_LTLIBRARIES = libtop.la |
| libtop_la_SOURCES = |
| # Dummy C++ source to cause C++ linking. |
| nodist_EXTRA_libtop_la_SOURCES = dummy.cxx |
| libtop_la_LIBADD = \ |
| sub1/libsub1.la \ |
| sub2/libsub2.la \ |
| … |
| |
| ‘EXTRA_*_SOURCES’ variables are used to keep track of source files |
| that might be compiled (this is mostly useful when doing conditional |
| compilation using ‘AC_SUBST’, *note Conditional Libtool Sources::), and |
| the ‘nodist_’ prefix means the listed sources are not to be distributed |
| (*note Program and Library Variables::). In effect the file ‘dummy.cxx’ |
| does not need to exist in the source tree. Of course if you have some |
| real source file to list in ‘libtop_la_SOURCES’ there is no point in |
| cheating with ‘nodist_EXTRA_libtop_la_SOURCES’. |
| |
| |
| File: automake.info, Node: Libtool Modules, Next: Libtool Flags, Prev: Libtool Convenience Libraries, Up: A Shared Library |
| |
| 8.3.6 Libtool Modules |
| --------------------- |
| |
| These are libtool libraries meant to be dlopened. They are indicated to |
| libtool by passing ‘-module’ at link-time. |
| |
| pkglib_LTLIBRARIES = mymodule.la |
| mymodule_la_SOURCES = doit.c |
| mymodule_la_LDFLAGS = -module |
| |
| Ordinarily, Automake requires that a library’s name start with ‘lib’. |
| However, when building a dynamically loadable module you might wish to |
| use a "nonstandard" name. Automake will not complain about such |
| nonstandard names if it knows the library being built is a libtool |
| module, i.e., if ‘-module’ explicitly appears in the library’s |
| ‘_LDFLAGS’ variable (or in the common ‘AM_LDFLAGS’ variable when no |
| per-library ‘_LDFLAGS’ variable is defined). |
| |
| As always, ‘AC_SUBST’ variables are black boxes to Automake since |
| their values are not yet known when ‘automake’ is run. Therefore if |
| ‘-module’ is set via such a variable, Automake cannot notice it and will |
| proceed as if the library was an ordinary libtool library, with strict |
| naming. |
| |
| If ‘mymodule_la_SOURCES’ is not specified, then it defaults to the |
| single file ‘mymodule.c’ (*note Default _SOURCES::). |
| |
| |
| File: automake.info, Node: Libtool Flags, Next: LTLIBOBJS, Prev: Libtool Modules, Up: A Shared Library |
| |
| 8.3.7 ‘_LIBADD’, ‘_LDFLAGS’, and ‘_LIBTOOLFLAGS’ |
| ------------------------------------------------ |
| |
| As shown in previous sections, the ‘LIBRARY_LIBADD’ variable should be |
| used to list extra libtool objects (‘.lo’ files) or libtool libraries |
| (‘.la’) to add to LIBRARY. |
| |
| The ‘LIBRARY_LDFLAGS’ variable is the place to list additional |
| libtool linking flags, such as ‘-version-info’, ‘-static’, and a lot |
| more. *Note Link mode: (libtool)Link mode. |
| |
| The ‘libtool’ command has two kinds of options: mode-specific options |
| and generic options. Mode-specific options such as the aforementioned |
| linking flags should be lumped with the other flags passed to the tool |
| invoked by ‘libtool’ (hence the use of ‘LIBRARY_LDFLAGS’ for libtool |
| linking flags). Generic options include ‘--tag=TAG’ and ‘--silent’ |
| (*note Invoking ‘libtool’: (libtool)Invoking libtool. for more options) |
| should appear before the mode selection on the command line; in |
| ‘Makefile.am’s they should be listed in the ‘LIBRARY_LIBTOOLFLAGS’ |
| variable. |
| |
| If ‘LIBRARY_LIBTOOLFLAGS’ is not defined, then the variable |
| ‘AM_LIBTOOLFLAGS’ is used instead. |
| |
| These flags are passed to libtool after the ‘--tag=TAG’ option |
| computed by Automake (if any), so ‘LIBRARY_LIBTOOLFLAGS’ (or |
| ‘AM_LIBTOOLFLAGS’) is a good place to override or supplement the |
| ‘--tag=TAG’ setting. |
| |
| The libtool rules also use a ‘LIBTOOLFLAGS’ variable that should not |
| be set in ‘Makefile.am’: this is a user variable (*note Flag Variables |
| Ordering::. It allows users to run ‘make LIBTOOLFLAGS=--silent’, for |
| instance. Note that the verbosity of ‘libtool’ can also be influenced |
| by the Automake support for silent rules (*note Automake Silent |
| Rules::). |
| |
| |
| File: automake.info, Node: LTLIBOBJS, Next: Libtool Issues, Prev: Libtool Flags, Up: A Shared Library |
| |
| 8.3.8 ‘LTLIBOBJS’ and ‘LTALLOCA’ |
| -------------------------------- |
| |
| Where an ordinary library might include ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ |
| (*note LIBOBJS::), a libtool library must use ‘$(LTLIBOBJS)’ or |
| ‘$(LTALLOCA)’. This is required because the object files that libtool |
| operates on do not necessarily end in ‘.o’. |
| |
| Nowadays, the computation of ‘LTLIBOBJS’ from ‘LIBOBJS’ is performed |
| automatically by Autoconf (*note ‘AC_LIBOBJ’ vs. ‘LIBOBJS’: |
| (autoconf)AC_LIBOBJ vs LIBOBJS.). |
| |
| |
| File: automake.info, Node: Libtool Issues, Prev: LTLIBOBJS, Up: A Shared Library |
| |
| 8.3.9 Common Issues Related to Libtool’s Use |
| -------------------------------------------- |
| |
| * Menu: |
| |
| * Error required file ltmain.sh not found:: The need to run libtoolize |
| * Objects created both with libtool and without:: Avoid a specific build race |
| |
| |
| File: automake.info, Node: Error required file ltmain.sh not found, Next: Objects created both with libtool and without, Up: Libtool Issues |
| |
| 8.3.9.1 Error: ‘required file `./ltmain.sh' not found’ |
| ...................................................... |
| |
| Libtool comes with a tool called ‘libtoolize’ that will install |
| libtool’s supporting files into a package. Running this command will |
| install ‘ltmain.sh’. You should execute it before ‘aclocal’ and |
| ‘automake’. |
| |
| People upgrading old packages to newer autotools are likely to face |
| this issue because older Automake versions used to call ‘libtoolize’. |
| Therefore old build scripts do not call ‘libtoolize’. |
| |
| Since Automake 1.6, it has been decided that running ‘libtoolize’ was |
| none of Automake’s business. Instead, that functionality has been moved |
| into the ‘autoreconf’ command (*note Using ‘autoreconf’: |
| (autoconf)autoreconf Invocation.). If you do not want to remember what |
| to run and when, just learn the ‘autoreconf’ command. Hopefully, |
| replacing existing ‘bootstrap.sh’ or ‘autogen.sh’ scripts by a call to |
| ‘autoreconf’ should also free you from any similar incompatible change |
| in the future. |
| |
| |
| File: automake.info, Node: Objects created both with libtool and without, Prev: Error required file ltmain.sh not found, Up: Libtool Issues |
| |
| 8.3.9.2 Objects ‘created with both libtool and without’ |
| ....................................................... |
| |
| Sometimes, the same source file is used both to build a libtool library |
| and to build another non-libtool target (be it a program or another |
| library). |
| |
| Let’s consider the following ‘Makefile.am’. |
| |
| bin_PROGRAMS = prog |
| prog_SOURCES = prog.c foo.c … |
| |
| lib_LTLIBRARIES = libfoo.la |
| libfoo_la_SOURCES = foo.c … |
| |
| (In this trivial case the issue could be avoided by linking ‘libfoo.la’ |
| with ‘prog’ instead of listing ‘foo.c’ in ‘prog_SOURCES’. But let’s |
| assume we really want to keep ‘prog’ and ‘libfoo.la’ separate.) |
| |
| Technically, it means that we should build ‘foo.$(OBJEXT)’ for |
| ‘prog’, and ‘foo.lo’ for ‘libfoo.la’. The problem is that in the course |
| of creating ‘foo.lo’, libtool may erase (or replace) ‘foo.$(OBJEXT)’, |
| and this cannot be avoided. |
| |
| Therefore, when Automake detects this situation it will complain with |
| a message such as |
| object 'foo.$(OBJEXT)' created both with libtool and without |
| |
| A workaround for this issue is to ensure that these two objects get |
| different basenames. As explained in *note Renamed Objects::, this |
| happens automatically when per-targets flags are used. |
| |
| bin_PROGRAMS = prog |
| prog_SOURCES = prog.c foo.c … |
| prog_CFLAGS = $(AM_CFLAGS) |
| |
| lib_LTLIBRARIES = libfoo.la |
| libfoo_la_SOURCES = foo.c … |
| |
| Adding ‘prog_CFLAGS = $(AM_CFLAGS)’ is almost a no-op, because when the |
| ‘prog_CFLAGS’ is defined, it is used instead of ‘AM_CFLAGS’. However as |
| a side effect it will cause ‘prog.c’ and ‘foo.c’ to be compiled as |
| ‘prog-prog.$(OBJEXT)’ and ‘prog-foo.$(OBJEXT)’, which solves the issue. |
| |
| |
| File: automake.info, Node: Program and Library Variables, Next: Default _SOURCES, Prev: A Shared Library, Up: Programs |
| |
| 8.4 Program and Library Variables |
| ================================= |
| |
| Associated with each program is a collection of variables that can be |
| used to modify how that program is built. There is a similar list of |
| such variables for each library. The canonical name of the program (or |
| library) is used as a base for naming these variables. |
| |
| In the list below, we use the name “maude” to refer to the program or |
| library. In your ‘Makefile.am’ you would replace this with the |
| canonical name of your program. This list also refers to “maude” as a |
| program, but in general the same rules apply for both static and dynamic |
| libraries; the documentation below notes situations where programs and |
| libraries differ. |
| |
| ‘maude_SOURCES’ |
| This variable, if it exists, lists all the source files that are |
| compiled to build the program. These files are added to the |
| distribution by default. When building the program, Automake will |
| cause each source file to be compiled to a single ‘.o’ file (or |
| ‘.lo’ when using libtool). Normally these object files are named |
| after the source file, but other factors can change this. If a |
| file in the ‘_SOURCES’ variable has an unrecognized extension, |
| Automake will do one of two things with it. If a suffix rule |
| exists for turning files with the unrecognized extension into ‘.o’ |
| files, then ‘automake’ will treat this file as it will any other |
| source file (*note Support for Other Languages::). Otherwise, the |
| file will be ignored as though it were a header file. |
| |
| The prefixes ‘dist_’ and ‘nodist_’ can be used to control whether |
| files listed in a ‘_SOURCES’ variable are distributed. ‘dist_’ is |
| redundant, as sources are distributed by default, but it can be |
| specified for clarity if desired. |
| |
| It is possible to have both ‘dist_’ and ‘nodist_’ variants of a |
| given ‘_SOURCES’ variable at once; this lets you easily distribute |
| some files and not others, for instance: |
| |
| nodist_maude_SOURCES = nodist.c |
| dist_maude_SOURCES = dist-me.c |
| |
| By default the output file (on Unix systems, the ‘.o’ file) will be |
| put into the current build directory. However, if the option |
| ‘subdir-objects’ is in effect in the current directory then the |
| ‘.o’ file will be put into the subdirectory named after the source |
| file. For instance, with ‘subdir-objects’ enabled, |
| ‘sub/dir/file.c’ will be compiled to ‘sub/dir/file.o’. Some people |
| prefer this mode of operation. You can specify ‘subdir-objects’ in |
| ‘AUTOMAKE_OPTIONS’ (*note Options::). |
| |
| ‘EXTRA_maude_SOURCES’ |
| Automake needs to know the list of files you intend to compile |
| _statically_. For one thing, this is the only way Automake has of |
| knowing what sort of language support a given ‘Makefile.in’ |
| requires. (1) This means that, for example, you can’t put a |
| configure substitution like ‘@my_sources@’ into a ‘_SOURCES’ |
| variable. If you intend to conditionally compile source files and |
| use ‘configure’ to substitute the appropriate object names into, |
| e.g., ‘_LDADD’ (see below), then you should list the corresponding |
| source files in the ‘EXTRA_’ variable. |
| |
| This variable also supports ‘dist_’ and ‘nodist_’ prefixes. For |
| instance, ‘nodist_EXTRA_maude_SOURCES’ would list extra sources |
| that may need to be built, but should not be distributed. |
| |
| ‘maude_AR’ |
| A static library is created by default by invoking ‘$(AR) |
| $(ARFLAGS)’ followed by the name of the library and then the |
| objects being put into the library. You can override this by |
| setting the ‘_AR’ variable. This is usually used with C++; some |
| C++ compilers require a special invocation in order to instantiate |
| all the templates that should go into a library. For instance, the |
| SGI C++ compiler likes this variable set like so: |
| libmaude_a_AR = $(CXX) -ar -o |
| |
| ‘maude_LIBADD’ |
| Extra objects can be added to a _library_ using the ‘_LIBADD’ |
| variable. For instance, this should be used for objects determined |
| by ‘configure’ (*note A Library::). |
| |
| In the case of libtool libraries, ‘maude_LIBADD’ can also refer to |
| other libtool libraries. |
| |
| ‘maude_LDADD’ |
| Extra objects (‘*.$(OBJEXT)’) and libraries (‘*.a’, ‘*.la’) can be |
| added to a _program_ by listing them in the ‘_LDADD’ variable. For |
| instance, this should be used for objects determined by ‘configure’ |
| (*note Linking::). |
| |
| ‘_LDADD’ and ‘_LIBADD’ are inappropriate for passing |
| program-specific linker flags (except for ‘-l’, ‘-L’, ‘-dlopen’ and |
| ‘-dlpreopen’). Use the ‘_LDFLAGS’ variable for this purpose. |
| |
| For instance, if your ‘configure.ac’ uses ‘AC_PATH_XTRA’, you could |
| link your program against the X libraries like so: |
| |
| maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS) |
| |
| We recommend that you use ‘-l’ and ‘-L’ only when referring to |
| third-party libraries, and give the explicit file names of any |
| library built by your package. Doing so will ensure that |
| ‘maude_DEPENDENCIES’ (see below) is correctly defined by default. |
| |
| ‘maude_LDFLAGS’ |
| This variable is used to pass extra flags to the link step of a |
| program or a shared library. It overrides the ‘AM_LDFLAGS’ |
| variable. |
| |
| ‘maude_LIBTOOLFLAGS’ |
| This variable is used to pass extra options to ‘libtool’. It |
| overrides the ‘AM_LIBTOOLFLAGS’ variable. These options are output |
| before ‘libtool’’s ‘--mode=MODE’ option, so they should not be |
| mode-specific options (those belong to the compiler or linker |
| flags). *Note Libtool Flags::. |
| |
| ‘maude_DEPENDENCIES’ |
| ‘EXTRA_maude_DEPENDENCIES’ |
| It is also occasionally useful to have a target (program or |
| library) depend on some other file that is not actually part of |
| that target. This can be done using the ‘_DEPENDENCIES’ variable. |
| Each target depends on the contents of such a variable, but no |
| further interpretation is done. |
| |
| Since these dependencies are associated to the link rule used to |
| create the programs they should normally list files used by the |
| link command. That is ‘*.$(OBJEXT)’, ‘*.a’, or ‘*.la’ files for |
| programs; ‘*.lo’ and ‘*.la’ files for Libtool libraries; and |
| ‘*.$(OBJEXT)’ files for static libraries. In rare cases you may |
| need to add other kinds of files such as linker scripts, but |
| _listing a source file in ‘_DEPENDENCIES’ is wrong_. If some |
| source file needs to be built before all the components of a |
| program are built, consider using the ‘BUILT_SOURCES’ variable |
| (*note Sources::). |
| |
| If ‘_DEPENDENCIES’ is not supplied, it is computed by Automake. |
| The automatically-assigned value is the contents of ‘_LDADD’ or |
| ‘_LIBADD’, with most configure substitutions, ‘-l’, ‘-L’, ‘-dlopen’ |
| and ‘-dlpreopen’ options removed. The configure substitutions that |
| are left in are only ‘$(LIBOBJS)’ and ‘$(ALLOCA)’; these are left |
| because it is known that they will not cause an invalid value for |
| ‘_DEPENDENCIES’ to be generated. |
| |
| ‘_DEPENDENCIES’ is more likely used to perform conditional |
| compilation using an ‘AC_SUBST’ variable that contains a list of |
| objects. *Note Conditional Sources::, and *note Conditional |
| Libtool Sources::. |
| |
| The ‘EXTRA_*_DEPENDENCIES’ variable may be useful for cases where |
| you merely want to augment the ‘automake’-generated ‘_DEPENDENCIES’ |
| variable rather than replacing it. |
| |
| ‘maude_LINK’ |
| You can override the linker on a per-program basis. By default the |
| linker is chosen according to the languages used by the program. |
| For instance, a program that includes C++ source code would use the |
| C++ compiler to link. The ‘_LINK’ variable must hold the name of a |
| command that can be passed all the ‘.o’ file names and libraries to |
| link against as arguments. Note that the name of the underlying |
| program is _not_ passed to ‘_LINK’; typically one uses ‘$@’: |
| |
| maude_LINK = $(CCLD) -magic -o $@ |
| |
| If a ‘_LINK’ variable is not supplied, it may still be generated |
| and used by Automake due to the use of per-target link flags such |
| as ‘_CFLAGS’, ‘_LDFLAGS’ or ‘_LIBTOOLFLAGS’, in cases where they |
| apply. |
| |
| ‘maude_CCASFLAGS’ |
| ‘maude_CFLAGS’ |
| ‘maude_CPPFLAGS’ |
| ‘maude_CXXFLAGS’ |
| ‘maude_FFLAGS’ |
| ‘maude_GCJFLAGS’ |
| ‘maude_LFLAGS’ |
| ‘maude_OBJCFLAGS’ |
| ‘maude_OBJCXXFLAGS’ |
| ‘maude_RFLAGS’ |
| ‘maude_UPCFLAGS’ |
| ‘maude_YFLAGS’ |
| Automake allows you to set compilation flags on a per-program (or |
| per-library) basis. A single source file can be included in |
| several programs, and it will potentially be compiled with |
| different flags for each program. This works for any language |
| directly supported by Automake. These "per-target compilation |
| flags" are ‘_CCASFLAGS’, ‘_CFLAGS’, ‘_CPPFLAGS’, ‘_CXXFLAGS’, |
| ‘_FFLAGS’, ‘_GCJFLAGS’, ‘_LFLAGS’, ‘_OBJCFLAGS’, ‘_OBJCXXFLAGS’, |
| ‘_RFLAGS’, ‘_UPCFLAGS’, and ‘_YFLAGS’. |
| |
| When using a per-target compilation flag, Automake will choose a |
| different name for the intermediate object files. Ordinarily a |
| file like ‘sample.c’ will be compiled to produce ‘sample.o’. |
| However, if the program’s ‘_CFLAGS’ variable is set, then the |
| object file will be named, for instance, ‘maude-sample.o’. (See |
| also *note Renamed Objects::). |
| |
| In compilations with per-target flags, the ordinary ‘AM_’ form of |
| the flags variable is _not_ automatically included in the |
| compilation (however, the user form of the variable _is_ included). |
| So for instance, if you want the hypothetical ‘maude’ compilations |
| to also use the value of ‘AM_CFLAGS’, you would need to write: |
| |
| maude_CFLAGS = … your flags … $(AM_CFLAGS) |
| |
| *Note Flag Variables Ordering::, for more discussion about the |
| interaction between user variables, ‘AM_’ shadow variables, and |
| per-target variables. |
| |
| ‘maude_SHORTNAME’ |
| On some platforms the allowable file names are very short. In |
| order to support these systems and per-target compilation flags at |
| the same time, Automake allows you to set a “short name” that will |
| influence how intermediate object files are named. For instance, |
| in the following example, |
| |
| bin_PROGRAMS = maude |
| maude_CPPFLAGS = -DSOMEFLAG |
| maude_SHORTNAME = m |
| maude_SOURCES = sample.c … |
| |
| the object file would be named ‘m-sample.o’ rather than |
| ‘maude-sample.o’. |
| |
| This facility is rarely needed in practice, and we recommend |
| avoiding it until you find it is required. |
| |
| ---------- Footnotes ---------- |
| |
| (1) There are other, more obscure reasons for this limitation as |
| well. |
| |
| |
| File: automake.info, Node: Default _SOURCES, Next: LIBOBJS, Prev: Program and Library Variables, Up: Programs |
| |
| 8.5 Default ‘_SOURCES’ |
| ====================== |
| |
| ‘_SOURCES’ variables are used to specify source files of programs (*note |
| A Program::), libraries (*note A Library::), and Libtool libraries |
| (*note A Shared Library::). |
| |
| When no such variable is specified for a target, Automake will define |
| one itself. The default is to compile a single C file whose base name |
| is the name of the target itself, with any extension replaced by |
| ‘AM_DEFAULT_SOURCE_EXT’, which defaults to ‘.c’. |
| |
| For example if you have the following somewhere in your ‘Makefile.am’ |
| with no corresponding ‘libfoo_a_SOURCES’: |
| |
| lib_LIBRARIES = libfoo.a sub/libc++.a |
| |
| ‘libfoo.a’ will be built using a default source file named ‘libfoo.c’, |
| and ‘sub/libc++.a’ will be built from ‘sub/libc++.c’. (In older |
| versions ‘sub/libc++.a’ would be built from ‘sub_libc___a.c’, i.e., the |
| default source was the canonized name of the target, with ‘.c’ appended. |
| We believe the new behavior is more sensible, but for backward |
| compatibility ‘automake’ will use the old name if a file or a rule with |
| that name exists and ‘AM_DEFAULT_SOURCE_EXT’ is not used.) |
| |
| Default sources are mainly useful in test suites, when building many |
| test programs each from a single source. For instance, in |
| |
| check_PROGRAMS = test1 test2 test3 |
| AM_DEFAULT_SOURCE_EXT = .cpp |
| |
| ‘test1’, ‘test2’, and ‘test3’ will be built from ‘test1.cpp’, |
| ‘test2.cpp’, and ‘test3.cpp’. Without the last line, they will be built |
| from ‘test1.c’, ‘test2.c’, and ‘test3.c’. |
| |
| Another case where this is convenient is building many Libtool |
| modules (‘moduleN.la’), each defined in its own file (‘moduleN.c’). |
| |
| AM_LDFLAGS = -module |
| lib_LTLIBRARIES = module1.la module2.la module3.la |
| |
| Finally, there is one situation where this default source computation |
| needs to be avoided: when a target should not be built from sources. We |
| already saw such an example in *note true::; this happens when all the |
| constituents of a target have already been compiled and just need to be |
| combined using a ‘_LDADD’ variable. Then it is necessary to define an |
| empty ‘_SOURCES’ variable, so that ‘automake’ does not compute a |
| default. |
| |
| bin_PROGRAMS = target |
| target_SOURCES = |
| target_LDADD = libmain.a libmisc.a |
| |
| |
| File: automake.info, Node: LIBOBJS, Next: Program Variables, Prev: Default _SOURCES, Up: Programs |
| |
| 8.6 Special handling for ‘LIBOBJS’ and ‘ALLOCA’ |
| =============================================== |
| |
| The ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables list object files that should |
| be compiled into the project to provide an implementation for functions |
| that are missing or broken on the host system. They are substituted by |
| ‘configure’. |
| |
| These variables are defined by Autoconf macros such as ‘AC_LIBOBJ’, |
| ‘AC_REPLACE_FUNCS’ (*note Generic Function Checks: (autoconf)Generic |
| Functions.), or ‘AC_FUNC_ALLOCA’ (*note Particular Function Checks: |
| (autoconf)Particular Functions.). Many other Autoconf macros call |
| ‘AC_LIBOBJ’ or ‘AC_REPLACE_FUNCS’ to populate ‘$(LIBOBJS)’. |
| |
| Using these variables is very similar to doing conditional |
| compilation using ‘AC_SUBST’ variables, as described in *note |
| Conditional Sources::. That is, when building a program, ‘$(LIBOBJS)’ |
| and ‘$(ALLOCA)’ should be added to the associated ‘*_LDADD’ variable, or |
| to the ‘*_LIBADD’ variable when building a library. However there is no |
| need to list the corresponding sources in ‘EXTRA_*_SOURCES’ nor to |
| define ‘*_DEPENDENCIES’. Automake automatically adds ‘$(LIBOBJS)’ and |
| ‘$(ALLOCA)’ to the dependencies, and it will discover the list of |
| corresponding source files automatically (by tracing the invocations of |
| the ‘AC_LIBSOURCE’ Autoconf macros). If you have already defined |
| ‘*_DEPENDENCIES’ explicitly for an unrelated reason, then you either |
| need to add these variables manually, or use ‘EXTRA_*_DEPENDENCIES’ |
| instead of ‘*_DEPENDENCIES’. |
| |
| These variables are usually used to build a portability library that |
| is linked with all the programs of the project. We now review a sample |
| setup. First, ‘configure.ac’ contains some checks that affect either |
| ‘LIBOBJS’ or ‘ALLOCA’. |
| |
| # configure.ac |
| … |
| AC_CONFIG_LIBOBJ_DIR([lib]) |
| … |
| AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS |
| AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS |
| AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS |
| AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA |
| … |
| AC_CONFIG_FILES([ |
| lib/Makefile |
| src/Makefile |
| ]) |
| AC_OUTPUT |
| |
| The ‘AC_CONFIG_LIBOBJ_DIR’ tells Autoconf that the source files of |
| these object files are to be found in the ‘lib/’ directory. Automake |
| can also use this information, otherwise it expects the source files are |
| to be in the directory where the ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ variables |
| are used. |
| |
| The ‘lib/’ directory should therefore contain ‘malloc.c’, ‘memcmp.c’, |
| ‘strdup.c’, ‘alloca.c’. Here is its ‘Makefile.am’: |
| |
| # lib/Makefile.am |
| |
| noinst_LIBRARIES = libcompat.a |
| libcompat_a_SOURCES = |
| libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA) |
| |
| The library can have any name, of course, and anyway it is not going |
| to be installed: it just holds the replacement versions of the missing |
| or broken functions so we can later link them in. Many projects also |
| include extra functions, specific to the project, in that library: they |
| are simply added on the ‘_SOURCES’ line. |
| |
| There is a small trap here, though: ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ |
| might be empty, and building an empty library is not portable. You |
| should ensure that there is always something to put in ‘libcompat.a’. |
| Most projects will also add some utility functions in that directory, |
| and list them in ‘libcompat_a_SOURCES’, so in practice ‘libcompat.a’ |
| cannot be empty. |
| |
| Finally here is how this library could be used from the ‘src/’ |
| directory. |
| |
| # src/Makefile.am |
| |
| # Link all programs in this directory with libcompat.a |
| LDADD = ../lib/libcompat.a |
| |
| bin_PROGRAMS = tool1 tool2 … |
| tool1_SOURCES = … |
| tool2_SOURCES = … |
| |
| When option ‘subdir-objects’ is not used, as in the above example, |
| the variables ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ can only be used in the |
| directory where their sources lie. E.g., here it would be wrong to use |
| ‘$(LIBOBJS)’ or ‘$(ALLOCA)’ in ‘src/Makefile.am’. However if both |
| ‘subdir-objects’ and ‘AC_CONFIG_LIBOBJ_DIR’ are used, it is OK to use |
| these variables in other directories. For instance ‘src/Makefile.am’ |
| could be changed as follows. |
| |
| # src/Makefile.am |
| |
| AUTOMAKE_OPTIONS = subdir-objects |
| LDADD = $(LIBOBJS) $(ALLOCA) |
| |
| bin_PROGRAMS = tool1 tool2 … |
| tool1_SOURCES = … |
| tool2_SOURCES = … |
| |
| Because ‘$(LIBOBJS)’ and ‘$(ALLOCA)’ contain object file names that |
| end with ‘.$(OBJEXT)’, they are not suitable for Libtool libraries |
| (where the expected object extension is ‘.lo’): ‘LTLIBOBJS’ and |
| ‘LTALLOCA’ should be used instead. |
| |
| ‘LTLIBOBJS’ is defined automatically by Autoconf and should not be |
| defined by hand (as in the past), however at the time of writing |
| ‘LTALLOCA’ still needs to be defined from ‘ALLOCA’ manually. *Note |
| ‘AC_LIBOBJ’ vs. ‘LIBOBJS’: (autoconf)AC_LIBOBJ vs LIBOBJS. |
| |
| |
| File: automake.info, Node: Program Variables, Next: Yacc and Lex, Prev: LIBOBJS, Up: Programs |
| |
| 8.7 Variables used when building a program |
| ========================================== |
| |
| Occasionally it is useful to know which ‘Makefile’ variables Automake |
| uses for compilations, and in which order (*note Flag Variables |
| Ordering::); for instance, you might need to do your own compilation in |
| some special cases. |
| |
| Some variables are inherited from Autoconf; these are ‘CC’, ‘CFLAGS’, |
| ‘CPPFLAGS’, ‘DEFS’, ‘LDFLAGS’, and ‘LIBS’. |
| |
| There are some additional variables that Automake defines on its own: |
| |
| ‘AM_CPPFLAGS’ |
| The contents of this variable are passed to every compilation that |
| invokes the C preprocessor; it is a list of arguments to the |
| preprocessor. For instance, ‘-I’ and ‘-D’ options should be listed |
| here. |
| |
| Automake already provides some ‘-I’ options automatically, in a |
| separate variable that is also passed to every compilation that |
| invokes the C preprocessor. In particular it generates ‘-I.’, |
| ‘-I$(srcdir)’, and a ‘-I’ pointing to the directory holding |
| ‘config.h’ (if you’ve used ‘AC_CONFIG_HEADERS’). You can disable |
| the default ‘-I’ options using the ‘nostdinc’ option. |
| |
| When a file to be included is generated during the build and not |
| part of a distribution tarball, its location is under |
| ‘$(builddir)’, not under ‘$(srcdir)’. This matters especially for |
| packages that use header files placed in sub-directories and want |
| to allow builds outside the source tree (*note VPATH Builds::). In |
| that case we recommend to use a pair of ‘-I’ options, such as, |
| e.g., ‘-Isome/subdir -I$(srcdir)/some/subdir’ or |
| ‘-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir’. Note |
| that the reference to the build tree should come before the |
| reference to the source tree, so that accidentally leftover |
| generated files in the source directory are ignored. |
| |
| ‘AM_CPPFLAGS’ is ignored in preference to a per-executable (or |
| per-library) ‘_CPPFLAGS’ variable if it is defined. |
| |
| ‘INCLUDES’ |
| This does the same job as ‘AM_CPPFLAGS’ (or any per-target |
| ‘_CPPFLAGS’ variable if it is used). It is an older name for the |
| same functionality. This variable is deprecated; we suggest using |
| ‘AM_CPPFLAGS’ and per-target ‘_CPPFLAGS’ instead. |
| |
| ‘AM_CFLAGS’ |
| This is the variable the ‘Makefile.am’ author can use to pass in |
| additional C compiler flags. In some situations, this is not used, |
| in preference to the per-executable (or per-library) ‘_CFLAGS’. |
| |
| ‘COMPILE’ |
| This is the command used to actually compile a C source file. The |
| file name is appended to form the complete command line. |
| |
| ‘AM_LDFLAGS’ |
| This is the variable the ‘Makefile.am’ author can use to pass in |
| additional linker flags. In some situations, this is not used, in |
| preference to the per-executable (or per-library) ‘_LDFLAGS’. |
| |
| ‘LINK’ |
| This is the command used to actually link a C program. It already |
| includes ‘-o $@’ and the usual variable references (for instance, |
| ‘CFLAGS’); it takes as “arguments” the names of the object files |
| and libraries to link in. This variable is not used when the |
| linker is overridden with a per-target ‘_LINK’ variable or |
| per-target flags cause Automake to define such a ‘_LINK’ variable. |
| |
| |
| File: automake.info, Node: Yacc and Lex, Next: C++ Support, Prev: Program Variables, Up: Programs |
| |
| 8.8 Yacc and Lex support |
| ======================== |
| |
| Automake has somewhat idiosyncratic support for Yacc and Lex. |
| |
| Automake assumes that the ‘.c’ file generated by ‘yacc’ (or ‘lex’) |
| should be named using the basename of the input file. That is, for a |
| yacc source file ‘foo.y’, Automake will cause the intermediate file to |
| be named ‘foo.c’ (as opposed to ‘y.tab.c’, which is more traditional). |
| |
| The extension of a yacc source file is used to determine the |
| extension of the resulting C or C++ source and header files. Note that |
| header files are generated only when the ‘-d’ Yacc option is used; see |
| below for more information about this flag, and how to specify it. |
| Files with the extension ‘.y’ will thus be turned into ‘.c’ sources and |
| ‘.h’ headers; likewise, ‘.yy’ will become ‘.cc’ and ‘.hh’, ‘.y++’ will |
| become ‘c++’ and ‘h++’, ‘.yxx’ will become ‘.cxx’ and ‘.hxx’, and ‘.ypp’ |
| will become ‘.cpp’ and ‘.hpp’. |
| |
| Similarly, lex source files can be used to generate C or C++; the |
| extensions ‘.l’, ‘.ll’, ‘.l++’, ‘.lxx’, and ‘.lpp’ are recognized. |
| |
| You should never explicitly mention the intermediate (C or C++) file |
| in any ‘SOURCES’ variable; only list the source file. |
| |
| The intermediate files generated by ‘yacc’ (or ‘lex’) will be |
| included in any distribution that is made. That way the user doesn’t |
| need to have ‘yacc’ or ‘lex’. |
| |
| If a ‘yacc’ source file is seen, then your ‘configure.ac’ must define |
| the variable ‘YACC’. This is most easily done by invoking the macro |
| ‘AC_PROG_YACC’ (*note Particular Program Checks: (autoconf)Particular |
| Programs.). |
| |
| When ‘yacc’ is invoked, it is passed ‘AM_YFLAGS’ and ‘YFLAGS’. The |
| latter is a user variable and the former is intended for the |
| ‘Makefile.am’ author. |
| |
| ‘AM_YFLAGS’ is usually used to pass the ‘-d’ option to ‘yacc’. |
| Automake knows what this means and will automatically adjust its rules |
| to update and distribute the header file built by ‘yacc -d’(1). What |
| Automake cannot guess, though, is where this header will be used: it is |
| up to you to ensure the header gets built before it is first used. |
| Typically this is necessary in order for dependency tracking to work |
| when the header is included by another file. The common solution is |
| listing the header file in ‘BUILT_SOURCES’ (*note Sources::) as follows. |
| |
| BUILT_SOURCES = parser.h |
| AM_YFLAGS = -d |
| bin_PROGRAMS = foo |
| foo_SOURCES = … parser.y … |
| |
| If a ‘lex’ source file is seen, then your ‘configure.ac’ must define |
| the variable ‘LEX’. You can use ‘AC_PROG_LEX’ to do this (*note |
| Particular Program Checks: (autoconf)Particular Programs.), but using |
| ‘AM_PROG_LEX’ macro (*note Macros::) is recommended. |
| |
| When ‘lex’ is invoked, it is passed ‘AM_LFLAGS’ and ‘LFLAGS’. The |
| latter is a user variable and the former is intended for the |
| ‘Makefile.am’ author. |
| |
| When ‘AM_MAINTAINER_MODE’ (*note maintainer-mode::) is used, the |
| rebuild rule for distributed Yacc and Lex sources are only used when |
| ‘maintainer-mode’ is enabled, or when the files have been erased. |
| |
| When ‘lex’ or ‘yacc’ sources are used, ‘automake -a’ automatically |
| installs an auxiliary program called ‘ylwrap’ in your package (*note |
| Auxiliary Programs::). This program is used by the build rules to |
| rename the output of these tools, and makes it possible to include |
| multiple ‘yacc’ (or ‘lex’) source files in a single directory. (This is |
| necessary because yacc’s output file name is fixed, and a parallel make |
| could conceivably invoke more than one instance of ‘yacc’ |
| simultaneously.) |
| |
| For ‘yacc’, simply managing locking is insufficient. The output of |
| ‘yacc’ always uses the same symbol names internally, so it isn’t |
| possible to link two ‘yacc’ parsers into the same executable. |
| |
| We recommend using the following renaming hack used in ‘gdb’: |
| #define yymaxdepth c_maxdepth |
| #define yyparse c_parse |
| #define yylex c_lex |
| #define yyerror c_error |
| #define yylval c_lval |
| #define yychar c_char |
| #define yydebug c_debug |
| #define yypact c_pact |
| #define yyr1 c_r1 |
| #define yyr2 c_r2 |
| #define yydef c_def |
| #define yychk c_chk |
| #define yypgo c_pgo |
| #define yyact c_act |
| #define yyexca c_exca |
| #define yyerrflag c_errflag |
| #define yynerrs c_nerrs |
| #define yyps c_ps |
| #define yypv c_pv |
| #define yys c_s |
| #define yy_yys c_yys |
| #define yystate c_state |
| #define yytmp c_tmp |
| #define yyv c_v |
| #define yy_yyv c_yyv |
| #define yyval c_val |
| #define yylloc c_lloc |
| #define yyreds c_reds |
| #define yytoks c_toks |
| #define yylhs c_yylhs |
| #define yylen c_yylen |
| #define yydefred c_yydefred |
| #define yydgoto c_yydgoto |
| #define yysindex c_yysindex |
| #define yyrindex c_yyrindex |
| #define yygindex c_yygindex |
| #define yytable c_yytable |
| #define yycheck c_yycheck |
| #define yyname c_yyname |
| #define yyrule c_yyrule |
| |
| For each define, replace the ‘c_’ prefix with whatever you like. |
| These defines work for ‘bison’, ‘byacc’, and traditional ‘yacc’s. If |
| you find a parser generator that uses a symbol not covered here, please |
| report the new name so it can be added to the list. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Please note that ‘automake’ recognizes ‘-d’ in ‘AM_YFLAGS’ only |
| if it is not clustered with other options; for example, it won’t be |
| recognized if ‘AM_YFLAGS’ is ‘-dt’, but it will be if ‘AM_YFLAGS’ is ‘-d |
| -t’ or ‘-t -d’. |
| |
| |
| File: automake.info, Node: C++ Support, Next: Objective C Support, Prev: Yacc and Lex, Up: Programs |
| |
| 8.9 C++ Support |
| =============== |
| |
| Automake includes full support for C++. |
| |
| Any package including C++ code must define the output variable ‘CXX’ |
| in ‘configure.ac’; the simplest way to do this is to use the |
| ‘AC_PROG_CXX’ macro (*note Particular Program Checks: |
| (autoconf)Particular Programs.). |
| |
| A few additional variables are defined when a C++ source file is |
| seen: |
| |
| ‘CXX’ |
| The name of the C++ compiler. |
| |
| ‘CXXFLAGS’ |
| Any flags to pass to the C++ compiler. |
| |
| ‘AM_CXXFLAGS’ |
| The maintainer’s variant of ‘CXXFLAGS’. |
| |
| ‘CXXCOMPILE’ |
| The command used to actually compile a C++ source file. The file |
| name is appended to form the complete command line. |
| |
| ‘CXXLINK’ |
| The command used to actually link a C++ program. |
| |
| |
| File: automake.info, Node: Objective C Support, Next: Objective C++ Support, Prev: C++ Support, Up: Programs |
| |
| 8.10 Objective C Support |
| ======================== |
| |
| Automake includes some support for Objective C. |
| |
| Any package including Objective C code must define the output |
| variable ‘OBJC’ in ‘configure.ac’; the simplest way to do this is to use |
| the ‘AC_PROG_OBJC’ macro (*note Particular Program Checks: |
| (autoconf)Particular Programs.). |
| |
| A few additional variables are defined when an Objective C source |
| file is seen: |
| |
| ‘OBJC’ |
| The name of the Objective C compiler. |
| |
| ‘OBJCFLAGS’ |
| Any flags to pass to the Objective C compiler. |
| |
| ‘AM_OBJCFLAGS’ |
| The maintainer’s variant of ‘OBJCFLAGS’. |
| |
| ‘OBJCCOMPILE’ |
| The command used to actually compile an Objective C source file. |
| The file name is appended to form the complete command line. |
| |
| ‘OBJCLINK’ |
| The command used to actually link an Objective C program. |
| |
| |
| File: automake.info, Node: Objective C++ Support, Next: Unified Parallel C Support, Prev: Objective C Support, Up: Programs |
| |
| 8.11 Objective C++ Support |
| ========================== |
| |
| Automake includes some support for Objective C++. |
| |
| Any package including Objective C++ code must define the output |
| variable ‘OBJCXX’ in ‘configure.ac’; the simplest way to do this is to |
| use the ‘AC_PROG_OBJCXX’ macro (*note Particular Program Checks: |
| (autoconf)Particular Programs.). |
| |
| A few additional variables are defined when an Objective C++ source |
| file is seen: |
| |
| ‘OBJCXX’ |
| The name of the Objective C++ compiler. |
| |
| ‘OBJCXXFLAGS’ |
| Any flags to pass to the Objective C++ compiler. |
| |
| ‘AM_OBJCXXFLAGS’ |
| The maintainer’s variant of ‘OBJCXXFLAGS’. |
| |
| ‘OBJCXXCOMPILE’ |
| The command used to actually compile an Objective C++ source file. |
| The file name is appended to form the complete command line. |
| |
| ‘OBJCXXLINK’ |
| The command used to actually link an Objective C++ program. |
| |
| |
| File: automake.info, Node: Unified Parallel C Support, Next: Assembly Support, Prev: Objective C++ Support, Up: Programs |
| |
| 8.12 Unified Parallel C Support |
| =============================== |
| |
| Automake includes some support for Unified Parallel C. |
| |
| Any package including Unified Parallel C code must define the output |
| variable ‘UPC’ in ‘configure.ac’; the simplest way to do this is to use |
| the ‘AM_PROG_UPC’ macro (*note Public Macros::). |
| |
| A few additional variables are defined when a Unified Parallel C |
| source file is seen: |
| |
| ‘UPC’ |
| The name of the Unified Parallel C compiler. |
| |
| ‘UPCFLAGS’ |
| Any flags to pass to the Unified Parallel C compiler. |
| |
| ‘AM_UPCFLAGS’ |
| The maintainer’s variant of ‘UPCFLAGS’. |
| |
| ‘UPCCOMPILE’ |
| The command used to actually compile a Unified Parallel C source |
| file. The file name is appended to form the complete command line. |
| |
| ‘UPCLINK’ |
| The command used to actually link a Unified Parallel C program. |
| |
| |
| File: automake.info, Node: Assembly Support, Next: Fortran 77 Support, Prev: Unified Parallel C Support, Up: Programs |
| |
| 8.13 Assembly Support |
| ===================== |
| |
| Automake includes some support for assembly code. There are two forms |
| of assembler files: normal (‘*.s’) and preprocessed by ‘CPP’ (‘*.S’ or |
| ‘*.sx’). |
| |
| The variable ‘CCAS’ holds the name of the compiler used to build |
| assembly code. This compiler must work a bit like a C compiler; in |
| particular it must accept ‘-c’ and ‘-o’. The values of ‘CCASFLAGS’ and |
| ‘AM_CCASFLAGS’ (or its per-target definition) is passed to the |
| compilation. For preprocessed files, ‘DEFS’, ‘DEFAULT_INCLUDES’, |
| ‘INCLUDES’, ‘CPPFLAGS’ and ‘AM_CPPFLAGS’ are also used. |
| |
| The autoconf macro ‘AM_PROG_AS’ will define ‘CCAS’ and ‘CCASFLAGS’ |
| for you (unless they are already set, it simply sets ‘CCAS’ to the C |
| compiler and ‘CCASFLAGS’ to the C compiler flags), but you are free to |
| define these variables by other means. |
| |
| Only the suffixes ‘.s’, ‘.S’, and ‘.sx’ are recognized by ‘automake’ |
| as being files containing assembly code. |
| |
| |
| File: automake.info, Node: Fortran 77 Support, Next: Fortran 9x Support, Prev: Assembly Support, Up: Programs |
| |
| 8.14 Fortran 77 Support |
| ======================= |
| |
| Automake includes full support for Fortran 77. |
| |
| Any package including Fortran 77 code must define the output variable |
| ‘F77’ in ‘configure.ac’; the simplest way to do this is to use the |
| ‘AC_PROG_F77’ macro (*note Particular Program Checks: |
| (autoconf)Particular Programs.). |
| |
| A few additional variables are defined when a Fortran 77 source file |
| is seen: |
| |
| ‘F77’ |
| The name of the Fortran 77 compiler. |
| |
| ‘FFLAGS’ |
| Any flags to pass to the Fortran 77 compiler. |
| |
| ‘AM_FFLAGS’ |
| The maintainer’s variant of ‘FFLAGS’. |
| |
| ‘RFLAGS’ |
| Any flags to pass to the Ratfor compiler. |
| |
| ‘AM_RFLAGS’ |
| The maintainer’s variant of ‘RFLAGS’. |
| |
| ‘F77COMPILE’ |
| The command used to actually compile a Fortran 77 source file. The |
| file name is appended to form the complete command line. |
| |
| ‘FLINK’ |
| The command used to actually link a pure Fortran 77 program or |
| shared library. |
| |
| Automake can handle preprocessing Fortran 77 and Ratfor source files |
| in addition to compiling them(1). Automake also contains some support |
| for creating programs and shared libraries that are a mixture of Fortran |
| 77 and other languages (*note Mixing Fortran 77 With C and C++::). |
| |
| These issues are covered in the following sections. |
| |
| * Menu: |
| |
| * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources |
| * Compiling Fortran 77 Files:: Compiling Fortran 77 sources |
| * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++ |
| |
| ---------- Footnotes ---------- |
| |
| (1) Much, if not most, of the information in the following sections |
| pertaining to preprocessing Fortran 77 programs was taken almost |
| verbatim from *note Catalogue of Rules: (make)Catalogue of Rules. |
| |
| |
| File: automake.info, Node: Preprocessing Fortran 77, Next: Compiling Fortran 77 Files, Up: Fortran 77 Support |
| |
| 8.14.1 Preprocessing Fortran 77 |
| ------------------------------- |
| |
| ‘N.f’ is made automatically from ‘N.F’ or ‘N.r’. This rule runs just |
| the preprocessor to convert a preprocessable Fortran 77 or Ratfor source |
| file into a strict Fortran 77 source file. The precise command used is |
| as follows: |
| |
| ‘.F’ |
| ‘$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) |
| $(AM_FFLAGS) $(FFLAGS)’ |
| |
| ‘.r’ |
| ‘$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)’ |
| |
| |
| File: automake.info, Node: Compiling Fortran 77 Files, Next: Mixing Fortran 77 With C and C++, Prev: Preprocessing Fortran 77, Up: Fortran 77 Support |
| |
| 8.14.2 Compiling Fortran 77 Files |
| --------------------------------- |
| |
| ‘N.o’ is made automatically from ‘N.f’, ‘N.F’ or ‘N.r’ by running the |
| Fortran 77 compiler. The precise command used is as follows: |
| |
| ‘.f’ |
| ‘$(F77) -c $(AM_FFLAGS) $(FFLAGS)’ |
| |
| ‘.F’ |
| ‘$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) |
| $(AM_FFLAGS) $(FFLAGS)’ |
| |
| ‘.r’ |
| ‘$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)’ |
| |
| |
| File: automake.info, Node: Mixing Fortran 77 With C and C++, Prev: Compiling Fortran 77 Files, Up: Fortran 77 Support |
| |
| 8.14.3 Mixing Fortran 77 With C and C++ |
| --------------------------------------- |
| |
| Automake currently provides _limited_ support for creating programs and |
| shared libraries that are a mixture of Fortran 77 and C and/or C++. |
| However, there are many other issues related to mixing Fortran 77 with |
| other languages that are _not_ (currently) handled by Automake, but that |
| are handled by other packages(1). |
| |
| Automake can help in two ways: |
| |
| 1. Automatic selection of the linker depending on which combinations |
| of source code. |
| |
| 2. Automatic selection of the appropriate linker flags (e.g., ‘-L’ and |
| ‘-l’) to pass to the automatically selected linker in order to link |
| in the appropriate Fortran 77 intrinsic and run-time libraries. |
| |
| These extra Fortran 77 linker flags are supplied in the output |
| variable ‘FLIBS’ by the ‘AC_F77_LIBRARY_LDFLAGS’ Autoconf macro. |
| *Note Fortran Compiler Characteristics: (autoconf)Fortran Compiler. |
| |
| If Automake detects that a program or shared library (as mentioned in |
| some ‘_PROGRAMS’ or ‘_LTLIBRARIES’ primary) contains source code that is |
| a mixture of Fortran 77 and C and/or C++, then it requires that the |
| macro ‘AC_F77_LIBRARY_LDFLAGS’ be called in ‘configure.ac’, and that |
| either ‘$(FLIBS)’ appear in the appropriate ‘_LDADD’ (for programs) or |
| ‘_LIBADD’ (for shared libraries) variables. It is the responsibility of |
| the person writing the ‘Makefile.am’ to make sure that ‘$(FLIBS)’ |
| appears in the appropriate ‘_LDADD’ or ‘_LIBADD’ variable. |
| |
| For example, consider the following ‘Makefile.am’: |
| |
| bin_PROGRAMS = foo |
| foo_SOURCES = main.cc foo.f |
| foo_LDADD = libfoo.la $(FLIBS) |
| |
| pkglib_LTLIBRARIES = libfoo.la |
| libfoo_la_SOURCES = bar.f baz.c zardoz.cc |
| libfoo_la_LIBADD = $(FLIBS) |
| |
| In this case, Automake will insist that ‘AC_F77_LIBRARY_LDFLAGS’ is |
| mentioned in ‘configure.ac’. Also, if ‘$(FLIBS)’ hadn’t been mentioned |
| in ‘foo_LDADD’ and ‘libfoo_la_LIBADD’, then Automake would have issued a |
| warning. |
| |
| * Menu: |
| |
| * How the Linker is Chosen:: Automatic linker selection |
| |
| ---------- Footnotes ---------- |
| |
| (1) For example, the cfortran package |
| (http://www-zeus.desy.de/~burow/cfortran/) addresses all of these |
| inter-language issues, and runs under nearly all Fortran 77, C and C++ |
| compilers on nearly all platforms. However, ‘cfortran’ is not yet Free |
| Software, but it will be in the next major release. |
| |
| |
| File: automake.info, Node: How the Linker is Chosen, Up: Mixing Fortran 77 With C and C++ |
| |
| 8.14.3.1 How the Linker is Chosen |
| ................................. |
| |
| When a program or library mixes several languages, Automake choose the |
| linker according to the following priorities. (The names in parentheses |
| are the variables containing the link command.) |
| |
| 1. Native Java (‘GCJLINK’) |
| 2. Objective C++ (‘OBJCXXLINK’) |
| 3. C++ (‘CXXLINK’) |
| 4. Fortran 77 (‘F77LINK’) |
| 5. Fortran (‘FCLINK’) |
| 6. Objective C (‘OBJCLINK’) |
| 7. Unified Parallel C (‘UPCLINK’) |
| 8. C (‘LINK’) |
| |
| For example, if Fortran 77, C and C++ source code is compiled into a |
| program, then the C++ linker will be used. In this case, if the C or |
| Fortran 77 linkers required any special libraries that weren’t included |
| by the C++ linker, then they must be manually added to an ‘_LDADD’ or |
| ‘_LIBADD’ variable by the user writing the ‘Makefile.am’. |
| |
| Automake only looks at the file names listed in ‘_SOURCES’ variables |
| to choose the linker, and defaults to the C linker. Sometimes this is |
| inconvenient because you are linking against a library written in |
| another language and would like to set the linker more appropriately. |
| *Note Libtool Convenience Libraries::, for a trick with |
| ‘nodist_EXTRA_…_SOURCES’. |
| |
| A per-target ‘_LINK’ variable will override the above selection. |
| Per-target link flags will cause Automake to write a per-target ‘_LINK’ |
| variable according to the language chosen as above. |
| |
| |
| File: automake.info, Node: Fortran 9x Support, Next: Java Support with gcj, Prev: Fortran 77 Support, Up: Programs |
| |
| 8.15 Fortran 9x Support |
| ======================= |
| |
| Automake includes support for Fortran 9x. |
| |
| Any package including Fortran 9x code must define the output variable |
| ‘FC’ in ‘configure.ac’; the simplest way to do this is to use the |
| ‘AC_PROG_FC’ macro (*note Particular Program Checks: |
| (autoconf)Particular Programs.). |
| |
| A few additional variables are defined when a Fortran 9x source file |
| is seen: |
| |
| ‘FC’ |
| The name of the Fortran 9x compiler. |
| |
| ‘FCFLAGS’ |
| Any flags to pass to the Fortran 9x compiler. |
| |
| ‘AM_FCFLAGS’ |
| The maintainer’s variant of ‘FCFLAGS’. |
| |
| ‘FCCOMPILE’ |
| The command used to actually compile a Fortran 9x source file. The |
| file name is appended to form the complete command line. |
| |
| ‘FCLINK’ |
| The command used to actually link a pure Fortran 9x program or |
| shared library. |
| |
| * Menu: |
| |
| * Compiling Fortran 9x Files:: Compiling Fortran 9x sources |
| |
| |
| File: automake.info, Node: Compiling Fortran 9x Files, Up: Fortran 9x Support |
| |
| 8.15.1 Compiling Fortran 9x Files |
| --------------------------------- |
| |
| ‘FILE.o’ is made automatically from ‘FILE.f90’, ‘FILE.f95’, ‘FILE.f03’, |
| or ‘FILE.f08’ by running the Fortran 9x compiler. The precise command |
| used is as follows: |
| |
| ‘.f90’ |
| ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<’ |
| |
| ‘.f95’ |
| ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<’ |
| |
| ‘.f03’ |
| ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<’ |
| |
| ‘.f08’ |
| ‘$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<’ |
| |
| |
| File: automake.info, Node: Java Support with gcj, Next: Vala Support, Prev: Fortran 9x Support, Up: Programs |
| |
| 8.16 Compiling Java sources using gcj |
| ===================================== |
| |
| Automake includes support for natively compiled Java, using ‘gcj’, the |
| Java front end to the GNU Compiler Collection (rudimentary support for |
| compiling Java to bytecode using the ‘javac’ compiler is also present, |
| _albeit deprecated_; *note Java::). |
| |
| Any package including Java code to be compiled must define the output |
| variable ‘GCJ’ in ‘configure.ac’; the variable ‘GCJFLAGS’ must also be |
| defined somehow (either in ‘configure.ac’ or ‘Makefile.am’). The |
| simplest way to do this is to use the ‘AM_PROG_GCJ’ macro. |
| |
| By default, programs including Java source files are linked with |
| ‘gcj’. |
| |
| As always, the contents of ‘AM_GCJFLAGS’ are passed to every |
| compilation invoking ‘gcj’ (in its role as an ahead-of-time compiler, |
| when invoking it to create ‘.class’ files, ‘AM_JAVACFLAGS’ is used |
| instead). If it is necessary to pass options to ‘gcj’ from |
| ‘Makefile.am’, this variable, and not the user variable ‘GCJFLAGS’, |
| should be used. |
| |
| ‘gcj’ can be used to compile ‘.java’, ‘.class’, ‘.zip’, or ‘.jar’ |
| files. |
| |
| When linking, ‘gcj’ requires that the main class be specified using |
| the ‘--main=’ option. The easiest way to do this is to use the |
| ‘_LDFLAGS’ variable for the program. |
| |
| |
| File: automake.info, Node: Vala Support, Next: Support for Other Languages, Prev: Java Support with gcj, Up: Programs |
| |
| 8.17 Vala Support |
| ================= |
| |
| Automake provides initial support for Vala |
| (<http://www.vala-project.org/>). This requires valac version 0.7.0 or |
| later, and currently requires the user to use GNU ‘make’. |
| |
| foo_SOURCES = foo.vala bar.vala zardoc.c |
| |
| Any ‘.vala’ file listed in a ‘_SOURCES’ variable will be compiled |
| into C code by the Vala compiler. The generated ‘.c’ files are |
| distributed. The end user does not need to have a Vala compiler |
| installed. |
| |
| Automake ships with an Autoconf macro called ‘AM_PROG_VALAC’ that |
| will locate the Vala compiler and optionally check its version number. |
| |
| -- Macro: AM_PROG_VALAC ([MINIMUM-VERSION], [ACTION-IF-FOUND], |
| [ACTION-IF-NOT-FOUND]) Search for a Vala compiler in ‘PATH’. If it |
| is found, the variable ‘VALAC’ is set to point to it (see below for |
| more details). This macro takes three optional arguments. The |
| first argument, if present, is the minimum version of the Vala |
| compiler required to compile this package. If a compiler is found |
| and satisfies MINIMUM-VERSION, then ACTION-IF-FOUND is run (this |
| defaults to do nothing). Otherwise, ACTION-IF-NOT-FOUND is run. |
| If ACTION-IF-NOT-FOUND is not specified, the default value is to |
| print a warning in case no compiler is found, or if a too-old |
| version of the compiler is found. |
| |
| There are a few variables that are used when compiling Vala sources: |
| |
| ‘VALAC’ |
| Absolute path to the Vala compiler, or simply ‘valac’ if no |
| suitable compiler Vala could be found at configure runtime. |
| |
| ‘VALAFLAGS’ |
| Additional arguments for the Vala compiler. |
| |
| ‘AM_VALAFLAGS’ |
| The maintainer’s variant of ‘VALAFLAGS’. |
| |
| lib_LTLIBRARIES = libfoo.la |
| libfoo_la_SOURCES = foo.vala |
| |
| Note that currently, you cannot use per-target ‘*_VALAFLAGS’ (*note |
| Renamed Objects::) to produce different C files from one Vala source |
| file. |
| |
| |
| File: automake.info, Node: Support for Other Languages, Next: Dependencies, Prev: Vala Support, Up: Programs |
| |
| 8.18 Support for Other Languages |
| ================================ |
| |
| Automake currently only includes full support for C, C++ (*note C++ |
| Support::), Objective C (*note Objective C Support::), Objective C++ |
| (*note Objective C++ Support::), Fortran 77 (*note Fortran 77 |
| Support::), Fortran 9x (*note Fortran 9x Support::), and Java (*note |
| Java Support with gcj::). There is only rudimentary support for other |
| languages, support for which will be improved based on user demand. |
| |
| Some limited support for adding your own languages is available via |
| the suffix rule handling (*note Suffixes::). |
| |
| |
| File: automake.info, Node: Dependencies, Next: EXEEXT, Prev: Support for Other Languages, Up: Programs |
| |
| 8.19 Automatic dependency tracking |
| ================================== |
| |
| As a developer it is often painful to continually update the |
| ‘Makefile.am’ whenever the include-file dependencies change in a |
| project. Automake supplies a way to automatically track dependency |
| changes (*note Dependency Tracking::). |
| |
| Automake always uses complete dependencies for a compilation, |
| including system headers. Automake’s model is that dependency |
| computation should be a side effect of the build. To this end, |
| dependencies are computed by running all compilations through a special |
| wrapper program called ‘depcomp’. ‘depcomp’ understands how to coax |
| many different C and C++ compilers into generating dependency |
| information in the format it requires. ‘automake -a’ will install |
| ‘depcomp’ into your source tree for you. If ‘depcomp’ can’t figure out |
| how to properly invoke your compiler, dependency tracking will simply be |
| disabled for your build. |
| |
| Experience with earlier versions of Automake (*note Dependency |
| Tracking Evolution: (automake-history)Dependency Tracking Evolution.) |
| taught us that it is not reliable to generate dependencies only on the |
| maintainer’s system, as configurations vary too much. So instead |
| Automake implements dependency tracking at build time. |
| |
| Automatic dependency tracking can be suppressed by putting |
| ‘no-dependencies’ in the variable ‘AUTOMAKE_OPTIONS’, or passing |
| ‘no-dependencies’ as an argument to ‘AM_INIT_AUTOMAKE’ (this should be |
| the preferred way). Or, you can invoke ‘automake’ with the ‘-i’ option. |
| Dependency tracking is enabled by default. |
| |
| The person building your package also can choose to disable |
| dependency tracking by configuring with ‘--disable-dependency-tracking’. |
| |
| |
| File: automake.info, Node: EXEEXT, Prev: Dependencies, Up: Programs |
| |
| 8.20 Support for executable extensions |
| ====================================== |
| |
| On some platforms, such as Windows, executables are expected to have an |
| extension such as ‘.exe’. On these platforms, some compilers (GCC among |
| them) will automatically generate ‘foo.exe’ when asked to generate |
| ‘foo’. |
| |
| Automake provides mostly-transparent support for this. Unfortunately |
| _mostly_ doesn’t yet mean _fully_. Until the English dictionary is |
| revised, you will have to assist Automake if your package must support |
| those platforms. |
| |
| One thing you must be aware of is that, internally, Automake rewrites |
| something like this: |
| |
| bin_PROGRAMS = liver |
| |
| to this: |
| |
| bin_PROGRAMS = liver$(EXEEXT) |
| |
| The targets Automake generates are likewise given the ‘$(EXEEXT)’ |
| extension. |
| |
| The variables ‘TESTS’ and ‘XFAIL_TESTS’ (*note Simple Tests::) are |
| also rewritten if they contain filenames that have been declared as |
| programs in the same ‘Makefile’. (This is mostly useful when some |
| programs from ‘check_PROGRAMS’ are listed in ‘TESTS’.) |
| |
| However, Automake cannot apply this rewriting to ‘configure’ |
| substitutions. This means that if you are conditionally building a |
| program using such a substitution, then your ‘configure.ac’ must take |
| care to add ‘$(EXEEXT)’ when constructing the output variable. |
| |
| Sometimes maintainers like to write an explicit link rule for their |
| program. Without executable extension support, this is easy—you simply |
| write a rule whose target is the name of the program. However, when |
| executable extension support is enabled, you must instead add the |
| ‘$(EXEEXT)’ suffix. |
| |
| This might be a nuisance for maintainers who know their package will |
| never run on a platform that has executable extensions. For those |
| maintainers, the ‘no-exeext’ option (*note Options::) will disable this |
| feature. This works in a fairly ugly way; if ‘no-exeext’ is seen, then |
| the presence of a rule for a target named ‘foo’ in ‘Makefile.am’ will |
| override an ‘automake’-generated rule for ‘foo$(EXEEXT)’. Without the |
| ‘no-exeext’ option, this use will give a diagnostic. |
| |
| |
| File: automake.info, Node: Other Objects, Next: Other GNU Tools, Prev: Programs, Up: Top |
| |
| 9 Other Derived Objects |
| *********************** |
| |
| Automake can handle derived objects that are not C programs. Sometimes |
| the support for actually building such objects must be explicitly |
| supplied, but Automake will still automatically handle installation and |
| distribution. |
| |
| * Menu: |
| |
| * Scripts:: Executable scripts |
| * Headers:: Header files |
| * Data:: Architecture-independent data files |
| * Sources:: Derived sources |
| |
| |
| File: automake.info, Node: Scripts, Next: Headers, Up: Other Objects |
| |
| 9.1 Executable Scripts |
| ====================== |
| |
| It is possible to define and install programs that are scripts. Such |
| programs are listed using the ‘SCRIPTS’ primary name. When the script |
| is distributed in its final, installable form, the ‘Makefile’ usually |
| looks as follows: |
| |
| # Install my_script in $(bindir) and distribute it. |
| dist_bin_SCRIPTS = my_script |
| |
| Scripts are not distributed by default; as we have just seen, those |
| that should be distributed can be specified using a ‘dist_’ prefix as |
| with other primaries. |
| |
| Scripts can be installed in ‘bindir’, ‘sbindir’, ‘libexecdir’, |
| ‘pkglibexecdir’, or ‘pkgdatadir’. |
| |
| Scripts that need not be installed can be listed in ‘noinst_SCRIPTS’, |
| and among them, those which are needed only by ‘make check’ should go in |
| ‘check_SCRIPTS’. |
| |
| When a script needs to be built, the ‘Makefile.am’ should include the |
| appropriate rules. For instance the ‘automake’ program itself is a Perl |
| script that is generated from ‘automake.in’. Here is how this is |
| handled: |
| |
| bin_SCRIPTS = automake |
| CLEANFILES = $(bin_SCRIPTS) |
| EXTRA_DIST = automake.in |
| |
| do_subst = sed -e 's,[@]datadir[@],$(datadir),g' \ |
| -e 's,[@]PERL[@],$(PERL),g' \ |
| -e 's,[@]PACKAGE[@],$(PACKAGE),g' \ |
| -e 's,[@]VERSION[@],$(VERSION),g' \ |
| … |
| |
| automake: automake.in Makefile |
| $(do_subst) < $(srcdir)/automake.in > automake |
| chmod +x automake |
| |
| Such scripts for which a build rule has been supplied need to be |
| deleted explicitly using ‘CLEANFILES’ (*note Clean::), and their sources |
| have to be distributed, usually with ‘EXTRA_DIST’ (*note Basics of |
| Distribution::). |
| |
| Another common way to build scripts is to process them from |
| ‘configure’ with ‘AC_CONFIG_FILES’. In this situation Automake knows |
| which files should be cleaned and distributed, and what the rebuild |
| rules should look like. |
| |
| For instance if ‘configure.ac’ contains |
| |
| AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script]) |
| |
| to build ‘src/my_script’ from ‘src/my_script.in’, then a |
| ‘src/Makefile.am’ to install this script in ‘$(bindir)’ can be as simple |
| as |
| |
| bin_SCRIPTS = my_script |
| CLEANFILES = $(bin_SCRIPTS) |
| |
| There is no need for ‘EXTRA_DIST’ or any build rule: Automake infers |
| them from ‘AC_CONFIG_FILES’ (*note Requirements::). ‘CLEANFILES’ is |
| still useful, because by default Automake will clean targets of |
| ‘AC_CONFIG_FILES’ in ‘distclean’, not ‘clean’. |
| |
| Although this looks simpler, building scripts this way has one |
| drawback: directory variables such as ‘$(datadir)’ are not fully |
| expanded and may refer to other directory variables. |
| |
| |
| File: automake.info, Node: Headers, Next: Data, Prev: Scripts, Up: Other Objects |
| |
| 9.2 Header files |
| ================ |
| |
| Header files that must be installed are specified by the ‘HEADERS’ |
| family of variables. Headers can be installed in ‘includedir’, |
| ‘oldincludedir’, ‘pkgincludedir’ or any other directory you may have |
| defined (*note Uniform::). For instance, |
| |
| include_HEADERS = foo.h bar/bar.h |
| |
| will install the two files as ‘$(includedir)/foo.h’ and |
| ‘$(includedir)/bar.h’. |
| |
| The ‘nobase_’ prefix is also supported, |
| |
| nobase_include_HEADERS = foo.h bar/bar.h |
| |
| will install the two files as ‘$(includedir)/foo.h’ and |
| ‘$(includedir)/bar/bar.h’ (*note Alternative::). |
| |
| Usually, only header files that accompany installed libraries need to |
| be installed. Headers used by programs or convenience libraries are not |
| installed. The ‘noinst_HEADERS’ variable can be used for such headers. |
| However when the header actually belongs to a single convenience library |
| or program, we recommend listing it in the program’s or library’s |
| ‘_SOURCES’ variable (*note Program Sources::) instead of in |
| ‘noinst_HEADERS’. This is clearer for the ‘Makefile.am’ reader. |
| ‘noinst_HEADERS’ would be the right variable to use in a directory |
| containing only headers and no associated library or program. |
| |
| All header files must be listed somewhere; in a ‘_SOURCES’ variable |
| or in a ‘_HEADERS’ variable. Missing ones will not appear in the |
| distribution. |
| |
| For header files that are built and must not be distributed, use the |
| ‘nodist_’ prefix as in ‘nodist_include_HEADERS’ or |
| ‘nodist_prog_SOURCES’. If these generated headers are needed during the |
| build, you must also ensure they exist before they are used (*note |
| Sources::). |
| |
| |
| File: automake.info, Node: Data, Next: Sources, Prev: Headers, Up: Other Objects |
| |
| 9.3 Architecture-independent data files |
| ======================================= |
| |
| Automake supports the installation of miscellaneous data files using the |
| ‘DATA’ family of variables. |
| |
| Such data can be installed in the directories ‘datadir’, |
| ‘sysconfdir’, ‘sharedstatedir’, ‘localstatedir’, or ‘pkgdatadir’. |
| |
| By default, data files are _not_ included in a distribution. Of |
| course, you can use the ‘dist_’ prefix to change this on a per-variable |
| basis. |
| |
| Here is how Automake declares its auxiliary data files: |
| |
| dist_pkgdata_DATA = clean-kr.am clean.am … |
| |
| |
| File: automake.info, Node: Sources, Prev: Data, Up: Other Objects |
| |
| 9.4 Built Sources |
| ================= |
| |
| Because Automake’s automatic dependency tracking works as a side-effect |
| of compilation (*note Dependencies::) there is a bootstrap issue: a |
| target should not be compiled before its dependencies are made, but |
| these dependencies are unknown until the target is first compiled. |
| |
| Ordinarily this is not a problem, because dependencies are |
| distributed sources: they preexist and do not need to be built. Suppose |
| that ‘foo.c’ includes ‘foo.h’. When it first compiles ‘foo.o’, ‘make’ |
| only knows that ‘foo.o’ depends on ‘foo.c’. As a side-effect of this |
| compilation ‘depcomp’ records the ‘foo.h’ dependency so that following |
| invocations of ‘make’ will honor it. In these conditions, it’s clear |
| there is no problem: either ‘foo.o’ doesn’t exist and has to be built |
| (regardless of the dependencies), or accurate dependencies exist and |
| they can be used to decide whether ‘foo.o’ should be rebuilt. |
| |
| It’s a different story if ‘foo.h’ doesn’t exist by the first ‘make’ |
| run. For instance, there might be a rule to build ‘foo.h’. This time |
| ‘file.o’’s build will fail because the compiler can’t find ‘foo.h’. |
| ‘make’ failed to trigger the rule to build ‘foo.h’ first by lack of |
| dependency information. |
| |
| The ‘BUILT_SOURCES’ variable is a workaround for this problem. A |
| source file listed in ‘BUILT_SOURCES’ is made on ‘make all’ or ‘make |
| check’ (or even ‘make install’) before other targets are processed. |
| However, such a source file is not _compiled_ unless explicitly |
| requested by mentioning it in some other ‘_SOURCES’ variable. |
| |
| So, to conclude our introductory example, we could use ‘BUILT_SOURCES |
| = foo.h’ to ensure ‘foo.h’ gets built before any other target (including |
| ‘foo.o’) during ‘make all’ or ‘make check’. |
| |
| ‘BUILT_SOURCES’ is actually a bit of a misnomer, as any file which |
| must be created early in the build process can be listed in this |
| variable. Moreover, all built sources do not necessarily have to be |
| listed in ‘BUILT_SOURCES’. For instance, a generated ‘.c’ file doesn’t |
| need to appear in ‘BUILT_SOURCES’ (unless it is included by another |
| source), because it’s a known dependency of the associated object. |
| |
| It might be important to emphasize that ‘BUILT_SOURCES’ is honored |
| only by ‘make all’, ‘make check’ and ‘make install’. This means you |
| cannot build a specific target (e.g., ‘make foo’) in a clean tree if it |
| depends on a built source. However it will succeed if you have run |
| ‘make all’ earlier, because accurate dependencies are already available. |
| |
| The next section illustrates and discusses the handling of built |
| sources on a toy example. |
| |
| * Menu: |
| |
| * Built Sources Example:: Several ways to handle built sources. |
| |
| |
| File: automake.info, Node: Built Sources Example, Up: Sources |
| |
| 9.4.1 Built Sources Example |
| --------------------------- |
| |
| Suppose that ‘foo.c’ includes ‘bindir.h’, which is |
| installation-dependent and not distributed: it needs to be built. Here |
| ‘bindir.h’ defines the preprocessor macro ‘bindir’ to the value of the |
| ‘make’ variable ‘bindir’ (inherited from ‘configure’). |
| |
| We suggest several implementations below. It’s not meant to be an |
| exhaustive listing of all ways to handle built sources, but it will give |
| you a few ideas if you encounter this issue. |
| |
| First Try |
| ......... |
| |
| This first implementation will illustrate the bootstrap issue mentioned |
| in the previous section (*note Sources::). |
| |
| Here is a tentative ‘Makefile.am’. |
| |
| # This won't work. |
| bin_PROGRAMS = foo |
| foo_SOURCES = foo.c |
| nodist_foo_SOURCES = bindir.h |
| CLEANFILES = bindir.h |
| bindir.h: Makefile |
| echo '#define bindir "$(bindir)"' >$@ |
| |
| This setup doesn’t work, because Automake doesn’t know that ‘foo.c’ |
| includes ‘bindir.h’. Remember, automatic dependency tracking works as a |
| side-effect of compilation, so the dependencies of ‘foo.o’ will be known |
| only after ‘foo.o’ has been compiled (*note Dependencies::). The |
| symptom is as follows. |
| |
| % make |
| source='foo.c' object='foo.o' libtool=no \ |
| depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \ |
| depmode=gcc /bin/sh ./depcomp \ |
| gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c |
| foo.c:2: bindir.h: No such file or directory |
| make: *** [foo.o] Error 1 |
| |
| In this example ‘bindir.h’ is not distributed nor installed, and it |
| is not even being built on-time. One may wonder if the |
| ‘nodist_foo_SOURCES = bindir.h’ line has any use at all. This line |
| simply states that ‘bindir.h’ is a source of ‘foo’, so for instance, it |
| should be inspected while generating tags (*note Tags::). In other |
| words, it does not help our present problem, and the build would fail |
| identically without it. |
| |
| Using ‘BUILT_SOURCES’ |
| ..................... |
| |
| A solution is to require ‘bindir.h’ to be built before anything else. |
| This is what ‘BUILT_SOURCES’ is meant for (*note Sources::). |
| |
| bin_PROGRAMS = foo |
| foo_SOURCES = foo.c |
| nodist_foo_SOURCES = bindir.h |
| BUILT_SOURCES = bindir.h |
| CLEANFILES = bindir.h |
| bindir.h: Makefile |
| echo '#define bindir "$(bindir)"' >$@ |
| |
| See how ‘bindir.h’ gets built first: |
| |
| % make |
| echo '#define bindir "/usr/local/bin"' >bindir.h |
| make all-am |
| make[1]: Entering directory `/home/adl/tmp' |
| source='foo.c' object='foo.o' libtool=no \ |
| depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \ |
| depmode=gcc /bin/sh ./depcomp \ |
| gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c |
| gcc -g -O2 -o foo foo.o |
| make[1]: Leaving directory `/home/adl/tmp' |
| |
| However, as said earlier, ‘BUILT_SOURCES’ applies only to the ‘all’, |
| ‘check’, and ‘install’ targets. It still fails if you try to run ‘make |
| foo’ explicitly: |
| |
| % make clean |
| test -z "bindir.h" || rm -f bindir.h |
| test -z "foo" || rm -f foo |
| rm -f *.o |
| % : > .deps/foo.Po # Suppress previously recorded dependencies |
| % make foo |
| source='foo.c' object='foo.o' libtool=no \ |
| depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \ |
| depmode=gcc /bin/sh ./depcomp \ |
| gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c |
| foo.c:2: bindir.h: No such file or directory |
| make: *** [foo.o] Error 1 |
| |
| Recording Dependencies manually |
| ............................... |
| |
| Usually people are happy enough with ‘BUILT_SOURCES’ because they never |
| build targets such as ‘make foo’ before ‘make all’, as in the previous |
| example. However if this matters to you, you can avoid ‘BUILT_SOURCES’ |
| and record such dependencies explicitly in the ‘Makefile.am’. |
| |
| bin_PROGRAMS = foo |
| foo_SOURCES = foo.c |
| nodist_foo_SOURCES = bindir.h |
| foo.$(OBJEXT): bindir.h |
| CLEANFILES = bindir.h |
| bindir.h: Makefile |
| echo '#define bindir "$(bindir)"' >$@ |
| |
| You don’t have to list _all_ the dependencies of ‘foo.o’ explicitly, |
| only those that might need to be built. If a dependency already exists, |
| it will not hinder the first compilation and will be recorded by the |
| normal dependency tracking code. (Note that after this first |
| compilation the dependency tracking code will also have recorded the |
| dependency between ‘foo.o’ and ‘bindir.h’; so our explicit dependency is |
| really useful to the first build only.) |
| |
| Adding explicit dependencies like this can be a bit dangerous if you |
| are not careful enough. This is due to the way Automake tries not to |
| overwrite your rules (it assumes you know better than it). |
| ‘foo.$(OBJEXT): bindir.h’ supersedes any rule Automake may want to |
| output to build ‘foo.$(OBJEXT)’. It happens to work in this case |
| because Automake doesn’t have to output any ‘foo.$(OBJEXT):’ target: it |
| relies on a suffix rule instead (i.e., ‘.c.$(OBJEXT):’). Always check |
| the generated ‘Makefile.in’ if you do this. |
| |
| Build ‘bindir.h’ from ‘configure’ |
| ................................. |
| |
| It’s possible to define this preprocessor macro from ‘configure’, either |
| in ‘config.h’ (*note Defining Directories: (autoconf)Defining |
| Directories.), or by processing a ‘bindir.h.in’ file using |
| ‘AC_CONFIG_FILES’ (*note Configuration Actions: (autoconf)Configuration |
| Actions.). |
| |
| At this point it should be clear that building ‘bindir.h’ from |
| ‘configure’ works well for this example. ‘bindir.h’ will exist before |
| you build any target, hence will not cause any dependency issue. |
| |
| The Makefile can be shrunk as follows. We do not even have to |
| mention ‘bindir.h’. |
| |
| bin_PROGRAMS = foo |
| foo_SOURCES = foo.c |
| |
| However, it’s not always possible to build sources from ‘configure’, |
| especially when these sources are generated by a tool that needs to be |
| built first. |
| |
| Build ‘bindir.c’, not ‘bindir.h’. |
| ................................. |
| |
| Another attractive idea is to define ‘bindir’ as a variable or function |
| exported from ‘bindir.o’, and build ‘bindir.c’ instead of ‘bindir.h’. |
| |
| noinst_PROGRAMS = foo |
| foo_SOURCES = foo.c bindir.h |
| nodist_foo_SOURCES = bindir.c |
| CLEANFILES = bindir.c |
| bindir.c: Makefile |
| echo 'const char bindir[] = "$(bindir)";' >$@ |
| |
| ‘bindir.h’ contains just the variable’s declaration and doesn’t need |
| to be built, so it won’t cause any trouble. ‘bindir.o’ is always |
| dependent on ‘bindir.c’, so ‘bindir.c’ will get built first. |
| |
| Which is best? |
| .............. |
| |
| There is no panacea, of course. Each solution has its merits and |
| drawbacks. |
| |
| You cannot use ‘BUILT_SOURCES’ if the ability to run ‘make foo’ on a |
| clean tree is important to you. |
| |
| You won’t add explicit dependencies if you are leery of overriding an |
| Automake rule by mistake. |
| |
| Building files from ‘./configure’ is not always possible, neither is |
| converting ‘.h’ files into ‘.c’ files. |
| |
| |
| File: automake.info, Node: Other GNU Tools, Next: Documentation, Prev: Other Objects, Up: Top |
| |
| 10 Other GNU Tools |
| ****************** |
| |
| Since Automake is primarily intended to generate ‘Makefile.in’s for use |
| in GNU programs, it tries hard to interoperate with other GNU tools. |
| |
| * Menu: |
| |
| * Emacs Lisp:: Emacs Lisp |
| * gettext:: Gettext |
| * Libtool:: Libtool |
| * Java:: Java bytecode compilation (deprecated) |
| * Python:: Python |
| |
| |
| File: automake.info, Node: Emacs Lisp, Next: gettext, Up: Other GNU Tools |
| |
| 10.1 Emacs Lisp |
| =============== |
| |
| Automake provides some support for Emacs Lisp. The ‘LISP’ primary is |
| used to hold a list of ‘.el’ files. Possible prefixes for this primary |
| are ‘lisp_’ and ‘noinst_’. Note that if ‘lisp_LISP’ is defined, then |
| ‘configure.ac’ must run ‘AM_PATH_LISPDIR’ (*note Macros::). |
| |
| Lisp sources are not distributed by default. You can prefix the |
| ‘LISP’ primary with ‘dist_’, as in ‘dist_lisp_LISP’ or |
| ‘dist_noinst_LISP’, to indicate that these files should be distributed. |
| |
| Automake will byte-compile all Emacs Lisp source files using the |
| Emacs found by ‘AM_PATH_LISPDIR’, if any was found. When performing |
| such byte-compilation, the flags specified in the (developer-reserved) |
| ‘AM_ELCFLAGS’ and (user-reserved) ‘ELCFLAGS’ make variables will be |
| passed to the Emacs invocation. |
| |
| Byte-compiled Emacs Lisp files are not portable among all versions of |
| Emacs, so it makes sense to turn this off if you expect sites to have |
| more than one version of Emacs installed. Furthermore, many packages |
| don’t actually benefit from byte-compilation. Still, we recommend that |
| you byte-compile your Emacs Lisp sources. It is probably better for |
| sites with strange setups to cope for themselves than to make the |
| installation less nice for everybody else. |
| |
| There are two ways to avoid byte-compiling. Historically, we have |
| recommended the following construct. |
| |
| lisp_LISP = file1.el file2.el |
| ELCFILES = |
| |
| ‘ELCFILES’ is an internal Automake variable that normally lists all |
| ‘.elc’ files that must be byte-compiled. Automake defines ‘ELCFILES’ |
| automatically from ‘lisp_LISP’. Emptying this variable explicitly |
| prevents byte-compilation. |
| |
| Since Automake 1.8, we now recommend using ‘lisp_DATA’ instead: |
| |
| lisp_DATA = file1.el file2.el |
| |
| Note that these two constructs are not equivalent. ‘_LISP’ will not |
| install a file if Emacs is not installed, while ‘_DATA’ will always |
| install its files. |
| |
| |
| File: automake.info, Node: gettext, Next: Libtool, Prev: Emacs Lisp, Up: Other GNU Tools |
| |
| 10.2 Gettext |
| ============ |
| |
| If ‘AM_GNU_GETTEXT’ is seen in ‘configure.ac’, then Automake turns on |
| support for GNU gettext, a message catalog system for |
| internationalization (*note Introduction: (gettext)Top.). |
| |
| The ‘gettext’ support in Automake requires the addition of one or two |
| subdirectories to the package: ‘po’ and possibly also ‘intl’. The |
| latter is needed if ‘AM_GNU_GETTEXT’ is not invoked with the ‘external’ |
| argument, or if ‘AM_GNU_GETTEXT_INTL_SUBDIR’ is used. Automake ensures |
| that these directories exist and are mentioned in ‘SUBDIRS’. |
| |
| |
| File: automake.info, Node: Libtool, Next: Java, Prev: gettext, Up: Other GNU Tools |
| |
| 10.3 Libtool |
| ============ |
| |
| Automake provides support for GNU Libtool (*note Introduction: |
| (libtool)Top.) with the ‘LTLIBRARIES’ primary. *Note A Shared |
| Library::. |
| |
| |
| File: automake.info, Node: Java, Next: Python, Prev: Libtool, Up: Other GNU Tools |
| |
| 10.4 Java bytecode compilation (deprecated) |
| =========================================== |
| |
| Automake provides some minimal support for Java bytecode compilation |
| with the ‘JAVA’ primary (in addition to the support for compiling Java |
| to native machine code; *note Java Support with gcj::). Note however |
| that _the interface and most features described here are deprecated_. |
| Future Automake releases will strive to provide a better and cleaner |
| interface, which however _won’t be backward-compatible_; the present |
| interface will probably be removed altogether some time after the |
| introduction of the new interface (if that ever materializes). In any |
| case, the current ‘JAVA’ primary features are frozen and will no longer |
| be developed, not even to take bug fixes. |
| |
| Any ‘.java’ files listed in a ‘_JAVA’ variable will be compiled with |
| ‘JAVAC’ at build time. By default, ‘.java’ files are not included in |
| the distribution, you should use the ‘dist_’ prefix to distribute them. |
| |
| Here is a typical setup for distributing ‘.java’ files and installing |
| the ‘.class’ files resulting from their compilation. |
| |
| javadir = $(datadir)/java |
| dist_java_JAVA = a.java b.java … |
| |
| Currently Automake enforces the restriction that only one ‘_JAVA’ |
| primary can be used in a given ‘Makefile.am’. The reason for this |
| restriction is that, in general, it isn’t possible to know which |
| ‘.class’ files were generated from which ‘.java’ files, so it would be |
| impossible to know which files to install where. For instance, a |
| ‘.java’ file can define multiple classes; the resulting ‘.class’ file |
| names cannot be predicted without parsing the ‘.java’ file. |
| |
| There are a few variables that are used when compiling Java sources: |
| |
| ‘JAVAC’ |
| The name of the Java compiler. This defaults to ‘javac’. |
| |
| ‘JAVACFLAGS’ |
| The flags to pass to the compiler. This is considered to be a user |
| variable (*note User Variables::). |
| |
| ‘AM_JAVACFLAGS’ |
| More flags to pass to the Java compiler. This, and not |
| ‘JAVACFLAGS’, should be used when it is necessary to put Java |
| compiler flags into ‘Makefile.am’. |
| |
| ‘JAVAROOT’ |
| The value of this variable is passed to the ‘-d’ option to ‘javac’. |
| It defaults to ‘$(top_builddir)’. |
| |
| ‘CLASSPATH_ENV’ |
| This variable is a shell expression that is used to set the |
| ‘CLASSPATH’ environment variable on the ‘javac’ command line. (In |
| the future we will probably handle class path setting differently.) |
| |
| |
| File: automake.info, Node: Python, Prev: Java, Up: Other GNU Tools |
| |
| 10.5 Python |
| =========== |
| |
| Automake provides support for Python compilation with the ‘PYTHON’ |
| primary. A typical setup is to call ‘AM_PATH_PYTHON’ in ‘configure.ac’ |
| and use a line like the following in ‘Makefile.am’: |
| |
| python_PYTHON = tree.py leave.py |
| |
| Any files listed in a ‘_PYTHON’ variable will be byte-compiled with |
| ‘py-compile’ at install time. ‘py-compile’ actually creates both |
| standard (‘.pyc’) and optimized (‘.pyo’) byte-compiled versions of the |
| source files. Note that because byte-compilation occurs at install |
| time, any files listed in ‘noinst_PYTHON’ will not be compiled. Python |
| source files are included in the distribution by default, prepend |
| ‘nodist_’ (as in ‘nodist_python_PYTHON’) to omit them. |
| |
| Automake ships with an Autoconf macro called ‘AM_PATH_PYTHON’ that |
| will determine some Python-related directory variables (see below). If |
| you have called ‘AM_PATH_PYTHON’ from ‘configure.ac’, then you may use |
| the variables ‘python_PYTHON’ or ‘pkgpython_PYTHON’ to list Python |
| source files in your ‘Makefile.am’, depending on where you want your |
| files installed (see the definitions of ‘pythondir’ and ‘pkgpythondir’ |
| below). |
| |
| -- Macro: AM_PATH_PYTHON ([VERSION], [ACTION-IF-FOUND], |
| [ACTION-IF-NOT-FOUND]) |
| |
| Search for a Python interpreter on the system. This macro takes |
| three optional arguments. The first argument, if present, is the |
| minimum version of Python required for this package: |
| ‘AM_PATH_PYTHON’ will skip any Python interpreter that is older |
| than VERSION. If an interpreter is found and satisfies VERSION, |
| then ACTION-IF-FOUND is run. Otherwise, ACTION-IF-NOT-FOUND is |
| run. |
| |
| If ACTION-IF-NOT-FOUND is not specified, as in the following |
| example, the default is to abort ‘configure’. |
| |
| AM_PATH_PYTHON([2.2]) |
| |
| This is fine when Python is an absolute requirement for the |
| package. If Python >= 2.5 was only _optional_ to the package, |
| ‘AM_PATH_PYTHON’ could be called as follows. |
| |
| AM_PATH_PYTHON([2.5],, [:]) |
| |
| If the ‘PYTHON’ variable is set when ‘AM_PATH_PYTHON’ is called, |
| then that will be the only Python interpreter that is tried. |
| |
| ‘AM_PATH_PYTHON’ creates the following output variables based on |
| the Python installation found during configuration. |
| |
| ‘PYTHON’ |
| The name of the Python executable, or ‘:’ if no suitable |
| interpreter could be found. |
| |
| Assuming ACTION-IF-NOT-FOUND is used (otherwise ‘./configure’ will |
| abort if Python is absent), the value of ‘PYTHON’ can be used to |
| setup a conditional in order to disable the relevant part of a |
| build as follows. |
| |
| AM_PATH_PYTHON(,, [:]) |
| AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :]) |
| |
| ‘PYTHON_VERSION’ |
| The Python version number, in the form MAJOR.MINOR (e.g., ‘2.5’). |
| This is currently the value of ‘sys.version[:3]’. |
| |
| ‘PYTHON_PREFIX’ |
| The string ‘${prefix}’. This term may be used in future work that |
| needs the contents of Python’s ‘sys.prefix’, but general consensus |
| is to always use the value from ‘configure’. |
| |
| ‘PYTHON_EXEC_PREFIX’ |
| The string ‘${exec_prefix}’. This term may be used in future work |
| that needs the contents of Python’s ‘sys.exec_prefix’, but general |
| consensus is to always use the value from ‘configure’. |
| |
| ‘PYTHON_PLATFORM’ |
| The canonical name used by Python to describe the operating system, |
| as given by ‘sys.platform’. This value is sometimes needed when |
| building Python extensions. |
| |
| ‘pythondir’ |
| The directory name for the ‘site-packages’ subdirectory of the |
| standard Python install tree. |
| |
| ‘pkgpythondir’ |
| This is the directory under ‘pythondir’ that is named after the |
| package. That is, it is ‘$(pythondir)/$(PACKAGE)’. It is provided |
| as a convenience. |
| |
| ‘pyexecdir’ |
| This is the directory where Python extension modules (shared |
| libraries) should be installed. An extension module written in C |
| could be declared as follows to Automake: |
| |
| pyexec_LTLIBRARIES = quaternion.la |
| quaternion_la_SOURCES = quaternion.c support.c support.h |
| quaternion_la_LDFLAGS = -avoid-version -module |
| |
| ‘pkgpyexecdir’ |
| This is a convenience variable that is defined as |
| ‘$(pyexecdir)/$(PACKAGE)’. |
| |
| All of these directory variables have values that start with either |
| ‘${prefix}’ or ‘${exec_prefix}’ unexpanded. This works fine in |
| ‘Makefiles’, but it makes these variables hard to use in ‘configure’. |
| This is mandated by the GNU coding standards, so that the user can run |
| ‘make prefix=/foo install’. The Autoconf manual has a section with more |
| details on this topic (*note Installation Directory Variables: |
| (autoconf)Installation Directory Variables.). See also *note Hard-Coded |
| Install Paths::. |
| |
| |
| File: automake.info, Node: Documentation, Next: Install, Prev: Other GNU Tools, Up: Top |
| |
| 11 Building documentation |
| ************************* |
| |
| Currently Automake provides support for Texinfo and man pages. |
| |
| * Menu: |
| |
| * Texinfo:: Texinfo |
| * Man Pages:: Man pages |
| |
| |
| File: automake.info, Node: Texinfo, Next: Man Pages, Up: Documentation |
| |
| 11.1 Texinfo |
| ============ |
| |
| If the current directory contains Texinfo source, you must declare it |
| with the ‘TEXINFOS’ primary. Generally Texinfo files are converted into |
| info, and thus the ‘info_TEXINFOS’ variable is most commonly used here. |
| Any Texinfo source file should have the ‘.texi’ extension. Automake |
| also accepts ‘.txi’ or ‘.texinfo’ extensions, but their use is |
| discouraged now, and will elicit runtime warnings. |
| |
| Automake generates rules to build ‘.info’, ‘.dvi’, ‘.ps’, ‘.pdf’ and |
| ‘.html’ files from your Texinfo sources. Following the GNU Coding |
| Standards, only the ‘.info’ files are built by ‘make all’ and installed |
| by ‘make install’ (unless you use ‘no-installinfo’, see below). |
| Furthermore, ‘.info’ files are automatically distributed so that Texinfo |
| is not a prerequisite for installing your package. |
| |
| It is worth noting that, contrary to what happens with the other |
| formats, the generated ‘.info’ files are by default placed in ‘srcdir’ |
| rather than in the ‘builddir’. This can be changed with the |
| ‘info-in-builddir’ option. |
| |
| Other documentation formats can be built on request by ‘make dvi’, |
| ‘make ps’, ‘make pdf’ and ‘make html’, and they can be installed with |
| ‘make install-dvi’, ‘make install-ps’, ‘make install-pdf’ and ‘make |
| install-html’ explicitly. ‘make uninstall’ will remove everything: the |
| Texinfo documentation installed by default as well as all the above |
| optional formats. |
| |
| All of these targets can be extended using ‘-local’ rules (*note |
| Extending::). |
| |
| If the ‘.texi’ file ‘@include’s ‘version.texi’, then that file will |
| be automatically generated. The file ‘version.texi’ defines four |
| Texinfo flags you can reference using ‘@value{EDITION}’, |
| ‘@value{VERSION}’, ‘@value{UPDATED}’, and ‘@value{UPDATED-MONTH}’. |
| |
| ‘EDITION’ |
| ‘VERSION’ |
| Both of these flags hold the version number of your program. They |
| are kept separate for clarity. |
| |
| ‘UPDATED’ |
| This holds the date the primary ‘.texi’ file was last modified. |
| |
| ‘UPDATED-MONTH’ |
| This holds the name of the month in which the primary ‘.texi’ file |
| was last modified. |
| |
| The ‘version.texi’ support requires the ‘mdate-sh’ script; this |
| script is supplied with Automake and automatically included when |
| ‘automake’ is invoked with the ‘--add-missing’ option. |
| |
| If you have multiple Texinfo files, and you want to use the |
| ‘version.texi’ feature, then you have to have a separate version file |
| for each Texinfo file. Automake will treat any include in a Texinfo |
| file that matches ‘vers*.texi’ just as an automatically generated |
| version file. |
| |
| Sometimes an info file actually depends on more than one ‘.texi’ |
| file. For instance, in GNU Hello, ‘hello.texi’ includes the file |
| ‘fdl.texi’. You can tell Automake about these dependencies using the |
| ‘TEXI_TEXINFOS’ variable. Here is how GNU Hello does it: |
| |
| info_TEXINFOS = hello.texi |
| hello_TEXINFOS = fdl.texi |
| |
| By default, Automake requires the file ‘texinfo.tex’ to appear in the |
| same directory as the ‘Makefile.am’ file that lists the ‘.texi’ files. |
| If you used ‘AC_CONFIG_AUX_DIR’ in ‘configure.ac’ (*note Finding |
| ‘configure’ Input: (autoconf)Input.), then ‘texinfo.tex’ is looked for |
| there. In both cases, ‘automake’ then supplies ‘texinfo.tex’ if |
| ‘--add-missing’ is given, and takes care of its distribution. However, |
| if you set the ‘TEXINFO_TEX’ variable (see below), it overrides the |
| location of the file and turns off its installation into the source as |
| well as its distribution. |
| |
| The option ‘no-texinfo.tex’ can be used to eliminate the requirement |
| for the file ‘texinfo.tex’. Use of the variable ‘TEXINFO_TEX’ is |
| preferable, however, because that allows the ‘dvi’, ‘ps’, and ‘pdf’ |
| targets to still work. |
| |
| Automake generates an ‘install-info’ rule; some people apparently use |
| this. By default, info pages are installed by ‘make install’, so |
| running ‘make install-info’ is pointless. This can be prevented via the |
| ‘no-installinfo’ option. In this case, ‘.info’ files are not installed |
| by default, and user must request this explicitly using ‘make |
| install-info’. |
| |
| By default, ‘make install-info’ and ‘make uninstall-info’ will try to |
| run the ‘install-info’ program (if available) to update (or |
| create/remove) the ‘${infodir}/dir’ index. If this is undesired, it can |
| be prevented by exporting the ‘AM_UPDATE_INFO_DIR’ variable to "‘no’". |
| |
| The following variables are used by the Texinfo build rules. |
| |
| ‘MAKEINFO’ |
| The name of the program invoked to build ‘.info’ files. This |
| variable is defined by Automake. If the ‘makeinfo’ program is |
| found on the system then it will be used by default; otherwise |
| ‘missing’ will be used instead. |
| |
| ‘MAKEINFOHTML’ |
| The command invoked to build ‘.html’ files. Automake defines this |
| to ‘$(MAKEINFO) --html’. |
| |
| ‘MAKEINFOFLAGS’ |
| User flags passed to each invocation of ‘$(MAKEINFO)’ and |
| ‘$(MAKEINFOHTML)’. This user variable (*note User Variables::) is |
| not expected to be defined in any ‘Makefile’; it can be used by |
| users to pass extra flags to suit their needs. |
| |
| ‘AM_MAKEINFOFLAGS’ |
| ‘AM_MAKEINFOHTMLFLAGS’ |
| Maintainer flags passed to each ‘makeinfo’ invocation. Unlike |
| ‘MAKEINFOFLAGS’, these variables are meant to be defined by |
| maintainers in ‘Makefile.am’. ‘$(AM_MAKEINFOFLAGS)’ is passed to |
| ‘makeinfo’ when building ‘.info’ files; and |
| ‘$(AM_MAKEINFOHTMLFLAGS)’ is used when building ‘.html’ files. |
| |
| For instance, the following setting can be used to obtain one |
| single ‘.html’ file per manual, without node separators. |
| AM_MAKEINFOHTMLFLAGS = --no-headers --no-split |
| |
| ‘AM_MAKEINFOHTMLFLAGS’ defaults to ‘$(AM_MAKEINFOFLAGS)’. This |
| means that defining ‘AM_MAKEINFOFLAGS’ without defining |
| ‘AM_MAKEINFOHTMLFLAGS’ will impact builds of both ‘.info’ and |
| ‘.html’ files. |
| |
| ‘TEXI2DVI’ |
| The name of the command that converts a ‘.texi’ file into a ‘.dvi’ |
| file. This defaults to ‘texi2dvi’, a script that ships with the |
| Texinfo package. |
| |
| ‘TEXI2PDF’ |
| The name of the command that translates a ‘.texi’ file into a |
| ‘.pdf’ file. This defaults to ‘$(TEXI2DVI) --pdf --batch’. |
| |
| ‘DVIPS’ |
| The name of the command that builds a ‘.ps’ file out of a ‘.dvi’ |
| file. This defaults to ‘dvips’. |
| |
| ‘TEXINFO_TEX’ |
| |
| If your package has Texinfo files in many directories, you can use |
| the variable ‘TEXINFO_TEX’ to tell Automake where to find the |
| canonical ‘texinfo.tex’ for your package. The value of this |
| variable should be the relative path from the current ‘Makefile.am’ |
| to ‘texinfo.tex’: |
| |
| TEXINFO_TEX = ../doc/texinfo.tex |
| |
| |
| File: automake.info, Node: Man Pages, Prev: Texinfo, Up: Documentation |
| |
| 11.2 Man Pages |
| ============== |
| |
| A package can also include man pages (but see the GNU standards on this |
| matter, *note (standards)Man Pages::.) Man pages are declared using the |
| ‘MANS’ primary. Generally the ‘man_MANS’ variable is used. Man pages |
| are automatically installed in the correct subdirectory of ‘mandir’, |
| based on the file extension. |
| |
| File extensions such as ‘.1c’ are handled by looking for the valid |
| part of the extension and using that to determine the correct |
| subdirectory of ‘mandir’. Valid section names are the digits ‘0’ |
| through ‘9’, and the letters ‘l’ and ‘n’. |
| |
| Sometimes developers prefer to name a man page something like |
| ‘foo.man’ in the source, and then rename it to have the correct suffix, |
| for example ‘foo.1’, when installing the file. Automake also supports |
| this mode. For a valid section named SECTION, there is a corresponding |
| directory named ‘manSECTIONdir’, and a corresponding ‘_MANS’ variable. |
| Files listed in such a variable are installed in the indicated section. |
| If the file already has a valid suffix, then it is installed as-is; |
| otherwise the file suffix is changed to match the section. |
| |
| For instance, consider this example: |
| man1_MANS = rename.man thesame.1 alsothesame.1c |
| |
| In this case, ‘rename.man’ will be renamed to ‘rename.1’ when installed, |
| but the other files will keep their names. |
| |
| By default, man pages are installed by ‘make install’. However, |
| since the GNU project does not require man pages, many maintainers do |
| not expend effort to keep the man pages up to date. In these cases, the |
| ‘no-installman’ option will prevent the man pages from being installed |
| by default. The user can still explicitly install them via ‘make |
| install-man’. |
| |
| For fast installation, with many files it is preferable to use |
| ‘manSECTION_MANS’ over ‘man_MANS’ as well as files that do not need to |
| be renamed. |
| |
| Man pages are not currently considered to be source, because it is |
| not uncommon for man pages to be automatically generated. Therefore |
| they are not automatically included in the distribution. However, this |
| can be changed by use of the ‘dist_’ prefix. For instance here is how |
| to distribute and install the two man pages of GNU ‘cpio’ (which |
| includes both Texinfo documentation and man pages): |
| |
| dist_man_MANS = cpio.1 mt.1 |
| |
| The ‘nobase_’ prefix is meaningless for man pages and is disallowed. |
| |
| Executables and manpages may be renamed upon installation (*note |
| Renaming::). For manpages this can be avoided by use of the ‘notrans_’ |
| prefix. For instance, suppose an executable ‘foo’ allowing to access a |
| library function ‘foo’ from the command line. The way to avoid renaming |
| of the ‘foo.3’ manpage is: |
| |
| man_MANS = foo.1 |
| notrans_man_MANS = foo.3 |
| |
| ‘notrans_’ must be specified first when used in conjunction with |
| either ‘dist_’ or ‘nodist_’ (*note Fine-grained Distribution Control::). |
| For instance: |
| |
| notrans_dist_man3_MANS = bar.3 |
| |
| |
| File: automake.info, Node: Install, Next: Clean, Prev: Documentation, Up: Top |
| |
| 12 What Gets Installed |
| ********************** |
| |
| Naturally, Automake handles the details of actually installing your |
| program once it has been built. All files named by the various |
| primaries are automatically installed in the appropriate places when the |
| user runs ‘make install’. |
| |
| * Menu: |
| |
| * Basics of Installation:: What gets installed where |
| * The Two Parts of Install:: Installing data and programs separately |
| * Extending Installation:: Adding your own rules for installation |
| * Staged Installs:: Installation in a temporary location |
| * Install Rules for the User:: Useful additional rules |
| |
| |
| File: automake.info, Node: Basics of Installation, Next: The Two Parts of Install, Up: Install |
| |
| 12.1 Basics of Installation |
| =========================== |
| |
| A file named in a primary is installed by copying the built file into |
| the appropriate directory. The base name of the file is used when |
| installing. |
| |
| bin_PROGRAMS = hello subdir/goodbye |
| |
| In this example, both ‘hello’ and ‘goodbye’ will be installed in |
| ‘$(bindir)’. |
| |
| Sometimes it is useful to avoid the basename step at install time. |
| For instance, you might have a number of header files in subdirectories |
| of the source tree that are laid out precisely how you want to install |
| them. In this situation you can use the ‘nobase_’ prefix to suppress |
| the base name step. For example: |
| |
| nobase_include_HEADERS = stdio.h sys/types.h |
| |
| will install ‘stdio.h’ in ‘$(includedir)’ and ‘types.h’ in |
| ‘$(includedir)/sys’. |
| |
| For most file types, Automake will install multiple files at once, |
| while avoiding command line length issues (*note Length Limitations::). |
| Since some ‘install’ programs will not install the same file twice in |
| one invocation, you may need to ensure that file lists are unique within |
| one variable such as ‘nobase_include_HEADERS’ above. |
| |
| You should not rely on the order in which files listed in one |
| variable are installed. Likewise, to cater for parallel make, you |
| should not rely on any particular file installation order even among |
| different file types (library dependencies are an exception here). |
| |
| |
| File: automake.info, Node: The Two Parts of Install, Next: Extending Installation, Prev: Basics of Installation, Up: Install |
| |
| 12.2 The Two Parts of Install |
| ============================= |
| |
| Automake generates separate ‘install-data’ and ‘install-exec’ rules, in |
| case the installer is installing on multiple machines that share |
| directory structure—these targets allow the machine-independent parts to |
| be installed only once. ‘install-exec’ installs platform-dependent |
| files, and ‘install-data’ installs platform-independent files. The |
| ‘install’ target depends on both of these targets. While Automake tries |
| to automatically segregate objects into the correct category, the |
| ‘Makefile.am’ author is, in the end, responsible for making sure this is |
| done correctly. |
| |
| Variables using the standard directory prefixes ‘data’, ‘info’, |
| ‘man’, ‘include’, ‘oldinclude’, ‘pkgdata’, or ‘pkginclude’ are installed |
| by ‘install-data’. |
| |
| Variables using the standard directory prefixes ‘bin’, ‘sbin’, |
| ‘libexec’, ‘sysconf’, ‘localstate’, ‘lib’, or ‘pkglib’ are installed by |
| ‘install-exec’. |
| |
| For instance, ‘data_DATA’ files are installed by ‘install-data’, |
| while ‘bin_PROGRAMS’ files are installed by ‘install-exec’. |
| |
| Any variable using a user-defined directory prefix with ‘exec’ in the |
| name (e.g., ‘myexecbin_PROGRAMS’) is installed by ‘install-exec’. All |
| other user-defined prefixes are installed by ‘install-data’. |
| |
| |
| File: automake.info, Node: Extending Installation, Next: Staged Installs, Prev: The Two Parts of Install, Up: Install |
| |
| 12.3 Extending Installation |
| =========================== |
| |
| It is possible to extend this mechanism by defining an |
| ‘install-exec-local’ or ‘install-data-local’ rule. If these rules |
| exist, they will be run at ‘make install’ time. These rules can do |
| almost anything; care is required. |
| |
| Automake also supports two install hooks, ‘install-exec-hook’ and |
| ‘install-data-hook’. These hooks are run after all other install rules |
| of the appropriate type, exec or data, have completed. So, for |
| instance, it is possible to perform post-installation modifications |
| using an install hook. *Note Extending::, for some examples. |
| |