"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/automake.info-1" between
automake-1.16.2.tar.xz and automake-1.16.3.tar.xz

About: GNU Automake is a Makefile generator (input Makefile.am, output Makefile.in; intended for use with autoconf).

automake.info-1  (automake-1.16.2.tar.xz):automake.info-1  (automake-1.16.3.tar.xz)
File: automake.info, Node: Top, Next: Introduction, Up: (dir) File: automake.info, Node: Top, Next: Introduction, Up: (dir)
GNU Automake GNU Automake
************ ************
This manual is for GNU Automake (version 1.16.2, 1 February 2020), a This manual is for GNU Automake (version 1.16.3, 19 November 2020), a
program that creates GNU standards-compliant Makefiles from template program that creates GNU standards-compliant Makefiles from template
files. files.
Copyright © 1995–2020 Free Software Foundation, Inc. Copyright © 1995–2020 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover texts, Foundation; with no Invariant Sections, with no Front-Cover texts,
and with no Back-Cover Texts. A copy of the license is included in and with no Back-Cover Texts. A copy of the license is included in
skipping to change at line 42 skipping to change at line 42
* Install:: What gets installed * Install:: What gets installed
* Clean:: What gets cleaned * Clean:: What gets cleaned
* Dist:: What goes in a distribution * Dist:: What goes in a distribution
* Tests:: Support for test suites * Tests:: Support for test suites
* Rebuilding:: Automatic rebuilding of Makefile * Rebuilding:: Automatic rebuilding of Makefile
* Options:: Changing Automake’s behavior * Options:: Changing Automake’s behavior
* Miscellaneous:: Miscellaneous rules * Miscellaneous:: Miscellaneous rules
* Include:: Including extra files in an Automake template * Include:: Including extra files in an Automake template
* Conditionals:: Conditionals * Conditionals:: Conditionals
* Silencing Make:: Obtain less verbose output from ‘make’ * Silencing Make:: Obtain less verbose output from ‘make’
* Gnits:: The effect of ‘--gnu’ and ‘--gnits’
* Not Enough:: When Automake is not Enough * Not Enough:: When Automake is not Enough
* Distributing:: Distributing the Makefile.in * Distributing:: Distributing the Makefile.in
* API Versioning:: About compatibility between Automake versions * API Versioning:: About compatibility between Automake versions
* Upgrading:: Upgrading to a Newer Automake Version * Upgrading:: Upgrading to a Newer Automake Version
* FAQ:: Frequently Asked Questions * FAQ:: Frequently Asked Questions
* Copying This Manual:: How to make copies of this manual * Copying This Manual:: How to make copies of this manual
* Indices:: Indices of variables, macros, and concepts * Indices:: Indices of variables, macros, and concepts
— The Detailed Node Listing — — The Detailed Node Listing —
skipping to change at line 374 skipping to change at line 373
‘Makefile.am’, ‘aclocal.m4’, ..., some of them claiming to be _generated ‘Makefile.am’, ‘aclocal.m4’, ..., some of them claiming to be _generated
by_ Autoconf or Automake. But the exact purpose of these files and by_ Autoconf or Automake. But the exact purpose of these files and
their relations is probably fuzzy. The goal of this chapter is to 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 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 powerful it is. If you’ve never installed or seen such a package, do
not worry: this chapter will walk you through it. not worry: this chapter will walk you through it.
If you need some teaching material, more illustrations, or a less If you need some teaching material, more illustrations, or a less
‘automake’-centered continuation, some slides for this introduction are ‘automake’-centered continuation, some slides for this introduction are
available in Alexandre Duret-Lutz’s Autotools Tutorial available in Alexandre Duret-Lutz’s Autotools Tutorial
(http://www.lrde.epita.fr/~adl/autotools.html). This chapter is the (https://www.lrde.epita.fr/~adl/autotools.html). This chapter is the
written version of the first part of his tutorial. written version of the first part of his tutorial.
* Menu: * Menu:
* GNU Build System:: Introducing the GNU Build System * GNU Build System:: Introducing the GNU Build System
* Use Cases:: Use Cases for the GNU Build System * Use Cases:: Use Cases for the GNU Build System
* Why Autotools:: How Autotools Help * Why Autotools:: How Autotools Help
* Hello World:: A Small Hello World Package * Hello World:: A Small Hello World Package
File: automake.info, Node: GNU Build System, Next: Use Cases, Up: Autotools I ntroduction File: automake.info, Node: GNU Build System, Next: Use Cases, Up: Autotools I ntroduction
skipping to change at line 1015 skipping to change at line 1014
We have already mentioned ‘make dist’. This target collects all your We have already mentioned ‘make dist’. This target collects all your
source files and the necessary parts of the build system to create a source files and the necessary parts of the build system to create a
tarball named ‘PACKAGE-VERSION.tar.gz’. tarball named ‘PACKAGE-VERSION.tar.gz’.
Another, more useful command is ‘make distcheck’. The ‘distcheck’ Another, more useful command is ‘make distcheck’. The ‘distcheck’
target constructs ‘PACKAGE-VERSION.tar.gz’ just as well as ‘dist’, but 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 additionally ensures most of the use cases presented so far work:
• It attempts a full compilation of the package (*note Basic • It attempts a full compilation of the package (*note Basic
Installation::), unpacking the newly constructed tarball, running Installation::): unpacking the newly constructed tarball, running
‘make’, ‘make check’, ‘make install’, as well as ‘make ‘make’, ‘make dvi’, ‘make check’, ‘make install’, as well as ‘make
installcheck’, and even ‘make dist’, installcheck’, and even ‘make dist’,
• it tests VPATH builds with read-only source tree (*note VPATH • it tests VPATH builds with read-only source tree (*note VPATH
Builds::), Builds::),
• it makes sure ‘make clean’, ‘make distclean’, and ‘make uninstall’ • it makes sure ‘make clean’, ‘make distclean’, and ‘make uninstall’
do not omit any file (*note Standard Targets::), do not omit any file (*note Standard Targets::),
• and it checks that ‘DESTDIR’ installations work (*note DESTDIR::). • and it checks that ‘DESTDIR’ installations work (*note DESTDIR::).
All of these actions are performed in a temporary directory, so that All of these actions are performed in a temporary directory, so that
no root privileges are required. Please note that the exact location no root privileges are required. The exact location and the exact
and the exact structure of such a subdirectory (where the extracted structure of such a subdirectory (where the extracted sources are
sources are placed, how the temporary build and install directories are placed, how the temporary build and install directories are named and
named and how deeply they are nested, etc.) is to be considered an how deeply they are nested, etc.) is to be considered an implementation
implementation detail, which can change at any time; so do not rely on detail, which can change at any time; so do not rely on it.
it.
Releasing a package that fails ‘make distcheck’ means that one of the Releasing a package that fails ‘make distcheck’ means that one of the
scenarios we presented will not work and some users will be scenarios we presented will not work and some users will be
disappointed. Therefore it is a good practice to release a package only disappointed. Therefore it is a good practice to release a package only
after a successful ‘make distcheck’. This of course does not imply that 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 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 embarrassing errors you may find in packages released by people who have
never heard about ‘distcheck’ (like ‘DESTDIR’ not working because of a never heard about ‘distcheck’ (like ‘DESTDIR’ not working because of a
typo, or a distributed file being erased by ‘make clean’, or even typo, or a distributed file being erased by ‘make clean’, or even
‘VPATH’ builds not working). ‘VPATH’ builds not working).
skipping to change at line 1577 skipping to change at line 1575
File: automake.info, Node: Strictness, Next: Uniform, Prev: General Operation , Up: Generalities File: automake.info, Node: Strictness, Next: Uniform, Prev: General Operation , Up: Generalities
3.2 Strictness 3.2 Strictness
============== ==============
While Automake is intended to be used by maintainers of GNU packages, it 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 does make some effort to accommodate those who wish to use it, but do
not want to use all the GNU conventions. not want to use all the GNU conventions.
To this end, Automake supports three levels of “strictness”—the To this end, Automake supports three levels of “strictness”—how
strictness indicating how stringently Automake should check standards stringently Automake should enforce conformance with GNU conventions.
conformance. Each strictness level can be selected using an option of the same name;
see *note Options::.
The valid strictness levels are: The strictness levels are:
‘gnu’
This is the default level of strictness. Automake will check for
basic compliance with the GNU standards for software packaging.
*Note (standards)Top:: for full details of these standards.
Currently the following checks are made:
• The files ‘INSTALL’, ‘NEWS’, ‘README’, ‘AUTHORS’, and
‘ChangeLog’, plus one of ‘COPYING.LIB’, ‘COPYING.LESSER’ or
‘COPYING’, are required at the topmost directory of the
package.
If the ‘--add-missing’ option is given, ‘automake’ will add a
generic version of the ‘INSTALL’ file as well as the ‘COPYING’
file containing the text of the current version of the GNU
General Public License existing at the time of this Automake
release (version 3 as this is written,
<https://www.gnu.org/copyleft/gpl.html>). However, an
existing ‘COPYING’ file will never be overwritten by
‘automake’.
• The options ‘no-installman’ and ‘no-installinfo’ are
prohibited.
Future versions of Automake will add more checks at this level of
strictness; it is advisable to be familiar with the precise
requirements of the GNU standards.
Future versions of Automake may, at this level of strictness,
require certain non-standard GNU tools to be available to
maintainer-only Makefile rules. For instance, in the future
‘pathchk’ (*note (coreutils)pathchk invocation::) may be required
to run ‘make dist’.
‘foreign’ ‘foreign’
Automake will check for only those things that are absolutely Automake will check for only those things that are absolutely
required for proper operation. For instance, whereas GNU standards required for proper operation. For instance, whereas GNU standards
dictate the existence of a ‘NEWS’ file, it will not be required in dictate the existence of a ‘NEWS’ file, it will not be required in
this mode. This strictness will also turn off some warnings by this mode. This strictness will also turn off some warnings by
default (among them, portability warnings). The name comes from default (among them, portability warnings).
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’ ‘gnits’
Automake will check for compliance to the as-yet-unwritten “Gnits Automake will check for compliance to the as-yet-unwritten “Gnits
standards”. These are based on the GNU standards, but are even standards”. These are based on the GNU standards, but are even
more detailed. Unless you are a Gnits standards contributor, it is more detailed. Unless you are a Gnits standards contributor, it is
recommended that you avoid this option until such time as the Gnits recommended that you avoid this option until such time as the Gnits
standard is actually published (which may never happen). standard is actually published (which may never happen).
*Note Gnits::, for more information on the precise implications of Currently, ‘--gnits’ does all the checks that ‘--gnu’ does, and
the strictness level. checks the following as well:
• ‘make installcheck’ will check to make sure that the ‘--help’
and ‘--version’ really print a usage message and a version
string, respectively. This is the ‘std-options’ option (*note
Options::).
• ‘make dist’ will check to make sure the ‘NEWS’ file has been
updated to the current version.
• ‘VERSION’ is checked to make sure its format complies with
Gnits standards.
• If ‘VERSION’ indicates that this is an alpha release, and the
file ‘README-alpha’ appears in the topmost directory of a
package, then it is included in the distribution. This is
done in ‘--gnits’ mode, and no other, because this mode is the
only one where version number formats are constrained, and
hence the only mode where Automake can automatically determine
whether ‘README-alpha’ should be included.
• The file ‘THANKS’ is required.
File: automake.info, Node: Uniform, Next: Length Limitations, Prev: Strictnes s, Up: Generalities File: automake.info, Node: Uniform, Next: Length Limitations, Prev: Strictnes s, Up: Generalities
3.3 The Uniform Naming Scheme 3.3 The Uniform Naming Scheme
============================= =============================
Automake variables generally follow a “uniform naming scheme” that makes Automake variables generally follow a “uniform naming scheme” that makes
it easy to decide how programs (and other derived objects) are built, it easy to decide how programs (and other derived objects) are built,
and how they are installed. This scheme also supports ‘configure’ time and how they are installed. This scheme also supports ‘configure’ time
determination of what should be built. determination of what should be built.
skipping to change at line 1722 skipping to change at line 1769
Pages::). Pages::).
File: automake.info, Node: Length Limitations, Next: Canonicalization, Prev: Uniform, Up: Generalities File: automake.info, Node: Length Limitations, Next: Canonicalization, Prev: Uniform, Up: Generalities
3.4 Staying below the command line length limit 3.4 Staying below the command line length limit
=============================================== ===============================================
Traditionally, most unix-like systems have a length limitation for the Traditionally, most unix-like systems have a length limitation for the
command line arguments and environment contents when creating new command line arguments and environment contents when creating new
processes (see for example processes (see for example
<http://www.in-ulm.de/~mascheck/various/argmax/> for an overview on this <https://www.in-ulm.de/~mascheck/various/argmax/> for an overview on
issue), which of course also applies to commands spawned by ‘make’. 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 POSIX requires this limit to be at least 4096 bytes, and most modern
systems have quite high limits (or are unlimited). systems have quite high limits (or are unlimited).
In order to create portable Makefiles that do not trip over these In order to create portable Makefiles that do not trip over these
limits, it is necessary to keep the length of file lists bounded. limits, it is necessary to keep the length of file lists bounded.
Unfortunately, it is not possible to do so fully transparently within Unfortunately, it is not possible to do so fully transparently within
Automake, so your help may be needed. Typically, you can split long Automake, so your help may be needed. Typically, you can split long
file lists manually and use different installation directory names for file lists manually and use different installation directory names for
each list. For example, each list. For example,
skipping to change at line 1891 skipping to change at line 1938
longer installed automatically, and it should be safe to remove it. longer installed automatically, and it should be safe to remove it.
‘py-compile’ ‘py-compile’
This is used to byte-compile Python scripts. This is used to byte-compile Python scripts.
‘test-driver’ ‘test-driver’
This implements the default test driver offered by the parallel This implements the default test driver offered by the parallel
testsuite harness. testsuite harness.
‘texinfo.tex’ ‘texinfo.tex’
Not a program, this file is required for ‘make dvi’, ‘make ps’ and When Texinfo sources are in the package, this file is required for
‘make pdf’ to work when Texinfo sources are in the package. The ‘make dvi’, ‘make ps’ and ‘make pdf’. The latest version can be
latest version can be downloaded from downloaded from <https://www.gnu.org/software/texinfo/>. A working
<https://www.gnu.org/software/texinfo/>. TeX distribution, or at least a ‘tex’ program, is also required.
Furthermore, ‘make dist’ invokes ‘make dvi’, so these become
requirements for making a distribution with Texinfo sources.
‘ylwrap’ ‘ylwrap’
This program wraps ‘lex’ and ‘yacc’ to rename their output files. This program wraps ‘lex’ and ‘yacc’ to rename their output files.
It also ensures that, for instance, multiple ‘yacc’ instances can It also ensures that, for instance, multiple ‘yacc’ instances can
be invoked in a single directory in parallel. be invoked in a single directory in parallel.
File: automake.info, Node: Examples, Next: automake Invocation, Prev: General ities, Up: Top File: automake.info, Node: Examples, Next: automake Invocation, Prev: General ities, Up: Top
4 Some example packages 4 Some example packages
*********************** ***********************
skipping to change at line 2125 skipping to change at line 2174
reinstalled even if they already exist in the source tree. This reinstalled even if they already exist in the source tree. This
involves removing the file from the source tree before creating the involves removing the file from the source tree before creating the
new symlink (or, with ‘--copy’, copying the new file). new symlink (or, with ‘--copy’, copying the new file).
‘--foreign’ ‘--foreign’
Set the global strictness to ‘foreign’. For more information, see Set the global strictness to ‘foreign’. For more information, see
*note Strictness::. *note Strictness::.
‘--gnits’ ‘--gnits’
Set the global strictness to ‘gnits’. For more information, see Set the global strictness to ‘gnits’. For more information, see
*note Gnits::. *note Strictness::.
‘--gnu’ ‘--gnu’
Set the global strictness to ‘gnu’. For more information, see Set the global strictness to ‘gnu’. For more information, see
*note Gnits::. This is the default strictness. *note Strictness::. This is the default strictness.
‘--help’ ‘--help’
Print a summary of the command line options and exit. Print a summary of the command line options and exit.
‘-i’ ‘-i’
‘--ignore-deps’ ‘--ignore-deps’
This disables the dependency tracking feature in generated This disables the dependency tracking feature in generated
‘Makefile’s; see *note Dependencies::. ‘Makefile’s; see *note Dependencies::.
‘--include-deps’ ‘--include-deps’
skipping to change at line 2165 skipping to change at line 2214
future release. future release.
‘-v’ ‘-v’
‘--verbose’ ‘--verbose’
Cause Automake to print information about which files are being Cause Automake to print information about which files are being
read or created. read or created.
‘--version’ ‘--version’
Print the version number of Automake and exit. Print the version number of Automake and exit.
‘-W CATEGORY’ ‘-W CATEGORY[,CATEGORY...]’
‘--warnings=CATEGORY’ ‘--warnings=CATEGORY[,CATEGORY...]’
Output warnings falling in CATEGORY. CATEGORY can be one of: Output warnings about a CATEGORY of potential problems with the
package. CATEGORY can be any of:
‘cross’
Constructs compromising the ability to cross-compile the
package.
‘gnu’ ‘gnu’
warnings related to the GNU Coding Standards (*note Minor deviations from the GNU Coding Standards (*note
(standards)Top::). (standards)Top::).
‘obsolete’ ‘obsolete’
obsolete features or constructions Obsolete features or constructions.
‘override’ ‘override’
user redefinitions of Automake rules or variables Redefinitions of Automake rules or variables.
‘portability’ ‘portability’
portability issues (e.g., use of ‘make’ features that are Portability issues (e.g., use of ‘make’ features that are
known to be not portable) known to be not portable).
‘portability-recursive’
Recursive, or nested, Make variable expansions (‘$(foo$(x))’).
These are not universally supported, but are more portable
than the other non-portable constructs diagnosed by
‘-Wportability’. These warnings are turned on by
‘-Wportability’ but can then be turned off specifically by
‘-Wno-portability-recursive’.
‘extra-portability’ ‘extra-portability’
extra portability issues related to obscure tools. One Extra portability issues, related to rarely-used tools such as
example of such a tool is the Microsoft ‘lib’ archiver. the Microsoft ‘lib’ archiver.
‘syntax’ ‘syntax’
weird syntax, unused variables, typos Questionable syntax, unused variables, typos, etc.
‘unsupported’ ‘unsupported’
unsupported or incomplete features Unsupported or incomplete features.
‘all’ ‘all’
all the warnings Turn on all the above categories of warnings.
‘none’ ‘none’
turn off all the warnings Turn off all the above categories of warnings.
‘error’ ‘error’
treat warnings as errors Treat warnings as errors.
A category can be turned off by prefixing its name with ‘no-’. For A category can be turned off by prefixing its name with ‘no-’. For
instance, ‘-Wno-syntax’ will hide the warnings about unused instance, ‘-Wno-syntax’ will hide the warnings about unused
variables. variables.
The categories output by default are ‘obsolete’, ‘syntax’ and Warnings in the ‘gnu’, ‘obsolete’, ‘portability’, ‘syntax’, and
‘unsupported’. Additionally, ‘gnu’ and ‘portability’ are enabled ‘unsupported’ categories are turned on by default. The ‘gnu’ and
in ‘--gnu’ and ‘--gnits’ strictness. ‘portability’ categories are turned off in ‘--foreign’ strictness.
Turning off ‘portability’ will also turn off ‘extra-portability’, Turning off ‘portability’ will also turn off ‘extra-portability’,
and similarly turning on ‘extra-portability’ will also turn on and similarly turning on ‘extra-portability’ will also turn on
‘portability’. However, turning on ‘portability’ or turning off ‘portability’. However, turning on ‘portability’ or turning off
‘extra-portability’ will not affect the other category. ‘extra-portability’ will not affect the other category.
Unknown warning categories supplied as an argument to ‘-W’ will
themselves produce a warning, in the ‘unsupported’ category. This
warning is never treated as an error.
The environment variable ‘WARNINGS’ can contain a comma separated The environment variable ‘WARNINGS’ can contain a comma separated
list of categories to enable. It will be taken into account before list of categories to enable. ‘-W’ settings on the command line
the command-line switches, this way ‘-Wnone’ will also ignore any take precedence; for instance, ‘-Wnone’ also turns off any warning
warning category enabled by ‘WARNINGS’. This variable is also used categories enabled by ‘WARNINGS’.
by other tools like ‘autoconf’; unknown categories are ignored for
this reason. Unknown warning categories named in ‘WARNINGS’ are silently
ignored.
If the environment variable ‘AUTOMAKE_JOBS’ contains a positive If the environment variable ‘AUTOMAKE_JOBS’ contains a positive
number, it is taken as the maximum number of Perl threads to use in number, it is taken as the maximum number of Perl threads to use in
‘automake’ for generating multiple ‘Makefile.in’ files concurrently. ‘automake’ for generating multiple ‘Makefile.in’ files concurrently.
This is an experimental feature. This is an experimental feature.
File: automake.info, Node: configure, Next: Directories, Prev: automake Invoc ation, Up: Top File: automake.info, Node: configure, Next: Directories, Prev: automake Invoc ation, Up: Top
6 Scanning ‘configure.ac’, using ‘aclocal’ 6 Scanning ‘configure.ac’, using ‘aclocal’
****************************************** ******************************************
skipping to change at line 3307 skipping to change at line 3373
will instead invoke the ‘missing’ script, in order to give useful will instead invoke the ‘missing’ script, in order to give useful
advice to the user about the missing maintainer tool. *Note advice to the user about the missing maintainer tool. *Note
maintainer-mode::, for more information on when the ‘missing’ maintainer-mode::, for more information on when the ‘missing’
script is appropriate. script is appropriate.
‘AM_SILENT_RULES’ ‘AM_SILENT_RULES’
Control the machinery for less verbose build output (*note Automake Control the machinery for less verbose build output (*note Automake
Silent Rules::). Silent Rules::).
‘AM_WITH_DMALLOC’ ‘AM_WITH_DMALLOC’
Add support for the Dmalloc package (http://dmalloc.com/). If the Add support for the Dmalloc package (https://dmalloc.com/). If the
user runs ‘configure’ with ‘--with-dmalloc’, then define user runs ‘configure’ with ‘--with-dmalloc’, then define
‘WITH_DMALLOC’ and add ‘-ldmalloc’ to ‘LIBS’. ‘WITH_DMALLOC’ and add ‘-ldmalloc’ to ‘LIBS’.
File: automake.info, Node: Obsolete Macros, Next: Private Macros, Prev: Publi c Macros, Up: Macros File: automake.info, Node: Obsolete Macros, Next: Private Macros, Prev: Publi c Macros, Up: Macros
6.4.2 Obsolete Macros 6.4.2 Obsolete Macros
--------------------- ---------------------
Although using some of the following macros was required in past 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 releases, you should not use any of them in new code. _All these macros
skipping to change at line 3683 skipping to change at line 3749
to avoid this check is to use the ‘AC_SUBST’ method to declare to avoid this check is to use the ‘AC_SUBST’ method to declare
conditional directories; since ‘automake’ does not know the values of conditional directories; since ‘automake’ does not know the values of
‘AC_SUBST’ variables it cannot ensure the corresponding directory ‘AC_SUBST’ variables it cannot ensure the corresponding directory
exists. exists.
File: automake.info, Node: Alternative, Next: Subpackages, Prev: Conditional Subdirectories, Up: Directories File: automake.info, Node: Alternative, Next: Subpackages, Prev: Conditional Subdirectories, Up: Directories
7.3 An Alternative Approach to Subdirectories 7.3 An Alternative Approach to Subdirectories
============================================= =============================================
If you’ve ever read Peter Miller’s excellent paper, Recursive Make If you’ve ever read Peter Miller’s excellent paper, ‘Recursive Make
Considered Harmful (http://miller.emu.id.au/pmiller/books/rmch/), the Considered Harmful’, the preceding sections on the use of make recursion
preceding sections on the use of make recursion will probably come as will probably come as unwelcome advice. For those who haven’t read the
unwelcome advice. For those who haven’t read the paper, Miller’s main paper, Miller’s main thesis is that recursive ‘make’ invocations are
thesis is that recursive ‘make’ invocations are both slow and both slow and error-prone.
error-prone.
Automake provides sufficient cross-directory support (1) to enable Automake provides sufficient cross-directory support (1) to enable
you to write a single ‘Makefile.am’ for a complex multi-directory you to write a single ‘Makefile.am’ for a complex multi-directory
package. package.
By default an installable file specified in a subdirectory will have By default an installable file specified in a subdirectory will have
its directory name stripped before installation. For instance, in this its directory name stripped before installation. For instance, in this
example, the header file will be installed as ‘$(includedir)/stdio.h’: example, the header file will be installed as ‘$(includedir)/stdio.h’:
include_HEADERS = inc/stdio.h include_HEADERS = inc/stdio.h
skipping to change at line 4211 skipping to change at line 4276
8.3.1 The Libtool Concept 8.3.1 The Libtool Concept
------------------------- -------------------------
Libtool abstracts shared and static libraries into a unified concept Libtool abstracts shared and static libraries into a unified concept
henceforth called “libtool libraries”. Libtool libraries are files henceforth called “libtool libraries”. Libtool libraries are files
using the ‘.la’ suffix, and can designate a static library, a shared using the ‘.la’ suffix, and can designate a static library, a shared
library, or maybe both. Their exact nature cannot be determined until library, or maybe both. Their exact nature cannot be determined until
‘./configure’ is run: not all platforms support all kinds of libraries, ‘./configure’ is run: not all platforms support all kinds of libraries,
and users can explicitly select which libraries should be built. and users can explicitly select which libraries should be built.
(However the package’s maintainers can tune the default; *note The (However the package’s maintainers can tune the default; *note The
AC_PROG_LIBTOOL’ macro: (libtool)AC_PROG_LIBTOOL.) LT_INIT’ macro: (libtool)LT_INIT.)
Because object files for shared and static libraries must be compiled Because object files for shared and static libraries must be compiled
differently, libtool is also used during compilation. Object files differently, libtool is also used during compilation. Object files
built by libtool are called “libtool objects”: these are files using the built by libtool are called “libtool objects”: these are files using the
‘.lo’ suffix. Libtool libraries are built from these libtool objects. ‘.lo’ suffix. Libtool libraries are built from these libtool objects.
You should not assume anything about the structure of ‘.la’ or ‘.lo’ You should not assume anything about the structure of ‘.la’ or ‘.lo’
files and how libtool constructs them: this is libtool’s concern, and 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 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 existence of these files matters, because they are used as targets and
skipping to change at line 5513 skipping to change at line 5578
in ‘foo_LDADD’ and ‘libfoo_la_LIBADD’, then Automake would have issued a in ‘foo_LDADD’ and ‘libfoo_la_LIBADD’, then Automake would have issued a
warning. warning.
* Menu: * Menu:
* How the Linker is Chosen:: Automatic linker selection * How the Linker is Chosen:: Automatic linker selection
---------- Footnotes ---------- ---------- Footnotes ----------
(1) For example, the cfortran package (1) For example, the cfortran package
(http://www-zeus.desy.de/~burow/cfortran/) addresses all of these (https://www-zeus.desy.de/~burow/cfortran/) addresses all of these
inter-language issues, and runs under nearly all Fortran 77, C and C++ inter-language issues, and runs under nearly all Fortran 77, C and C++
compilers on nearly all platforms. However, ‘cfortran’ is not yet Free compilers on nearly all platforms. However, ‘cfortran’ is not yet Free
Software, but it will be in the next major release. Software, but it will be in the next major release.
File: automake.info, Node: How the Linker is Chosen, Up: Mixing Fortran 77 Wit h C and C++ File: automake.info, Node: How the Linker is Chosen, Up: Mixing Fortran 77 Wit h C and C++
8.14.3.1 How the Linker is Chosen 8.14.3.1 How the Linker is Chosen
................................. .................................
When a program or library mixes several languages, Automake chooses the When a program or library mixes several languages, Automake chooses the
skipping to change at line 5648 skipping to change at line 5713
When linking, ‘gcj’ requires that the main class be specified using When linking, ‘gcj’ requires that the main class be specified using
the ‘--main=’ option. The easiest way to do this is to use the the ‘--main=’ option. The easiest way to do this is to use the
‘_LDFLAGS’ variable for the program. ‘_LDFLAGS’ variable for the program.
File: automake.info, Node: Vala Support, Next: Support for Other Languages, P rev: Java Support with gcj, Up: Programs File: automake.info, Node: Vala Support, Next: Support for Other Languages, P rev: Java Support with gcj, Up: Programs
8.17 Vala Support 8.17 Vala Support
================= =================
Automake provides initial support for Vala Automake provides initial support for Vala
(<http://www.vala-project.org/>). This requires valac version 0.7.0 or (<https://www.vala-project.org/>). This requires valac version 0.7.0 or
later, and currently requires the user to use GNU ‘make’. later, and currently requires the user to use GNU ‘make’.
foo_SOURCES = foo.vala bar.vala zardoc.c foo_SOURCES = foo.vala bar.vala zardoc.c
Any ‘.vala’ file listed in a ‘_SOURCES’ variable will be compiled Any ‘.vala’ file listed in a ‘_SOURCES’ variable will be compiled
into C code by the Vala compiler. The generated ‘.c’ files are into C code by the Vala compiler. The generated ‘.c’ files are
distributed. The end user does not need to have a Vala compiler distributed. The end user does not need to have a Vala compiler
installed. installed.
Automake ships with an Autoconf macro called ‘AM_PROG_VALAC’ that Automake ships with an Autoconf macro called ‘AM_PROG_VALAC’ that
will locate the Vala compiler and optionally check its version number. will locate the Vala compiler and optionally check its version number.
-- Macro: AM_PROG_VALAC ([MINIMUM-VERSION], [ACTION-IF-FOUND], -- Macro: AM_PROG_VALAC ([MINIMUM-VERSION], [ACTION-IF-FOUND],
[ACTION-IF-NOT-FOUND]) Search for a Vala compiler in ‘PATH’. If it [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 is found, the variable ‘VALAC’ is set to point to it (see below for
more details). This macro takes three optional arguments. The more details). This macro takes three optional arguments. The
first argument, if present, is the minimum version of the Vala first argument, if present, is the minimum version of the Vala API
compiler required to compile this package. If a compiler is found required to compile this package. For Vala releases, this is the
and satisfies MINIMUM-VERSION, then ACTION-IF-FOUND is run (this same as the major and minor release number; e.g., when ‘valac
defaults to do nothing). Otherwise, ACTION-IF-NOT-FOUND is run. --version’ reports ‘0.48.7’, ‘valac --api-version’ reports ‘0.48’.
If ACTION-IF-NOT-FOUND is not specified, the default value is to If a compiler is found and satisfies MINIMUM-VERSION, then
print a warning in case no compiler is found, or if a too-old ACTION-IF-FOUND is run (this defaults to do nothing). Otherwise,
version of the compiler is found. 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: There are a few variables that are used when compiling Vala sources:
‘VALAC’ ‘VALAC’
Absolute path to the Vala compiler, or simply ‘valac’ if no Absolute path to the Vala compiler, or simply ‘valac’ if no
suitable Vala compiler could be found at configure runtime. suitable Vala compiler could be found at configure runtime.
‘VALAFLAGS’ ‘VALAFLAGS’
Additional arguments for the Vala compiler. Additional arguments for the Vala compiler.
skipping to change at line 5972 skipping to change at line 6040
(regardless of the dependencies), or accurate dependencies exist and (regardless of the dependencies), or accurate dependencies exist and
they can be used to decide whether ‘foo.o’ should be rebuilt. 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’ 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 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’. ‘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 ‘make’ failed to trigger the rule to build ‘foo.h’ first by lack of
dependency information. dependency information.
The ‘BUILT_SOURCES’ variable is a workaround for this problem. A The ‘BUILT_SOURCES’ variable is a workaround for this problem. A
source file listed in ‘BUILT_SOURCES’ is made on ‘make all’ or ‘make source file listed in ‘BUILT_SOURCES’ is made when ‘make all’, ‘make
check’ (or even ‘make install’) before other targets are processed. check’, ‘make install’, ‘make install-exec’ (or ‘make dist’) is run,
However, such a source file is not _compiled_ unless explicitly before other targets are processed. However, such a source file is not
requested by mentioning it in some other ‘_SOURCES’ variable. _compiled_ unless explicitly requested by mentioning it in some other
‘_SOURCES’ variable.
So, to conclude our introductory example, we could use ‘BUILT_SOURCES 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.h’ to ensure ‘foo.h’ gets built before any other target (including
‘foo.o’) during ‘make all’ or ‘make check’. ‘foo.o’) during ‘make all’ or ‘make check’.
‘BUILT_SOURCES’ is actually a bit of a misnomer, as any file which ‘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 must be created early in the build process can be listed in this
variable. Moreover, all built sources do not necessarily have to be variable. Moreover, all built sources do not necessarily have to be
listed in ‘BUILT_SOURCES’. For instance, a generated ‘.c’ file doesn’t listed in ‘BUILT_SOURCES’. For instance, a generated ‘.c’ file doesn’t
need to appear in ‘BUILT_SOURCES’ (unless it is included by another need to appear in ‘BUILT_SOURCES’ (unless it is included by another
source), because it’s a known dependency of the associated object. source), because it’s a known dependency of the associated object.
It might be important to emphasize that ‘BUILT_SOURCES’ is honored To emphasize, ‘BUILT_SOURCES’ is honored only by ‘make all’, ‘make
only by ‘make all’, ‘make check’ and ‘make install’. This means you check’, ‘make install’, and ‘make install-exec’ (and ‘make dist’). This
cannot build a specific target (e.g., ‘make foo’) in a clean tree if it means you cannot build an arbitrary target (e.g., ‘make foo’) in a clean
depends on a built source. However it will succeed if you have run tree if it depends on a built source. However it will succeed if you
‘make all’ earlier, because accurate dependencies are already available. have run ‘make all’ earlier, because accurate dependencies are already
available.
The next section illustrates and discusses the handling of built The next section illustrates and discusses the handling of built
sources on a toy example. sources on a toy example.
* Menu: * Menu:
* Built Sources Example:: Several ways to handle built sources. * Built Sources Example:: Several ways to handle built sources.
File: automake.info, Node: Built Sources Example, Up: Sources File: automake.info, Node: Built Sources Example, Up: Sources
skipping to change at line 6398 skipping to change at line 6468
Assuming ACTION-IF-NOT-FOUND is used (otherwise ‘./configure’ will Assuming ACTION-IF-NOT-FOUND is used (otherwise ‘./configure’ will
abort if Python is absent), the value of ‘PYTHON’ can be used to abort if Python is absent), the value of ‘PYTHON’ can be used to
set up a conditional in order to disable the relevant part of a set up a conditional in order to disable the relevant part of a
build as follows. build as follows.
AM_PATH_PYTHON(,, [:]) AM_PATH_PYTHON(,, [:])
AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :]) AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
‘PYTHON_VERSION’ ‘PYTHON_VERSION’
The Python version number, in the form MAJOR.MINOR (e.g., ‘2.5’). The Python version number, in the form MAJOR.MINOR (e.g., ‘2.5’).
This is currently the value of ‘sys.version[:3]’. This is currently the value of ‘'%u.%u' % sys.version_info[:2]’.
‘PYTHON_PREFIX’ ‘PYTHON_PREFIX’
The string ‘${prefix}’. This term may be used in future work that The string ‘${prefix}’. This term may be used in future work that
needs the contents of Python’s ‘sys.prefix’, but general consensus needs the contents of Python’s ‘sys.prefix’, but general consensus
is to always use the value from ‘configure’. is to always use the value from ‘configure’.
‘PYTHON_EXEC_PREFIX’ ‘PYTHON_EXEC_PREFIX’
The string ‘${exec_prefix}’. This term may be used in future work The string ‘${exec_prefix}’. This term may be used in future work
that needs the contents of Python’s ‘sys.exec_prefix’, but general that needs the contents of Python’s ‘sys.exec_prefix’, but general
consensus is to always use the value from ‘configure’. consensus is to always use the value from ‘configure’.
skipping to change at line 6603 skipping to change at line 6673
‘TEXI2PDF’ ‘TEXI2PDF’
The name of the command that translates a ‘.texi’ file into a The name of the command that translates a ‘.texi’ file into a
‘.pdf’ file. This defaults to ‘$(TEXI2DVI) --pdf --batch’. ‘.pdf’ file. This defaults to ‘$(TEXI2DVI) --pdf --batch’.
‘DVIPS’ ‘DVIPS’
The name of the command that builds a ‘.ps’ file out of a ‘.dvi’ The name of the command that builds a ‘.ps’ file out of a ‘.dvi’
file. This defaults to ‘dvips’. file. This defaults to ‘dvips’.
‘TEXINFO_TEX’ ‘TEXINFO_TEX’
If your package has Texinfo files in many directories, you can use If your package has Texinfo files in many directories, you can use
the variable ‘TEXINFO_TEX’ to tell Automake where to find the the variable ‘TEXINFO_TEX’ to tell Automake where to find the
canonical ‘texinfo.tex’ for your package. The value of this canonical ‘texinfo.tex’ for your package. The value of this
variable should be the relative path from the current ‘Makefile.am’ variable should be the relative path from the current ‘Makefile.am’
to ‘texinfo.tex’: to ‘texinfo.tex’:
TEXINFO_TEX = ../doc/texinfo.tex TEXINFO_TEX = ../doc/texinfo.tex
File: automake.info, Node: Man Pages, Prev: Texinfo, Up: Documentation File: automake.info, Node: Man Pages, Prev: Texinfo, Up: Documentation
skipping to change at line 6697 skipping to change at line 6766
primaries are automatically installed in the appropriate places when the primaries are automatically installed in the appropriate places when the
user runs ‘make install’. user runs ‘make install’.
* Menu: * Menu:
* Basics of Installation:: What gets installed where * Basics of Installation:: What gets installed where
* The Two Parts of Install:: Installing data and programs separately * The Two Parts of Install:: Installing data and programs separately
* Extending Installation:: Adding your own rules for installation * Extending Installation:: Adding your own rules for installation
* Staged Installs:: Installation in a temporary location * Staged Installs:: Installation in a temporary location
* Install Rules for the User:: Useful additional rules * Install Rules for the User:: Useful additional rules
File: automake.info, Node: Basics of Installation, Next: The Two Parts of Inst
all, 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 Installat
ion, 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, Pre
v: 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.
 End of changes. 38 change blocks. 
83 lines changed or deleted 152 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)