From: Mathieu Lirzin Date: Tue, 19 Sep 2017 11:43:07 +0000 (+0200) Subject: maint: Reset master X-Git-Tag: v1.16~30 X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=c2757b974cb4c182333859edb45a01194550bc0e;p=thirdparty%2Fautomake.git maint: Reset master --- diff --git a/.autom4te.cfg b/.autom4te.cfg deleted file mode 100644 index 787905ad8..000000000 --- a/.autom4te.cfg +++ /dev/null @@ -1,5 +0,0 @@ -## autom4te.cfg for the Automake package. -## -begin-language: "Autoconf-without-aclocal-m4" -args: --cache=.autom4te.cache -end-language: "Autoconf-without-aclocal-m4" diff --git a/.git-log-fix b/.git-log-fix deleted file mode 100644 index d87a0ec22..000000000 --- a/.git-log-fix +++ /dev/null @@ -1,13 +0,0 @@ -# This file is expected to be used via gitlog-to-changelog's --amend=FILE -# option. It specifies what changes to make to each given SHA1's commit -# log and metadata, using Perl-eval'able expressions. - -3b369e6bbe0fb6d7359398935706c87dd9375cb6 -# Date: Thu Feb 16 22:29:32 2012 +0100 -# Fix a typo. -s| bur | bug | - -22729165f6bb902daeb8a4d8e7cb06982390f327 -# Date: Fri Feb 17 10:13:15 2012 +0100 -# Fix a typo. -s|.fix-git-log|.git-log-fix| diff --git a/.gitattributes b/.gitattributes deleted file mode 100644 index 0d86adb5e..000000000 --- a/.gitattributes +++ /dev/null @@ -1 +0,0 @@ -*.texi* diff=texinfo diff --git a/.gitignore b/.gitignore deleted file mode 100644 index 56bdce2c6..000000000 --- a/.gitignore +++ /dev/null @@ -1,68 +0,0 @@ -/announcement -/maintainer/autoconf-*/ -/maintainer/autoconf-*.tar.gz -/ChangeLog -/aclocal.m4 -/configure -/Makefile.in -/Makefile -/.autom4te.cache -/config.cache -/config.log -/config.status -/config.status.lineno -/configure.lineno -/bin/aclocal -/bin/aclocal-1.* -/bin/automake -/bin/automake-1.* -/runtest -/doc/.dirstamp -/doc/automake*.info -/doc/automake*.info-[0-9] -/doc/automake*.html -/doc/automake*.dvi -/doc/automake*.pdf -/doc/automake*.ps -/doc/automake*.t2d/ -/doc/automake*.t2p/ -/doc/automake*.1 -/doc/aclocal*.1 -/doc/stamp-vti -/doc/version.texi -/doc/amhello-*.tar.gz -/doc/amhello/Makefile.in -/doc/amhello/aclocal.m4 -/doc/amhello/config.h.in -/doc/amhello/config.h.in~ -/doc/amhello/configure -/doc/amhello/depcomp -/doc/amhello/compile -/doc/amhello/install-sh -/doc/amhello/missing -/doc/web-manual -/lib/Automake/Config.pm -/test-suite.log -/t/ax/test-defs.sh -/t/ax/shell-no-trail-bslash -/t/ax/cc-no-c-o -/t/testsuite-part.am -/t/*-w.tap -/t/*-w.sh -/t/depcomp-*.tap -/t/*.dir -/t/*.log -/t/*.trs -/contrib/t/*.dir -/contrib/t/*.log -/contrib/t/*.trs -/t/pm/*.log -/t/pm/*.trs -/t/perf/*.log -/t/perf/*.trs -cscope.files -cscope.in.out -cscope.out -cscope.po.out -tags -TAGS diff --git a/AUTHORS b/AUTHORS deleted file mode 100644 index a3c5c0113..000000000 --- a/AUTHORS +++ /dev/null @@ -1,27 +0,0 @@ -Authors of GNU Automake. - -David Mackenzie - First version of most ".am" files. - Wrote sh version of automake.in. - -Tom Tromey - Touched all ".am" files. - Rewrote automake.in - -Alexandre Oliva - Some of the user-side dependency tracking system. - Some more random hacking. - -Alexandre Duret-Lutz - Major overhaul of everything. - Maintenance since 2002. - -Ralf Wildenhues - Random breakage. - Maintenance since 2006. - -Stefano Lattarini - Testsuite overhaul. - TAP support and custom testsuite drivers. - Random breakage. - De-facto maintenance since 2012. diff --git a/COPYING b/COPYING deleted file mode 100644 index 73e818e98..000000000 --- a/COPYING +++ /dev/null @@ -1,339 +0,0 @@ - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989-2017 Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Lesser General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - - Copyright (C) - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - , 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. diff --git a/GNUmakefile b/GNUmakefile deleted file mode 100644 index fc1e911ae..000000000 --- a/GNUmakefile +++ /dev/null @@ -1,88 +0,0 @@ -# Maintainer makefile for Automake. Requires GNU make. - -# Copyright (C) 2012-2017 Free Software Foundation, Inc. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -ifeq ($(filter bootstrap,$(MAKECMDGOALS)),) - -ifeq ($(wildcard Makefile),) - # Any target but 'bootstrap' specified in an unconfigured tree - # is an error, even when the user is running GNU make. - $(warning There seems to be no Makefile in this directory.) - $(warning You must run ./configure before running 'make'.) - $(error Fatal Error) -endif -include ./Makefile -include $(srcdir)/maintainer/maint.mk -include $(srcdir)/maintainer/syntax-checks.mk - -else # ! bootstrap in $(MAKECMDGOALS) - -other-targets := $(filter-out bootstrap,$(MAKECMDGOALS)) -config-status := $(wildcard ./config.status) - -BOOTSTRAP_SHELL ?= /bin/sh -export BOOTSTRAP_SHELL - -# Allow the user (or more likely the developer) to ask for a bootstrap -# of the package. -# -# Two issues that must be kept in mind in the implementation below: -# -# [1] "make bootstrap" can be invoked before 'configure' is run (and in -# fact, even before it is created, if we are bootstrapping from a -# freshly-cloned checkout). -# -# [2] When re-bootstrapping an already configured tree, we must ensure -# that the automatic remake rules for Makefile and company do not -# kick in, because the tree might be in an inconsistent state (e.g., -# we have just switched from 'maint' to 'master', and have the built -# 'automake' script left from 'maint', but the files 'lib/am/*.am' -# are from 'master': if 'automake' gets run and uses those files -- -# boom!). - -ifdef config-status # Bootstrap from an already-configured tree. - # We need the definition of $(srcdir) in the 'bootstrap' rule - # below. - srcdir := $(shell echo @srcdir@ | $(config-status) --file=-) - ifndef srcdir - $(error Could not obtain $$(srcdir) from $(config-status)) - endif - # Also, if we are re-bootstrapping an already-configured tree, we - # want to re-configure it with the same pre-existing configuration. - old-configure-flags := $(shell $(config-status) --config) -else # Assume we are bootstrapping from an unconfigured srcdir. - srcdir := . - old-configure-flags := -endif - -configure-flags := $(old-configure-flags) $(BOOTSTRAP_CONFIGURE_FLAGS) - -.PHONY: bootstrap -bootstrap: - cd $(srcdir) && $(SHELL) ./bootstrap - $(srcdir)/configure $(configure-flags) - $(MAKE) clean - $(MAKE) check TESTS=t/get-sysconf - -# Ensure that all the specified targets but 'bootstrap' (if any) are -# run with a properly re-bootstrapped tree. -ifdef other-targets -$(other-targets): restart -.PHONY: $(other-targets) restart -restart: bootstrap; $(MAKE) $(AM_MAKEFLAGS) $(other-targets) -endif - -endif # ! bootstrap in $(MAKECMDGOALS) diff --git a/HACKING b/HACKING deleted file mode 100644 index 21dab2a74..000000000 --- a/HACKING +++ /dev/null @@ -1,410 +0,0 @@ -============================================================================ -= This file - -* This file attempts to describe the rules to use when hacking - automake. - -============================================================================ -= Administrivia - -* The correct response to most actual bugs is to write a new test case - which demonstrates the bug. Then fix the bug, re-run the test suite, - and check everything in. - -* If you incorporate a change from somebody on the net: - - First, if it is a large change, you must make sure they have - signed the appropriate paperwork. - - Second, be sure to add their name and email address to THANKS. - -* If a change fixes a test, mention the test in the commit message. - If a change fixes a bug registered in the Automake debbugs tracker, - mention the bug number in the commit message. - -* If somebody reports a new bug, mention his name in the commit message - that fixes or exposes the bug, and put him into THANKS. - -* When documenting a non-trivial idiom or example in the manual, be - sure to add a test case for it, and to reference such test case from - a proper Texinfo comment. - -* Some files in the automake package are not owned by automake; these - files are listed in the $(FETCHFILES) variable in Makefile.am. They - should never be edited here. Almost all of them can be updated from - respective upstreams with "make fetch" (this should be done especially - before releases). The only exception is the 'lib/COPYING' (from FSF), - which should be updated by hand whenever the GPL gets updated (which - shouldn't happen that often anyway :-) - -* Changes other than *trivial* bug fixes must be mentioned in NEWS. - -* Changes which are potentially controversial, require a non-trivial - plan, or must be implemented gradually with a roadmap spanning several - releases (either minor or major) should be discussed on the list, - and have a proper entry in the PLANS directory. This entry should be - always committed in the "maint" branch, even if the change it deals - with is only for the master branch, or a topic branch. Usually, in - addition to this, it is useful to open a "wishlist" report on the - Automake debbugs tracker, to keep the idea more visible, and have the - discussions surrounding it easily archived in a central place. - -============================================================================ -= Naming - -* We've adopted the convention that internal AC_SUBSTs and make variables - should be named with a leading 'am__', and internally generated targets - should be named with a leading 'am--'. This convention, although in - place from at least February 2001, isn't yet universally used. - But all new code should use it. - - We used to use '_am_' as the prefix for an internal AC_SUBSTs. - However, it turns out that NEWS-OS 4.2R complains if a Makefile - variable begins with the underscore character. Yay for them. - I changed the target naming convention just to be safe. - -============================================================================ -= Editing '.am' files - -* Always use $(...) and not ${...} - -* Prefer ':' over 'true', mostly for consistency with existing code. - -* Use '##' comments liberally. Comment anything even remotely unusual. - -* Never use basename or dirname. Instead, use sed. - -* Do not use 'cd' within back-quotes, use '$(am__cd)' instead. - Otherwise the directory name may be printed, depending on CDPATH. - More generally, do not ever use plain 'cd' together with a relative - directory that does not start with a dot, or you might end up in one - computed with CDPATH. - -* For install and uninstall rules, if a loop is required, it should be - silent. Then the body of the loop itself should print each "important" - command it runs. The printed commands should be preceded by a single - space. - -* Ensure install rules do not create any installation directory where - nothing is to be actually installed. See automake bug#11030. - -============================================================================ -= Editing automake.in and aclocal.in - -* Indent using GNU style. For historical reasons, the perl code - contains portions indented using Larry Wall's style (perl-mode's - default), and other portions using the GNU style (cperl-mode's - default). Write new code using GNU style. - -* Don't use & for function calls, unless really required. - The use of & prevents prototypes from being checked. - -============================================================================ -= Automake versioning and compatibility scheme - -* There are three kinds of automake releases: - - - new major releases (e.g., 2.0, 5.0) - - new minor releases (e.g., 1.14, 2.1) - - micro a.k.a. "bug-fixing" releases (e.g., 1.13.2, 2.0.1, 3.5.17). - - A new major release should have the major version number bumped, and - the minor and micro version numbers reset to zero. A new minor release - should have the major version number unchanged, the minor version number - bumped, and the micro version number reset to zero. Finally, a new - micro version should have the major and minor version numbers unchanged, - and the micro version number bumped by one. - - For example, the first minor version after 1.13.2 will be 1.14; the - first bug-fixing version after 1.14 that will be 1.14.1; the first - new major version after all such releases will be 2.0; the first - bug-fixing version after 2.0 will be 2.0.1; and a further bug-fixing - version after 2.0.1 will be 2.0.2. - -* Micro releases should be just bug-fixing releases; no new features - should be added, and ideally, only trivial bugs, recent regressions, - or documentation issues should be addressed by them. On the other - hand, it's OK to include testsuite work and even testsuite refactoring - in a micro version, since a regression there is not going to annoy or - inconvenience Automake users, but only the Automake developers. - -* Minor releases can introduce new "safe" features, do non-trivial but - mostly safe code clean-ups, and even add new runtime warnings (rigorously - non-fatal). But they shouldn't include any backward incompatible change, - nor contain any potentially destabilizing refactoring or sweeping change, - nor introduce new features whose implementation might be liable to cause - bugs or regressions in existing code. However, it might be acceptable to - introduce very limited and localized backward-incompatibilities, *only* - if that is necessary to fix non-trivial bugs, address serious performance - issues, or greatly enhance usability. But please, do this sparsely and - rarely! - -* Major releases can introduce backward-incompatibilities (albeit such - incompatibilities should be announced well in advance, and a smooth - transition plan prepared for them), and try more risking and daring - refactorings and code cleanups. - -* For more information, refer to the extensive discussion associated - with automake bug#13578. - -============================================================================ -= Working with git - -* To regenerate dependent files created by aclocal and automake, - use the 'bootstrap' script. It uses the code from the source - tree, so the resulting files (aclocal.m4 and Makefile.in) should - be the same as you would get if you install this version of - automake and use it to generate those files. Be sure to have the - latest stable version of Autoconf installed and available early - in your PATH. - -* The Automake git tree currently carries three basic branches: 'micro', - 'maint' and 'master'. - -* The 'micro' branch, reserved to changes that should go into the next - micro release; so it will just see fixes for regressions, trivial - bugs, or documentation issues, and no "active" development whatsoever. - Since emergency regression-fixing or security releases could be cut - from this branch at any time, it should always be kept in a releasable - state. - -* The 'maint' branch is where the development of the next minor release - takes place. It should be kept in a stable, almost-releasable state, - to simplify testing and deploying of new minor version. Note that - this is not a hard rule, and such "stability" is not expected to be - absolute (emergency releases are cut from the 'micro' branch anyway). - -* The 'master' branch is reserved for the development of the next major - release. Experimenting a little is OK here, but don't let the branch - grow too unstable; if you need to do exploratory programming or - over-arching change, you should use a dedicated topic branch, and - only merge that back once it is reasonably stable. - -* The 'micro' branch should be kept regularly merged into the 'maint' - branch, and the 'maint' branch into the 'master' branch. It is advisable - to merge only after a set of related commits have been applied, to avoid - introducing too much noise in the history. - -* There may be a number of longer-lived feature branches for new - developments. They should be based off of a common ancestor of all - active branches to which the feature should or might be merged later. - -* After a new minor release is done, the 'maint' branch is to be merged - into the 'micro' branch, and then a "new" 'maint' branch created - stemming from the resulting commit. - Similarly, after a new major release is done, the 'master' branch is to - be merged into both the 'micro' and 'maint' branches, and then "new" - 'master' branch created stemming from the resulting commit. - -* When fixing a bug (especially a long-standing one), it may be useful - to commit the fix to a new temporary branch based off the commit that - introduced the bug. Then this "bugfix branch" can be merged into all - the active branches descending from the buggy commit. This offers a - simple way to fix the bug consistently and effectively. - -* When merging, prefer 'git merge --log' over plain 'git merge', so that - a later 'git log' gives an indication of which actual patches were - merged even when they don't appear early in the list. - -* The 'master', 'maint' and 'micro' branches should not be rewound, i.e., - should always fast-forward, except maybe for privacy issues. For - feature branches, the announcement for the branch should document - the rewinding policy. - If a topic branch is expected to be rewound, it is good practice to put - it in the 'experimental/*' namespace; for example, a rewindable branch - dealing with Vala support could be named like "experimental/vala-work". - -============================================================================ -= Writing a good commit message - -* Here is the general format that Automake's commit messages are expected - to follow. See the further points below for clarifications and minor - corrections. - - topic: brief description (this is the "summary line") - - - - Here goes a more detailed explanation of why the commit is needed, - and a general overview of what it does, and how. This section - should almost always be provided, possibly only with the expection - of obvious fixes or very trivial changes. - - And if the detailed explanation is quite long or detailed, you can - want to break it in more paragraphs. - - Then you can add references to relevant mailing list discussions - (if any), with proper links. But don't take this as an excuse for - writing incomplete commit messages! The "distilled" conclusions - reached in such discussions should have been placed in the - paragraphs above. - - Finally, here you can thank people that motivated or helped the - change. So, thanks to John Doe for bringing up the issue, and to - J. Random Hacker for providing suggestions and testing the patch. - - - -* The should usually be provided (but - for short or trivial changes), and should follow the GNU guidelines - for ChangeLog entries (described explicitly in the GNU Coding - Standards); it might be something of this sort: - - * some/file (func1): Improved frobnication. - (func2): Adjusted accordingly. - * another/file (foo, bar): Likewise. - * tests/foo.tap: New test. - * tests/Makefile.am (TESTS): Add it. - -* If your commit fixes an automake bug registered in the tracker (say - numbered 1234), you should put the following line after the summary - line: - - This change fixes automake bug#1234. - -* If your commit is just related to the given bug report, but does not - fix it, you might want to add a line like this instead: - - This change is related to automake bug#1234. - -* When referring to older commits, use 'git describe' output as pointer. - But also try to identify the given commit by date and/or summary line - if possible. Examples: - - Since yesterday's commit, v1.11-2019-g4d2bf42, ... - - ... removed in commit 'v1.11-1674-g02e9072' of 01-01-2012, - "dist: ditch support for lzma"... - -* If the commit is a tiny change that is exempt from copyright paperwork, the - commit message should contain a separate line after the detailed list of - touched files like the following: - - Copyright-paperwork-exempt: yes - -============================================================================ -= Test suite - -* Use "make check" and "make maintainer-check" liberally. - -* Export the 'keep_testdirs' environment variable to "yes" to keep - test directories for successful tests also. - -* Use perl coverage information to ensure your new code is thoroughly - tested by your new tests. - -* See file 't/README' for more information. - -============================================================================ -= Release procedure - -* The steps outlined here are meant to be followed for alpha and stable - releases as well. Where differences are expected, they will be - explicitly described. - -* Fetch new versions of the files that are maintained by the FSF by - running "make fetch". In case any file in the automake repository - has been updated, commit and re-run the testsuite. - -* Ensure that the copyright notices of the distributed files is up to - date. The maintainer-only target "update-copyright" can help with - this. - -* Check NEWS; in particular, ensure that all the relevant differences - with the last release are actually reported. - -* Update the version number in configure.ac. - (The idea is that every other alpha number will be a net release. - The repository will always have its own "odd" number so we can easily - distinguish net and repo versions.) - -* Run these commands, in this order: - - make bootstrap - make check keep_testdirs=yes - make maintainer-check - make distcheck - make check-no-trailing-backslash-in-recipes - make check-cc-no-c-o - - It is also advised to run "git clean -fdx" before invoking the - bootstrap, to ensure a really clean rebuild. However, it must - be done carefully, because that command will remove *all* the - files that are not tracked by git! - -* Run "make git-tag-release". - This will run the maintainer checks, verify that the local git - repository and working tree are clean and up-to-date, and create - a proper signed git tag for the release (based on the contents - of $(VERSION)). - -* Run "make git-upload-release". - This will first verify that you are releasing from a tagged version - and that the local git repository and working tree are clean and - up-to-date, and will then run "make dist" to create the tarballs, - and invoke the 'gnupload' script sign and upload them to the correct - locations. In case you need to sign with a non-default key, you can - use "make GNUPLOADFLAGS='--user KEY' git-upload-release". - -* For stable releases you'll have to update the manuals at www.gnu.org. - - - Generate manuals (with the help of the standard gendocs.sh script): - - make web-manual - - The ready-to-be-uploaded manuals (in several formats) will be left - in the 'doc/web-manuals' directory. - - - Commit the updated manuals to web CVS: - - make web-manual-update - - If your local username is different from your username at Savannah, - you'll have to override the 'CVS_USER' make variable accordingly; - for example: - - make web-manual-update CVS_USER=slattarini - - - Check for link errors, fix them, recheck until convergence: - - -* Create an announcement message with "make announcement". Edit the - generated 'announcement' file appropriately, in particularly filling - in by hand any "TODO" left in there. - -* Update version number in configure.ac to next alpha number. - Re-run ./bootstrap and commit. - -* Don't forget to "git push" your changes so they appear in the public - git tree. - -* Send the announcement generated in the earlier steps at least to - and . If the release - is a stable one, the announcement must also go to ; - if it is an alpha or beta release, announcement should be sent also - to , to maximize the possibility of early - testing on exotic or proprietary systems. Finally, copy an abridged - version of the announcement into the NEWS feed at: - . - Be sure to link a version to the complete announcement (from - the version you sent to the automake list, as get archived on - ). - ------ - -Copyright (C) 2003-2017 Free Software Foundation, Inc. - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2, or (at your option) -any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see . - -Local Variables: -mode: text -End: diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 422dd3a1c..000000000 --- a/INSTALL +++ /dev/null @@ -1,369 +0,0 @@ -Installation Instructions -************************* - -Copyright (C) 1994-2017 Free Software Foundation, Inc. - - Copying and distribution of this file, with or without modification, -are permitted in any medium without royalty provided the copyright -notice and this notice are preserved. This file is offered as-is, -without warranty of any kind. - -Basic Installation -================== - - Briefly, the shell command `./configure && make && make install' -should configure, build, and install this package. The following -more-detailed instructions are generic; see the `README' file for -instructions specific to this package. Some packages provide this -`INSTALL' file but do not implement all of the features documented -below. The lack of an optional feature in a given package is not -necessarily a bug. More recommendations for GNU packages can be found -in *note Makefile Conventions: (standards)Makefile Conventions. - - The `configure' shell script attempts to guess correct values for -various system-dependent variables used during compilation. It uses -those values to create a `Makefile' in each directory of the package. -It may also create one or more `.h' files containing system-dependent -definitions. Finally, it creates a shell script `config.status' that -you can run in the future to recreate the current configuration, and a -file `config.log' containing compiler output (useful mainly for -debugging `configure'). - - It can also use an optional file (typically called `config.cache' -and enabled with `--cache-file=config.cache' or simply `-C') that saves -the results of its tests to speed up reconfiguring. Caching is -disabled by default to prevent problems with accidental use of stale -cache files. - - If you need to do unusual things to compile the package, please try -to figure out how `configure' could check whether to do them, and mail -diffs or instructions to the address given in the `README' so they can -be considered for the next release. If you are using the cache, and at -some point `config.cache' contains results you don't want to keep, you -may remove or edit it. - - The file `configure.ac' (or `configure.in') is used to create -`configure' by a program called `autoconf'. You need `configure.ac' if -you want to change it or regenerate `configure' using a newer version -of `autoconf'. - - The simplest way to compile this package is: - - 1. `cd' to the directory containing the package's source code and type - `./configure' to configure the package for your system. - - Running `configure' might take a while. While running, it prints - some messages telling which features it is checking for. - - 2. Type `make' to compile the package. - - 3. Optionally, type `make check' to run any self-tests that come with - the package, generally using the just-built uninstalled binaries. - - 4. Type `make install' to install the programs and any data files and - documentation. When installing into a prefix owned by root, it is - recommended that the package be configured and built as a regular - user, and only the `make install' phase executed with root - privileges. - - 5. Optionally, type `make installcheck' to repeat any self-tests, but - this time using the binaries in their final installed location. - This target does not install anything. Running this target as a - regular user, particularly if the prior `make install' required - root privileges, verifies that the installation completed - correctly. - - 6. You can remove the program binaries and object files from the - source code directory by typing `make clean'. To also remove the - files that `configure' created (so you can compile the package for - a different kind of computer), type `make distclean'. There is - also a `make maintainer-clean' target, but that is intended mainly - for the package's developers. If you use it, you may have to get - all sorts of other programs in order to regenerate files that came - with the distribution. - - 7. Often, you can also type `make uninstall' to remove the installed - files again. In practice, not all packages have tested that - uninstallation works correctly, even though it is required by the - GNU Coding Standards. - - 8. Some packages, particularly those that use Automake, provide `make - distcheck', which can by used by developers to test that all other - targets like `make install' and `make uninstall' work correctly. - This target is generally not run by end users. - -Compilers and Options -===================== - - Some systems require unusual options for compilation or linking that -the `configure' script does not know about. Run `./configure --help' -for details on some of the pertinent environment variables. - - You can give `configure' initial values for configuration parameters -by setting variables in the command line or in the environment. Here -is an example: - - ./configure CC=c99 CFLAGS=-g LIBS=-lposix - - *Note Defining Variables::, for more details. - -Compiling For Multiple Architectures -==================================== - - You can compile the package for more than one kind of computer at the -same time, by placing the object files for each architecture in their -own directory. To do this, you can use GNU `make'. `cd' to the -directory where you want the object files and executables to go and run -the `configure' script. `configure' automatically checks for the -source code in the directory that `configure' is in and in `..'. This -is known as a "VPATH" build. - - With a non-GNU `make', it is safer to compile the package for one -architecture at a time in the source code directory. After you have -installed the package for one architecture, use `make distclean' before -reconfiguring for another architecture. - - On MacOS X 10.5 and later systems, you can create libraries and -executables that work on multiple system types--known as "fat" or -"universal" binaries--by specifying multiple `-arch' options to the -compiler but only a single `-arch' option to the preprocessor. Like -this: - - ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \ - CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \ - CPP="gcc -E" CXXCPP="g++ -E" - - This is not guaranteed to produce working output in all cases, you -may have to build one architecture at a time and combine the results -using the `lipo' tool if you have problems. - -Installation Names -================== - - By default, `make install' installs the package's commands under -`/usr/local/bin', include files under `/usr/local/include', etc. You -can specify an installation prefix other than `/usr/local' by giving -`configure' the option `--prefix=PREFIX', where PREFIX must be an -absolute file name. - - You can specify separate installation prefixes for -architecture-specific files and architecture-independent files. If you -pass the option `--exec-prefix=PREFIX' to `configure', the package uses -PREFIX as the prefix for installing programs and libraries. -Documentation and other data files still use the regular prefix. - - In addition, if you use an unusual directory layout you can give -options like `--bindir=DIR' to specify different values for particular -kinds of files. Run `configure --help' for a list of the directories -you can set and what kinds of files go in them. In general, the -default for these options is expressed in terms of `${prefix}', so that -specifying just `--prefix' will affect all of the other directory -specifications that were not explicitly provided. - - The most portable way to affect installation locations is to pass the -correct locations to `configure'; however, many packages provide one or -both of the following shortcuts of passing variable assignments to the -`make install' command line to change installation locations without -having to reconfigure or recompile. - - The first method involves providing an override variable for each -affected directory. For example, `make install -prefix=/alternate/directory' will choose an alternate location for all -directory configuration variables that were expressed in terms of -`${prefix}'. Any directories that were specified during `configure', -but not in terms of `${prefix}', must each be overridden at install -time for the entire installation to be relocated. The approach of -makefile variable overrides for each directory variable is required by -the GNU Coding Standards, and ideally causes no recompilation. -However, some platforms have known limitations with the semantics of -shared libraries that end up requiring recompilation when using this -method, particularly noticeable in packages that use GNU Libtool. - - The second method involves providing the `DESTDIR' variable. For -example, `make install DESTDIR=/alternate/directory' will prepend -`/alternate/directory' before all installation names. The approach of -`DESTDIR' overrides is not required by the GNU Coding Standards, and -does not work on platforms that have drive letters. On the other hand, -it does better at avoiding recompilation issues, and works well even -when some directory options were not specified in terms of `${prefix}' -at `configure' time. - -Optional Features -================= - - If the package supports it, you can cause programs to be installed -with an extra prefix or suffix on their names by giving `configure' the -option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'. - - Some packages pay attention to `--enable-FEATURE' options to -`configure', where FEATURE indicates an optional part of the package. -They may also pay attention to `--with-PACKAGE' options, where PACKAGE -is something like `gnu-as' or `x' (for the X Window System). The -`README' should mention any `--enable-' and `--with-' options that the -package recognizes. - - For packages that use the X Window System, `configure' can usually -find the X include and library files automatically, but if it doesn't, -you can use the `configure' options `--x-includes=DIR' and -`--x-libraries=DIR' to specify their locations. - - Some packages offer the ability to configure how verbose the -execution of `make' will be. For these packages, running `./configure ---enable-silent-rules' sets the default to minimal output, which can be -overridden with `make V=1'; while running `./configure ---disable-silent-rules' sets the default to verbose, which can be -overridden with `make V=0'. - -Particular systems -================== - - On HP-UX, the default C compiler is not ANSI C compatible. If GNU -CC is not installed, it is recommended to use the following options in -order to use an ANSI C compiler: - - ./configure CC="cc -Ae -D_XOPEN_SOURCE=500" - -and if that doesn't work, install pre-built binaries of GCC for HP-UX. - - HP-UX `make' updates targets which have the same time stamps as -their prerequisites, which makes it generally unusable when shipped -generated files such as `configure' are involved. Use GNU `make' -instead. - - On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot -parse its `' header file. The option `-nodtk' can be used as -a workaround. If GNU CC is not installed, it is therefore recommended -to try - - ./configure CC="cc" - -and if that doesn't work, try - - ./configure CC="cc -nodtk" - - On Solaris, don't put `/usr/ucb' early in your `PATH'. This -directory contains several dysfunctional programs; working variants of -these programs are available in `/usr/bin'. So, if you need `/usr/ucb' -in your `PATH', put it _after_ `/usr/bin'. - - On Haiku, software installed for all users goes in `/boot/common', -not `/usr/local'. It is recommended to use the following options: - - ./configure --prefix=/boot/common - -Specifying the System Type -========================== - - There may be some features `configure' cannot figure out -automatically, but needs to determine by the type of machine the package -will run on. Usually, assuming the package is built to be run on the -_same_ architectures, `configure' can figure that out, but if it prints -a message saying it cannot guess the machine type, give it the -`--build=TYPE' option. TYPE can either be a short name for the system -type, such as `sun4', or a canonical name which has the form: - - CPU-COMPANY-SYSTEM - -where SYSTEM can have one of these forms: - - OS - KERNEL-OS - - See the file `config.sub' for the possible values of each field. If -`config.sub' isn't included in this package, then this package doesn't -need to know the machine type. - - If you are _building_ compiler tools for cross-compiling, you should -use the option `--target=TYPE' to select the type of system they will -produce code for. - - If you want to _use_ a cross compiler, that generates code for a -platform different from the build platform, you should specify the -"host" platform (i.e., that on which the generated programs will -eventually be run) with `--host=TYPE'. - -Sharing Defaults -================ - - If you want to set default values for `configure' scripts to share, -you can create a site shell script called `config.site' that gives -default values for variables like `CC', `cache_file', and `prefix'. -`configure' looks for `PREFIX/share/config.site' if it exists, then -`PREFIX/etc/config.site' if it exists. Or, you can set the -`CONFIG_SITE' environment variable to the location of the site script. -A warning: not all `configure' scripts look for a site script. - -Defining Variables -================== - - Variables not defined in a site shell script can be set in the -environment passed to `configure'. However, some packages may run -configure again during the build, and the customized values of these -variables may be lost. In order to avoid this problem, you should set -them in the `configure' command line, using `VAR=value'. For example: - - ./configure CC=/usr/local2/bin/gcc - -causes the specified `gcc' to be used as the C compiler (unless it is -overridden in the site shell script). - -Unfortunately, this technique does not work for `CONFIG_SHELL' due to -an Autoconf limitation. Until the limitation is lifted, you can use -this workaround: - - CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash - -`configure' Invocation -====================== - - `configure' recognizes the following options to control how it -operates. - -`--help' -`-h' - Print a summary of all of the options to `configure', and exit. - -`--help=short' -`--help=recursive' - Print a summary of the options unique to this package's - `configure', and exit. The `short' variant lists options used - only in the top level, while the `recursive' variant lists options - also present in any nested packages. - -`--version' -`-V' - Print the version of Autoconf used to generate the `configure' - script, and exit. - -`--cache-file=FILE' - Enable the cache: use and save the results of the tests in FILE, - traditionally `config.cache'. FILE defaults to `/dev/null' to - disable caching. - -`--config-cache' -`-C' - Alias for `--cache-file=config.cache'. - -`--quiet' -`--silent' -`-q' - Do not print messages saying which checks are being made. To - suppress all normal output, redirect it to `/dev/null' (any error - messages will still be shown). - -`--srcdir=DIR' - Look for the package's source code in directory DIR. Usually - `configure' can determine that directory automatically. - -`--prefix=DIR' - Use DIR as the installation prefix. *note Installation Names:: - for more details, including other options available for fine-tuning - the installation locations. - -`--no-create' -`-n' - Run the configure checks, but stop before creating any output - files. - -`configure' also accepts some other, not widely useful, options. Run -`configure --help' for more details. diff --git a/Makefile.am b/Makefile.am deleted file mode 100644 index b780307f7..000000000 --- a/Makefile.am +++ /dev/null @@ -1,134 +0,0 @@ -## Process this file with automake to create Makefile.in - -## Makefile for Automake. - -# Copyright (C) 1995-2017 Free Software Foundation, Inc. - -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -## Might be updated later. -CLEANFILES = -DISTCLEANFILES = -MAINTAINERCLEANFILES = -EXTRA_DIST = -TAGS_FILES = -dist_noinst_DATA = -nodist_noinst_DATA = -dist_noinst_SCRIPTS = -nodist_noinst_SCRIPTS = - -## ------------ ## -## Top level. ## -## ------------ ## - -EXTRA_DIST += \ - bootstrap \ - GNUmakefile \ - HACKING \ - PLANS - -# We want a handful of substitutions to be fully-expanded by make; -# then use config.status to substitute the remainder where a single -# expansion is sufficient. We use a funny notation here to avoid -# configure substitutions in our text. -do_subst = ( sed \ - -e "s,[@]configure_input[@],Generated from $$in; do not edit by hand.,g" \ - -e 's,[@]datadir[@],$(datadir),g' \ - -e 's,[@]amdir[@],$(amdir),g' \ - -e 's,[@]bindir[@],$(bindir),g' \ - -e 's,[@]docdir[@],$(docdir),g' \ - -e 's,[@]pkgvdatadir[@],$(pkgvdatadir),g' \ - -e 's,[@]scriptdir[@],$(scriptdir),g' \ - -e 's,[@]automake_acdir[@],$(automake_acdir),g' \ - -e 's,[@]system_acdir[@],$(system_acdir),g' \ -## Hack to avoid a spurious substitution in the Automake script (part 1). - -e 's,[@]am__isrc[@],!!@!!am__isrc!!@!!,g' \ - | $(SHELL) ./config.status --file=- \ -## Hack to avoid a spurious substitution in the Automake script (part 2). - | sed -e 's,!!@!!am__isrc!!@!!,@''am__isrc@,g' \ - ) - -# Generated files shouldn't contain unexpanded '@substitutions@', and -# should be made read-only, to prevent them from being edited by mistake -# instead of the file the are generated from. -generated_file_finalize = $(AM_V_at) \ - if LC_ALL=C grep '@[a-zA-Z0-9_][a-zA-Z0-9_]*@' $@-t; then \ - echo "$@ contains unexpanded substitution (see lines above)"; \ - exit 1; \ - fi; \ - chmod a-w $@-t && mv -f $@-t $@ - -# Wrapper for the build environment. -nodist_noinst_SCRIPTS += pre-inst-env -CLEANFILES += $(noinst_SCRIPTS) - -# The master location for INSTALL is lib/INSTALL. -# This is where "make fetch" will install new versions. -# Make sure we also update this copy. -INSTALL: lib/INSTALL - $(AM_V_GEN)cp $(srcdir)/lib/INSTALL $@ - -# We don't use the default name for the autom4te cache directory, -# so we need this. -maintainer-clean-local: - rm -rf .autom4te.cache - -# So that automake won't complain about the missing ChangeLog. -# The real rule for ChangeLog generation is now in maintainer/maint.mk -# (as it is maintainer-specific). -ChangeLog: - -# Third-party, obsolescent or experimental stuff. -EXTRA_DIST += \ - contrib/tap-driver.pl \ - contrib/check-html.am \ - contrib/multilib/README \ - contrib/multilib/config-ml.in \ - contrib/multilib/symlink-tree \ - contrib/multilib/multilib.am \ - contrib/multilib/multi.m4 \ - contrib/README - -# Older files, kept mostly for historical interest. -EXTRA_DIST += \ - old/ChangeLog-tests \ - old/ChangeLog.96 \ - old/ChangeLog.98 \ - old/ChangeLog.00 \ - old/ChangeLog.01 \ - old/ChangeLog.02 \ - old/ChangeLog.03 \ - old/ChangeLog.04 \ - old/ChangeLog.09 \ - old/ChangeLog.11 \ - old/TODO - -# Maintainer-specific files and scripts. -EXTRA_DIST += \ - maintainer/am-ft \ - maintainer/am-xft \ - maintainer/rename-tests \ - maintainer/maint.mk \ - maintainer/syntax-checks.mk - -# Most work delegated to sub-dir makefile fragments. -include $(srcdir)/bin/local.mk -include $(srcdir)/doc/local.mk -include $(srcdir)/lib/local.mk -include $(srcdir)/lib/Automake/local.mk -include $(srcdir)/lib/am/local.mk -include $(srcdir)/m4/local.mk -include $(srcdir)/t/local.mk - -# vim: ft=automake noet diff --git a/NEWS b/NEWS deleted file mode 100644 index 2b4803f71..000000000 --- a/NEWS +++ /dev/null @@ -1,3091 +0,0 @@ -New in 2.0: - -* Compilation and object files: - - - If a source file is placed in a subdirectory, the corresponding compiled - object will *always* be put into the subdirectory named after the source - file, rather than in the current directory. For instance, 'src/file.c' - and 'src/file.f90' will be compiled to 'src/file.o', and 'sub/dir/mu.cc' - will be compiled to 'sub/dir/mu.o'. Put in another way, Automake 2.0 - and later will *unconditionally* behave as older Automake versions did - when the 'subdir-objects' option was given. - -* Texinfo support: - - - Automake used to implement an undocumented hack causing '.info' files - that appeared to be cleaned (by e.g. being listed in the CLEANFILES - variable) to also be built in the builddir rather than in the srcdir; - this was for backward compatibility with packages such as Texinfo, - which did things like: - - info_TEXINFOS = texinfo.txi info-stnd.texi info.texi - DISTCLEANFILES = texinfo texinfo-* info*.info* - # Do not create info files for distribution. - dist-info: - @: - - in order not to distribute .info files. - - Now that we have the 'info-in-builddir' option that explicitly causes - generated '.info' files to be placed in the builddir, this hack is no - longer necessary. We have thus removed\ it. - -* Aclocal search path: - - - Third-party m4 files located in the system-wide aclocal directory, - as well as in any directory listed in the ACLOCAL_PATH environment - variable, now take precedence over "built-in" Automake macros. - For example, assuming Automake is installed in the '/usr/local' - hierarchy, a definition of the AM_PROG_VALAC macro found in file - (say) '/usr/local/share/aclocal/my-vala.m4' should take precedence - over the same-named automake-provided macro, as defined in file - '/usr/local/share/aclocal-2.0/vala.m4'. - -* Obsolescent features flagged: - - - Use of the special makefile variable 'ACLOCAL_AMFLAGS' is deprecated. - To specify locations of extra m4 files, the 'AC_CONFIG_MACRO_DIR' or - 'AC_CONFIG_MACRO_DIRS' (the latter introduced with autoconf 2.70) - should be used instead. And use of the '--install' aclocal option in - 'ACLOCAL_AMFLAGS' has proved to be a bad idea anyway -- see automake - bug#9037. - -* Obsolete features removed: - - - Support for the long-deprecated name 'configure.in' for the Autoconf - input file has been removed altogether. Just use the modern name - 'configure.ac' instead. - - - Support for the long-obsolete variable $(ACLOCAL_M4_SOURCES) has - been removed. It should be safe to simply remove any definition - of it you have in your Makefiles. - -* Removed support for obsolete platforms: - - - Support for automatic dependency tracking with the SGI C/C++ compilers - on IRIX has been removed. The SGI depmode had been reported broken - "in the wild" already, and we don't think investing time in debugging - and fixing it would have been worthwhile, especially considering that - SGI has last updated those compilers in 2006, and is expected to retire - support for them in December 2013: - - - - Support for DJGPP on MS-DOS and/or Windows 95/98/ME has been removed. - Note that both Cygwin and MSYS/MinGW on modern Windows versions will - continue to be fully supported. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* WARNING: Future backward-incompatibilities! - - - Makefile recipes generated by Automake 2.0 will expect to use an - 'rm' program that doesn't complain when called without any non-option - argument if the '-f' option is given (so that commands like "rm -f" - and "rm -rf" will act as a no-op, instead of raising usage errors). - This behavior of 'rm' is very widespread in the wild, and it will be - required in the next POSIX version: - - - - Accordingly, AM_INIT_AUTOMAKE now expands some shell code that checks - that the default 'rm' program in PATH satisfies this requirement, - aborting the configure process if this is not the case. For the - moment, it's still possible to force the configuration process to - succeed even with a broken 'rm', that that will no longer be the case - for Automake 2.0. - - - Automake 2.0 will require Autoconf 2.70 or later (which is still - unreleased at the moment of writing, but is planned to be released - before Automake 2.0 is). - - - Automake 2.0 will drop support for the long-deprecated 'configure.in' - name for the Autoconf input file. You are advised to start using the - recommended name 'configure.ac' instead, ASAP. - - - The ACLOCAL_AMFLAGS special make variable will be fully deprecated in - Automake 2.0: it will raise warnings in the "obsolete" category (but - still no hard error of course, for compatibilities with the many, many - packages that still relies on that variable). You are advised to - start relying on the new Automake support for AC_CONFIG_MACRO_DIRS - instead (which was introduced in Automake 1.13). - - - Automake 2.0 will remove support for automatic dependency tracking - with the SGI C/C++ compilers on IRIX. The SGI depmode has been - reported broken "in the wild" already, and we don't think investing - time in debugging and fixing is worthwhile, especially considering - that SGI has last updated those compilers in 2006, and retired - support for them in December 2013: - - - - Automake 2.0 will remove support for MS-DOS and Windows 95/98/ME - (support for them was offered by relying on the DJGPP project). - Note however that both Cygwin and MSYS/MinGW on modern Windows - versions will continue to be fully supported. - - - Automake-provided scripts and makefile recipes might (finally!) - start assuming a POSIX shell in Automake 2.0. There still is no - certainty about this though: we'd first like to wait and see - whether future Autoconf versions will be enhanced to guarantee - that such a shell is always found and provided by the checks in - ./configure. - - - Starting from Automake 2.0, third-party m4 files located in the - system-wide aclocal directory, as well as in any directory listed - in the ACLOCAL_PATH environment variable, will take precedence - over "built-in" Automake macros. For example (assuming Automake - is installed in the /usr/local hierarchy), a definition of the - AM_PROG_VALAC macro found in '/usr/local/share/aclocal/my-vala.m4' - should take precedence over the same-named automake-provided macro - (defined in '/usr/local/share/aclocal-2.0/vala.m4'). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in ?.?.?: - -* Miscellaneous changes - - - When subdir-objects is in effect, Automake will now construct - shorter object file names when no programs and libraries name - clashes are encountered. This should make the discouraged use of - 'foo_SHORTNAME' unnecessary in many cases. - -* Bugs fixed: - - - Automatic dependency tracking has been fixed to work also when the - 'subdir-object' option is used and some 'foo_SOURCES' definition - contains unexpanded references to make variables, as in, e.g.: - - a_src = sources/libs/aaa - b_src = sources/bbb - foo_SOURCES = $(a_src)/bar.c $(b_src)/baz.c - - With such a setup, the created makefile fragment containing dependency - tracking information will be correctly placed under the directories - named 'sources/libs/aaa/.deps' and 'sources/bbb/.deps', rather than - mistakenly under directories named (literally!) '$(src_a)/.deps' and - '$(src_b)/.deps' (this was the first part of automake bug#13928). - - Notice that in order to fix this bug we had to slightly change the - semantics of how config.status bootstraps the makefile fragments - required for the dependency tracking to work: rather than attempting - to parse the Makefiles via grep and sed trickeries only, we actually - invoke 'make' on a slightly preprocessed version of those Makefiles, - using a private target that is only meant to bootstrap the required - makefile fragments. - - - The 'subdir-object' option no longer causes object files corresponding - to source files specified with an explicit '$(srcdir)' component to be - placed in the source tree rather than in the build tree. - - For example, if Makefile.am contains: - - AUTOMAKE_OPTIONS = subdir-objects - foo_SOURCES = $(srcdir)/foo.c $(srcdir)/s/bar.c $(top_srcdir)/baz.c - - then "make all" will create 'foo.o' and 's/bar.o' in $(builddir) rather - than in $(srcdir), and will create 'baz.o' in $(top_builddir) rather - than in $(top_srcdir). - - This was the second part of automake bug#13928. - - - Installed 'aclocal' m4 macros can now accept installation directories - containing '@' characters (automake bug#20903) - - - When combining AC_LIBOBJ or AC_FUNC_ALLOCA with the - "--disable-dependency-tracking" configure option in an out of source - build, the build sub-directory defined by AC_CONFIG_LIBOBJ_DIR is now - properly created. (automake bug#27781) - - - The time printed by 'mdate-sh' is now using the UTC time zone to support - the reproducible build effort. (automake bug#20314) - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.15.1: - -* Bugs fixed: - - - The code has been adapted to remove a warning present since Perl - 5.22 stating that "Unescaped left brace in regex is deprecated". - This warning has become an hard error in Perl 5.26 (bug#22372). - - - The generated Makefiles do not rely on the obsolescent GZIP - environment variable which was used for passing arguments to - 'gzip'. Compatibility with old versions has been - preserved. (bug#20132) - -* Miscellaneous changes: - - - Support the Windows version of the Intel C Compiler (icl) in the - 'compile' script in the same way the (compatible) Microsoft C - Compiler is supported. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.15: - -* Improvements and refactorings in the install-sh script: - - - It has been modernized, and now makes the following assumptions - *unconditionally*: - (1) a working 'dirname' program is available; - (2) the ${var:-value} shell parameters substitution works; - (3) the "set -f" and "set +f" shell commands work, and, respectively, - disable and enable shell globbing. - - - The script implements stricter error checking, and now it complains - and bails out if any of the following expectations is not met: - (1) the options -d and -t are never used together; - (2) the argument passed to option -t is a directory; - (3) if there are two or more SOURCEFILE arguments, the - DESTINATION argument must be a directory. - -* Automake-generated testsuites: - - - The default test-driver used by the Automake-generated testsuites - now appends the result and exit status of each "plain" test to the - associated log file (automake bug#11814). - - - The perl implementation of the TAP testsuite driver is no longer - installed in the Automake's scripts directory, and is instead just - distributed as a "contrib" addition. There should be no reason to - use this implementation anyway in real packages, since the awk+shell - implementation of the TAP driver (which is documented in the manual) - is more portable and has feature parity with the perl implementation. - - - The rule generating 'test-suite.log' no longer risk incurring in an - extra useless "make all" recursive invocation in some corner cases - (automake bug#16302). - -* Distribution: - - - Automake bug#18286: "make distcheck" could sometimes fail to detect - files missing from the distribution tarball, especially in those cases - where both the generated files and their dependencies are explicitly - in $(srcdir). An important example of this are *generated* makefile - fragments included at Automake time in Makefile.am; e.g.: - - ... - $(srcdir)/fragment.am: $(srcdir)/data.txt $(srcdir)/preproc.sh - cd $(srcdir) && $(SHELL) preproc.sh fragment.am - include $(srcdir)/fragment.am - ... - - If the use forgot to add data.txt and/or preproc.sh in the distribution - tarball, "make distcheck" would have erroneously succeeded! This issue - is now fixed. - - - As a consequence of the previous change, "make distcheck" will run - using '$(distdir)/_build/sub' as the build directory, rather than - simply '$(distdir)/_build' (as it was the case for Automake 1.14 and - earlier). Consequently, the './configure' and 'make' invocations - issued by the distcheck recipe now have $(srcdir) equal to '../..', - rather than to just '..'. Dependent and similar variables (e.g., - '$(top_srcdir)') are also changed accordingly. - - Thus, Makefiles that made assumptions about the exact values of the - build and source directories used by "make distcheck" will have to - be adjusted. Notice that making such assumptions was a bad and - unsupported practice anyway, since the exact locations of those - directories should be considered implementation details, and we - reserve the right to change them at any time. - -* Miscellaneous bugs fixed: - - - The expansion of AM_INIT_AUTOMAKE ends once again with a trailing - newline (bug#16841). Regression introduced in Automake 1.14. - - - We no longer risk to use '$ac_aux_dir' before it's defined (see - automake bug#15981). Bug introduced in Automake 1.14. - - - The code used to detect whether the currently used make is GNU make - or not (relying on the private macro 'am__is_gnu_make') no longer - risks causing "Arg list too long" for projects using automatic - dependency tracking and having a ton of source files (bug#18744). - - - Automake tries to offer a more deterministic output for generated - Makefiles, in the face of the newly-introduced randomization for - hash keys order in Perl 5.18. - - - In older Automake versions, if a user defined one single Makefile - fragment (say 'foo.am') to be included via Automake includes in - his main Makefile.am, and defined a custom make rule to generate that - file from other data, Automake used to spuriously complain with some - message like "... overrides Automake target '$(srcdir)/foo.am". - This bug is now fixed. - - - The user can now extend the special .PRECIOUS target, the same way - he could already do with the .MAKE .and .PHONY targets. - - - Some confusing typos have been fixed in the manual and in few warning - messages (automake bug#16827 and bug#16997). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.14.1: - -* Bugs fixed: - - - The user is no longer allowed to override the --srcdir nor the --prefix - configure options used by "make distcheck" (bug#14991). - - - Fixed a gross inefficiency in the recipes for installing byte-compiled - python files, that was causing an O(N^2) performance on the number N of - files, instead of the expected O(N) performance. Note that this bug - was only relevant when the number of python files was high (which is - unusual in practice). - - - Automake try to offer a more deterministic output for warning messages, - in the face of the newly-introduced randomization for hash keys order - in Perl 5.18. - - - The 'test-driver' script now actually error out with a clear error - message on the most common invalid usages. - - - Several spurious failures/hangs in the testsuite (bugs #14706, #14707, - #14760, #14911, #15181, #15237). - -* Documentation fixes: - - - Fixed typos in the 'fix-timestamp.sh' example script that made it - nonsensical. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.14: - -* C compilation, and the AC_PROG_CC and AM_PROG_CC_C_O macros: - - - The 'compile' script is now unconditionally required for all packages - that perform C compilation (if you are using the '--add-missing' - option, automake will fetch that script for you, so you shouldn't - need any explicit adjustment). This new behaviour is needed to avoid - obscure errors when the 'subdir-objects' option is used, and the - compiler is an inferior one that doesn't grasp the combined use of - both the "-c -o" options; see discussion about automake bug#13378 for - more details: - - - - - The next major Automake version (2.0) will unconditionally activate - the 'subdir-objects' option. In order to smooth out the transition, - we now give a warning (in the category 'unsupported') whenever a - source file is present in a subdirectory but the 'subdir-object' is - not enabled. For example, the following usage will trigger such a - warning: - - bin_PROGRAMS = sub/foo - sub_foo_SOURCES = sub/main.c sub/bar.c - - - Automake will automatically enhance the autoconf-provided macro - AC_PROG_CC to force it to check, at configure time, that the - C compiler supports the combined use of both the '-c' and '-o' - options. The result of this check is saved in the cache variable - 'am_cv_prog_cc_c_o', and said result can be overridden by - pre-defining that variable. - - - The AM_PROG_CC_C_O macro can still be called, albeit that should no - longer be necessary. This macro is now just a thin wrapper around the - Automake-enhanced AC_PROG_CC. This means, among the other things, - that its behaviour is changed in three ways: - - 1. It no longer invokes the Autoconf-provided AC_PROG_CC_C_O - macro behind the scenes. - - 2. It caches the check result in the 'am_cv_prog_cc_c_o' variable, - and not in a 'ac_cv_prog_cc_*_c_o' variable whose exact name is - dynamically computed only at configure runtime (really!) from - the content of the '$CC' variable. - - 3. It no longer automatically AC_DEFINE the C preprocessor - symbol 'NO_MINUS_C_MINUS_O'. - -* Texinfo support: - - - Automake can now be instructed to place '.info' files generated from - Texinfo input in the builddir rather than in the srcdir; this is done - specifying the new automake option 'info-in-builddir'. This feature - was requested by the developers of GCC, GDB, GNU binutils and the GNU - bfd library. See the extensive discussion about automake bug#11034 - for more details. - - - For quite a long time, Automake has been implementing an undocumented - hack which ensured that '.info' files which appeared to be cleaned - (by being listed in the CLEANFILES or DISTCLEANFILES variables) were - built in the builddir rather than in the srcdir; this hack was - introduced to ensure better backward-compatibility with package - such as Texinfo, which do things like: - - info_TEXINFOS = texinfo.txi info-stnd.texi info.texi - DISTCLEANFILES = texinfo texinfo-* info*.info* - # Do not create info files for distribution. - dist-info: - @: - - in order not to distribute generated '.info' files. - - Now that we have the 'info-in-builddir' option that explicitly causes - generated '.info' files to be placed in the builddir, this hack should - be longer necessary, so we deprecate it with runtime warnings. - It will be removed altogether in Automake 2.0. - -* Relative directory in Makefile fragments: - - - The special Automake-time substitutions '%reldir%' and '%canon_reldir%' - (and their short versions, '%D%' and '%C%' respectively) can now be used - in an included Makefile fragment. The former is substituted with the - relative directory of the included fragment (compared to the top-level - including Makefile), and the latter with the canonicalized version of - the same relative directory. - - # in 'Makefile.am': - bin_PROGRAMS = # will be updated by included Makefile fragments - include src/Makefile.inc - - # in 'src/Makefile.inc': - bin_PROGRAMS += %reldir%/foo - %canon_reldir%_foo_SOURCES = %reldir%/bar.c - - This should be especially useful for packages using a non-recursive - build system. - -* Deprecated distribution formats: - - - The 'shar' and 'compress' distribution formats are deprecated, and - scheduled for removal in Automake 2.0. Accordingly, the use of the - 'dist-shar' and 'dist-tarZ' will cause warnings at automake runtime - (in the 'obsolete' category), and the recipes of the Automake-generated - targets 'dist-shar' and 'dist-tarZ' will unconditionally display - (non-fatal) warnings at make runtime. - -* New configure runtime warnings about "rm -f" support: - - - To simplify transition to Automake 2.0, the shell code expanded by - AM_INIT_AUTOMAKE now checks (at configure runtime) that the default - 'rm' program in PATH doesn't complain when called without any - non-option argument if the '-f' option is given (so that commands like - "rm -f" and "rm -rf" act as a no-op, instead of raising usage errors). - If this is not the case, the configure script is aborted, to call the - attention of the user on the issue, and invite him to fix his PATH. - The checked 'rm' behavior is very widespread in the wild, and will be - required by future POSIX versions: - - - - The user can still force the configure process to complete even in the - presence of a broken 'rm' by defining the ACCEPT_INFERIOR_RM_PROGRAM - environment variable to "yes". And the generated Makefiles should - still work correctly even when such broken 'rm' is used. But note - that this will no longer be the case with Automake 2.0 though, so, if - you encounter the warning, please report it to us ASAP (and try to fix - your environment as well). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.13.4: - -* Bugs fixed: - - - Fix a minor regression introduced in Automake 1.13.3: when two or more - user-defined suffix rules were present in a single Makefile.am, - automake would needlessly include definition of some make variables - related to C compilation in the generated Makefile.in (bug#14560). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.13.3: - -* Documentation fixes: - - - The documentation no longer mistakenly reports that the obsolete - 'AM_MKDIR_PROG_P' macro and '$(mkdir_p)' make variable are going - to be removed in Automake 2.0. - -* Bugs fixed: - - - Byte-compilation of Emacs lisp files could fail spuriously on - Solaris, when /bin/ksh or /usr/xpg4/bin/sh were used as shell. - - - If the same user-defined suffixes were transformed into different - Automake-known suffixes in different Makefile.am files in the same - project, automake could get confused and generate inconsistent - Makefiles (automake bug#14441). - For example, if 'Makefile.am' contained a ".ext.cc:" suffix rule, - and 'sub/Makefile.am' contained a ".ext.c:" suffix rule, automake - would have mistakenly placed into 'Makefile.in' rules to compile - "*.c" files into object files, and into 'sub/Makefile.in' rules to - compile "*.cc" files into object files --- rather than the other - way around. This is now fixed. - -* Testsuite work: - - - The test cases no longer have the executable bit set. This should - make it clear that they are not meant to be run directly; as - explained in t/README, they can only be run through the custom - 'runtest' script, or by a "make check" invocation. - - - The testsuite has seen the introduction of a new helper function - 'run_make', and several related changes. These serve a two-fold - purpose: - - 1. Remove brittleness due to the use of "make -e" in test cases. - - 2. Seamlessly allow the use of parallel make ("make -j...") in the - test cases, even where redirection of make output is involved - (see automake bug#11413 for a description of the subtle issues - in this area). - - - Several spurious failures have been fixed (they hit especially - MinGW/MSYS builds). See automake bugs #14493, #14494, #14495, - #14498, #14499, #14500, #14501, #14517 and #14528. - - - Some other minor miscellaneous changes and fixlets. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.13.2: - -* Documentation fixes: - - - The long-deprecated but still supported two-arguments invocation form - of AM_INIT_AUTOMAKE is documented once again. This seems the sanest - thing to do, given that support for such usage might need to remain - in place for an unspecified amount of time in order to cater to people - who want to define the version number for their package dynamically at - configure runtime (unfortunately, Autoconf does not yet support this - scenario, so we cannot delegate the work to it). - - - The serial testsuite harness is no longer reported as "deprecated", - but as "discouraged". We have no plan to remove it, nor to make its - use cause runtime warnings. - - - The parallel testsuite is no longer reported as "experimental"; it - is well tested, and should be stable now. - - - The 'shar' and 'tarZ' distribution formats and the 'dist-shar' and - 'dist-tarZ' options are obsolescent, and their use is deprecated - in the documentation. - - - Other minor miscellaneous fixes and improvements; in particular, - some improvements in cross-references. - -* Obsolescent features: - - - Use of suffix-less info files (that can be specified through the - '@setfilename' macro in Texinfo input files) is discouraged, and - its use will raise warnings in the 'obsolete' category. Simply - use the '.info' extension for all your info files, transforming - usages like: - - @setfilename myprogram - - into: - - @setfilename myprogram.info - - - Use of Texinfo input files with '.txi' or '.texinfo' extensions - is discouraged, and its use will raise warnings in the 'obsolete' - category. You are advised to simply use the '.texi' extension - instead. - -* Bugs fixed: - - - When the 'ustar' option is used, the generated configure script no - longer risks hanging during the tests for the availability of the - 'pax' utility, even if the user running configure has a UID or GID - that requires more than 21 bits to be represented. - See automake bug#8343 and bug#13588. - - - The obsolete macros AM_CONFIG_HEADER or AM_PROG_CC_STDC work once - again, as they did in Automake 1.12.x (albeit printing runtime - warnings in the 'obsolete' category). Removing them has turned - out to be a very bad idea, because it complicated distro packing - enormously. Making them issue fatal warnings, as we did in - Automake 1.13, has turned out to be a similarly very bad idea, - for exactly the same reason. - - - aclocal will no longer error out if the first local m4 directory - (as specified by the '-I' option or the 'AC_CONFIG_MACRO_DIRS' or - 'AC_CONFIG_MACRO_DIR' macros) doesn't exist; it will merely report - a warning in the 'unsupported' category. This is done to support - some pre-existing real-world usages. See automake bug#13514. - - - aclocal will no longer consider directories for extra m4 files more - than once, even if they are specified multiple times. This ensures - packages that specify both - - AC_CONFIG_MACRO_DIR([m4]) in configure.ac - ACLOCAL_AMFLAGS = -I m4 in Makefile.am - - will work correctly, even when the 'm4' directory contains no - package-specific files, but is used only to install third-party - m4 files (as can happen with e.g., "libtoolize --install"). - See automake bug#13514. - - - Analysis of make flags in Automake-generated rules has been made more - robust, and more future-proof. For example, in presence of make that - (like '-I') take an argument, the characters in said argument will no - longer be spuriously considered as a set of additional make options. - In particular, automake-generated rules will no longer spuriously - believe to be running in dry mode ("make -n") if run with an invocation - like "make -I noob"; nor will they believe to be running in keep-going - mode ("make -k") if run with an invocation like "make -I kool" - (automake bug#12554). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.13.1: - -* Bugs fixed: - - - Use of the obsolete macros AM_CONFIG_HEADER or AM_PROG_CC_STDC now - causes a clear and helpful error message, instead of obscure ones - (issue introduced in Automake 1.13). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.13: - -* Bugs fixed: - - - ylwrap renames properly header guards in generated header files - (*.h), instead of leaving Y_TAB_H. - - - ylwrap now also converts header guards in implementation files - (*.c). Because ylwrap failed to rename properly #include in the - implementation files, current versions of Bison (e.g., 2.7) - duplicate the generated header file in the implementation file. - The header guard then protects the implementation file from - duplicate definitions from the header file. - -* Version requirements: - - - Autoconf 2.65 or greater is now required. - - - The rules to build PDF and DVI output from Texinfo input now - require Texinfo 4.9 or later. - -* Obsolete features: - - - Support for the "Cygnus-style" trees (once enabled by the 'cygnus' - option) has been removed. See discussion about automake bug#11034 - for more background: . - - - The deprecated aclocal option '--acdir' has been removed. You - should use the options '--automake-acdir' and '--system-acdir' - instead (which have been introduced in Automake 1.11.2). - - - The following long-obsolete m4 macros have been removed: - - AM_PROG_CC_STDC: superseded by AC_PROG_CC since October 2002 - fp_PROG_CC_STDC: broken alias for AM_PROG_CC_STDC - fp_WITH_DMALLOC: old alias for AM_WITH_DMALLOC - AM_CONFIG_HEADER: superseded by AC_CONFIG_HEADERS since July 2002 - ud_PATH_LISPDIR: old alias for AM_PATH_LISPDIR - jm_MAINTAINER_MODE: old alias for AM_MAINTAINER_MODE - ud_GNU_GETTEXT: old alias for AM_GNU_GETTEXT - gm_PROG_LIBTOOL: old alias for AC_PROG_LIBTOOL - fp_C_PROTOTYPES: old alias for AM_C_PROTOTYPES (which was part - of the now-removed automatic de-ANSI-fication - support of Automake) - - - All the "old alias" macros in 'm4/obsolete.m4' have been removed. - - - Use of the long-deprecated two- and three-arguments invocation forms - of the AM_INIT_AUTOMAKE is no longer documented. It's still supported - though (albeit with a warning in the 'obsolete' category), to cater - for people who want to define the version number for their package - dynamically (e.g., from the current VCS revision). We'll have to - continue this support until Autoconf itself is fixed to allow better - support for such dynamic version numbers. - -* Elisp byte-compilation: - - - The byte compilation of '.el' files into '.elc' files is now done - with a suffix rule. This has simplified the compilation process, and - more importantly made it less brittle. The downside is that emacs is - now invoked once for each '.el' files, which cause some noticeable - slowdowns. These should however be mitigated on multicore machines - (which are becoming the norm today) if concurrent make ("make -j") - is used. - - - Elisp files placed in a subdirectory are now byte-compiled to '.elc' - files in the same subdirectory; for example, byte-compiling of file - 'sub/foo.el' file will result in 'sub/foo.elc' rather than in - 'foo.elc'. This behaviour is backward-incompatible with older - Automake versions, but it is more natural and more sane. See also - automake bug#7441. - - - The Emacs invocation performing byte-compilation of '.el' files honors - the $(AM_ELCFLAGS) and $(ELCFLAGS) variables; as typical, the former - one is developer-reserved and the latter one user-reserved. - - - The 'elisp-comp' script, once provided by Automake, has been rendered - obsoleted by the just-described changes, and thus removed. - -* Changes to Automake-generated testsuite harnesses: - - - The parallel testsuite harness (previously only enabled by the - 'parallel-tests' option) is the default one; the older serial - testsuite harness will still be available through the use of the - 'serial-tests' option (introduced in Automake 1.12). - - - The 'color-tests' option is now unconditionally activated by default. - In particular, this means that testsuite output is now colorized by - default if the attached terminal seems to support ANSI escapes, and - that the user can force output colorization by setting the variable - AM_COLOR_TESTS to "always". The 'color-tests' is still recognized - for backward-compatibility, although it's a handled as a no-op now. - -* Silent rules support: - - - Support for silent rules is now always active in Automake-generated - Makefiles. So, although the verbose output is still the default, - the user can now always use "./configure --enable-silent-rules" or - "make V=0" to enable quieter output in the package he's building. - - - The 'silent-rules' option has now become a no-op, preserved for - backward-compatibility only. In particular, its use no longer - disables the warnings in the 'portability-recursive' category. - -* Texinfo Support: - - - The rules to build PDF and DVI files from Texinfo input now require - Texinfo 4.9 or later. - - - The rules to build PDF and DVI files from Texinfo input now use the - '--build-dir' option, to keep the auxiliary files used by texi2dvi - and texi2pdf around without cluttering the build directory, and to - make it possible to run the "dvi" and "pdf" recipes in parallel. - -* Automatic remake rules and 'missing' script: - - - The 'missing' script no longer tries to update the timestamp of - out-of-date files that require a maintainer-specific tool to be - remade, in case the user lacks such a tool (or has a too-old version - of it). It just gives a useful warning, and in some cases also a - tip about how to obtain such a tool. - - - The missing script has thus become useless as a (poor) way to work - around the sketched-timestamps issues that can happen for projects - that keep generated files committed in their VCS repository. Such - projects are now encouraged to write a custom "fix-timestamps.sh" - script to avoid such issues; a simple example is provided in the - "CVS and generated files" chapter of the automake manual. - -* Recursive targets: - - - The user can now define his own recursive targets that recurse - in the directories specified in $(SUBDIRS). This can be done by - specifying the name of such targets in invocations of the new - 'AM_EXTRA_RECURSIVE_TARGETS' m4 macro. - -* Tags: - - - Any failure in the recipe of the "tags", "ctags", "cscope" or - "cscopelist" targets in a subdirectory is now propagated to the - top-level make invocation. - - - Tags are correctly computed also for files in _SOURCES variables that - only list files with non-standard suffixes (see automake bug#12372). - -* Improvements to aclocal and related rebuilds rules: - - - Autoconf-provided macros AC_CONFIG_MACRO_DIR and AC_CONFIG_MACRO_DIRS - are now traced by aclocal, and can be used to declare the local m4 - include directories. Formerly, one had to specify it with an explicit - '-I' option to the 'aclocal' invocation. - - - The special make variable ACLOCAL_AMFLAGS is deprecated; future - Automake versions will warn about its use, and later version will - remove support for it altogether. - -* The depcomp script: - - - Dropped support for libtool 1.4. - - - Various internal refactorings. They should cause no visible change, - but the chance for regression is there anyway, so please report any - unexpected or suspicious behaviour. - - - Support for pre-8.0 versions of the Intel C Compiler has been dropped. - This should cause no problem, since icc 8.0 has been released in - December 2003 -- almost nine years ago. - - - Support for tcc (the Tiny C Compiler) has been improved, and is now - handled through a dedicated 'tcc' mode. - -* The ylwrap script: - - - ylwrap generates header guards with a single '_' for series of non - alphabetic characters, instead of several. This is what Bison >= - 2.5.1 does. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Bugs fixed in 1.12.6: - -* Python-related bugs: - - - The default installation location for python modules has been improved - for Python 3 on Debian and Ubuntu systems, changing from: - - ${prefix}/lib/python3/dist-packages - - to - - ${prefix}/lib/python3.x/site-packages - - This change should ensure modules installed using the default ${prefix} - "/usr/local" are found by default by system python 3.x installations. - See automake bug#10227. - - - Python byte-compilation supports the new layout mandated by PEP-3147, - with its __pycache__ directory (automake bug#8847). - -* Build system issues: - - - The maintainer rebuild rules for Makefiles and aclocal.m4 in - Automake's own build system works correctly again (bug introduced - in Automake 1.12.5). - -* Testsuite issues: - - - The Vala-related tests has been changed to adjust to the removal of - the 'posix' profile in the valac compiler. See automake bug#12934 - a.k.a. bug#12522. - - - Some spurious testsuite failures related to older tools and systems - have been fixed. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.12.5: - -* Vala support: - - - The AM_PROG_VALAC macro has been enhanced to takes two further - optional arguments; it's signature now being - - AM_PROG_VALAC([MINIMUM-VERSION], [ACTION-IF-FOUND], - [ACTION-IF-NOT-FOUND]) - - - By default, AM_PROG_VALAC no longer aborts the configure invocation - if the Vala compiler found is too old, but simply prints a warning - messages (as it did when the Vala compiler was not found). This - should avoid unnecessary difficulties for end users that just want - to compile the unmodified, distributed Vala-generated C sources, - but happens to have an old Vala compiler in their PATH. This fixes - automake bug#12688. - - - If no proper Vala compiler is found at configure runtime, AM_PROG_VALAC - will set the AC_SUBST'd variable 'VALAC' to 'valac' rather than to ':'. - This is a better default, because with it a triggered makefile rule - invoking a Vala compilation will clearly fail with an informative error - message like "valac: command not found", rather than silently, with - the error possibly going unnoticed or triggering harder-to-diagnose - fallout failures in later steps. - -* Miscellaneous changes: - - - automake and aclocal no longer honours the 'perllibdir' environment - variable. That had always been intended only as an hack required in - the testsuite, not meant for any use beyond that. - -Bugs fixed in 1.12.5: - -* Long-standing bugs: - - - Automake no longer generates spurious remake rules invoking autoheader - to regenerate the template corresponding to header files specified after - the first one in AC_CONFIG_HEADERS (automake bug#12495). - - - When wrapping Microsoft tools, the 'compile' script falls back to - finding classic 'libname.a' style libraries when 'name.lib' and - 'name.dll.lib' aren't available. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.12.4: - -* Warnings and deprecations: - - - Warnings in the 'obsolete' category are enabled by default both in - automake and aclocal. - -* Miscellaneous changes: - - - Some testsuite weaknesses and spurious failures have been fixed. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.12.3: - -* Miscellaneous changes: - - - The '.m4' files provided by Automake no longer define serial numbers. - This should cause no difference in the behaviour of aclocal though. - - - Some testsuite weaknesses and spurious failures have been fixed. - - - There is initial support for automatic dependency tracking with the - Portland Group C/C++ compilers, thanks to the new new depmode 'pgcc'. - -Bugs fixed in 1.12.3: - -* Long-standing bugs: - - - Instead of renaming only self-references of files (typically for - #lines), ylwrap now also renames references to the other generated - files. This fixes support for GLR and C++ parsers from Bison (PR - automake/491 and automake bug#7648): 'parser.c' now properly - #includes 'parser.h' instead of 'y.tab.h'. - - - Generated files unknown to ylwrap are now preserved. This fixes - C++ support for Bison (automake bug#7648): location.hh and the - like are no longer discarded. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.12.2: - -* Warnings and deprecations: - - - Automake now issues a warning (in the 'portability' category) if - 'configure.in' is used instead of 'configure.ac' as the Autoconf - input file. Such a warning will also be present in the next - Autoconf version (2.70). - -* Cleaning rules: - - - Recursive cleaning rules descends into the $(SUBDIRS) in the natural - order (as done by the other recursive rules), rather than in the - inverse order. They used to do that in order to work a round a - limitation in an older implementation of the automatic dependency - tracking support, but that limitation had been lifted years ago - already, when the automatic dependency tracking based on side-effects - of compilation had been introduced. - - - Cleaning rules for compiled objects (both "plain" and libtool) work - better when subdir objects are involved, not triggering a distinct - 'rm' invocation for each such object. They do so by removing *any* - compiled object file that is in the same directory of a subdir - object. See automake bug#10697. - -* Silent rules support: - - - A new predefined $(AM_V_P) make variable is provided; it expands - to a shell conditional that can be used in recipes to know whether - make is being run in silent or verbose mode. - -Bugs fixed in 1.12.2: - -* SECURITY VULNERABILITIES! - - - The 'distcheck' recipe no longer grants temporary world-write - permissions on the extracted distdir. Even if such rights were - only granted for a vanishingly small time window, the implied - race condition proved to be enough to allow a local attacker - to run arbitrary code with the privileges of the user running - "make distcheck". This is CVE-2012-3386. - -* Long-standing bugs: - - - The "recheck" targets behaves better in the face of build failures - related to previously failed tests. For example, if a test is a - compiled program that must be rerun by "make recheck", and its - compilation fails, it will still be rerun by further "make recheck" - invocations. See automake bug#11791. - -* Bugs introduced by 1.12.1: - - - Automake provides once again the '$(mkdir_p)' make variable and the - '@mkdir_p@' substitution (both as simple aliases for '$(MKDIR_P)'), - for better backward-compatibility. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.12.1: - -* New supported languages: - - - Support for Objective C++ has been added; it should work similarly to - the support for Objective C. - -* Deprecated obsolescent features: - - - Use of the long-deprecated two- and three-arguments invocation forms - of the AM_INIT_AUTOMAKE macro now elicits a warning in the 'obsolete' - category. Starting from some future major Automake release (likely - post-1.13), such usages will no longer be allowed. - - - Support for the "Cygnus-style" trees (enabled by the 'cygnus' option) is - now deprecated (its use triggers a warning in the 'obsolete' category). - It will be removed in the next major Automake release (1.13). - - - The long-obsolete (since 1.10) automake-provided $(mkdir_p) make - variable, @mkdir_p@ configure-time substitution and AM_PROG_MKDIR - m4 macro are deprecated, eliciting a warning in the 'obsolete' - category. - -* Miscellaneous changes: - - - The Automake test cases now require a proper POSIX-conforming shell. - Older non-POSIX Bourne shells (like Solaris 10 /bin/sh) will no longer - be accepted. In most cases, the user shouldn't have to specify such - POSIX shell explicitly, since it will be looked up at configure time. - Still, when this lookup fails, or when the user wants to override its - conclusion, the variable 'AM_TEST_RUNNER_SHELL' can be used (pointing - to the shell that will be used to run the Automake test cases). - -Bugs fixed in 1.12.1: - -* Bugs introduced by 1.12: - - - Several weaknesses in Automake's own build system and test suite - have been fixed. - -* Bugs introduced by 1.11.3: - - - When given non-option arguments, aclocal rejects them, instead of - silently ignoring them. - -* Long-standing bugs: - - - When the 'color-tests' option is in use, forcing of colored testsuite - output through "AM_COLOR_TESTS=always" works even if the terminal is - a non-ANSI one, i.e., if the TERM environment variable has a value of - "dumb". - - - Several inefficiencies and poor performances in the implementation - of the parallel-tests 'check' and 'recheck' targets have been fixed. - - - The post-processing of output "#line" directives done the ylwrap - script is more faithful w.r.t. files in a subdirectory; for example, - if the processed file is "src/grammar.y", ylwrap will correctly - produce directives like: - #line 7 "src/grammar.y" - rather than like - #line 7 "grammar.y" - as it did before. - -* Bugs with new Perl versions: - - - Aclocal works correctly with perl 5.16.0 (automake bug#11543). - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.12: - -* Obsolete features removed: - - - The never documented nor truly used script 'acinstall' has been - removed. - - - Support for automatic de-ANSI-fication has been removed. - - - The support for the "obscure" multilib feature has been removed - from Automake core (but remains available in the 'contrib/' - directory of the Automake distribution). - - - Support for ".log -> .html" conversion and the check-html and - recheck-html targets has been removed from Automake core (but - remains available in the 'contrib/' directory of the Automake - distribution). - - - The deprecated 'lzma' compression format for distribution archives - has been removed, in favor of 'xz' and 'lzip'. - - - The obsolete AM_WITH_REGEX macro has been removed. - - - The long-deprecated options '--output-dir', '--Werror' and - '--Wno-error' have been removed. - - - The chapter on the history of Automake has been moved out of the - reference manual, into a new dedicated Texinfo file. - -* New targets: - - - New 'cscope' target to build a cscope database for the source tree. - -* Changes to Automake-generated testsuite harnesses: - - - The new automake option 'serial-tests' has been introduced. It can - be used to explicitly instruct automake to use the older serial - testsuite harness. This is still the default at the moment, but it - might change in future versions. - - - The 'recheck' target (provided by the parallel testsuite harness) now - depends on the 'all' target. This allows for a better user-experience - in test-driven development. See automake bug#11252. - - - Test scripts that exit with status 99 to signal an "hard error" (e.g., - and unexpected or internal error, or a failure to set up the test case - scenario) have their outcome reported as an 'ERROR' now. Previous - versions of automake reported such an outcome as a 'FAIL' (the only - difference with normal failures being that hard errors were counted - as failures even when the test originating them was listed in - XFAIL_TESTS). - - - The testsuite summary displayed by the parallel-test harness has a - completely new format, that always list the numbers of passed, failed, - xfailed, xpassed, skipped and errored tests, even when these numbers - are zero (but using smart coloring when the color-tests option is in - effect). - - - The default testsuite driver offered by the 'parallel-tests' option is - now implemented (partly at least) with the help of automake-provided - auxiliary scripts (e.g., 'test-driver'), instead of relying entirely - on code in the generated Makefile.in. - This has two noteworthy implications. The first one is that projects - using the 'parallel-tests' option should now either run automake with - the '--add-missing' option, or manually copy the 'test-driver' script - into their tree. The second, and more important, implication is that - now, when the 'parallel-tests' option is in use, TESTS_ENVIRONMENT can - no longer be used to define a test runner, and the command specified - in LOG_COMPILER (and _LOG_COMPILER) must be a *real* executable - program or script. For example, this is still a valid usage (albeit - a little contorted): - - TESTS_ENVIRONMENT = \ - if test -n '$(STRICT_TESTS)'; then \ - maybe_errexit='-e'; \ - else \ - maybe_errexit=''; \ - fi; - LOG_COMPILER = $(SHELL) $$maybe_errexit - - OTOH, this is no longer a valid usage: - - TESTS_ENVIRONMENT = \ - $(SHELL) `test -n '$(STRICT_TESTS_CHECKING)' && echo ' -e'` - - neither is this: - - TESTS_ENVIRONMENT = \ - run_with_perl_or_shell () \ - { \ - if grep -q '^#!.*perl' $$1; then - $(PERL) $$1; \ - else \ - $(SHELL) $$1; \ - fi; \ - } - LOG_COMPILER = run_with_perl_or_shell - - - The package authors can now use customary testsuite drivers within - the framework provided by the 'parallel-tests' testsuite harness. - Consistently with the existing syntax, this can be done by defining - special makefile variables 'LOG_DRIVER' and '_LOG_DRIVER'. - - - A new developer-reserved variable 'AM_TESTS_FD_REDIRECT' can be used - to redirect/define file descriptors used by the test scripts. - - - The parallel-tests harness generates now, in addition the '.log' files - holding the output produced by the test scripts, a new set of '.trs' - files, holding "metadata" derived by the execution of the test scripts; - among such metadata are the outcomes of the test cases run by a script. - - - Initial and still experimental support for the TAP test protocol is - now provided. - -* Changes to Yacc and Lex support: - - - C source and header files derived from non-distributed Yacc and/or - Lex sources are now removed by a simple "make clean" (while they were - previously removed only by "make maintainer-clean"). - - - Slightly backward-incompatible change, relevant only for use of Yacc - with C++: the extensions of the header files produced by the Yacc - rules are now modelled after the extension of the corresponding - sources. For example, yacc files named "foo.y++" and "bar.yy" will - produce header files named "foo.h++" and "bar.hh" respectively, where - they would have previously produced header files named simply "foo.h" - and "bar.h". This change offers better compatibility with 'bison -o'. - -* Miscellaneous changes: - - - The AM_PROG_VALAC macro now causes configure to exit with status 77, - rather than 1, if the vala compiler found is too old. - - - The build system of Automake itself now avoids the use of make - recursion as much as possible. - - - Automake now prefers to quote 'like this' or "like this", rather - than `like this', in diagnostic message and generated Makefiles, - to accommodate the new GNU Coding Standards recommendations. - - - Automake has a new option '--print-libdir' that prints the path of the - directory containing the Automake-provided scripts and data files. - - - The 'dist' and 'dist-all' targets now can run compressors in parallel. - - - The rules to create pdf, dvi and ps output from Texinfo files now - works better with modern 'texi2dvi' script, by explicitly passing - it the '--clean' option to ensure stray auxiliary files are not - left to clutter the build directory. - - - Automake can now generate silenced rules for texinfo outputs. - - - Some auxiliary files that are automatically distributed by Automake - (e.g., 'install-sh', or the 'depcomp' script for packages compiling - C sources) might now be listed in the DIST_COMMON variable in many - Makefile.in files, rather than in the top-level one. - - - Messages of types warning or error from 'automake' and 'aclocal' - are now prefixed with the respective type, and presence of -Werror - is noted. - - - Automake's early configure-time sanity check now tries to avoid - sleeping for a second, which slowed down cached configure runs - noticeably. In that case, it will check back at the end of the - configure script to ensure that at least one second has passed, to - avoid time stamp issues with makefile rules rerunning autotools - programs. - - - The warnings in the category 'extra-portability' are now enabled by - '-Wall'. In previous versions, one has to use '-Wextra-portability' - to enable them. - -Bugs fixed in 1.12: - - - Various minor bugfixes for recent or long-standing bugs. - -* Bugs introduced by 1.11: - - - The AM_COND_IF macro also works if the shell expression for the - conditional is no longer valid for the condition. - - - The automake-provided parallel testsuite harness no longer fails - with BSD make used in parallel mode when there are test scripts in - a subdirectory, like in: - - TESTS = sub/foo.test sub/bar.test - -* Long-standing bugs: - - - Automake's own build system finally have a real "installcheck" target. - - - Vala-related cleanup rules are now more complete, and work better in - a VPATH setup. - - - Files listed with the AC_REQUIRE_AUX_FILE macro in configure.ac are - now automatically distributed also if the directory of the auxiliary - files coincides with the top-level directory. - - - Automake now detects the presence of the '-d' flag in the various - '*YFLAGS' variables even when their definitions involve indirections - through other variables, such as in: - foo_opts = -d - AM_YFLAGS = $(foo_opts) - - - Automake now complains if a '*YFLAGS' variable has any conditional - content, not only a conditional definition. - - - Explicit enabling and/or disabling of Automake warning categories - through the '-W...' options now always takes precedence over the - implicit warning level implied by Automake strictness (foreign, gnu - or gnits), regardless of the order in which such strictness and - warning flags appear. For example, a setting like: - AUTOMAKE_OPTIONS = -Wall --foreign - will cause the warnings in category 'portability' to be enabled, even - if those warnings are by default disabled in 'foreign' strictness. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Bugs fixed in 1.11.5: - -* Bugs introduced by 1.11.3: - - - Vala files with '.vapi' extension are now recognized and handled - correctly again. See automake bug#11222. - - - Vala support work again for projects that contain some program - built from '.vala' (and possibly '.c') sources and some other - program built from '.c' sources *only*. See automake bug#11229. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.11.4: - -* Miscellaneous changes: - - - The 'ar-lib' script now ignores the "s" (symbol index) and "S" (no - symbol index) modifiers as well as the "s" action, as the symbol index - is created unconditionally by Microsoft lib. Also, the "q" (quick) - action is now a synonym for "r" (replace). Also, the script has been - ignoring the "v" (verbose) modifier already since Automake 1.11.3. - - - When the 'compile' script is used to wrap MSVC, it now accepts an - optional space between the -I, -L and -l options and their respective - arguments, for better POSIX compliance. - - - There is an initial, experimental support for automatic dependency - tracking with tcc (the Tiny C Compiler). Its associated depmode is - currently recognized as "icc" (but this and other details are likely - to change in future versions). - - - Automatic dependency tracking now works also with the IBM XL C/C++ - compilers, thanks to the new new depmode 'xlc'. - -Bugs fixed in 1.11.4: - -* Bugs introduced by 1.11.2: - - - A definition of 'noinst_PYTHON' before 'python_PYTHON' (or similar) - no longer cause spurious failures upon "make install". - - - The user can now instruct the 'uninstall-info' rule not to update - the '${infodir}/dir' file by exporting the environment variable - 'AM_UPDATE_INFO_DIR' to the value "no". This is done for consistency - with how the 'install-info' rule operates since automake 1.11.2. - -* Long-standing bugs: - - - It is now possible for a foo_SOURCES variable to hold Vala sources - together with C header files, as well as with sources and headers for - other supported languages (e.g., C++). Previously, only mixing C and - Vala sources was supported. - - - If "aclocal --install" is used, and the first directory specified with - '-I' is non-existent, aclocal will now create it before trying to copy - files in it. - - - An empty declaration of a "foo_PRIMARY" no longer cause the generated - install rules to create an empty $(foodir) directory; for example, if - Makefile.am contains something like: - - pkglibexec_SCRIPTS = - if FALSE - pkglibexec_SCRIPTS += bar.sh - endif - - the $(pkglibexec) directory will not be created upon "make install". - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.11.3: - -* Miscellaneous changes: - - - Automake's own build system is more silent by default, making use of - the 'silent-rules' option. - - - The master copy of the 'gnupload' script is now maintained in gnulib, - not in automake. - - - The 'missing' script no longer tries to wrap calls to 'tar'. - - - "make dist" no longer wraps 'tar' invocations with the 'missing' - script. Similarly, the obsolescent variable '$(AMTAR)' (which you - shouldn't be using BTW ;-) no longer invokes the 'missing' script - to wrap tar, but simply invokes the 'tar' program itself. - - - "make dist" can now create lzip-compressed tarballs. - - - In the Automake info documentation, the Top node and the nodes about - the invocation of the automake and aclocal programs have been renamed; - now, calling "info automake" will open the Top node, while calling - "info automake-invocation" and "info aclocal-invocation" will access - the nodes about the invocation of respectively automake and aclocal. - - - Automake is now distributed as a gzip-compressed and an xz-compressed - tarball. Previously, bzip2 was used instead of xz. - - - The last relics of Python 1.5 support have been removed from the - AM_PATH_PYTHON macro. - - - For programs and libraries, automake now detects EXTRA_foo_DEPENDENCIES - and adds them to the normal list of dependencies, but without - overwriting the foo_DEPENDENCIES variable, which is normally computed - by automake. - -Bugs fixed in 1.11.3: - -* Bugs introduced by 1.11.2: - - - Automake now correctly recognizes the prefix/primary combination - 'pkglibexec_SCRIPTS' as valid. - - - The parallel-tests harness no longer trips on sed implementations - with stricter limits on the length of input lines (problem seen at - least on Solaris 8). - -* Long-standing bugs: - - - The "deleted header file problem" for *.am files is avoided by stub - rules. This allows 'make' to trigger a rerun of 'automake' also if - some previously needed '.am' file has been removed. - - - The 'silent-rules' option now generates working makefiles even - for the uncommon 'make' implementations that do not support the - nested-variables extension to POSIX 2008. For such 'make' - implementations, whether a build is silent is determined at - configure time, and cannot be overridden at make time with - "make V=0" or "make V=1". - - - Vala support now works better in VPATH setups. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.11.2: - -* Changes to aclocal: - - - The `--acdir' option is deprecated. Now you should use the new options - `--automake-acdir' and `--system-acdir' instead. - - - The `ACLOCAL_PATH' environment variable is now interpreted as a - colon-separated list of additional directories to search after the - automake internal acdir (by default ${prefix}/share/aclocal-APIVERSION) - and before the system acdir (by default ${prefix}/share/aclocal). - -* Miscellaneous changes: - - - The Automake support for automatic de-ANSI-fication has been - deprecated. It will probably be removed in the next major Automake - release (1.12). - - - The `lzma' compression scheme and associated automake option `dist-lzma' - is obsoleted by `xz' and `dist-xz' due to upstream changes. - - - You may adjust the compression options used in dist-xz and dist-bzip2. - The default is now merely -e for xz, but still -9 for bzip; you may - specify a different level via the XZ_OPT and BZIP2 envvars respectively. - E.g., "make dist-xz XZ_OPT=-7" or "make dist-bzip2 BZIP2=-5" - - - The `compile' script now converts some options for MSVC for a better - user experience. Similarly, the new `ar-lib' script wraps Microsoft lib. - - - The py-compile script now accepts empty arguments passed to the options - `--destdir' and `--basedir', and complains about unrecognized options. - Moreover, a non-option argument or a special `--' argument terminates - the list of options. - - - A developer that needs to pass specific flags to configure at "make - distcheck" time can now, and indeed is advised to, do so by defining - the developer-reserved makefile variable AM_DISTCHECK_CONFIGURE_FLAGS, - instead of the old DISTCHECK_CONFIGURE_FLAGS. - The DISTCHECK_CONFIGURE_FLAGS variable should now be reserved for the - user; still, the old Makefile.am files that used to define it will - still continue to work as before. - - - New macro AM_PROG_AR that looks for an archiver and wraps it in the new - 'ar-lib' auxiliary script if the selected archiver is Microsoft lib. - This new macro is required for LIBRARIES and LTLIBRARIES when automake - is run with -Wextra-portability and -Werror. - - - When using DejaGnu-based testsuites, the user can extend the `site.exp' - file generated by automake-provided rules by defining the special make - variable `$(EXTRA_DEJAGNU_SITE_CONFIG)'. - - - The `install-info' rule can now be instructed not to create/update - the `${infodir}/dir' file, by exporting the new environment variable - `AM_UPDATE_INFO_DIR' to the value "no". - -Bugs fixed in 1.11.2: - -* Bugs introduced by 1.11: - - - The parallel-tests driver no longer produces erroneous results with - Tru64/OSF 5.1 sh upon unreadable log files. - - - The `parallel-tests' test driver does not report spurious successes - when used with concurrent FreeBSD make (e.g., "make check -j3"). - - - When the parallel-tests driver is in use, automake now explicitly - rejects invalid entries and conditional contents in TEST_EXTENSIONS, - instead of issuing confusing and apparently unrelated error messages - (e.g., "non-POSIX variable name", "bad characters in variable name", - or "redefinition of TEST_EXTENSIONS), or even, in some situations, - silently producing broken `Makefile.in' files. - - - The `silent-rules' option now truly silences all compile rules, even - when dependency tracking is disabled. Also, when `silent-rules' is - not used, `make' output no longer contains spurious backslash-only - lines, thus once again matching what Automake did before 1.11. - - - The AM_COND_IF macro also works if the shell expression for the - conditional is no longer valid for the condition. - -* Long-standing bugs: - - - The order of Yacc and Lex flags is fixed to be consistent with other - languages: $(AM_YFLAGS) comes before $(YFLAGS), and $(AM_LFLAGS) before - $(LFLAGS), so that the user variables override the developer variables. - - - "make distcheck" now correctly complains also when "make uninstall" - leaves one and only one file installed in $(prefix). - - - A "make uninstall" issued before a "make install", or after a mere - "make install-data" or a mere "make install-exec" does not spuriously - fail anymore. - - - Automake now warns about more primary/directory invalid combinations, - such as "doc_LIBRARIES" or "pkglib_PROGRAMS". - - - Rules generated by Automake now try harder to not change any files when - `make -n' is invoked. Fixes include compilation of Emacs Lisp, Vala, or - Yacc source files and the rule to update config.h. - - - Several scripts and the parallel-tests testsuite driver now exit with - the right exit status upon receiving a signal. - - - A per-Makefile.am setting of -Werror does not erroneously carry over - to the handling of other Makefile.am files. - - - The code for automatic dependency tracking works around a Solaris - make bug triggered by sources containing repeated slashes when the - `subdir-objects' option was used. - - - The makedepend and hp depmodes now work better with VPATH builds. - - - Java sources specified with check_JAVA are no longer compiled for - "make all", but only for "make check". - - - An usage like "java_JAVA = foo.java" will now cause Automake to warn - and error out if `javadir' is undefined, instead of silently producing - a broken Makefile.in. - - - aclocal and automake now honour the configure-time definitions of - AUTOCONF and AUTOM4TE when they spawn autoconf or autom4te processes. - - - The `install-info' recipe no longer tries to guess whether the - `install-info' program is from Debian or from GNU, and adaptively - change its behaviour; this has proven to be frail and easy to - regress. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Bugs fixed in 1.11.1: - - - Lots of minor bugfixes. - -* Bugs introduced by 1.11: - - - The `parallel-tests' test driver works around a GNU make 3.80 bug with - trailing white space in the test list (`TESTS = foo $(EMPTY)'). - -* Long standing bugs: - - - On Darwin 9, `pythondir' and `pyexecdir' pointed below `/Library/Python' - even if the `--prefix' argument pointed outside of a system directory. - AM_PATH_PYTHON has been fixed to ignore the value returned from python's - `get_python_lib' function if it points outside the configured prefix, - unless the `--prefix' argument was either `/usr' or below `/System'. - - - The testsuite does not try to change the mode of `ltmain.sh' files from - a Libtool installation (symlinked to test directories) any more. - - - AM_PROG_GCJ uses AC_CHECK_TOOLS to look for `gcj' now, so that prefixed - tools are preferred in a cross-compile setup. - - - The distribution is tarred up with mode 755 now by the `dist*' targets. - This fixes a race condition where untrusted users could modify files - in the $(PACKAGE)-$(VERSION) distdir before packing if the toplevel - build directory was world-searchable. This is CVE-2009-4029. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.11: - -* Version requirements: - - - Autoconf 2.62 or greater is required. - -* Changes to aclocal: - - - The autoconf version check implemented by aclocal in aclocal.m4 - (and new in Automake 1.10) is degraded to a warning. This helps - in the common case where the Autoconf versions used are compatible. - -* Changes to automake: - - - The automake program can run multiple threads for creating most - Makefile.in files concurrently, if at least Perl 5.7.2 is available - with interpreter-based threads enabled. Set the environment variable - AUTOMAKE_JOBS to the maximum number of threads to use, in order to - enable this experimental feature. - -* Changes to Libtool support: - - - Libtool generic flags are now passed to the install and uninstall - modes as well. - - - distcheck works with Libtool 2.x even when LT_OUTPUT is used, as - config.lt is removed correctly now. - -* Languages changes: - - - subdir-object mode works now with Fortran (F77, FC, preprocessed - Fortran, and Ratfor). - - - For files with extension .f90, .f95, .f03, or .f08, the flag - $(FCFLAGS_f[09]x) computed by AC_FC_SRCEXT is now used in compile rules. - - - Files with extension .sx are also treated as preprocessed assembler. - - - The default source file extension (.c) can be overridden with - AM_DEFAULT_SOURCE_EXT now. - - - Python 3.0 is supported now, Python releases prior to 2.0 are no - longer supported. - - - AM_PATH_PYTHON honors python's idea about the site directory. - - - There is initial support for the Vala programming language, when using - Vala 0.7.0 or later. - -* Miscellaneous changes: - - - Automake development is done in a git repository on Savannah now, see - - https://git.sv.gnu.org/gitweb/?p=automake.git - - A read-only CVS mirror is provided at - - cvs -d :pserver:anonymous@pserver.git.sv.gnu.org:/automake.git \ - checkout -d automake HEAD - - - "make dist" can now create xz-compressed tarballs, - as well as (deprecated?) lzma-compressed tarballs. - - - `automake --add-missing' will by default install the GPLv3 file as - COPYING if it is missing. It will also warn that the license file - should be added to source control. Note that Automake will never - overwrite an existing COPYING file, even when the `--force-missing' - option is used. - - - The manual is now distributed under the terms of the GNU FDL 1.3. - - - Automake ships and installs man pages for automake and aclocal now. - - - New shorthand `$(pkglibexecdir)' for `$(libexecdir)/@PACKAGE@'. - - - install-sh supports -C, which does not update the installed file - (and its time stamps) if the contents did not change. - - - The `gnupload' script has been revamped. - - - The `depcomp' and `compile' scripts now work with MSVC under MSYS. - - - The targets `install' and `uninstall' are more efficient now, in that - for example multiple files from one Automake variable such as - `bin_SCRIPTS' are copied in one `install' (or `libtool --mode=install') - invocation if they do not have to be renamed. - - Both install and uninstall may sometimes enter (`cd' into) the target - installation directory now, when no build-local scripts are used. - - Both install and uninstall do not fail anymore but do nothing if an - installation directory variable like `bindir' is set to the empty string. - - For built-in rules, `make install' now fails reliably if installation - of a file failed. Conversely, `make uninstall' even succeeds when - issued multiple times. - - These changes may need some adjustments from users: For example, - some `install' programs refuse to install multiple copies of the - same file in one invocation, so you may need to remove duplicate - entries from file lists. - - Also, within one set of files, say, nobase_data_DATA, the order of - installation may be changed, or even unstable among different hosts, - due to the use of associative arrays in awk. The increased use of - awk matches a similar move in Autoconf to provide for better scaling. - - Further, most undocumented per-rule install command variables such as - binSCRIPT_INSTALL have been removed because they are not needed any - more. Packages which use them should be using the appropriate one of - INSTALL_{DATA,PROGRAM,SCRIPT} or their install_sh_{DATA,PROGRAM,SCRIPT} - counterpart, depending on the type of files and the need for automatic - target directory creation. - - - The "deleted header file problem" for *.m4 files is avoided by - stub rules. This allows `make' to trigger a rerun of `aclocal' - also if some previously needed macro file has been removed. - - - Rebuild rules now also work for a removed `subdir/Makefile.in' in - an otherwise up to date tree. - - - The `color-tests' option causes colored test result output on terminals. - - - The `parallel-tests' option enables a new test driver that allows for - parallel test execution, inter-test dependencies, lazy test execution - for unit-testing, re-testing only failed tests, and formatted result output - as RST (reStructuredText) and HTML. Enabling this option may require some - changes to your test suite setup; see the manual for details. - - - The `silent-rules' option enables Linux kernel-style silent build output. - This option requires the widely supported but non-POSIX `make' feature - of recursive variable expansion, so do not use it if your package needs - to build with `make' implementations that do not support it. - - To enable less verbose build output, the developer has to use the Automake - option `silent-rules' in `AM_INIT_AUTOMAKE', or call the `AM_SILENT_RULES' - macro. The user may then set the default verbosity by passing the - `--enable-silent-rules' option to `configure'. At `make' run time, this - default may be overridden using `make V=0' for less verbose, and `make V=1' - for backward-compatible verbose output. - - - New prefix `notrans_' for manpages which should not be transformed - by --program-transform. - - - New macro AM_COND_IF for conditional evaluation and conditional - config files. - - - For AC_CONFIG_LINKS, if source and destination are equal, do not - remove the file in a non-VPATH build. Such setups work with Autoconf - 2.62 or newer. - - - AM_MAINTAINER_MODE now allows for an optional argument specifying - the default setting. - - - AM_SUBST_NOTMAKE may prevent substitution of AC_SUBSTed variables, - useful especially for multi-line values. - - - Automake's early configure-time sanity check now diagnoses an - unsafe absolute source directory name and makes configure fail. - - - The Automake macros and rules cope better with whitespace in the - current directory name, as long as the relative path to `configure' - does not contain whitespace. To this end, the values of `$(MISSING)' - and `$(install_sh)' may contain suitable quoting, and their expansion - might need `eval'uation if used outside of a makefile. These - undocumented variables may be used in several documented macros such - as $(AUTOCONF) or $(MAKEINFO). - -Bugs fixed in 1.11: - -* Long-standing bugs: - - - Fix aix dependency tracking for libtool objects. - - - Work around AIX sh quoting issue in AC_PROG_CC_C_O, leading to - unnecessary use of the `compile' script. - - - For nobase_*_LTLIBRARIES with nonempty directory components, the - correct `-rpath' argument is used now. - - - `config.status --file=Makefile depfiles' now also works with the - extra quoting used internally by Autoconf 2.62 and newer - (it used to work only without the `--file=' bit). - - - The `missing' script works better with versioned tool names. - - - Semantics for `missing help2man' have been revamped: - - Previously, if `help2man' was not present, `missing help2man' would have - the following semantics: if some man page was out of date but present, then - a warning would be printed, but the exit status was 0. If the man page was - not present at all, then `missing' would create a replacement man page - containing an error message, and exit with a status of 2. This does not play - well with `make': the next run will see this particular man page as being up - to date, and will only error out on the next generated man page, if any; - repeat until all pages are done. This was not desirable. - - These are the new semantics: if some man page is not present, and help2man - is not either, then `missing' will warn and generate the replacement page - containing the error message, but exit successfully. However, `make dist' - will ensure that no such bogus man pages are packaged into a tarball. - - - Targets provided by automake behave better with `make -n', in that they - take care not to create files. - - - `config.status Makefile... depfiles' works fine again in the presence of - disabled dependency tracking. - - - The default no-op recursive rules for these targets also work with BSD make - now: html, install-html, install-dvi, install-pdf, install-pdf, install-info. - - - `make distcheck' works also when both a directory and some file below it - have been added to a distribution variable, such as EXTRA_DIST or *_SOURCES. - - - Texinfo dvi, ps, pdf, and html output files are not removed upon - `make mostlyclean' any more; only the LaTeX by-products are. - - - Renamed objects also work with the `subdir-objects' option and - source file languages which Automake does not know itself. - - - `automake' now correctly complains about variable assignments which are - preceded by a comment, extend over multiple lines with backslash-escaped - newlines, and end in a comment sign. Previous versions would silently - and wrongly ignore such assignments completely. - -* Bugs introduced by 1.10: - - - Fix output of dummy dependency files in presence of post-processed - Makefile.in's again, but also cope with long lines. - - - $(EXEEXT) is automatically appended to filenames of XFAIL_TESTS - that have been declared as programs in the same Makefile. - This is for consistency with the analogous change to TESTS in 1.10. - - - Fix order of standard includes to again be `-I. -I$(srcdir)', - followed by directories containing config headers. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.10: - -* Version requirements: - - - Autoconf 2.60 or greater is required. - - - Perl 5.6 or greater is required. - -* Changes to aclocal: - - - aclocal now also supports -Wmumble and -Wno-mumble options. - - - `dirlist' entries (for the aclocal search path) may use shell - wildcards such as `*', `?', or `[...]'. - - - aclocal supports an --install option that will cause system-wide - third-party macros to be installed in the local directory - specified with the first -I flag. This option also uses #serial - lines in M4 files to upgrade local macros. - - The new aclocal options --dry-run and --diff help to review changes - before they are installed. - - - aclocal now outputs an autoconf version check in aclocal.m4 in - projects using automake. - - For a few years, automake and aclocal have been calling autoconf - (or its underlying engine autom4te) to accurately retrieve the - data they need from configure.ac and its siblings. Doing so can - only work if all autotools use the same version of autoconf. For - instance a Makefile.in generated by automake for one version of - autoconf may stop working if configure is regenerated with another - version of autoconf, and vice versa. - - This new version check ensures that the whole build system has - been generated using the same autoconf version. - -* Support for new Autoconf macros: - - - The new AC_REQUIRE_AUX_FILE Autoconf macro is supported. - - - If `subdir-objects' is set, and AC_CONFIG_LIBOBJ_DIR is specified, - $(LIBOBJS), $(LTLIBOBJS), $(ALLOCA), and $(LTALLOCA) can be used - in different directories. However, only one instance of such a - library objects directory is supported. - -* Change to Libtool support: - - - Libtool generic flags (those that go before the --mode=MODE option) - can be specified using AM_LIBTOOLFLAGS and target_LIBTOOLFLAGS. - -* Yacc and Lex changes: - - - The rebuild rules for distributed Yacc and Lex output will avoid - overwriting existing files if AM_MAINTAINER_MODE and maintainer-mode - is not enabled. - - - ylwrap is now always used for lex and yacc source files, - regardless of whether there is more than one source per directory. - -* Languages changes: - - - Preprocessed assembler (*.S) compilation now honors CPPFLAGS, - AM_CPPFLAGS and per-target _CPPFLAGS, and supports dependency - tracking, unlike non-preprocessed assembler (*.s). - - - subdir-object mode works now with Assembler. Automake assumes - that the compiler understands `-c -o'. - - - Preprocessed assembler (*.S) compilation now also honors - $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES). - - - Improved support for Objective C: - - Autoconf's new AC_PROG_OBJC will enable automatic dependency tracking. - - A new section of the manual documents the support. - - - New support for Unified Parallel C: - - AM_PROG_UPC looks for a UPC compiler. - - A new section of the manual documents the support. - - - Per-target flags are now correctly handled in link rules. - - For instance maude_CFLAGS correctly overrides AM_CFLAGS; likewise - for maude_LDFLAGS and AM_LDFLAGS. Previous versions bogusly - preferred AM_CFLAGS over maude_CFLAGS while linking, and they - used both AM_LDFLAGS and maude_LDFLAGS on the same link command. - - The fix for compiler flags (i.e., using maude_CFLAGS instead of - AM_CFLAGS) should not hurt any package since that is how _CFLAGS - is expected to work (and actually works during compilation). - - However using maude_LDFLAGS "instead of" AM_LDFLAGS rather than - "in addition to" breaks backward compatibility with older versions. - If your package used both variables, as in - - AM_LDFLAGS = common flags - bin_PROGRAMS = a b c - a_LDFLAGS = more flags - ... - - and assumed *_LDFLAGS would sum up, you should rewrite it as - - AM_LDFLAGS = common flags - bin_PROGRAMS = a b c - a_LDFLAGS = $(AM_LDFLAGS) more flags - ... - - This new behavior of *_LDFLAGS is more coherent with other - per-target variables, and the way *_LDFLAGS variables were - considered internally. - -* New installation targets: - - - New targets mandated by GNU Coding Standards: - install-dvi - install-html - install-ps - install-pdf - By default they will only install Texinfo manuals. - You can customize them with *-local variants: - install-dvi-local - install-html-local - install-ps-local - install-pdf-local - - - The undocumented recursive target `uninstall-info' no longer exists. - (`uninstall' is in charge of removing all possible documentation - flavors, including optional formats such as dvi, ps, or info even - when `no-installinfo' is used.) - -* Miscellaneous changes: - - - Automake no longer complains if input files for AC_CONFIG_FILES - are specified using shell variables. - - - clean, distribution, or rebuild rules are normally disabled for - inputs and outputs of AC_CONFIG_FILES, AC_CONFIG_HEADERS, and - AC_CONFIG_LINK specified using shell variables. However, if these - variables are used as ${VAR}, and AC_SUBSTed, then Automake will - be able to output rules anyway. - (See the Automake documentation for AC_CONFIG_FILES.) - - - $(EXEEXT) is automatically appended to filenames of TESTS - that have been declared as programs in the same Makefile. - This is mostly useful when some check_PROGRAMS are listed in TESTS. - - - `-Wportability' has finally been turned on by default for `gnu' and - `gnits' strictness. This means, automake will complain about %-rules - or $(GNU Make functions) unless you switch to `foreign' strictness or - use `-Wno-portability'. - - - Automake now uses AC_PROG_MKDIR_P (new in Autoconf 2.60), and uses - $(MKDIR_P) instead of $(mkdir_p) to create directories. The - $(mkdir_p) variable is still defined (to the same value as - $(MKDIR_P)) but should be considered obsolete. If you are using - $(mkdir_p) in some of your rules, please plan to update them to - $(MKDIR_P) at some point. - - - AM_C_PROTOTYPES and ansi2knr are now documented as being obsolete. - They still work in this release, but may be withdrawn in a future one. - - - Inline compilation rules for gcc3-style dependency tracking are - more readable. - - - Automake installs a "Hello World!" example package in $(docdir). - This example is used throughout the new "Autotools Introduction" - chapter of the manual. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.9: - -* Makefile.in bloat reduction: - - - Inference rules are used to compile sources in subdirectories when - the `subdir-objects' option is used and no per-target flags are - used. This should reduce the size of some projects a lot, because - Automake used to output an explicit rule for each such object in - the past. - - - Automake no longer outputs three rules (.o, .obj, .lo) for each - object that must be built with explicit rules. It just outputs - the rules required to build the kind of object considered: either - the two .o and .obj rules for usual objects, or the .lo rule for - libtool objects. - -* Change to Libtool support: - - - Libtool tags are used with libtool versions that support them. - (I.e., with Libtool 1.5 or greater.) - - - Automake is now able to handle setups where a libtool library is - conditionally installed in different directories, as in - - if COND - lib_LTLIBRARIES = liba.la - else - pkglib_LTLIBRARIES = liba.la - endif - liba_la_SOURCES = ... - -* Changes to aclocal: - - - aclocal now ensures that AC_DEFUNs and AU_DEFUNs it discovers are - really evaluated, before it decides to include them in aclocal.m4. - This solves nasty problems with conditional redefinitions of - Autoconf macros in /usr/share/aclocal/*.m4 files causing extraneous - *.m4 files to be included in any project using these macros. - (Calls to AC_PROG_EGREP causing libtool.m4 to be included is the - most famous instance of this bug.) - - - Do not complain about missing conditionally AC_REQUIREd macros - that are not actually used. In 1.8.x aclocal would correctly - determine which of these macros were really needed (and include - only these in the package); unfortunately it would also require - all of them to be present in order to run. This created - situations were aclocal would not work on a tarball distributing - all the macros it uses. For instance running aclocal on a project - containing only the subset of the Gettext macros in use by the - project did not work, because gettext conditionally requires other - macros. - -* Portability improvements: - - - Tar format can be chosen with the new options tar-v7, tar-ustar, and - tar-pax. The new option filename-length-max=99 helps diagnosing - filenames that are too long for tar-v7. (PR/414) - - - Variables augmented with `+=' are now automatically flattened (i.e., - trailing backslashes removed) and then wrapped around 80 columns - (adding trailing backslashes). In previous versions, a long series - of - VAR += value1 - VAR += value2 - VAR += value3 - ... - would result in a single-line definition of VAR that could possibly - exceed the maximum line length of some make implementations. - - Non-augmented variables are still output as they are defined in - the Makefile.am. - -* Miscellaneous: - - - Support Fortran 90/95 with the new "fc" and "ppfc" languages. - Works the same as the old Fortran 77 implementation; just replace - F77 with FC everywhere (exception: FFLAGS becomes FCFLAGS). - Requires a version of autoconf which provides AC_PROG_FC (>=2.59). - - - Support for conditional _LISP. - - - Support for conditional -hook and -local rules (PR/428). - - - Diagnose AC_CONFIG_AUX_DIR calls following AM_INIT_AUTOMAKE. (PR/49) - - - Automake will not write any Makefile.ins after the first error it - encounters. The previous Makefile.ins (if any) will be left in - place. (Warnings will not prevent output, but remember they can - be turned into errors with -Werror.) - - - The restriction that SUBDIRS must contain direct children is gone. - Do not abuse. - - - The manual tells more about SUBDIRS vs. DIST_SUBDIRS. - It also gives an example of nested packages using AC_CONFIG_SUBDIRS. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Bugs fixed in 1.8.5: - -* Long-standing bugs: - - - Define DIST_SUBDIRS even when the `no-dist' or `cygnus' options are used - so that `make distclean' and `make maintainer-clean' can work. - - - Define AR and ARFLAGS even when only EXTRA_LIBRARIES are defined. - - - Fix many rules to please FreeBSD make, which runs commands with `sh -e'. - - - Polish diagnostic when no input file is found. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Bugs fixed in 1.8.4: - -* Long-standing bugs: - - - Fix AM_PATH_PYTHON to correctly display $PYTHON when it has been - overridden by the user. - - - Honor PATH_SEPARATOR in various places of the Automake package, for - the sake of OS/2. - - - Adjust dependency tracking mode detection to ICC 8.0's new output. - (PR/416) - - - Fix install-sh so it can install the `mv' binary... using `mv'. - - - Fix tru64 dependency tracking for libtool objects. - - - Work around Exuberant Ctags when creating a TAGS files in a directory - without files to scan but with subdirectories to include. - -* Bugs introduced by 1.8: - - - Fix an "internal error" when @LIBOBJS@ is used in a variable that is - not defined in the same conditions as the _LDADD that uses it. - - - Do not warn when JAVAROOT is overridden, this is legitimate. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Bugs fixed in 1.8.3: - -* Long-standing bugs: - - - Quote filenames in installation rules, in case $DESTDIR, $prefix, - or any of the other *dir variables contain a space. - - Please note that Automake does not and cannot support spaces in - filenames that are involved during the build. This change affects - only installation paths, so that `make install' does not bomb out - in packages configured with - ./configure --prefix '/c/Program Files' - - - Fix the depfiles output so it works with GNU sed (<4.1) even when - POSIXLY_CORRECT is set. - - - Do not AC_SUBST(LIBOBJS) in AM_WITH_REGEX. This macro was unusable - since Autoconf 2.54, which defines LIBOBJS itself. - - - Fix a potential (but unlikely) race condition in parallel elisp - builds. (Introduced in 1.7.3.) - - - Do not assume that users override _DEPENDENCIES in all conditions - where Automake will try to define them. - - - Do not use `mkdir -p' in mkinstalldirs, unless this is GNU mkdir. - Solaris 8's `mkdir -p' is not thread-safe and can break parallel - builds. - - This fix also affects the $(mkdir_p) variable defined since - Automake 1.8. It will be set to `mkdir -p' only if mkdir is GNU - mkdir, and to `mkinstalldirs' or `install-sh -d' otherwise. - - - Secure temporary directory creation in `make distcheck'. (PR/413) - - - Do not generate two build rules for `parser.h' when the - parser appears in two different conditionals. - - - Work around a Solaris 8 /bin/sh bug in the test for dependency - checking. Usually ./configure will not pick this shell; so this - fix only helps cases where the shell is forced to /bin/sh. - -* Bugs introduced by 1.8: - - - In some situations (hand-written `m4_include's), aclocal would - call the `File::Spec->rel2abs' method, which was only introduced - in Perl 5.6. This new version reestablish support Perl 5.005. - - It is likely that the next major Automake releases will require at - least Perl 5.6. Consider upgrading your development environment - if you are still using the five-year-old Perl 5.005. - - - Automake would sometimes fail to define rules for targets listed - in variables defined in multiple conditions. For instance on - if C1 - bin_PROGRAMS = a - else - bin_PROGRAMS = b - endif - it would define only the `a.$(OBJEXT): a.c' rule and omit the - `b.$(OBJEXT): b.c' rule. - -* New sections in manual: - - - Third-Party Makefiles: how to interface third party Makefiles. - - Upgrading: upgrading packages to newer Automake versions. - - Multiple Outputs: handling tools that produce many outputs. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Bug fixed in 1.8.2: - -* A (well known) portability bug slipped in the changes made to - install-sh in Automake 1.8.1. The broken install-sh would refuse to - install anything on Tru64. - -* Fix install rules for conditionally built python files. (This never - really worked.) - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Bug fixed in 1.8.1: - -* Bugs introduced by 1.8: - - - Fix Config.pm import error with old Perl versions (at least - 5.005_03). One symptom is that aclocal could not find its macro - directory. - - - Automake 1.8 used `mkdir -m 0755 -p --' to ensure that directories - created by `make install' are always world readable, even if the - installer happens to have an overly restrictive umask (e.g. 077). - This was a mistake and has been reverted. There are at least two - reasons why we must not use `-m 0755': - - it causes special bits like SGID to be ignored, - - it may be too restrictive (some setups expect 775 directories). - - - Fix aclocal to honor definitions located in files which have been - m4_included manually. aclocal 1.8 had been updated to check - m4_included files for new requirements, but forgot that these - m4_included files can also provide new definitions. - - Note that if you have such a setup, we recommend you get rid of - it. In the past, there was a reason to m4_include files manually: - aclocal used to duplicate entire M4 files into aclocal.m4, even - files that were distributed. Some packages were therefore - m4_including the distributed file directly, and playing some - tricks to ensure aclocal would not copy that file to aclocal.m4, - in order to limit the amount of duplication. Since aclocal 1.8.x - will precisely output m4_includes for local M4 files, we recommend - that you clean up your setup, removing all manual m4_includes and - letting aclocal output them. - - - Output detailed menus in the Info version if the Automake manual, - so that Emacs can locate the indexes. - - - configure.ac and configure were listed twice in DIST_COMMON (an - internal variable where Automake lists configury files to - distribute). This was harmless, but unaesthetic. - - - Use `chmod a-w' instead of `chmod -w' as the latter honors umask. - This was an issue only in the Automake package itself, not in - its output. - - - Automake assumed that all AC_CONFIG_LINKS arguments had the form - DEST:SRC. This was wrong, as some packages do - AC_CONFIG_LINKS($computedlinks). This version no longer abort in - that situation. - - - Contrary to mkinstalldirs, $(mkdir_p) was expecting exactly one - argument. This caused two kinds of failures: - - Rules installing data in a conditionally defined directory - failed when that directory was undefined. In this case no - argument was supplied. - - `make installdirs' failed, because several directories were - passed to $(mkdir_p). This was an issue only on platform - were $(mkdir_p) is implemented with `install-sh -d'. - $(mkdir_p) as been changed to accept 0 or more arguments, as - mkinstalldirs did. - -* Long-standing bugs: - - - Fix an unexpected diagnostic occurring when users attempt - to override some internal variables that Automake appends to. - - - aclocal now scans configure.ac for macro definitions (PR/319). - - - Fix a portability issue with OSF1/Tru64 Make. If a directory - distributes files which are outside itself (this usually occurs - when using AC_CONFIG_AUX_DIR([../dir]) to use auxiliary files - from a parent package), then `make distcheck' fails due to an - optimization performed by OSF1/Tru64 Make in its VPATH handling. - (tests/subpkg2.test failure) - - - Fix another portability issue with Sun and OSF1/Tru64 Make. - In a VPATH-build configuration, `make install' would install - nobase_ files to wrong locations. - - - Fix a Perl `uninitialized value' diagnostic occurring when - automake complains that a Texinfo file does not have a - @setfilename statement. - - - Erase config.status.lineno during `make distclean'. This file - can be created by config.status. Automake already knew about - configure.lineno, but forgot config.status.lineno. - - - Distribute all files, even those which are built and installed - conditionally. This change affects files listed in conditionally - defined *_HEADERS and *_PYTHON variable (unless they are nodist_*) - as well as those listed in conditionally defined dist_*_DATA, - dist_*_JAVA, dist_*_LISP, and dist_*_SCRIPTS variables. - - - Fix AM_PATH_LISPDIR to avoid \? in sed regular expressions; it - doesn't conform to POSIX. - - - Normalize help strings for configure variables and options added - by Automake macros. - -* Anticipation: - - - Check for python2.4 in AM_PATH_PYTHON. - -* Spurious failures in test suite: - - - tests/libtool5.test, tests/ltcond.test, tests/ltcond2.test, - tests/ltconv.test: fix failures with CVS Libtool. - - tests/aclocal6.test: fix failure if autom4te.cache is disabled. - - tests/txinfo24.test, tests/txinfo25.test, tests/txinfo28.test: - fix failures with old Texinfo versions. - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New in 1.8: - -* Meta-News - - - The NEWS file is more verbose. - -* Requirements - - - Autoconf 2.58 or greater is required. - -* New features - - - Default source file names in the absence of a _SOURCES declaration - are made by removing any target extension before appending `.c', so - to make the libtool module `foo.la' from `foo.c', you only need to - do this: - - lib_LTLIBRARIES = foo.la - foo_la_LDFLAGS = -module - - For backward compatibility, foo_la.c will be used instead of - foo.c if this file exists or is the explicit target of a rule. - However -Wobsolete will warn about this deprecated naming. - - - AR's `cru' flags are now set in a global ARFLAGS variable instead - of being hard-coded in each $(AR) invocation, so they can be - substituted from configure.ac. This has been requested by people - dealing with non-POSIX ar implementations. - - - New warning option: -Woverride. This will warn about any user - target or variable definitions which override Automake - definitions. - - - Texinfo rules back up and restore info files when makeinfo fails. - - - Texinfo rules now support the `html' target. - Running this requires Texinfo 4.0 or greater. - - `html' is a new recursive target, so if your package mixes - hand-crafted `Makefile.in's with Automake-generated - `Makefile.in's, you should adjust the former to support (or - ignore) this target so that `make html' recurses successfully. If - you had a custom `html' rule in your `Makefile.am', it's better to - rename it as `html-local', otherwise your rule will override - Automake's new rule (you can check that by running `automake - -Woverride') and that will stop the recursion to subdirectories. - - Last but not least, this `html' rule is declared PHONY, even when - overridden. Fortunately, it appears that few packages use a - non-PHONY `html' rule. - - - Any file which is m4_included from configure.ac will appear as a - configure and Makefile.in dependency, and will be automatically - distributed. - - - The rules for rebuilding Makefiles and Makefile.ins will now - rebuild all Makefiles and all Makefile.ins at once when one of - configure's dependencies has changed. This is considerably faster - than previous implementations, where config.status and automake - were run separately in each directory (this still happens when you - change a Makefile.am locally, without touching configure.ac or - friends). Doing this also solves a longstanding issue: these - rebuild rules failed to work when adding new directories to the - tree, forcing you to run automake manually. - - - For similar reasons, the rules to rebuild configure, - config.status, and aclocal.m4 are now defined in all directories. - Note that if you were using the CONFIG_STATUS_DEPENDENCIES and - CONFIGURE_DEPENDENCIES (formerly undocumented) variables, you - should better define them in all directories. This is easily done - using an AC_SUBST (make sure you prefix these dependencies with - $(top_srcdir) since this variable will appear at different - levels of the build tree). - - - aclocal will now use `m4_include' instead of copying local m4 - files into aclocal.m4. (Local m4 files are those you ship with - your project, other files will be copied as usual.) - - Because m4_included files are automatically distributed, it means - for most projects there is no point in EXTRA_DISTing the list of - m4 files which are used. (You can probably get rid of - m4/Makefile.am if you had one.) - - - aclocal will avoid touching aclocal.m4 when possible, so that - Autom4te's cache isn't needlessly invalidated. This behavior can - be switched off with the new `--force' option. - - - aclocal now uses Autoconf's --trace to detect macros which are - actually used and will no longer include unused macros simply - because they where mentioned. This was often the case for macros - called conditionally. - - - New options no-dist and no-dist-gzip. - - - compile, depcomp, elisp-comp, install-sh, mdate-sh, mkinstalldirs, - py-compile, and ylwrap, now all understand --version and --help. - - - Automake will now recognize AC_CONFIG_LINKS so far as removing created - links as part of the distclean target and including source files in - distributions. - - - AM_PATH_PYTHON now supports ACTION-IF-FOUND and ACTION-IF-NOT-FOUND - argument. The latter can be used to override the default behavior - (which is to abort). - - - Automake will exit with $? = 63 on version mismatch. (So does - Autoconf 2.58) missing knows this, and in this case it will - emulate the tools as if they were absent. Because older versions - of Automake and Autoconf did not use this exit code, this change - will only be useful in projects generated with future versions of - these tools. - - - When using AC_CONFIG_FILES with multiple input files, Automake - generates the first ".in" input file for which a ".am" exists. - (Former versions would try to use only the first input file.) - - - lisp_DATA is now allowed. If you are using the empty ELCFILES - idiom to disable byte-compilation of lisp_LISP files, it is - recommended that you switch to using lisp_DATA. Note that - this is not strictly equivalent: lisp_DATA will install elisp - files even if emacs is not installed, while *_LISP do not - install anything unless emacs is found. - - - Makefiles will prefer `mkdir -p' over mkinstalldirs if it is - available. This selection is achieved through the Makefile - variable $(mkdir_p) that is set by AM_INIT_AUTOMAKE to either - `mkdir -m 0755 -p --', `$(mkinstalldirs) -m 0755', or - `$(install_sh) -m 0755 -d'. - -* Obsolete features - - - Because `mkdir -p' is available on most platforms, and we can use - `install-sh -d' when it is not, the use of the mkinstalldirs - script is being phased out. `automake --add-missing' no longer - installs it, and if you remove mkinstalldirs from your package, - automake will define $(mkinstalldirs) as an alias for $(mkdir_p). - - Gettext 0.12.1 still requires mkinstalldirs. Fortunately - gettextize and autopoint will install it when needed. Automake - will continue to define the $(mkinstalldirs) and to distribute - mkinstalldirs when this script is in the source tree. - - - AM_PROG_CC_STDC is now empty. The content of this macro was - merged in AC_PROG_CC. If your code uses $am_cv_prog_cc_stdc, you - should adjust it to use $ac_cv_prog_cc_stdc instead. (This - renaming should be safe, even if you have to support several, - versions of Automake, because AC_PROG_CC defines this variable - since Autoconf 2.54.) - - - Some users where using the undocumented ACLOCAL_M4_SOURCES - variable to override the aclocal.m4 dependencies computed - (inaccurately) by older versions of Automake. Because Automake - now tracks configure's m4 dependencies accurately (see m4_include - above), the use of ACLOCAL_M4_SOURCES should be considered - obsolete and will be flagged as such when running `automake - -Wobsolete'. - -* Bug fixes - - - Defining programs conditionally using Automake conditionals no - longer leads to a combinatorial explosion. The following - construct used to be troublesome when used with dozens of - conditions. - - bin_PROGRAMS = a - if COND1 - bin_PROGRAMS += a1 - endif - if COND2 - bin_PROGRAMS += a2 - endif - if COND3 - bin_PROGRAMS += a3 - endif - ... - - Likewise for _SOURCES, _LDADD, and _LIBADD variables. - - - Due to implementation constraints, previous versions of Automake - proscribed multiple conditional definitions of some variables - like bin_PROGRAMS: - - if COND1 - bin_PROGRAMS = a1 - endif - if COND2 - bin_PROGRAMS = a2 - endif - - All _PROGRAMS, _LDADD, and _LIBADD variables were affected. - This restriction has been lifted, and these variables now - support multiple conditional definitions as do other variables. - - - Cleanup the definitions of $(distdir) and $(top_distdir). - $(top_distdir) now points to the root of the distribution - directory created during `make dist', as it did in Automake 1.4, - not to the root of the build tree as it did in intervening - versions. Furthermore these two variables are now only defined in - the top level Makefile, and passed to sub-directories when running - `make dist'. - - - The --no-force option now correctly checks the Makefile.in's - dependencies before deciding not to update it. - - - Do not assume that make files are called Makefile in cleaning rules. - - - Update .info files in the source tree, not in the build tree. This - is what the GNU Coding Standard recommend. Only Automake 1.7.x - used to update these files in the build tree (previous versions did - it in the source tree too), and it caused several problems, varying - from mere annoyance to portability issues. - - - COPYING, COPYING.LIB, and COPYING.LESSER are no longer overwritten - when --add-missing and --force-missing are used. For backward - compatibility --add-missing will continue to install COPYING (in - `gnu' strictness) when none of these three files exist, but this - use is deprecated: you should better choose a license yourself and - install it once for all in your source tree (and in your code - management system). - - - Fix ylwrap so that it does not overwrite header files that haven't - changed, as the inline rule already does. - - - User-defined rules override automake-defined rules for the same - targets, even when rules do not have commands. This is not new - (and was documented), however some of the automake-generated - rules have escaped this principle in former Automake versions. - Rules for the following targets are affected by this fix: - - clean, clean-am, dist-all, distclean, distclean-am, dvi, dvi-am, - info, info-am, install-data-am, install-exec-am, install-info, - install-info-am, install-man, installcheck-am, maintainer-clean, - maintainer-clean-am, mostlyclean, mostlyclean-am, pdf, pdf-am, - ps, ps-am, uninstall-am, uninstall-info, uninstall-man - - Practically it means that an attempt to supplement the dependencies - of some target, as in - - clean: my-clean-rule - - will now *silently override* the automake definition of the - rule for this target. Running `automake -Woverride' will diagnose - all such overriding definitions. - - It should be noted that almost all of these targets support a *-local - variant that is meant to supplement the automake-defined rule - (See node `Extending' in the manual). The above rule should - be rewritten as - - clean-local: my-clean-rule - - These *-local targets have been documented since at least - Automake 1.2, so you should not fear the change if you have - to support multiple automake versions. - -* Miscellaneous - - - The Automake manual is now distributed under the terms of the GNU FDL. - - - Targets dist-gzip, dist-bzip2, dist-tarZ, dist-zip are always defined. - - - core dumps are no longer removed by the cleaning rules. There are - at least three reasons for this: - 1. These files should not be created by any build step, - so their removal do not fit any of the cleaning rules. - Actually, they may be precious to the developer. - 2. If such file is created during a build, then it's clearly a - bug Automake should not hide. Not removing the file will - cause `make distcheck' to complain about its presence. - 3. Operating systems have different naming conventions for - core dump files. A core file on one system might be a - completely legitimate data file on another system. - - - RUNTESTFLAGS, CTAGSFLAGS, ETAGSFLAGS, JAVACFLAGS are no longer - defined by Automake. This means that any definition in the - environment will be used, unless overridden in the Makefile.am or - on the command line. The old behavior, where these variables were - defined empty in each Makefile, can be obtained by AC_SUBSTing or - AC_ARG_VARing each variable from configure.ac. - - - CONFIGURE_DEPENDENCIES and CONFIG_STATUS_DEPENDENCIES are now - documented. (The is not a new feature, these variables have - been there since at least Automake 1.4.) - -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Bugs fixed in 1.7.9: -* Fix install-strip to work with nobase_ binaries. -* Fix renaming of #line directives in ylwrap. -* Rebuild with Autoconf 2.59. (1.7.8 was not installable with pdksh.) - -Bugs fixed in 1.7.8: -* Remove spurious blank lines in cleaning rules introduced in 1.7.7. -* Fix detection of Debian's install-info, broken since version 1.5. - (Debian bug #213524). -* Honor -module if it appears in AM_LDFLAGS (i.e., relax name checking) - This was only done for libfoo_LDFLAGS and LDFLAGS in previous versions. - -Bugs fixed in 1.7.7: -* The implementation of automake's --no-force option is unreliable, - so this option is ignored in this version. A real fix will appear in - Automake 1.8. (Debian Bug #206299) -* AM_PATH_PYTHON: really check the whole list of interpreters if no - argument is given. (PR/399) -* Do not warn about leading `_' in variable names, even with -Wportability. -* Support user redefinitions of TEXINFO_TEX. -* depcomp: support AIX Compiler version 6. -* Fix missing rebuilds during `make dist' with BSD make. - (Could produce tarballs containing out-of-date files.) -* Resurrect multilib support. -* Noteworthy manual updates: - - Extending aclocal: how to write m4 macros that won't trigger warnings - with Automake 1.8. - - A Shared Library: Rewrite and split into subsections. - -Bugs fixed in 1.7.6: -* Fix depcomp's icc mode for ICC 7.1. -* Diagnose calls to AC_CONFIG_FILES and friends with not enough arguments. -* Fix maintainer-clean's removal of autom4te.cache in VPATH builds. -* Fix AM_PATH_LISPDIR to work with POSIXLY_CORRECT=1. -* Fix the location reported in some diagnostics related to AUTOMAKE_OPTIONS. -* Remove Latin-1 characters from elisp-comp. -* Update the manual's @dircategory to match the Free Software Directory. - -Bugs fixed in 1.7.5: -* Update install-sh's license to remove an advertising clause. - (Debian bug #191717) -* Fix a bug introduced in 1.7.4, related to BUILT_SOURCE handling, - that caused invalid Makefile.ins to be generated. -* Make sure AM_MAKE_INCLUDE doesn't fail when a `doit' file exists. -* New FAQ entry: renamed objects. - -Bugs fixed in 1.7.4: -* Tweak the TAGS rule to support Exuberant Ctags (in addition to - the Emacs implementation) -* Fix output of aclocal.m4 dependencies in subdirectories. -* Use `mv -f' instead of `mv' in fastdep rules. -* Upgrade mdate-sh to work on OS/2. -* Don't byte-compile elisp files when ELCFILES is set empty. - (this documented feature was broken by 1.7.3) -* Diagnose trailing backslashes on last line of Makefile.am. -* Diagnose whitespace following trailing backslashes. -* Multiple tests are now correctly supported in DEJATOOL. (PR/388) -* Fix rebuilt rules for AC_CONFIG_FILES([Makefile:Makefile.in:Makefile.bot]) - Makefiles. (PR/389) -* `make install' will build `BUILT_SOURCES' first. -* Minor documentation fixes. - -Bugs fixed in 1.7.3: -* Fix stamp files numbering (when using multiple AC_CONFIG_HEADERS). -* Query distutils for `pythondir' and `pythonexecdir', instead of - using an hardcoded path. This should allow builds on 64-bit - distributions that usually use lib64/ instead of lib/. -* AM_PATH_PYTHON will also search for python2.3. -* elisp files are now built all at once instead of one by one. Besides - incurring a speed-up, this is required to support interdependent elisp files. -* Support for DJGPP: - - `make distcheck' will now work in `_inst/' and `_build' instead - of `=inst/' and `=build/' - - use `_dirstamp' when the file-system doesn't support `.dirstamp' - - install/uninstall `*.i[0-9][0-9]'-style info files - - more changes that affect only the Automake package (not its output) -* Fix some incompatibilities with upcoming perl-5.10. -* Properly quote AC_PACKAGE_TARNAME and AC_PACKAGE_VERSION when defining - PACKAGE and VERSION. -* depcomp fixes: - - dashmstdout and dashXmstdout modes: don't use `-o /dev/null', this - is troublesome with gcc and Solaris compilers. (PR/385) - - makedepend mode: work with Libtool. (PR/385 too) - - support for ICC. -* better support for unusual gettext setups, such as multiple po/ directories - (PR/381): - - Flag missing po/ and intl/ directories as warnings, not errors. - - Disable these warnings if po/ does not exist. -* Noteworthy manual updates: - - New FAQ chapter. - - Document how AC_CONFIG_AUX_DIR interacts with missing files. - (Debian Bug #39542) - - Document `AM_YFLAGS = -d'. (PR/382) - -Bugs fixed in 1.7.2: -* Fix installation and uninstallation of Info files built in subdirectories. -* Do not run `./configure --with-included-gettext' during `make distcheck' - if AM_GNU_GETTEXT([external]) is used. -* Correctly uninstall renamed man pages. -* Do not strip escaped newline in variables defined in one condition - and augmented in another condition. -* Fix ansi2knr rules for LIBOBJS sources. -* Clean all known Texinfo index files, not only those which appear to - be used, because we cannot know which indexes are used in included files. - (PR/375, Debian Bug #168671) -* Honor only the first @setfilename seen in a Texinfo file. -* Treat "required file X not found" diagnostics as errors (exit status 1). -* Don't complain that a required file is not found when it is a Makefile - target. (PR/357) -* Don't use single suffix inference rules when building `.info'-less - Info files, for the sake of Solaris make. -* The `check' target now depends on `$(BUILT_SOURCES)'. (PR/359) -* Recognize multiple inference rules such as `.a.b .c.d:'. (PR/371) -* Warn about multiple inference rules when -Wportability is used. (PR/372) -* Fix building of deansified files from subdirectories. (PR/370) -* Add missing `fi' in the .c->.obj rules. -* Improve install-sh to work even when names contain spaces or certain - (but not all) shell metachars. -* Fix the following spurious failures in the test suite: - depcomp2.test, gnits2.test, gnits3.test, python3.test, texinfo13.test -* Noteworthy manual updates: - - Augment the section about BUILT_SOURCES. - - Mention that AM_PROG_CC_STDC is a relic that is better avoided today. - -Bugs fixed in 1.7.1: -* Honor `ansi2knr' for files built in subdirectories, or using per-targets - flags. -* Aclocal should now recognize macro names containing parentheses, e.g. - AC_DEFUN([AC_LANG_PREPROC(Fortran 90)], [...]). -* Erase *.sum and *.log files created by DejaGnu, during `make distclean'. - (Debian Bug#153697) -* Install Python files even if they were built. (PR/369) -* Have stamp-vti dependent upon configure instead of configure.ac, as the - version might not be defined in the latter. (PR/358) -* Reorder arguments passed to a couple of commands, so things works - when POSIXLY_CORRECT=1. -* Fix a regex that can cause Perl to segfault on large input. - (Debian Bug#162583) -* Fix distribution of packages that have some sources defined conditionally, - as in the `Conditional compilation using Automake conditionals' example - of the manual. -* Fix spurious test suite failures on IRIX. -* Don't report a required variable as undefined if it has been - defined conditionally for the "right" conditions. -* Fix cleaning of the /tmp subdirectory used by `make distcheck', in case - `make distcheck' fails. -* Fix distribution of included Makefile fragment, so we don't create - spurious directories in the distribution. (PR/366) -* Don't complain that a target lacks `.$(EXEEXT)' when it has it. - -New in 1.7: -* Autoconf 2.54 is required. -* `aclocal' and `automake' will no longer warn about obsolete - configure macros. This is done by `autoconf -Wobsolete'. -* AM_CONFIG_HEADER, AM_SYS_POSIX_TERMIOS and - AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL are obsolete (although still - supported). You should use AC_CONFIG_HEADERS, AC_SYS_POSIX_TERMIOS, - and AC_HEADER_TIOCGWINSZ instead. `autoupdate' can upgrade - `configure.ac' for you. -* Support for per-program and per-library `_CPPFLAGS'. -* New `ctags' target (builds CTAGS files). -* Support for -Wmumble and -Wno-mumble, where mumble is a warning category - (see `automake --help' or the manual for a list of them). -* Honor the WARNINGS environment variable. -* Omit the call to depcomp when using gcc3: call the compiler directly. -* A new option, std-options, tests that programs support --help and --version - when `make installcheck' is run. This is enabled by --gnits. -* Texinfo rules now support the `ps' and `pdf' targets. -* Info files are now created in the build directory, not the source directory. -* info_TEXINFOS supports files in subdirectories (this requires Texinfo 4.1 - or greater). -* `make distcheck' will enforce DESTDIR support by attempting - a DESTDIR install. -* `+=' can be used in conditionals, even if the augmented variable - was defined for another condition. -* Makefile fragments (inserted with `include') are always distributed. -* Use Autoconf's --trace interface to inspect configure.ac and get - a more accurate view of it. -* Add support for extending aclocal's default macro search path - using a `dirlist' file within the aclocal directory. -* automake --output-dir is deprecated. -* The part of the distcheck target that checks whether uninstall actually - removes all installed files has been moved in a separate target, - distuninstallcheck, so it can be overridden easily. -* Many bug fixes. - -New in 1.6.3: -* Support for AM_INIT_GETTEXT([external]) -* Bug fixes, including: - - Fix Automake's own `make install' so it works even if `ln' doesn't. - - nobase_ programs and scripts honor --program-transform correctly. - - Erase configure.lineno during `make distclean'. - - Erase YACC and LEX outputs during `make maintainer-clean'. - -New in 1.6.2: -* Many bug fixes, including: - - Requiring the current version works. - - Fix "$@" portability issues (for Zsh). - - Fix output of dummy dependency files in presence of post-processed - Makefile.in's. - - Don't compute dependencies in background to avoid races with libtool. - - Fix handling of _OBJECTS variables for targets sharing source variables. - - Check dependency mode for Java when AM_PROG_GCJ is used. - -New in 1.6.1: -* automake --output-dir is deprecated -* Many bug fixes, including: - - Don't choke on AM_LDFLAGS definitions. - - Clean libtool objects from subdirectories. - - Allow configure variables with reserved suffix and unknown prefix - (e.g. AC_SUBST(mumble_LDFLAGS) when 'mumble' is not a target). - - Fix the definition of AUTOMAKE and ACLOCAL in configure. - -New in 1.6: -* Autoconf 2.52 is required. -* automake no longer run libtoolize. - This is the job of autoreconf (from GNU Autoconf). -* `dist' generates all the archive flavors, as did `dist-all'. -* `dist-gzip' generates the Gzip tar file only. -* Combining Automake Makefile conditionals no longer lead to a combinatorial - explosion. Makefile.in's keep a reasonable size. -* AM_FUNC_ERROR_AT_LINE, AM_FUNC_STRTOD, AM_FUNC_OBSTACK, AM_PTRDIFF_T - are no longer shipped, since Autoconf 2.52 provides them (both as AM_ - and AC_). -* `#line' of Lex and Yacc files are properly set. -* EXTRA_DIST can contain generated directories. -* Support for dot-less extensions in suffix rules. -* The part of the distcheck target that checks whether distclean actually - cleans all built files has been moved in a separate target, distcleancheck, - so it can be overridden easily. -* `make distcheck' will pass additional options defined in - $(DISTCHECK_CONFIGURE_FLAGS) to configure. -* Fixed CDPATH portability problems, in particular for MacOS X. -* Fixed handling of nobase_ targets. -* Fixed support of implicit rules leading to .lo objects. -* Fixed late inclusion of --add-missing files (e.g. depcomp) in DIST_COMMON -* Added uninstall-hook target -* `AC_INIT AM_INIT_AUTOMAKE(tarname,version)' is an obsolete construct. - You can now use `AC_INIT(pkgname,version) AM_INIT_AUTOMAKE' instead. - (Note that "pkgname" is not "tarname", see the manual for details.) - It is also possible to pass a list of global Automake options as - first argument to this new form of AM_INIT_AUTOMAKE. -* Compiler-based assembler is now called `CCAS'; people expected `AS' - to be a real assembler. -* AM_INIT_AUTOMAKE will set STRIP itself when it needs it. Adding - AC_CHECK_TOOL([STRIP], [strip]) manually is no longer required. -* aclocal and automake are also installed with the version number - appended, and some of the install directory names have changed. - This lets you have multiple versions installed simultaneously. -* Support for parsers and lexers in subdirectories. - -New in 1.5: -* Support for `configure.ac'. -* Support for `else COND', `endif COND' and negated conditions `!COND'. -* `make dist-all' is much faster. -* Allows '@' AC_SUBSTs in macro names. -* Faster AM_INIT_AUTOMAKE (requires update of `missing' script) -* User-side dependency tracking. Developers no longer need GNU make -* Python support -* Uses DIST_SUBDIRS in some situations when SUBDIRS is conditional -* Most files are correctly handled if they appear in subdirs - For instance, a _DATA file can appear in a subdir -* GNU tar is no longer required for `make dist' -* Added support for `dist_' and `nodist_' prefixes -* Added support for `nobase_' prefix -* Compiled Java support -* Support for per-executable and per-library compilation flags -* Many bug fixes - -New in 1.4: -* Added support for the Fortran 77 programming language. -* Re-indexed the Automake Texinfo manual. -* Added `AM_FOOFLAGS' variable for each compiler invocation; - e.g. AM_CFLAGS can be used in Makefile.am to set C compiler flags -* Support for latest autoconf, including support for objext -* Can now put `.' in SUBDIRS to control build order -* `include' command and `+=' support for macro assignment -* Dependency tracking no long susceptible to deleted header file problem -* Maintainer mode now a conditional. @MAINT@ is now an anachronism. -* Bug fixes - -New in 1.3: -* Bug fixes -* Better Cygwin32 support -* Support for suffix rules with _SOURCES variables -* New options `readme-alpha' and `check-news'; Gnits mode sets these -* @LEXLIB@ no longer required when lex source seen - Lex support in `missing', and new lex macro. Update your missing script. -* Built-in support for assembly -* aclocal gives error if `AM_' macro not found -* Passed YFLAGS, not YACCFLAGS, to yacc -* AM_PROG_CC_STDC does not have to come before AC_PROG_CPP -* Dependencies computed as a side effect of compilation -* Preliminary support for Java -* DESTDIR support at "make install" time -* Improved ansi2knr support; you must use the latest ansi2knr.c (included) - -New in 1.2: -* Bug fixes -* Better DejaGnu support -* Added no-installinfo option -* Added Emacs Lisp support -* Added --no-force option -* Included `aclocal' program -* Automake will now generate rules to regenerate aclocal.m4, if appropriate -* Now uses `AM_' macro names everywhere -* ansi2knr option can have directory prefix (eg `../lib/ansi2knr') - ansi2knr now works correctly on K&R sources -* Better C++, yacc, lex support -* Will compute _DEPENDENCIES variables automatically if not supplied -* Will interpolate $(...) and ${...} when examining contents of a variable -* .deps files now in build directory, not source directory; dependency - handling generally rewritten -* DATA, MANS and BUILT_SOURCES no longer included in distribution -* can now put config.h into a subdir -* Added dist-all target -* Support for install-info program (see texinfo 3.9) -* Support for "yacc -d" -* configure substitutions are automatically discovered and included - in generated Makefile.in -* Special --cygnus mode -* OMIT_DEPENDENCIES can now hold list of dependencies to be omitted - when making distribution. Some dependencies are auto-ignored. -* Changed how libraries are specified in _LIBRARIES variable -* Full libtool support, from Gord Matzigkeit -* No longer have to explicitly touch stamp-h when using AC_CONFIG_HEADER; - AM_CONFIG_HEADER handles it automatically -* Texinfo output files no longer need .info extension -* Added `missing' support -* Cygwin32 support -* Conditionals in Makefile.am, from Ian Taylor - -New in 1.0: -* Bug fixes -* distcheck target runs install and installcheck targets -* Added preliminary support for DejaGnu. - -New in 0.33: -* More bug fixes -* More checking -* More libtool fixes from Gord Matzigkeit; libtool support is still - preliminary however -* Added support for jm_MAINTAINER_MODE -* dist-zip support -* New "distcheck" target - -New in 0.32: -* Many bug fixes -* mkinstalldirs and mdate-sh now appear in directory specified by - AC_CONFIG_AUX_DIR. -* Removed DIST_SUBDIRS, DIST_OTHER -* AC_ARG_PROGRAM only required when an actual program exists -* dist-hook target now run before distribution packaged up; idea from - Dieter Baron. Other hooks exist, too. -* Preliminary (unfinished) support for libtool -* Added short option names. -* Better "dist" support when gluing together multiple packages - -New in 0.31: -* Bug fixes -* Documentation updates (many from François Pinard) -* strictness `normal' now renamed to `foreign' -* Renamed --install-missing to --add-missing -* Now handles AC_CONFIG_AUX_DIR -* Now handles TESTS macro -* DIST_OTHER renamed to EXTRA_DIST -* DIST_SUBDIRS is deprecated -* @ALLOCA@ and @LIBOBJS@ now work in _LDADD variables -* Better error messages in many cases -* Program names are canonicalized -* Added "check" prefix; from Gord Matzigkeit - -New in 0.30: -* Bug fixes -* configure.in scanner knows about AC_PATH_XTRA, AC_OUTPUT ":" syntax -* Beginnings of a test suite -* Automatically adds -I options for $(srcdir), ".", and path to config.h -* Doesn't print anything when running -* Beginnings of MAINT_CHARSET support -* Can specify version in AUTOMAKE_OPTIONS -* Most errors recognizable by Emacs' M-x next-error -* Added --verbose option -* All "primary" variables now obsolete; use EXTRA_PRIMARY to supply - configure-generated names -* Required macros now distributed in aclocal.m4 -* New documentation -* --strictness=gnu is default - -New in 0.29: -* Many bug fixes -* More sophisticated configure.in scanning; now understands ALLOCA and - LIBOBJS directly, handles AC_CONFIG_HEADER more precisely, etc. -* TEXINFOS and MANS now obsolete; use info_TEXINFOS and man_MANS instead. -* CONFIG_HEADER variable now obsolete -* Can handle multiple Texinfo sources -* Allow hierarchies deeper than 2. From Gord Matzigkeit. -* HEADERS variable no longer needed; now can put .h files directly into - foo_SOURCES variable. -* Automake automatically rebuilds files listed in AC_OUTPUT. The - corresponding ".in" files are included in the distribution. - -New in 0.28: -* Added --gnu and --gnits options -* More standards checking -* Bug fixes -* Cleaned up 'dist' targets -* Added AUTOMAKE_OPTIONS variable and several options -* Now scans configure.in to get some information (preliminary) - -New in 0.27: -* Works with Perl 4 again - -New in 0.26: -* Added --install-missing option. -* Pretty-prints generated macros and rules -* Comments in Makefile.am are placed more intelligently in Makefile.in -* Generates .PHONY target -* Rule or macro in Makefile.am now overrides contents of Automake file -* Substantial cleanups from François Pinard - -New in 0.25: -* Bug fixes. -* Works with Perl 4 again. - -New in 0.24: -* New uniform naming scheme. -* --strictness option -* Works with Perl 5 -* '.c' files corresponding to '.y' or '.l' files are automatically - distributed. -* Many bug fixes and cleanups - -New in 0.23: -* Allow objects to be conditionally included in libraries via lib_LIBADD. - -New in 0.22: -* Bug fixes in 'clean' code. -* Now generates 'installdirs' target. -* man page installation reworked. -* 'make dist' no longer re-creates all Makefile.in's. - -New in 0.21: -* Reimplemented in Perl -* Added --amdir option (for debugging) -* Texinfo support cleaned up. -* Automatic de-ANSI-fication cleaned up. -* Cleaned up 'clean' targets. - -New in 0.20: -* Automatic dependency tracking -* More documentation -* New variables DATA and PACKAGEDATA -* SCRIPTS installed using $(INSTALL_SCRIPT) -* No longer uses double-colon rules -* Bug fixes -* Changes in advance of internationalization - ------ - -Copyright (C) 1995-2017 Free Software Foundation, Inc. - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2, or (at your option) -any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see . diff --git a/PLANS/README b/PLANS/README deleted file mode 100644 index 87cb8dc36..000000000 --- a/PLANS/README +++ /dev/null @@ -1,25 +0,0 @@ -"Plans" for future or on-going Automake development. - -The contents is meant to help ensure a more controlled and smooth -development and evolution for Automake, in several ways. - - - Having the plans clearly spelled out should will avoid messy - roadmaps with no clear way forward or with muddy or ill-defined - aims or purposes; a trap this is too easy to fall into. - - - Keeping planned changes cooking and re-hashed for a while should - ensure rough edges are smoothed up, transitions are planned in a - proper way (hopefully avoiding debacles like the AM_MKDIR_PROG_P - deprecation and the AM_CONFIG_HEADER too-abrupt removal), and - "power users" have more chances of getting informed in due time, - thus having all the time to prepare for the changes or raise - objections against them. - - - Having the plans clearly stated and registered in a "centralized" - location should make it more difficult to them to slip through - the cracks, getting forgotten or (worse) only half-implemented. - - - Even for discussions and plans registered on the Bug Tracker - as well, a corresponding entry in the PLANS directory can help - in keeping main ideas summarized, and consensus and/or objections - registered and easily compared. diff --git a/PLANS/obsolete-removed/am-prog-mkdir-p.txt b/PLANS/obsolete-removed/am-prog-mkdir-p.txt deleted file mode 100644 index f2fd4c8d0..000000000 --- a/PLANS/obsolete-removed/am-prog-mkdir-p.txt +++ /dev/null @@ -1,72 +0,0 @@ -We have dropped any plan to remove the obsolescent macro AM_PROG_MKDIR_P, -(today just an alias for the Autoconf-provided macro AC_PROG_MKDIR_P), as -well as the related $(mkdir_p) make variable and the @mkdir_p@ configure -substitution. - -That planned removal has already proven source of countless headaches and -backward-compatibility issues, which vastly outweigh any "clean-up benefit" -we would get from the removal of that obsolescent but unobtrusive cruft. - --*-*-*- - -Let's see a bit of history. - -I had already scheduled the removal of the long-deprecated AM_PROG_MKDR_P -macro (superseded by the Autoconf-provided one AC_PROG_MKDIR_P) for -Automake 1.13 -- see commit 'v1.12-20-g8a1c64f'. - -Alas, it turned out the latest Gettext version at the time (0.18.1.1) was -still using that macro: - - - -And since the maintenance of Gettext was stalled, I couldn't get a fix -committed and released in time for the appearance of Automake 1.13: - - - - - -So, on strong advice by Jim Meyering, in commit 'v1.12.4-158-gdf23daf' -I re-introduced AM_PROG_MKDIR_P in Automake (thanks to Jim for having -convinced me to do so in time!) - -But then, Gettext (as said, the greatest "offender" in the use of -AM_PROG_MKDIR_P), in its latest release 0.18.2, finally removed all the -uses of that macro still present in its code base. Yay. So I thought -we could finally and quite safely remove AM_PROG_MKDIR_P in Automake 1.14; -and I proceeded to do so, see commit 'v1.13-30-gd01834b' and the merge -commit 'v1.13-5-gb373ad9'. Well, it turned out I was wrong, again, and -in a trickier and sublter way this time. Let's see the details. - -If a package's 'configure.ac' contains a call like: - - AM_GNU_GETTEXT_VERSION([0.18]) - -then the 'autopoint' script will bring the data files from the Gettext -release *1.18* into the package's tree -- yes, even even if the developer -has installed *and is using* Gettext 1.18.2! Now, these data files -comprise m4 files (that will be seen by subsequent aclocal and autoconf -calls), and of course, the pre-0.18.2 version of some of these files -still contains occurrences of AM_PROG_MKDIR_P -- so Automake 1.13 errors -out, and we lose. That already happened in practice: - - - -Moreover, while I might see it as not unreasonable to ask a developer -using Automake 2.0 to also update Gettext to 1.18.2, that would not -be enough; in order for gettext to use the correct data files, that -developer would have to update his configure.ac to read: - - AM_GNU_GETTEXT_VERSION([0.18.2]) - -thus requiring *all* of his co-developers to install Gettext 1.18.2, -even if they are still using, say, Automake 1.13 or 1.14. Bad. - -So I decided to re-instate this macro as a simple alias for AC_PROG_MKDIR_P -(plus a non-fatal runtime warning in the 'obsolete' category), and drop -any plan to remove it (see how much good those plans have done us so far). -See commit v1.13.1-109-g030ecb4. - -Similarly, the obsolete '@mkdir_p@' substitution and '$(mkdir_p)' make -variable are still supported, as simple aliases to '$(MKDIR_P)'. diff --git a/PLANS/obsolete-removed/configure.in.txt b/PLANS/obsolete-removed/configure.in.txt deleted file mode 100644 index d3f6da795..000000000 --- a/PLANS/obsolete-removed/configure.in.txt +++ /dev/null @@ -1,28 +0,0 @@ -In Automake 1.13.x (once planned, then dropped) ------------------------------------------------ - -We are already warning about 'configure.in' used as the name for the -Autoconf input file ('configure.ac' should be used instead); we've -been doing that since Automake 1.12.4. - -We had scheduled to remove support for it altogether in Automake 1.13 -(and announced that in our NEWS file), because we thought that Autoconf -too would have started deprecating it by the time our 1.13 release was -done. Alas, this hasn't been the case: the deprecation code is only -present in the development version of autoconf so far (scheduled to -become Autoconf 2.70). So ... - - -For Automake 2.0 ----------------- - -... we have decided to wait until 2.70 is out before really removing -'configure.in' support. Since we plan to require Autoconf 2.70 in -Automake 2.0 (so that we can remove the hacky code emulating -AC_CONFIG_MACRO_DIRS for older autoconf versions), we are quite sure -that Autoconf will actually have started deprecating 'configure.in' -by the time Automake 2.0 is released. - -Note that the removal of 'configure.in' has already been implemented -in our 'master' branch (from where the 2.0 release will be finally -cut); see commits 'v1.13-17-gbff57c8' and 'v1.13-21-g7626e63'. diff --git a/PLANS/rm-f-without-args.txt b/PLANS/rm-f-without-args.txt deleted file mode 100644 index b940fc3e9..000000000 --- a/PLANS/rm-f-without-args.txt +++ /dev/null @@ -1,40 +0,0 @@ -Summary -------- - -POSIX will say in a future version that calling "rm -f" with no argument -is OK; and this sensible behaviour seem to be already very widespread in -"the wild" (and possibly lacking only on those systems that are well on -their way to obsolescence). - -Se we'd like to simplify several automake-generated "cleaning" rules -accordingly, to get rid of the awful idiom: - - test -z "$(VAR)" || rm -f $(VAR) - -See automake bug#10828. - -For Automake 1.14 (DONE) ------------------------- - -Add a temporary "probe check" in AM_INIT_AUTOMAKE that verifies that -the no-args "rm -f" usage is supported on the system configure is -being run on; complain loudly if this is not the case, and tell the -user to report the situation to us. - -For Automake 2.0 ----------------- - -Make any failure in the configure-time probe check introduced by the -previous point fatal; and in case of failure, also suggest to the user -to install an older version of GNU coreutils to work around the -limitation of his system (this version should be old enough not to -be bootstrapped with Automake 2.0, otherwise the user will face a -bootstrapping catch-22). - -In all our recipes, start assuming "rm -f" with no argument is OK; -simplify and de-uglify the recipes accordingly. - -For Automake 3.0 ----------------- - -Remove the runtime probe altogether. diff --git a/PLANS/subdir-objects.txt b/PLANS/subdir-objects.txt deleted file mode 100644 index c6a046f52..000000000 --- a/PLANS/subdir-objects.txt +++ /dev/null @@ -1,67 +0,0 @@ -Summary -------- - -We want to make the behaviour currently enabled by the 'subdir-objects' -the default one, and in fact the *only* one, in Automake 2.0. -See automake bug#13378: . - -Details -------- - -The fact that Automake-generated Makefiles place compiled object files in -the current directory by default, also when the corresponding source file -is in a subdirectory, is basically an historical accident, due to the fact -that the 'subdir-objects' option had only been introduced in April 1999, -starting with commit 'user-dep-gen-branchpoint-56-g88b5959', and never -made the default (likely to avoid backwards-compatibility issues). - -Since I believe the behaviour enabled by the 'subdir-objects' is the most -useful one, and in fact the *only* natural one, I'd like to make it the -only one available, simplifying the Automake implementation and APIs a -little in the process. - -Alas, since this also means changing the default behaviour of Automake -('subdir-objects' is not enabled by default, sadly), this means the -transition path will be less smooth than I'd like. - -DONE for automake 1.13.2 ------------------------- - -The bug spotted by Nick Bowler: - - - - -and exposed in test case 't/ccnoco4.sh' has been fixed (see commit -v1.13.1-56-g34001a9). The bug was due to the fact that Automake-generated -C compilation rules mistakenly passed the "-c -o" options combination -unconditionally (even to losing compiler) when the 'subdir-objects' was -used but sources were only present in the top-level directory. - -DONE for automake 1.14 ----------------------- - -We give a warning in the category 'unsupported' if the 'subdir-objects' -option is not specified. This should give the users enough forewarning -about the planned change, and give them time to update their packages -to the new semantic. - -We also make sure to avoid the warning when it would be irrelevant, i.e., -if all source files sit in "current" directory (thanks to Peter Johansson -for suggesting this). - -For automake 1.16 (*before* 2.0 can be released) ------------------------------------------------- - -Submit the pending patch series that fixes https://debbugs.gnu.org/13928 - -For automake 2.0 ----------------- - -Make the behaviour once activated by the 'subdir-object' option mandatory. -With that change, we'll drop support for the "old" behaviour of having -object files derived from sources in a subdirectory being placed in the -current directory rather than in that same subdirectory. - -Still keep the 'subdir-objects' option supported (as a simple no-op -now), to save useless churn in our user's build systems. diff --git a/PLANS/texi/drop-split-info-files.txt b/PLANS/texi/drop-split-info-files.txt deleted file mode 100644 index f13a32419..000000000 --- a/PLANS/texi/drop-split-info-files.txt +++ /dev/null @@ -1,27 +0,0 @@ -For in Automake 2.0 (DONE) --------------------------- - -We will drop split info files in Automake 2.0. -See automake bug#13351: . - -Basically, it has been confirmed that the original reason behind -the existence of split info files was indeed "efficiency, -especially memory size": - - -So split info files have lost their reason d'etre on modern systems -(where even Emacs has become a lightweight program ;-). And you are -not using an embedded system to read Info documentation, right? - -In addition, it appears that the use of split info files (at least -the way Automake-generated rules have been handling them for a long -time) can cause real problems in some (admittedly quite corner-case) -situations; see automake bug#12320: . - -This change should be completely transparent to the developer (no -adjustments needed to be made to Makefile.am or other parts of the -build system). In case some CI system or overly picky build script -used to rely on that feature, they'll have to be adjusted; but that -is expected to be a rare occurrence, and thus a price worth pay for -the nice simplifications and the fixlets this planned change will -offer us. diff --git a/PLANS/texi/warnings-for-automake-ng-compatibility.txt b/PLANS/texi/warnings-for-automake-ng-compatibility.txt deleted file mode 100644 index aca46b4a2..000000000 --- a/PLANS/texi/warnings-for-automake-ng-compatibility.txt +++ /dev/null @@ -1,21 +0,0 @@ -Done in automake 1.13.2: ------------------------- - -I have discouraged the use of '.txi' and '.texinfo' suffixes for -Texinfo inputs (see commit 'v1.13.1-6-ge1ed314') and the generation -of suffix-less info files (commit 'v1.13.1-4-g2af418d'). - -This is done to ease transition to Automake-NG (see commits -'v1.12.1-416-gd5459b9' and 'v1.12.1-392-ga0c7b6a' there), and -(to a lesser degree) to discourage use of seldom-tested setups. - - -The Future: ------------ - -I have no plans to do the further step of removing support for those -usages in future Automake versions. That would be a gratuitous -incompatibility (in Automake-NG, they have been useful because have -allowed further refactorings and improvements, but those were -based on GNU make features, and as such have no place in mainline -Automake). diff --git a/README b/README deleted file mode 100644 index e0150b81c..000000000 --- a/README +++ /dev/null @@ -1,68 +0,0 @@ -This is Automake, a Makefile generator. It aims to be portable and -to conform to the GNU Coding Standards for Makefile variables and -targets. - -See the INSTALL file for detailed information about how to configure -and install Automake. - -Automake is a Perl script. The input files are called Makefile.am. -The output files are called Makefile.in; they are intended for use -with Autoconf. Automake requires certain things to be done in your -configure.ac. - -Automake comes with extensive documentation; please refer to it for -more details about its purpose, features, and usage patterns. - -This package also includes the "aclocal" program, whose purpose is -to generate an 'aclocal.m4' based on the contents of 'configure.ac'. -It is useful as an extensible, maintainable mechanism for augmenting -autoconf. It is intended that other package authors will write m4 -macros which can be automatically used by aclocal. The documentation -for aclocal is currently found in the Automake manual. - -Automake has a test suite. Use "make check" to run it. For more -information, see the file t/README. - -Automake has a page on the web. See: - - https://www.gnu.org/software/automake/ - -Automake also has three mailing lists: - - * automake@gnu.org - For general discussions of Automake and its interactions with other - configuration/portability tools like Autoconf or Libtool. - - * bug-automake@gnu.org - Where to send bug reports and feature requests. - - * automake-patches@gnu.org - Where to send patches, and discuss the automake development process - and the design of new features. - -To obtain more information about these list, or to subscribe to them, -refer to - -New releases are announced to autotools-announce@gnu.org. If you want to -be informed, subscribe to that list by following the instructions at -. - -For any copyright year range specified as YYYY-ZZZZ in this package, -that the range specifies every single year in that closed interval. - ------ - -Copyright (C) 1994-2017 Free Software Foundation, Inc. - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2, or (at your option) -any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see . diff --git a/THANKS b/THANKS deleted file mode 100644 index a2b8c29ec..000000000 --- a/THANKS +++ /dev/null @@ -1,446 +0,0 @@ -Automake was originally written by David J. MacKenzie . -It would not be what it is today without the invaluable help of these -people: - -Adam J. Richter adam@yggdrasil.com -Adam Mercer ramercer@gmail.com -Adam Sampson ats@offog.org -Adrian Bunk bunk@fs.tum.de -Aharon Robbins arnold@skeeve.com -Akim Demaille akim@gnu.org -Alan Modra amodra@bigpond.net.au -Alex Hornby alex@anvil.co.uk -Alex Unleashed unledev@gmail.com -Alexander Mai st002279@hrzpub.tu-darmstadt.de -Alexander Martens alexander.martens@gtd.es -Alexander V. Lukyanov lav@yars.free.net -Alexander Turbov zaufi@sendmail.ru -Alexandre Duret-Lutz duret_g@epita.fr -Alexey Mahotkin alexm@hsys.msk.ru -Alfred M. Szmidt ams@gnu.org -Andrea Urbani matfanjol@mail.com -Andreas Bergmeier lcid-fire@gmx.net -Andreas Buening andreas.buening@nexgo.de -Andreas Köhler andi5.py@gmx.net -Andreas Schwab schwab@suse.de -Andrew Cagney cagney@tpgi.com.au -Andrew Eikum aeikum@codeweavers.com -Andrew Suffield asuffield@debian.org -Andris Pavenis pavenis@lanet.lv -Andy Wingo wingo@pobox.com -Angus Leeming a.leeming@ic.ac.uk -Anthony Green green@cygnus.com -Antonio Diaz Diaz ant_diaz@teleline.es -Arkadiusz Miskiewicz misiek@pld.ORG.PL -Art Haas ahaas@neosoft.com -Arto C. Nirkko anirkko@insel.ch -Assar Westerlund assar@sics.se -Axel Belinfante Axel.Belinfante@cs.utwente.nl -Bas Wijnen shevek@fmf.nl -Ben Pfaff blp@cs.standford.edu -Benoit Sigoure tsuna@lrde.epita.fr -Bernard Giroud bernard.giroud@creditlyonnais.ch -Bernard Urban Bernard.Urban@meteo.fr -Bernd Jendrissek berndfoobar@users.sourceforge.net -Bert Wesarg bert.wesarg@googlemail.com -Bill Currie bcurrie@tssc.co.nz -Bill Davidson bill@kayhay.com -Bill Fenner fenner@parc.xerox.com -Bob Friesenhahn bfriesen@simple.dallas.tx.us -Bob Proulx rwp@hprwp.fc.hp.com -Bob Rossi bob@brasko.net -Bobby Jack bobbykjack@yahoo.co.uk -Boris Kolpackov boris@codesynthesis.com -Braden N. McDaniel braden@endoframe.com -Brandon Black blblack@gmail.com -Brendan O'Dea bod@debian.org -Brian Cameron Brian.Cameron@Sun.COM -Brian Ford ford@vss.fsi.com -Brian Gough bjg@network-theory.co.uk -Brian Jones cbj@nortel.net -Bruce Korb bkorb@gnu.org -Bruno Haible haible@ilog.fr -Carnë Draug carandraug+dev@gmail.com -Carsten Lohrke carlo@gentoo.org -Charles Wilson cwilson@ece.gatech.edu -Chris Hoogendyk hoogendyk@bio.umass.edu -Chris Pickett chris.pickett@mail.mcgill.ca -Chris Provenzano proven@io.proven.org -Christian Cornelssen ccorn@cs.tu-berlin.de -Christina Gratorp christina.gratorp@gmail.com -Claudio Fontana sick_soul@yahoo.it -Clifford Wolf clifford@clifford.at -Colin Watson cjwatson@ubuntu.com -Dagobert Michelsen dam@opencsw.org -Daiki Ueno ueno@unixuser.org -Dalibor Topic robilad@kaffe.org -danbp danpb@nospam.postmaster.co.uk -Daniel Jacobowitz drow@false.org -Daniel Kahn Gillmor dkg@fifthhorseman.net -Daniel Richard G. skunk@iskunk.org -Debarshi Ray rishi@gnu.org -Dave Brolley brolley@redhat.com -Dave Goodell goodell@mcs.anl.gov -Dave Hart davehart@gmail.com -Dave Korn dave.korn.cygwin@googlemail.com -Dave Morrison dave@bnl.gov -David A. Swierczek swiercze@mr.med.ge.com -David A. Wheeler dwheeler@dwheeler.com -David Byron dbyron@dbyron.com -David Fang fang@csl.cornell.edu -Davyd Madeley davyd@fugro-fsi.com.au -David Pashley david@davidpashley.com -David Wohlferd dw@limegreensocks.com -David Zaroski cz253@cleveland.Freenet.Edu -Dean Povey dpovey@wedgetail.com -Dennis J. Linse Dennis.J.Linse@SAIC.com -Dennis Schridde devurandom@gmx.net -Derek R. Price derek.price@openavenue.com -Diab Jerius djerius@cfa.harvard.edu -Didier Cassirame faded@free.fr -Diego Elio Pettenò flameeyes@flameeyes.eu -Dieter Baron dillo@stieltjes.smc.univie.ac.at -Dieter Jurzitza DJurzitza@harmanbecker.com -Дилян Палаузов dilyan.palauzov@aegee.org -Dmitry Mikhin dmitrym@acres.com.au -Dmitry V. Levin ldv@altlinux.org -Doug Evans devans@cygnus.com -Duncan Gibson duncan@thermal.esa.int -Dilyan Palauzov dilyan.palauzov@aegee.org -Ed Hartnett ed@unidata.ucar.edu -Eleftherios Gkioulekas lf@amath.washington.edu -Elena A. Vengerova helen@oktetlabs.ru -Elmar Hoffmann elho@elho.net -Elrond Elrond@Wunder-Nett.org -Enrico Scholz enrico.scholz@informatik.tu-chemnitz.de -Erez Zadok ezk@cs.columbia.edu -Eric Bavier bavier@cray.com -Eric Blake eblake@redhat.com -Eric Dorland eric@debian.org -Eric Magnien emagnien@club-internet.fr -Eric Siegerman erics_97@pobox.com -Eric Sunshine sunshine@sunshineco.com -Erick Branderhorst branderh@iaehv.nl -Erik Lindahl E.Lindahl@chem.rug.nl -Esben Haabendal Soerensen bart@kom.aau.dk -Ezra Peisach epeisach@MED-XTAL.BU.EDU -Fabian Alenius fabian.alenius@gmail.com -Federico Simoncelli fsimonce@redhat.com -Felix Salfelder felix@salfelder.org -Flavien Astraud flav42@yahoo.fr -Florian Briegel briegel@zone42.de -Francesco Salvestrini salvestrini@gmail.com -François Pinard pinard@iro.umontreal.ca -Fred Fish fnf@ninemoons.com -Ganesan Rajagopal rganesan@novell.com -Garrett D'Amore garrett@qualcomm.com -Garth Corral garthc@inktomi.com -Gary V Vaughan gvaughan@oranda.demon.co.uk -Gavin Smith gavinsmith0123@gmail.com -Geoffrey Keating geoffk@apple.com -Glenn Amerine glenn@pie.mhsc.org -Gord Matzigkeit gord@gnu.ai.mit.edu -Gordon Sadler gbsadler1@lcisp.com -Graham Reitz grahamreitz@me.com -Greg A. Woods woods@most.weird.com -Greg Schafer gschafer@zip.com.au -Guido Draheim guidod@gmx.de -Guillermo Ontañón gontanonext@pandasoftware.es -Gustavo Carneiro gjc@inescporto.pt -Gwenole Beauchesne gbeauchesne@mandrakesoft.com -H.J. Lu hjl@lucon.org -H.Merijn Brand h.m.brand@hccnet.nl -Hans Ulrich Niedermann hun@n-dimensional.de -Hanspeter Niederstrasser fink@snaggledworks.com -Harald Dunkel harald@CoWare.com -Harlan Stenn Harlan.Stenn@pfcs.com -He Li tippa000@yahoo.com -Henrik Frystyk Nielsen frystyk@w3.org -Hib Eris hib@hiberis.nl -Hilko Bengen bengen@debian.org -Holger Hans Peter Freyther holger@freyther.de -Ian Lance Taylor ian@cygnus.com -Ignacy Gawedzki i@lri.fr -Илья Н. Голубев gin@mo.msk.ru -Imacat imacat@mail.imacat.idv.tw -Infirit infirit@gmail.com -Inoue inoue@ainet.or.jp -Jack Kelly jack@jackkelly.name -James Amundson amundson@users.sourceforge.net -James Bostock james.bostock@gmail.com -James Henstridge james@daa.com.au -James R. Van Zandt jrv@vanzandt.mv.com -James Youngman jay@gnu.org -Jan Engelhardt jengelh@medozas.de -Janos Farkas chexum@shadow.banki.hu -Jared Davis abiword@aiksaurus.com -Jason DeVinney jasondevinney@gmail.com -Jason Duell jcduell@lbl.gov -Jason Molenda crash@cygnus.co.jp -Javier Jardón jjardon@gnome.org -Jeff Bailey Jbailey@phn.ca -Jeff A. Daily jeff.daily@pnl.gov -Jeff Garzik jgarzik@pobox.com -Jeff Squyres jsquyres@lam-mpi.org -Jens Elkner elkner@imsgroup.de -Jens Krüger jens_krueger@physik.tu-muenchen.de -Jens Petersen petersen@redhat.com -Jeremy Nimmer jwnimmer@alum.mit.edu -Jerome Lovy jlovy@multimania.com -Jerome Santini santini@chambord.univ-orleans.fr -Jesse Chisholm jesse@ctc.volant.org -Jim Meyering meyering@na-net.ornl.gov -Joakim Tjernlund Joakim.Tjernlund@transmode.se -Jochen Kuepper jochen@uni-duesseldorf.de -Joel N. Weber II nemo@koa.iolani.honolulu.hi.us -Joerg-Martin Schwarz jms@jms.prima.ruhr.de -Johan Dahlin jdahlin@async.com.br -Johan Danielsson joda@pdc.kth.se -Johan Kristensen johankristensen@gmail.com -Johannes Nicolai johannes.nicolai@student.hpi.uni-potsdam.de -John Calcote john.calcote@gmail.com -John F Trudeau JohnTrudeau@firsthealth.com -John Pierce hawkfan@pyrotechnics.com -John Ratliff autoconf@technoplaza.net -John R. Cary cary@txcorp.com -John W. Coomes jcoomes@eng.Sun.COM -Jonathan L Peyton jonathan.l.peyton@intel.com -Jonathan Nieder jrnieder@gmail.com -Joseph S. Myers joseph@codesourcery.com -Josh MacDonald jmacd@cs.berkeley.edu -Joshua Cowan jcowan@jcowan.reslife.okstate.edu -js pendry js.pendry@msdw.com -Juergen A. Erhard jae@laden.ilk.de -Juergen Keil jk@tools.de -Juergen Leising juergen.leising@gmx.de -Julien Sopena julien.sopena@lip6.fr -Jürg Billeter j@bitron.ch -Karl Berry kb@cs.umb.edu -Karl Heuer kwzh@gnu.org -Kelley Cook kcook@gcc.gnu.org -Kent Boortz kent@mysql.com -Kevin Dalley kevin@aimnet.com -Kevin P. Fleming. kpfleming@cox.net -Kevin Ryde user42@zip.com.au -Kevin Street street@iname.com -Klaus Reichl Klaus.Reichl@alcatel.at -Krzysztof Żelechowski giecrilj@stegny.2a.pl -L. Peter Deutsch ghost@aladdin.com -Ladislav Strojil Ladislav.Strojil@seznam.cz -Larry Daniel larry@larrybrucedaniel.com -Larry Jones larry.jones@sdrc.com -Lars Hecking lhecking@nmrc.ucc.ie -Lars J. Aas larsa@sim.no -Laurent Morichetti laurentm@cup.hp.com -Leo Davis ldavis@fonix.com -Leonardo Boiko leoboiko@conectiva.com.br -Loulou Pouchet loulou@lrde.epita.fr -Ludovic Courtès ludo@gnu.org -Luo Yi luoyi.ly@gmail.com -Maciej Stachowiak mstachow@mit.edu -Maciej W. Rozycki macro@ds2.pg.gda.pl -Manu Rouat emmanuel.rouat@wanadoo.fr -Marc Herbert marc.herbert@intel.com -Marcus Brinkmann Marcus.Brinkmann@ruhr-uni-bochum.de -Marcus G. Daniels mgd@ute.santafe.edu -Marius Vollmer mvo@zagadka.ping.de -Marc-Antoine Perennou Marc-Antoine@Perennou.com -Mark D. Baushke mdb@cvshome.org -Mark Eichin eichin@cygnus.com -Mark Elbrecht snowball3@bigfoot.com -Mark Galassi rosalia@nis.lanl.gov -Mark Mitchell mark@codesourcery.com -Mark Phillips msp@nortelnetworks.com -Markku Rossi mtr@ngs.fi -Markus Duft Markus.Duft@salomon.at -Markus F.X.J. Oberhumer k3040e4@wildsau.idv-edu.uni-linz.ac.at -Martin Bravenboer martin@cs.uu.nl -Martin Frydl martin@idoox.com -Martin Waitz tali@admingilde.org -Mathias Doreille doreille@smr.ch -Mathias Froehlich M.Froehlich@science-computing.de -Mathias Hasselmann mathias.hasselmann@gmx.de -Matt Burgess matthew@linuxfromscratch.org -Matt Leach mleach@cygnus.com -Matthew D. Langston langston@SLAC.Stanford.EDU -Matthias Andree matthias.andree@gmx.de -Matthias Clasen clasen@mathematik.uni-freiburg.de -Matthias Klose doko@ubuntu.com -Matthieu Baerts matttbe@glx-dock.org -Max Horn max@quendi.de -Maxim Sinev good@goods.ru -Maynard Johnson maynardj@us.ibm.com -Merijn de Jonge M.de.Jonge@cwi.nl -Michael Brantley Michael-Brantley@deshaw.com -Michael Daniels mdaniels@rim.com -Michael Hofmann mhofma@googlemail.com -Michael Ploujnikov ploujj@gmail.com -Michael Zucchi notzed@gmail.com -Michel de Ruiter mdruiter@cs.vu.nl -Mike Castle dalgoda@ix.netcom.com -Mike Frysinger vapier@gentoo.org -Mike Nolta mrnolta@princeton.edu -Miles Bader miles@ccs.mt.nec.co.jp -Miloslav Trmac trmac@popelka.ms.mff.cuni.cz -Miodrag Vallat miodrag@ifrance.com -Mirko Streckenbach strecken@infosun.fmi.uni-passau.de -Miroslaw Dobrzanski-Neumann mne@mosaic-ag.com -Morten Eriksen mortene@sim.no -Motoyuki Kasahara m-kasahr@sra.co.jp -Nathanael Nerode neroden@twcny.rr.com -Nelson H. F. Beebe beebe@math.utah.edu -Nicholas Wourms nwourms@netscape.net -Nick Bowler nbowler@elliptictech.com -Nick Brown brownn@brocade.com -Nicola Fontana ntd@entidi.it -Nicolas Joly njoly@pasteur.fr -Nicolas Thiery nthiery@Icare.mines.edu -NightStrike nightstrike@gmail.com -Nik A. Melchior nam1@cse.wustl.edu -Nikolai Weibull now@bitwi.se -NISHIDA Keisuke knishida@nn.iij4u.or.jp -Noah Friedman friedman@gnu.ai.mit.edu -Norman Gray norman@astro.gla.ac.uk -Nyul Laszlo nyul@sol.cc.u-szeged.hu -OKUJI Yoshinori okuji@kuicr.kyoto-u.ac.jp -Olivier Fourdan fourdan@cena.fr -Olivier Louchart-Fletcher olivier@zipworld.com.au -Olly Betts olly@muscat.co.uk -Oren Ben-Kiki oren@ben-kiki.org -Owen Taylor otaylor@redhat.com -Panther Martin mrsmiley98@lycos.com -Patrick Welche prlw1@newn.cam.ac.uk -Patrik Weiskircher me@justp.at -Paul Berrevoets paul@swi.com -Paul D. Smith psmith@BayNetworks.COM -Paul Eggert eggert@twinsun.com -Paul Jarc prj@po.cwru.edu -Paul Lunau temp@lunau.me.uk -Paul Martinolich martinol@datasync.com -Paul Thomas PTHOMAS@novell.com -Pavel Raiskup praiskup@redhat.com -Pavel Roskin pavel_roskin@geocities.com -Pavel Sanda ps@twin.jikos.cz -Per Bothner bothner@cygnus.com -Per Cederqvist ceder@lysator.liu.se -Per Oyvind Hvidsten poeh@enter.vg -Peter Breitenlohner peb@mppmu.mpg.de -Peter Eisentraut peter_e@gmx.net -Peter Gavin pgavin@debaser.kicks-ass.org -Peter Hutterer peter.hutterer@who-t.net -Peter Johansson trojkan@gmail.com -Peter Mattis petm@scam.XCF.Berkeley.EDU -Peter Muir iyhi@yahoo.com -Peter O'Gorman peter@pogma.com -Peter Rosin peda@lysator.liu.se -Peter Seiderer seiderer123@ciselant.de -Petr Hracek phracek@redhat.com -Petter Reinholdtsen pere@hungry.com -Petteri Räty betelgeuse@gentoo.org -Phil Edwards phil@jaj.com -Phil Nelson phil@cs.wwu.edu -Philip Fong pwlfong@users.sourceforge.net -Philip S Tellis philip@ncst.ernet.in -Philipp A. Hartmann philipp.hartmann@offis.de -Пухальский Юрий Андреевич pooh@cryptopro.ru -Quentin Glidic sardemff7+gnu@sardemff7.net -Rainer Orth ro@techfak.uni-bielefeld.de -Rafael Laboissiere laboissiere@psy.mpg.de -Rainer Tammer tammer@tammer.net -Raja R Harinath harinath@cs.umn.edu -Ralf Corsepius ralf.corsepius@gmail.com -Ralf Menzel menzel@ls6.cs.uni-dortmund.de -Ralf Wildenhues Ralf.Wildenhues@gmx.de -Ralph Schleicher rs@purple.UL.BaWue.DE -Ramón García Fernández ramon@jl1.quim.ucm.es -Reuben Thomas rrt@sc3d.org -Rich Wales richw@webcom.com -Richard Boulton richard@tartarus.org -Richard Dawe rich@phekda.freeserve.co.uk -Richard W.M. Jones rjones@redhat.com -Rob Savoye rob@cygnus.com -Robert Bihlmeyer robbe@orcus.priv.at -Robert Boehne rboehne@ricardo-us.com -Robert Collins robert.collins@itdomain.com.au -Robert Swafford robert.swafford@l-3com.com -Roberto Bagnara bagnara@cs.unipr.it -Roman Fietze roman.fietze@telemotive.de -Ronald Copley ronald.copley@gmail.com -Ronald Landheer ronald@landheer.com -Roumen Petrov bugtrack@roumenpetrov.info -Russ Allbery rra@stanford.edu -Rusty Ballinger rusty@rlyeh.engr.sgi.com -Ryan Lortie desrt@desrt.ca -Ryan T. Sammartino ryants@shaw.ca -Sam Hocevar sam@zoy.org -Sam Sirlin sam@kalessin.jpl.nasa.gov -Sam Steingold sds@gnu.org -Sander Niemeijer niemeijer@science-and-technology.nl -Santiago Vila sanvila@unex.es -Scott James Remnant scott@netsplit.com -Sébastien Wilmet swilmet@gnome.org -Sergey Poznyakoff gray@gnu.org.ua -Sergey Vlasov vsu@mivlgu.murom.ru -Seth Alves alves@hungry.com -Shannon L. Brown slbrow@sandia.gov -Shuhei Amakawa sa264@cam.ac.uk -Shigio Yamaguchi shigio@tamacom.com -Simon Josefsson jas@extundo.com -Simon Richter sjr@debian.org -Stefan Nordhausen nordhaus@informatik.hu-berlin.de -Stefano Lattarini stefano.lattarini@gmail.com -Stepan Kasal kasal@math.cas.cz -Steve M. Robbins steve@nyongwa.montreal.qc.ca -Steve Goetze goetze@dovetail.com -Steven Drake sbd@NetBSD.org -Steven G. Johnson stevenj@alum.mit.edu -Sven Verdoolaege skimo@kotnet.org -Tamara L. Dahlgren dahlgren1@llnl.gov -Tatu Ylonen ylo@ssh.fi -Teun Burgers burgers@ecn.nl -The Crimson Binome steve@nyongwa.montreal.qc.ca -Theodoros V. Kalamatianos thkala@gmail.com -Thien-Thi Nguyen ttn@glug.org -Thomas Fitzsimmons fitzsim@redhat.com -Thomas Gagne tgagne@ix.netcom.com -Thomas Jahns jahns@dkrz.de -Thomas Klausner tk@giga.or.at -Thomas Morgan tmorgan@pobox.com -Thomas Schwinge tschwinge@gnu.org -Thomas Tanner tanner@ffii.org -Toralf Förster toralf.foerster@gmx.de -Tim Goodwin tjg@star.le.ac.uk -Tim Landscheidt tim@tim-landscheidt.de -Tim Mooney mooney@dogbert.cc.ndsu.NoDak.edu -Tim Retout diocles@debian.org -Tim Rice tim@multitalents.net -Tim Van Holder tim.van.holder@pandora.be -Tobias Hansen thansen@debian.org -Toshio Kuratomi toshio@tiki-lounge.com -Tom Epperly tepperly@llnl.gov -Tom Rini tom_rini@mentor.com -Ulrich Drepper drepper@gnu.ai.mit.edu -Ulrich Eckhardt eckhardt@satorlaser.com -Václav Haisman V.Haisman@sh.cvut.cz -Václav Zeman vhaisman@gmail.com -Vadim Zeitlin Vadim.zeitlin@dptmaths.ens-cachan.fr -Vasyl Khalak basiliomail@gmail.com -Vincent Lefevre vincent@vinc17.org -Vladimir Serbinenko phcoder@gmail.com -Volker Boerchers vboerchers@tecon.de -Weiller Ronfini weillerronfini@yahoo.com.br -Werner John john@oswf.de -Werner Koch wk@isil.d.shuttle.de -Werner Lemberg wl@gnu.org -William Pursell bill.pursell@gmail.com -William S Fulton wsf@fultondesigns.co.uk -Yann Droneaud ydroneaud@meuh.eu.org -Younes Younes younes@cs.tu-berlin.de -Zack Weinberg zackw@panix.com -Zbigniew Jędrzejewski-Szmek zbyszek@in.waw.pl -Zoltan Rado z.rado@chello.hu - -;; Local Variables: -;; mode: text -;; coding: utf-8 -;; End: diff --git a/bin/aclocal.in b/bin/aclocal.in deleted file mode 100644 index 45140feb5..000000000 --- a/bin/aclocal.in +++ /dev/null @@ -1,1243 +0,0 @@ -#!@PERL@ -w -# -*- perl -*- -# @configure_input@ - -eval 'case $# in 0) exec @PERL@ -S "$0";; *) exec @PERL@ -S "$0" "$@";; esac' - if 0; - -# aclocal - create aclocal.m4 by scanning configure.ac - -# Copyright (C) 1996-2017 Free Software Foundation, Inc. - -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -# Written by Tom Tromey , and -# Alexandre Duret-Lutz . - -BEGIN -{ - unshift (@INC, '@datadir@/@PACKAGE@-@APIVERSION@') - unless $ENV{AUTOMAKE_UNINSTALLED}; -} - -use strict; - -use Automake::Config; -use Automake::General; -use Automake::Channels; -use Automake::ChannelDefs; -use Automake::XFile; -use Automake::FileUtils; -use File::Basename; -use File::Path (); - -# Some globals. - -# Support AC_CONFIG_MACRO_DIRS also with older autoconf. -# FIXME: To be removed in Automake 2.0, once we can assume autoconf -# 2.70 or later. -# FIXME: keep in sync with 'internal/ac-config-macro-dirs.m4'. -my $ac_config_macro_dirs_fallback = - 'm4_ifndef([AC_CONFIG_MACRO_DIRS], [' . - 'm4_defun([_AM_CONFIG_MACRO_DIRS], [])' . - 'm4_defun([AC_CONFIG_MACRO_DIRS], [_AM_CONFIG_MACRO_DIRS($@)])' . - '])'; - -# We do not operate in threaded mode. -$perl_threads = 0; - -# Include paths for searching macros. We search macros in this order: -# user-supplied directories first, then the directory containing the -# automake macros, and finally the system-wide directories for -# third-party macros. -# @user_includes can be augmented with -I or AC_CONFIG_MACRO_DIRS. -# @automake_includes can be reset with the '--automake-acdir' option. -# @system_includes can be augmented with the 'dirlist' file or the -# ACLOCAL_PATH environment variable, and reset with the '--system-acdir' -# option. -my @user_includes = (); -my @automake_includes = ('@datadir@/aclocal-' . $APIVERSION); -my @system_includes = ('@datadir@/aclocal'); - -# Whether we should copy M4 file in $user_includes[0]. -my $install = 0; - -# --diff -my @diff_command; - -# --dry-run -my $dry_run = 0; - -# Name of the Autoconf input file. We used to support 'configure.in' -# as well once, that that is long obsolete now. -my $configure_ac = 'configure.ac'; - -# Output file name. -my $output_file = 'aclocal.m4'; - -# Option --force. -my $force_output = 0; - -# Modification time of the youngest dependency. -my $greatest_mtime = 0; - -# Which macros have been seen. -my %macro_seen = (); - -# Remember the order into which we scanned the files. -# It's important to output the contents of aclocal.m4 in the opposite order. -# (Definitions in first files we have scanned should override those from -# later files. So they must appear last in the output.) -my @file_order = (); - -# Map macro names to file names. -my %map = (); - -# Ditto, but records the last definition of each macro as returned by --trace. -my %map_traced_defs = (); - -# Map basenames to macro names. -my %invmap = (); - -# Map file names to file contents. -my %file_contents = (); - -# Map file names to file types. -my %file_type = (); -use constant FT_USER => 1; -use constant FT_AUTOMAKE => 2; -use constant FT_SYSTEM => 3; - -# Map file names to included files (transitively closed). -my %file_includes = (); - -# Files which have already been added. -my %file_added = (); - -# Files that have already been scanned. -my %scanned_configure_dep = (); - -# Serial numbers, for files that have one. -# The key is the basename of the file, -# the value is the serial number represented as a list. -my %serial = (); - -# Matches a macro definition. -# AC_DEFUN([macroname], ...) -# or -# AC_DEFUN(macroname, ...) -# When macroname is '['-quoted , we accept any character in the name, -# except ']'. Otherwise macroname stops on the first ']', ',', ')', -# or '\n' encountered. -my $ac_defun_rx = - "(?:AU_ALIAS|A[CU]_DEFUN|AC_DEFUN_ONCE)\\((?:\\[([^]]+)\\]|([^],)\n]+))"; - -# Matches an AC_REQUIRE line. -my $ac_require_rx = "AC_REQUIRE\\((?:\\[([^]]+)\\]|([^],)\n]+))\\)"; - -# Matches an m4_include line. -my $m4_include_rx = "(m4_|m4_s|s)include\\((?:\\[([^]]+)\\]|([^],)\n]+))\\)"; - -# Match a serial number. -my $serial_line_rx = '^#\s*serial\s+(\S*)'; -my $serial_number_rx = '^\d+(?:\.\d+)*$'; - -# Autoconf version. This variable is set by 'trace_used_macros'. -my $ac_version; - -# User directory containing extra m4 files for macros definition, -# as extracted from calls to the macro AC_CONFIG_MACRO_DIRS. -# This variable is updated by 'trace_used_macros'. -my @ac_config_macro_dirs; - -# If set, names a temporary file that must be erased on abnormal exit. -my $erase_me; - -# Constants for the $ERR_LEVEL parameter of the 'scan_m4_dirs' function. -use constant SCAN_M4_DIRS_SILENT => 0; -use constant SCAN_M4_DIRS_WARN => 1; -use constant SCAN_M4_DIRS_ERROR => 2; - -################################################################ - -# Prototypes for all subroutines. - -sub add_file ($); -sub add_macro ($); -sub check_acinclude (); -sub install_file ($$); -sub list_compare (\@\@); -sub parse_ACLOCAL_PATH (); -sub parse_arguments (); -sub reset_maps (); -sub scan_configure (); -sub scan_configure_dep ($); -sub scan_file ($$$); -sub scan_m4_dirs ($$@); -sub scan_m4_files (); -sub strip_redundant_includes (%); -sub trace_used_macros (); -sub unlink_tmp (;$); -sub usage ($); -sub version (); -sub write_aclocal ($@); -sub xmkdir_p ($); - -################################################################ - -# Erase temporary file ERASE_ME. Handle signals. -sub unlink_tmp (;$) -{ - my ($sig) = @_; - - if ($sig) - { - verb "caught SIG$sig, bailing out"; - } - if (defined $erase_me && -e $erase_me && !unlink ($erase_me)) - { - fatal "could not remove '$erase_me': $!"; - } - undef $erase_me; - - # reraise default handler. - if ($sig) - { - $SIG{$sig} = 'DEFAULT'; - kill $sig => $$; - } -} - -$SIG{'INT'} = $SIG{'TERM'} = $SIG{'QUIT'} = $SIG{'HUP'} = 'unlink_tmp'; -END { unlink_tmp } - -sub xmkdir_p ($) -{ - my $dir = shift; - local $@ = undef; - return - if -d $dir or eval { File::Path::mkpath $dir }; - chomp $@; - $@ =~ s/\s+at\s.*\bline\s\d+.*$//; - fatal "could not create directory '$dir': $@"; -} - -# Check macros in acinclude.m4. If one is not used, warn. -sub check_acinclude () -{ - foreach my $key (keys %map) - { - # FIXME: should print line number of acinclude.m4. - msg ('syntax', "macro '$key' defined in acinclude.m4 but never used") - if $map{$key} eq 'acinclude.m4' && ! exists $macro_seen{$key}; - } -} - -sub reset_maps () -{ - $greatest_mtime = 0; - %macro_seen = (); - @file_order = (); - %map = (); - %map_traced_defs = (); - %file_contents = (); - %file_type = (); - %file_includes = (); - %file_added = (); - %scanned_configure_dep = (); - %invmap = (); - %serial = (); - undef &search; -} - -# install_file ($SRC, $DESTDIR) -sub install_file ($$) -{ - my ($src, $destdir) = @_; - my $dest = $destdir . "/" . basename ($src); - my $diff_dest; - - verb "installing $src to $dest"; - - if ($force_output - || !exists $file_contents{$dest} - || $file_contents{$src} ne $file_contents{$dest}) - { - if (-e $dest) - { - msg 'note', "overwriting '$dest' with '$src'"; - $diff_dest = $dest; - } - else - { - msg 'note', "installing '$dest' from '$src'"; - } - - if (@diff_command) - { - if (! defined $diff_dest) - { - # $dest does not exist. We create an empty one just to - # run diff, and we erase it afterward. Using the real - # the destination file (rather than a temporary file) is - # good when diff is run with options that display the - # file name. - # - # If creating $dest fails, fall back to /dev/null. At - # least one diff implementation (Tru64's) cannot deal - # with /dev/null. However working around this is not - # worth the trouble since nobody run aclocal on a - # read-only tree anyway. - $erase_me = $dest; - my $f = new IO::File "> $dest"; - if (! defined $f) - { - undef $erase_me; - $diff_dest = '/dev/null'; - } - else - { - $diff_dest = $dest; - $f->close; - } - } - my @cmd = (@diff_command, $diff_dest, $src); - $! = 0; - verb "running: @cmd"; - my $res = system (@cmd); - Automake::FileUtils::handle_exec_errors "@cmd", 1 - if $res; - unlink_tmp; - } - elsif (!$dry_run) - { - xmkdir_p ($destdir); - xsystem ('cp', $src, $dest); - } - } -} - -# Compare two lists of numbers. -sub list_compare (\@\@) -{ - my @l = @{$_[0]}; - my @r = @{$_[1]}; - while (1) - { - if (0 == @l) - { - return (0 == @r) ? 0 : -1; - } - elsif (0 == @r) - { - return 1; - } - elsif ($l[0] < $r[0]) - { - return -1; - } - elsif ($l[0] > $r[0]) - { - return 1; - } - shift @l; - shift @r; - } -} - -################################################################ - -# scan_m4_dirs($TYPE, $ERR_LEVEL, @DIRS) -# ----------------------------------------------- -# Scan all M4 files installed in @DIRS for new macro definitions. -# Register each file as of type $TYPE (one of the FT_* constants). -# If a directory in @DIRS cannot be read: -# - fail hard if $ERR_LEVEL == SCAN_M4_DIRS_ERROR -# - just print a warning if $ERR_LEVEL == SCAN_M4_DIRS_WA -# - continue silently if $ERR_LEVEL == SCAN_M4_DIRS_SILENT -sub scan_m4_dirs ($$@) -{ - my ($type, $err_level, @dirlist) = @_; - - foreach my $m4dir (@dirlist) - { - if (! opendir (DIR, $m4dir)) - { - # TODO: maybe avoid complaining only if errno == ENONENT? - my $message = "couldn't open directory '$m4dir': $!"; - - if ($err_level == SCAN_M4_DIRS_ERROR) - { - fatal $message; - } - elsif ($err_level == SCAN_M4_DIRS_WARN) - { - msg ('unsupported', $message); - next; - } - elsif ($err_level == SCAN_M4_DIRS_SILENT) - { - next; # Silently ignore. - } - else - { - prog_error "invalid \$err_level value '$err_level'"; - } - } - - # We reverse the directory contents so that foo2.m4 gets - # used in preference to foo1.m4. - foreach my $file (reverse sort grep (! /^\./, readdir (DIR))) - { - # Only examine .m4 files. - next unless $file =~ /\.m4$/; - - # Skip some files when running out of srcdir. - next if $file eq 'aclocal.m4'; - - my $fullfile = File::Spec->canonpath ("$m4dir/$file"); - scan_file ($type, $fullfile, 'aclocal'); - } - closedir (DIR); - } -} - -# Scan all the installed m4 files and construct a map. -sub scan_m4_files () -{ - # First, scan configure.ac. It may contain macro definitions, - # or may include other files that define macros. - scan_file (FT_USER, $configure_ac, 'aclocal'); - - # Then, scan acinclude.m4 if it exists. - if (-f 'acinclude.m4') - { - scan_file (FT_USER, 'acinclude.m4', 'aclocal'); - } - - # Finally, scan all files in our search paths. - - if (@user_includes) - { - # Don't explore the same directory multiple times. This is here not - # only for speedup purposes. We need this when the user has e.g. - # specified 'ACLOCAL_AMFLAGS = -I m4' and has also set - # AC_CONFIG_MACRO_DIR[S]([m4]) in configure.ac. This makes the 'm4' - # directory to occur twice here and fail on the second call to - # scan_m4_dirs([m4]) when the 'm4' directory doesn't exist. - # TODO: Shouldn't there be rather a check in scan_m4_dirs for - # @user_includes[0]? - @user_includes = uniq @user_includes; - - # Don't complain if the first user directory doesn't exist, in case - # we need to create it later (can happen if '--install' was given). - scan_m4_dirs (FT_USER, - $install ? SCAN_M4_DIRS_SILENT : SCAN_M4_DIRS_WARN, - $user_includes[0]); - scan_m4_dirs (FT_USER, - SCAN_M4_DIRS_ERROR, - @user_includes[1..$#user_includes]); - } - scan_m4_dirs (FT_SYSTEM, SCAN_M4_DIRS_ERROR, @system_includes); - scan_m4_dirs (FT_AUTOMAKE, SCAN_M4_DIRS_ERROR, @automake_includes); - - # Construct a new function that does the searching. We use a - # function (instead of just evaluating $search in the loop) so that - # "die" is correctly and easily propagated if run. - my $search = "sub search {\nmy \$found = 0;\n"; - foreach my $key (reverse sort keys %map) - { - $search .= ('if (/\b\Q' . $key . '\E(?!\w)/) { add_macro ("' . $key - . '"); $found = 1; }' . "\n"); - } - $search .= "return \$found;\n};\n"; - eval $search; - prog_error "$@\n search is $search" if $@; -} - -################################################################ - -# Add a macro to the output. -sub add_macro ($) -{ - my ($macro) = @_; - - # Ignore unknown required macros. Either they are not really - # needed (e.g., a conditional AC_REQUIRE), in which case aclocal - # should be quiet, or they are needed and Autoconf itself will - # complain when we trace for macro usage later. - return unless defined $map{$macro}; - - verb "saw macro $macro"; - $macro_seen{$macro} = 1; - add_file ($map{$macro}); -} - -# scan_configure_dep ($file) -# -------------------------- -# Scan a configure dependency (configure.ac, or separate m4 files) -# for uses of known macros and AC_REQUIREs of possibly unknown macros. -# Recursively scan m4_included files. -sub scan_configure_dep ($) -{ - my ($file) = @_; - # Do not scan a file twice. - return () - if exists $scanned_configure_dep{$file}; - $scanned_configure_dep{$file} = 1; - - my $mtime = mtime $file; - $greatest_mtime = $mtime if $greatest_mtime < $mtime; - - my $contents = exists $file_contents{$file} ? - $file_contents{$file} : contents $file; - - my $line = 0; - my @rlist = (); - my @ilist = (); - foreach (split ("\n", $contents)) - { - ++$line; - # Remove comments from current line. - s/\bdnl\b.*$//; - s/\#.*$//; - # Avoid running all the following regexes on white lines. - next if /^\s*$/; - - while (/$m4_include_rx/go) - { - my $ifile = $2 || $3; - # Skip missing 'sinclude'd files. - next if $1 ne 'm4_' && ! -f $ifile; - push @ilist, $ifile; - } - - while (/$ac_require_rx/go) - { - push (@rlist, $1 || $2); - } - - # The search function is constructed dynamically by - # scan_m4_files. The last parenthetical match makes sure we - # don't match things that look like macro assignments or - # AC_SUBSTs. - if (! &search && /(^|\s+)(AM_[A-Z0-9_]+)($|[^\]\)=A-Z0-9_])/) - { - # Macro not found, but AM_ prefix found. - # Make this just a warning, because we do not know whether - # the macro is actually used (it could be called conditionally). - msg ('unsupported', "$file:$line", - "macro '$2' not found in library"); - } - } - - add_macro ($_) foreach (@rlist); - scan_configure_dep ($_) foreach @ilist; -} - -# add_file ($FILE) -# ---------------- -# Add $FILE to output. -sub add_file ($) -{ - my ($file) = @_; - - # Only add a file once. - return if ($file_added{$file}); - $file_added{$file} = 1; - - scan_configure_dep $file; -} - -# Point to the documentation for underquoted AC_DEFUN only once. -my $underquoted_manual_once = 0; - -# scan_file ($TYPE, $FILE, $WHERE) -# -------------------------------- -# Scan a single M4 file ($FILE), and all files it includes. -# Return the list of included files. -# $TYPE is one of FT_USER, FT_AUTOMAKE, or FT_SYSTEM, depending -# on where the file comes from. -# $WHERE is the location to use in the diagnostic if the file -# does not exist. -sub scan_file ($$$) -{ - my ($type, $file, $where) = @_; - my $basename = basename $file; - - # Do not scan the same file twice. - return @{$file_includes{$file}} if exists $file_includes{$file}; - # Prevent potential infinite recursion (if two files include each other). - return () if exists $file_contents{$file}; - - unshift @file_order, $file; - - $file_type{$file} = $type; - - fatal "$where: file '$file' does not exist" if ! -e $file; - - my $fh = new Automake::XFile $file; - my $contents = ''; - my @inc_files = (); - my %inc_lines = (); - - my $defun_seen = 0; - my $serial_seen = 0; - my $serial_older = 0; - - while ($_ = $fh->getline) - { - # Ignore '##' lines. - next if /^##/; - - $contents .= $_; - my $line = $_; - - if ($line =~ /$serial_line_rx/go) - { - my $number = $1; - if ($number !~ /$serial_number_rx/go) - { - msg ('syntax', "$file:$.", - "ill-formed serial number '$number', " - . "expecting a version string with only digits and dots"); - } - elsif ($defun_seen) - { - # aclocal removes all definitions from M4 file with the - # same basename if a greater serial number is found. - # Encountering a serial after some macros will undefine - # these macros... - msg ('syntax', "$file:$.", - 'the serial number must appear before any macro definition'); - } - # We really care about serials only for non-automake macros - # and when --install is used. But the above diagnostics are - # made regardless of this, because not using --install is - # not a reason not the fix macro files. - elsif ($install && $type != FT_AUTOMAKE) - { - $serial_seen = 1; - my @new = split (/\./, $number); - - verb "$file:$.: serial $number"; - - if (!exists $serial{$basename} - || list_compare (@new, @{$serial{$basename}}) > 0) - { - # Delete any definition we knew from the old macro. - foreach my $def (@{$invmap{$basename}}) - { - verb "$file:$.: ignoring previous definition of $def"; - delete $map{$def}; - } - $invmap{$basename} = []; - $serial{$basename} = \@new; - } - else - { - $serial_older = 1; - } - } - } - - # Remove comments from current line. - # Do not do it earlier, because the serial line is a comment. - $line =~ s/\bdnl\b.*$//; - $line =~ s/\#.*$//; - - while ($line =~ /$ac_defun_rx/go) - { - $defun_seen = 1; - if (! defined $1) - { - msg ('syntax', "$file:$.", "underquoted definition of $2" - . "\n run info Automake 'Extending aclocal'\n" - . " or see https://www.gnu.org/software/automake/manual/" - . "automake.html#Extending-aclocal") - unless $underquoted_manual_once; - $underquoted_manual_once = 1; - } - - # If this macro does not have a serial and we have already - # seen a macro with the same basename earlier, we should - # ignore the macro (don't exit immediately so we can still - # diagnose later #serial numbers and underquoted macros). - $serial_older ||= ($type != FT_AUTOMAKE - && !$serial_seen && exists $serial{$basename}); - - my $macro = $1 || $2; - if (!$serial_older && !defined $map{$macro}) - { - verb "found macro $macro in $file: $."; - $map{$macro} = $file; - push @{$invmap{$basename}}, $macro; - } - else - { - # Note: we used to give an error here if we saw a - # duplicated macro. However, this turns out to be - # extremely unpopular. It causes actual problems which - # are hard to work around, especially when you must - # mix-and-match tool versions. - verb "ignoring macro $macro in $file: $."; - } - } - - while ($line =~ /$m4_include_rx/go) - { - my $ifile = $2 || $3; - # Skip missing 'sinclude'd files. - next if $1 ne 'm4_' && ! -f $ifile; - push (@inc_files, $ifile); - $inc_lines{$ifile} = $.; - } - } - - # Ignore any file that has an old serial (or no serial if we know - # another one with a serial). - return () - if ($serial_older || - ($type != FT_AUTOMAKE && !$serial_seen && exists $serial{$basename})); - - $file_contents{$file} = $contents; - - # For some reason I don't understand, it does not work - # to do "map { scan_file ($_, ...) } @inc_files" below. - # With Perl 5.8.2 it undefines @inc_files. - my @copy = @inc_files; - my @all_inc_files = (@inc_files, - map { scan_file ($type, $_, - "$file:$inc_lines{$_}") } @copy); - $file_includes{$file} = \@all_inc_files; - return @all_inc_files; -} - -# strip_redundant_includes (%FILES) -# --------------------------------- -# Each key in %FILES is a file that must be present in the output. -# However some of these files might already include other files in %FILES, -# so there is no point in including them another time. -# This removes items of %FILES which are already included by another file. -sub strip_redundant_includes (%) -{ - my %files = @_; - - # Always include acinclude.m4, even if it does not appear to be used. - $files{'acinclude.m4'} = 1 if -f 'acinclude.m4'; - # File included by $configure_ac are redundant. - $files{$configure_ac} = 1; - - # Files at the end of @file_order should override those at the beginning, - # so it is important to preserve these trailing files. We can remove - # a file A if it is going to be output before a file B that includes - # file A, not the converse. - foreach my $file (reverse @file_order) - { - next unless exists $files{$file}; - foreach my $ifile (@{$file_includes{$file}}) - { - next unless exists $files{$ifile}; - delete $files{$ifile}; - verb "$ifile is already included by $file"; - } - } - - # configure.ac is implicitly included. - delete $files{$configure_ac}; - - return %files; -} - -sub trace_used_macros () -{ - my %files = map { $map{$_} => 1 } keys %macro_seen; - %files = strip_redundant_includes %files; - - # When AC_CONFIG_MACRO_DIRS is used, avoid possible spurious warnings - # from autom4te about macros being "m4_require'd but not m4_defun'd"; - # for more background, see: - # https://lists.gnu.org/archive/html/autoconf-patches/2012-11/msg00004.html - # as well as autoconf commit 'v2.69-44-g1ed0548', "warn: allow aclocal - # to silence m4_require warnings". - my $early_m4_code .= "m4_define([m4_require_silent_probe], [-])"; - - my $traces = ($ENV{AUTOM4TE} || '@am_AUTOM4TE@'); - $traces .= " --language Autoconf-without-aclocal-m4 "; - $traces = "echo '$early_m4_code' | $traces - "; - - # Support AC_CONFIG_MACRO_DIRS also with older autoconf. - # Note that we can't use '$ac_config_macro_dirs_fallback' here, because - # a bug in option parsing code of autom4te 2.68 and earlier will cause - # it to read standard input last, even if the "-" argument is specified - # early. - # FIXME: To be removed in Automake 2.0, once we can assume autoconf - # 2.70 or later. - $traces .= "$automake_includes[0]/internal/ac-config-macro-dirs.m4 "; - - # All candidate files. - $traces .= join (' ', - (map { "'$_'" } - (grep { exists $files{$_} } @file_order))) . " "; - - # All candidate macros. - $traces .= join (' ', - (map { "--trace='$_:\$f::\$n::\${::}%'" } - ('AC_DEFUN', - 'AC_DEFUN_ONCE', - 'AU_DEFUN', - '_AM_AUTOCONF_VERSION', - 'AC_CONFIG_MACRO_DIR_TRACE', - # FIXME: Tracing the next two macros is a hack for - # compatibility with older autoconf. Remove this in - # Automake 2.0, when we can assume Autoconf 2.70 or - # later. - 'AC_CONFIG_MACRO_DIR', - '_AM_CONFIG_MACRO_DIRS')), - # Do not trace $1 for all other macros as we do - # not need it and it might contains harmful - # characters (like newlines). - (map { "--trace='$_:\$f::\$n'" } (keys %macro_seen))); - - verb "running $traces $configure_ac"; - - my $tracefh = new Automake::XFile ("$traces $configure_ac |"); - - @ac_config_macro_dirs = (); - - my %traced = (); - - while ($_ = $tracefh->getline) - { - chomp; - my ($file, $macro, $arg1) = split (/::/); - - $traced{$macro} = 1 if exists $macro_seen{$macro}; - - if ($macro eq 'AC_DEFUN' || $macro eq 'AC_DEFUN_ONCE' - || $macro eq 'AU_DEFUN') - { - $map_traced_defs{$arg1} = $file; - } - elsif ($macro eq '_AM_AUTOCONF_VERSION') - { - $ac_version = $arg1; - } - elsif ($macro eq 'AC_CONFIG_MACRO_DIR_TRACE') - { - push @ac_config_macro_dirs, $arg1; - } - # FIXME: We still need to trace AC_CONFIG_MACRO_DIR - # for compatibility with older autoconf. Remove this - # once we can assume Autoconf 2.70 or later. - elsif ($macro eq 'AC_CONFIG_MACRO_DIR') - { - @ac_config_macro_dirs = ($arg1); - } - # FIXME:This is an hack for compatibility with older autoconf. - # Remove this once we can assume Autoconf 2.70 or later. - elsif ($macro eq '_AM_CONFIG_MACRO_DIRS') - { - # Empty leading/trailing fields might be produced by split, - # hence the grep is really needed. - push @ac_config_macro_dirs, grep (/./, (split /\s+/, $arg1)); - } - } - - # FIXME: in Autoconf >= 2.70, AC_CONFIG_MACRO_DIR calls - # AC_CONFIG_MACRO_DIR_TRACE behind the scenes, which could - # leave unwanted duplicates in @ac_config_macro_dirs. - # Remove this in Automake 2.0, when we'll stop tracing - # AC_CONFIG_MACRO_DIR explicitly. - @ac_config_macro_dirs = uniq @ac_config_macro_dirs; - - $tracefh->close; - - return %traced; -} - -sub scan_configure () -{ - # Make sure we include acinclude.m4 if it exists. - if (-f 'acinclude.m4') - { - add_file ('acinclude.m4'); - } - scan_configure_dep ($configure_ac); -} - -################################################################ - -# Write output. -# Return 0 iff some files were installed locally. -sub write_aclocal ($@) -{ - my ($output_file, @macros) = @_; - my $output = ''; - - my %files = (); - # Get the list of files containing definitions for the macros used. - # (Filter out unused macro definitions with $map_traced_defs. This - # can happen when an Autoconf macro is conditionally defined: - # aclocal sees the potential definition, but this definition is - # actually never processed and the Autoconf implementation is used - # instead.) - for my $m (@macros) - { - $files{$map{$m}} = 1 - if (exists $map_traced_defs{$m} - && $map{$m} eq $map_traced_defs{$m}); - } - # Do not explicitly include a file that is already indirectly included. - %files = strip_redundant_includes %files; - - my $installed = 0; - - for my $file (grep { exists $files{$_} } @file_order) - { - # Check the time stamp of this file, and of all files it includes. - for my $ifile ($file, @{$file_includes{$file}}) - { - my $mtime = mtime $ifile; - $greatest_mtime = $mtime if $greatest_mtime < $mtime; - } - - # If the file to add looks like outside the project, copy it - # to the output. The regex catches filenames starting with - # things like '/', '\', or 'c:\'. - if ($file_type{$file} != FT_USER - || $file =~ m,^(?:\w:)?[\\/],) - { - if (!$install || $file_type{$file} != FT_SYSTEM) - { - # Copy the file into aclocal.m4. - $output .= $file_contents{$file} . "\n"; - } - else - { - # Install the file (and any file it includes). - my $dest; - for my $ifile (@{$file_includes{$file}}, $file) - { - install_file ($ifile, $user_includes[0]); - } - $installed = 1; - } - } - else - { - # Otherwise, simply include the file. - $output .= "m4_include([$file])\n"; - } - } - - if ($installed) - { - verb "running aclocal anew, because some files were installed locally"; - return 0; - } - - # Nothing to output?! - # FIXME: Shouldn't we diagnose this? - return 1 if ! length ($output); - - if ($ac_version) - { - # Do not use "$output_file" here for the same reason we do not - # use it in the header below. autom4te will output the name of - # the file in the diagnostic anyway. - $output = "m4_ifndef([AC_AUTOCONF_VERSION], - [m4_copy([m4_PACKAGE_VERSION], [AC_AUTOCONF_VERSION])])dnl -m4_if(m4_defn([AC_AUTOCONF_VERSION]), [$ac_version],, -[m4_warning([this file was generated for autoconf $ac_version. -You have another version of autoconf. It may work, but is not guaranteed to. -If you have problems, you may need to regenerate the build system entirely. -To do so, use the procedure documented by the package, typically 'autoreconf'.])]) - -$output"; - } - - # We used to print "# $output_file generated automatically etc." But - # this creates spurious differences when using autoreconf. Autoreconf - # creates aclocal.m4t and then rename it to aclocal.m4, but the - # rebuild rules generated by Automake create aclocal.m4 directly -- - # this would gives two ways to get the same file, with a different - # name in the header. - $output = "# generated automatically by aclocal $VERSION -*- Autoconf -*- - -# Copyright (C) 1996-$RELEASE_YEAR Free Software Foundation, Inc. - -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY, to the extent permitted by law; without -# even the implied warranty of MERCHANTABILITY or FITNESS FOR A -# PARTICULAR PURPOSE. - -$ac_config_macro_dirs_fallback -$output"; - - # We try not to update $output_file unless necessary, because - # doing so invalidate Autom4te's cache and therefore slows down - # tools called after aclocal. - # - # We need to overwrite $output_file in the following situations. - # * The --force option is in use. - # * One of the dependencies is younger. - # (Not updating $output_file in this situation would cause - # make to call aclocal in loop.) - # * The contents of the current file are different from what - # we have computed. - if (!$force_output - && $greatest_mtime < mtime ($output_file) - && $output eq contents ($output_file)) - { - verb "$output_file unchanged"; - return 1; - } - - verb "writing $output_file"; - - if (!$dry_run) - { - if (-e $output_file && !unlink $output_file) - { - fatal "could not remove '$output_file': $!"; - } - my $out = new Automake::XFile "> $output_file"; - print $out $output; - } - return 1; -} - -################################################################ - -# Print usage and exit. -sub usage ($) -{ - my ($status) = @_; - - print <<'EOF'; -Usage: aclocal [OPTION]... - -Generate 'aclocal.m4' by scanning 'configure.ac' - -Options: - --automake-acdir=DIR directory holding automake-provided m4 files - --system-acdir=DIR directory holding third-party system-wide files - --diff[=COMMAND] run COMMAND [diff -u] on M4 files that would be - changed (implies --install and --dry-run) - --dry-run pretend to, but do not actually update any file - --force always update output file - --help print this help, then exit - -I DIR add directory to search list for .m4 files - --install copy third-party files to the first -I directory - --output=FILE put output in FILE (default aclocal.m4) - --print-ac-dir print name of directory holding system-wide - third-party m4 files, then exit - --verbose don't be silent - --version print version number, then exit - -W, --warnings=CATEGORY report the warnings falling in CATEGORY - -Warning categories include: - syntax dubious syntactic constructs (default) - unsupported unknown macros (default) - all all the warnings (default) - no-CATEGORY turn off warnings in CATEGORY - none turn off all the warnings - error treat warnings as errors - -Report bugs to <@PACKAGE_BUGREPORT@>. -GNU Automake home page: <@PACKAGE_URL@>. -General help using GNU software: . -EOF - exit $status; -} - -# Print version and exit. -sub version () -{ - print < -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. - -Written by Tom Tromey - and Alexandre Duret-Lutz . -EOF - exit 0; -} - -# Parse command line. -sub parse_arguments () -{ - my $print_and_exit = 0; - my $diff_command; - - my %cli_options = - ( - 'help' => sub { usage(0); }, - 'version' => \&version, - 'system-acdir=s' => sub { shift; @system_includes = @_; }, - 'automake-acdir=s' => sub { shift; @automake_includes = @_; }, - 'diff:s' => \$diff_command, - 'dry-run' => \$dry_run, - 'force' => \$force_output, - 'I=s' => \@user_includes, - 'install' => \$install, - 'output=s' => \$output_file, - 'print-ac-dir' => \$print_and_exit, - 'verbose' => sub { setup_channel 'verb', silent => 0; }, - 'W|warnings=s' => \&parse_warnings, - ); - - use Automake::Getopt (); - Automake::Getopt::parse_options %cli_options; - - if (@ARGV > 0) - { - fatal ("non-option arguments are not accepted: '$ARGV[0]'.\n" - . "Try '$0 --help' for more information."); - } - - if ($print_and_exit) - { - print "@system_includes\n"; - exit 0; - } - - if (defined $diff_command) - { - $diff_command = 'diff -u' if $diff_command eq ''; - @diff_command = split (' ', $diff_command); - $install = 1; - $dry_run = 1; - } - - # Finally, adds any directory listed in the 'dirlist' file. - if (@system_includes && open (DIRLIST, "$system_includes[0]/dirlist")) - { - while () - { - # Ignore '#' lines. - next if /^#/; - # strip off newlines and end-of-line comments - s/\s*\#.*$//; - chomp; - foreach my $dir (glob) - { - push (@system_includes, $dir) if -d $dir; - } - } - close (DIRLIST); - } -} - -# Add any directory listed in the 'ACLOCAL_PATH' environment variable -# to the list of system include directories. -sub parse_ACLOCAL_PATH () -{ - return if not defined $ENV{"ACLOCAL_PATH"}; - # Directories in ACLOCAL_PATH should take precedence over system - # directories, so we use unshift. However, directories that - # come first in ACLOCAL_PATH take precedence over directories - # coming later, which is why the result of split is reversed. - foreach my $dir (reverse split /:/, $ENV{"ACLOCAL_PATH"}) - { - unshift (@system_includes, $dir) if $dir ne '' && -d $dir; - } -} - -################################################################ - -# Don't refer to installation directories from the build environment -if (exists $ENV{"AUTOMAKE_UNINSTALLED"}) - { - @automake_includes = (); - @system_includes = (); - } - -@automake_includes = ($ENV{"ACLOCAL_AUTOMAKE_DIR"}) - if (exists $ENV{"ACLOCAL_AUTOMAKE_DIR"}); - -parse_WARNINGS; # Parse the WARNINGS environment variable. -parse_arguments; -parse_ACLOCAL_PATH; - -fatal "$configure_ac is required" unless -f $configure_ac; - -# We may have to rerun aclocal if some file have been installed, but -# it should not happen more than once. The reason we must run again -# is that once the file has been moved from /usr/share/aclocal/ to the -# local m4/ directory it appears at a new place in the search path, -# hence it should be output at a different position in aclocal.m4. If -# we did not rerun aclocal, the next run of aclocal would produce a -# different aclocal.m4. -my $loop = 0; -my $rerun_due_to_macrodir = 0; -while (1) - { - ++$loop; - prog_error "too many loops" if $loop > 2 + $rerun_due_to_macrodir; - - reset_maps; - scan_m4_files; - scan_configure; - last if $exit_code; - my %macro_traced = trace_used_macros; - - if (!$rerun_due_to_macrodir && @ac_config_macro_dirs) - { - # The directory specified in calls to the AC_CONFIG_MACRO_DIRS - # m4 macro (if any) must go after the user includes specified - # explicitly with the '-I' option. - push @user_includes, @ac_config_macro_dirs; - # We might have to scan some new directory of .m4 files. - $rerun_due_to_macrodir++; - next; - } - - if ($install && !@user_includes) - { - fatal "installation of third-party macros impossible without " . - "-I options nor AC_CONFIG_MACRO_DIR{,S} m4 macro(s)"; - } - - last if write_aclocal ($output_file, keys %macro_traced); - last if $dry_run; - } -check_acinclude; - -exit $exit_code; - -### Setup "GNU" style for perl-mode and cperl-mode. -## Local Variables: -## perl-indent-level: 2 -## perl-continued-statement-offset: 2 -## perl-continued-brace-offset: 0 -## perl-brace-offset: 0 -## perl-brace-imaginary-offset: 0 -## perl-label-offset: -2 -## cperl-indent-level: 2 -## cperl-brace-offset: 0 -## cperl-continued-brace-offset: 0 -## cperl-label-offset: -2 -## cperl-extra-newline-before-brace: t -## cperl-merge-trailing-else: nil -## cperl-continued-statement-offset: 2 -## End: diff --git a/bin/automake.in b/bin/automake.in deleted file mode 100644 index 6621302d8..000000000 --- a/bin/automake.in +++ /dev/null @@ -1,8213 +0,0 @@ -#!@PERL@ -w -# -*- perl -*- -# @configure_input@ - -eval 'case $# in 0) exec @PERL@ -S "$0";; *) exec @PERL@ -S "$0" "$@";; esac' - if 0; - -# automake - create Makefile.in from Makefile.am -# Copyright (C) 1994-2017 Free Software Foundation, Inc. - -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -# Originally written by David Mackenzie . -# Perl reimplementation by Tom Tromey , and -# Alexandre Duret-Lutz . - -package Automake; - -use strict; - -BEGIN -{ - unshift (@INC, '@datadir@/@PACKAGE@-@APIVERSION@') - unless $ENV{AUTOMAKE_UNINSTALLED}; -} - -use Automake::Config; -BEGIN -{ - if ($perl_threads) - { - require threads; - import threads; - require Thread::Queue; - import Thread::Queue; - } -} -use Automake::General; -use Automake::XFile; -use Automake::Channels; -use Automake::ChannelDefs; -use Automake::FileUtils; -use Automake::Location; -use Automake::Condition qw/TRUE FALSE/; -use Automake::DisjConditions; -use Automake::Options; -use Automake::Variable; -use Automake::VarDef; -use Automake::Rule; -use Automake::RuleDef; -use Automake::Wrap 'makefile_wrap'; -use Automake::Language; -use File::Basename; -use File::Spec; -use List::Util 'none'; -use Carp; - -## ----------------------- ## -## Subroutine prototypes. ## -## ----------------------- ## - -sub append_exeext (&$); -sub check_gnits_standards (); -sub check_gnu_standards (); -sub check_trailing_slash ($\$); -sub check_typos (); -sub define_files_variable ($\@$$); -sub define_standard_variables (); -sub define_verbose_libtool (); -sub define_verbose_texinfo (); -sub do_check_merge_target (); -sub get_number_of_threads (); -sub handle_compile (); -sub handle_data (); -sub handle_dist (); -sub handle_emacs_lisp (); -sub handle_factored_dependencies (); -sub handle_footer (); -sub handle_gettext (); -sub handle_headers (); -sub handle_install (); -sub handle_java (); -sub handle_languages (); -sub handle_libraries (); -sub handle_libtool (); -sub handle_ltlibraries (); -sub handle_makefiles_serial (); -sub handle_man_pages (); -sub handle_minor_options (); -sub handle_options (); -sub handle_programs (); -sub handle_python (); -sub handle_scripts (); -sub handle_silent (); -sub handle_subdirs (); -sub handle_tags (); -sub handle_targets (); -sub handle_tests (); -sub handle_tests_dejagnu (); -sub handle_texinfo (); -sub handle_user_recursion (); -sub initialize_per_input (); -sub lang_lex_finish (); -sub lang_sub_obj (); -sub lang_vala_finish (); -sub lang_yacc_finish (); -sub locate_aux_dir (); -sub parse_arguments (); -sub scan_aclocal_m4 (); -sub scan_autoconf_files (); -sub silent_flag (); -sub transform ($\%); -sub transform_token ($\%$); -sub usage (); -sub version (); -sub yacc_lex_finish_helper (); - -## ----------- ## -## Constants. ## -## ----------- ## - -# Some regular expressions. One reason to put them here is that it -# makes indentation work better in Emacs. - -# Writing singled-quoted-$-terminated regexes is a pain because -# perl-mode thinks of $' as the ${'} variable (instead of a $ followed -# by a closing quote. Letting perl-mode think the quote is not closed -# leads to all sort of misindentations. On the other hand, defining -# regexes as double-quoted strings is far less readable. So usually -# we will write: -# -# $REGEX = '^regex_value' . "\$"; - -my $IGNORE_PATTERN = '^\s*##([^#\n].*)?\n'; -my $WHITE_PATTERN = '^\s*' . "\$"; -my $COMMENT_PATTERN = '^#'; -my $TARGET_PATTERN='[$a-zA-Z0-9_.@%][-.a-zA-Z0-9_(){}/$+@%]*'; -# A rule has three parts: a list of targets, a list of dependencies, -# and optionally actions. -my $RULE_PATTERN = - "^($TARGET_PATTERN(?:(?:\\\\\n|\\s)+$TARGET_PATTERN)*) *:([^=].*|)\$"; - -# Only recognize leading spaces, not leading tabs. If we recognize -# leading tabs here then we need to make the reader smarter, because -# otherwise it will think rules like 'foo=bar; \' are errors. -my $ASSIGNMENT_PATTERN = '^ *([^ \t=:+]*)\s*([:+]?)=\s*(.*)' . "\$"; -# This pattern recognizes a Gnits version id and sets $1 if the -# release is an alpha release. We also allow a suffix which can be -# used to extend the version number with a "fork" identifier. -my $GNITS_VERSION_PATTERN = '\d+\.\d+([a-z]|\.\d+)?(-[A-Za-z0-9]+)?'; - -my $IF_PATTERN = '^if\s+(!?)\s*([A-Za-z][A-Za-z0-9_]*)\s*(?:#.*)?' . "\$"; -my $ELSE_PATTERN = - '^else(?:\s+(!?)\s*([A-Za-z][A-Za-z0-9_]*))?\s*(?:#.*)?' . "\$"; -my $ENDIF_PATTERN = - '^endif(?:\s+(!?)\s*([A-Za-z][A-Za-z0-9_]*))?\s*(?:#.*)?' . "\$"; -my $PATH_PATTERN = '(\w|[+/.-])+'; -# This will pass through anything not of the prescribed form. -my $INCLUDE_PATTERN = ('^include\s+' - . '((\$\(top_srcdir\)/' . $PATH_PATTERN . ')' - . '|(\$\(srcdir\)/' . $PATH_PATTERN . ')' - . '|([^/\$]' . $PATH_PATTERN . '))\s*(#.*)?' . "\$"); - -# Directories installed during 'install-exec' phase. -my $EXEC_DIR_PATTERN = - '^(?:bin|sbin|libexec|sysconf|localstate|lib|pkglib|.*exec.*)' . "\$"; - -# Values for AC_CANONICAL_* -use constant AC_CANONICAL_BUILD => 1; -use constant AC_CANONICAL_HOST => 2; -use constant AC_CANONICAL_TARGET => 3; - -# Values indicating when something should be cleaned. -use constant MOSTLY_CLEAN => 0; -use constant CLEAN => 1; -use constant DIST_CLEAN => 2; -use constant MAINTAINER_CLEAN => 3; - -# Libtool files. -my @libtool_files = qw(ltmain.sh config.guess config.sub); -# ltconfig appears here for compatibility with old versions of libtool. -my @libtool_sometimes = qw(ltconfig ltcf-c.sh ltcf-cxx.sh ltcf-gcj.sh); - -# Commonly found files we look for and automatically include in -# DISTFILES. -my @common_files = - (qw(ABOUT-GNU ABOUT-NLS AUTHORS BACKLOG COPYING COPYING.DOC COPYING.LIB - COPYING.LESSER ChangeLog INSTALL NEWS README THANKS TODO - ar-lib compile config.guess config.rpath - config.sub depcomp install-sh libversion.in mdate-sh - missing mkinstalldirs py-compile texinfo.tex ylwrap), - @libtool_files, @libtool_sometimes); - -# Commonly used files we auto-include, but only sometimes. This list -# is used for the --help output only. -my @common_sometimes = - qw(aclocal.m4 acconfig.h config.h.top config.h.bot configure - configure.ac stamp-vti); - -# Standard directories from the GNU Coding Standards, and additional -# pkg* directories from Automake. Stored in a hash for fast member check. -my %standard_prefix = - map { $_ => 1 } (qw(bin data dataroot doc dvi exec html include info - lib libexec lisp locale localstate man man1 man2 - man3 man4 man5 man6 man7 man8 man9 oldinclude pdf - pkgdata pkginclude pkglib pkglibexec ps sbin - sharedstate sysconf)); - -# Copyright on generated Makefile.ins. -my $gen_copyright = "\ -# Copyright (C) 1994-$RELEASE_YEAR Free Software Foundation, Inc. - -# This Makefile.in is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY, to the extent permitted by law; without -# even the implied warranty of MERCHANTABILITY or FITNESS FOR A -# PARTICULAR PURPOSE. -"; - -# These are used when keeping track of whether an object can be built -# by two different paths. -use constant COMPILE_LIBTOOL => 1; -use constant COMPILE_ORDINARY => 2; - -# We can't always associate a location to a variable or a rule, -# when it's defined by Automake. We use INTERNAL in this case. -use constant INTERNAL => new Automake::Location; - -# Serialization keys for message queues. -use constant QUEUE_MESSAGE => "msg"; -use constant QUEUE_CONF_FILE => "conf file"; -use constant QUEUE_LOCATION => "location"; -use constant QUEUE_STRING => "string"; - -## ---------------------------------- ## -## Variables related to the options. ## -## ---------------------------------- ## - -# TRUE if we should always generate Makefile.in. -my $force_generation = 1; - -# From the Perl manual. -my $symlink_exists = (eval 'symlink ("", "");', $@ eq ''); - -# TRUE if missing standard files should be installed. -my $add_missing = 0; - -# TRUE if we should copy missing files; otherwise symlink if possible. -my $copy_missing = 0; - -# TRUE if we should always update files that we know about. -my $force_missing = 0; - - -## ---------------------------------------- ## -## Variables filled during files scanning. ## -## ---------------------------------------- ## - -# Name of the Autoconf input file. We used to support 'configure.in' -# as well once, that that is long obsolete now. -my $configure_ac = 'configure.ac'; - -# Files found by scanning configure.ac for LIBOBJS. -my %libsources = (); - -# Names used in AC_CONFIG_HEADERS call. -my @config_headers = (); - -# Names used in AC_CONFIG_LINKS call. -my @config_links = (); - -# List of Makefile.am's to process, and their corresponding outputs. -my @input_files = (); -my %output_files = (); - -# Complete list of Makefile.am's that exist. -my @configure_input_files = (); - -# List of files in AC_CONFIG_FILES/AC_OUTPUT without Makefile.am's, -# and their outputs. -my @other_input_files = (); -# Where each AC_CONFIG_FILES/AC_OUTPUT/AC_CONFIG_LINK/AC_CONFIG_HEADERS -# appears. The keys are the files created by these macros. -my %ac_config_files_location = (); -# The condition under which AC_CONFIG_FOOS appears. -my %ac_config_files_condition = (); - -# Directory to search for configure-required files. This -# will be computed by locate_aux_dir() and can be set using -# AC_CONFIG_AUX_DIR in configure.ac. -# $CONFIG_AUX_DIR is the 'raw' directory, valid only in the source-tree. -my $config_aux_dir = ''; -my $config_aux_dir_set_in_configure_ac = 0; -# $AM_CONFIG_AUX_DIR is prefixed with $(top_srcdir), so it can be used -# in Makefiles. -my $am_config_aux_dir = ''; - -# Directory to search for AC_LIBSOURCE files, as set by AC_CONFIG_LIBOBJ_DIR -# in configure.ac. -my $config_libobj_dir = ''; - -# Whether AM_GNU_GETTEXT has been seen in configure.ac. -my $seen_gettext = 0; -# Whether AM_GNU_GETTEXT([external]) is used. -my $seen_gettext_external = 0; -# Where AM_GNU_GETTEXT appears. -my $ac_gettext_location; -# Whether AM_GNU_GETTEXT_INTL_SUBDIR has been seen. -my $seen_gettext_intl = 0; - -# The arguments of the AM_EXTRA_RECURSIVE_TARGETS call (if any). -my @extra_recursive_targets = (); - -# Lists of tags supported by Libtool. -my %libtool_tags = (); -# 1 if Libtool uses LT_SUPPORTED_TAG. If it does, then it also -# uses AC_REQUIRE_AUX_FILE. -my $libtool_new_api = 0; - -# Most important AC_CANONICAL_* macro seen so far. -my $seen_canonical = 0; - -# Where AM_MAINTAINER_MODE appears. -my $seen_maint_mode; - -# Actual version we've seen. -my $package_version = ''; - -# Where version is defined. -my $package_version_location; - -# TRUE if we've seen AM_PROG_AR -my $seen_ar = 0; - -# Location of AC_REQUIRE_AUX_FILE calls, indexed by their argument. -my %required_aux_file = (); - -# Where AM_INIT_AUTOMAKE is called. -my $seen_init_automake = 0; - -# TRUE if we've seen AM_AUTOMAKE_VERSION. -my $seen_automake_version = 0; - -# Hash table of discovered configure substitutions. Keys are names, -# values are 'FILE:LINE' strings which are used by error message -# generation. -my %configure_vars = (); - -# Ignored configure substitutions (i.e., variables not to be output in -# Makefile.in) -my %ignored_configure_vars = (); - -# Files included by $configure_ac. -my @configure_deps = (); - -# Greatest timestamp of configure's dependencies. -my $configure_deps_greatest_timestamp = 0; - -# Hash table of AM_CONDITIONAL variables seen in configure. -my %configure_cond = (); - -# This maps extensions onto language names. -my %extension_map = (); - -# List of the DIST_COMMON files we discovered while reading -# configure.ac. -my @configure_dist_common = (); - -# This maps languages names onto objects. -my %languages = (); -# Maps each linker variable onto a language object. -my %link_languages = (); - -# maps extensions to needed source flags. -my %sourceflags = (); - -# List of targets we must always output. -# FIXME: Complete, and remove falsely required targets. -my %required_targets = - ( - 'all' => 1, - 'dvi' => 1, - 'pdf' => 1, - 'ps' => 1, - 'info' => 1, - 'install-info' => 1, - 'install' => 1, - 'install-data' => 1, - 'install-exec' => 1, - 'uninstall' => 1, - - # FIXME: Not required, temporary hacks. - # Well, actually they are sort of required: the -recursive - # targets will run them anyway... - 'html-am' => 1, - 'dvi-am' => 1, - 'pdf-am' => 1, - 'ps-am' => 1, - 'info-am' => 1, - 'install-data-am' => 1, - 'install-exec-am' => 1, - 'install-html-am' => 1, - 'install-dvi-am' => 1, - 'install-pdf-am' => 1, - 'install-ps-am' => 1, - 'install-info-am' => 1, - 'installcheck-am' => 1, - 'uninstall-am' => 1, - 'tags-am' => 1, - 'ctags-am' => 1, - 'cscopelist-am' => 1, - 'install-man' => 1, - ); - -# Queue to push require_conf_file requirements to. -my $required_conf_file_queue; - -# The name of the Makefile currently being processed. -my $am_file = 'BUG'; - -################################################################ - -## ------------------------------------------ ## -## Variables reset by &initialize_per_input. ## -## ------------------------------------------ ## - -# Relative dir of the output makefile. -my $relative_dir; - -# Greatest timestamp of the output's dependencies (excluding -# configure's dependencies). -my $output_deps_greatest_timestamp; - -# These variables are used when generating each Makefile.in. -# They hold the Makefile.in until it is ready to be printed. -my $output_vars; -my $output_all; -my $output_header; -my $output_rules; -my $output_trailer; - -# This is the conditional stack, updated on if/else/endif, and -# used to build Condition objects. -my @cond_stack; - -# This holds the set of included files. -my @include_stack; - -# List of dependencies for the obvious targets. -my @all; -my @check; -my @check_tests; - -# Keys in this hash table are files to delete. The associated -# value tells when this should happen (MOSTLY_CLEAN, DIST_CLEAN, etc.) -my %clean_files; - -# Keys in this hash table are object files or other files in -# subdirectories which need to be removed. This only holds files -# which are created by compilations. The value in the hash indicates -# when the file should be removed. -my %compile_clean_files; - -# Keys in this hash table are directories where we expect to build a -# libtool object. We use this information to decide what directories -# to delete. -my %libtool_clean_directories; - -# Value of $(SOURCES), used by tags.am. -my @sources; -# Sources which go in the distribution. -my @dist_sources; - -# This hash maps object file names onto their corresponding source -# file names. This is used to ensure that each object is created -# by a single source file. -my %object_map; - -# This hash maps object file names onto an integer value representing -# whether this object has been built via ordinary compilation or -# libtool compilation (the COMPILE_* constants). -my %object_compilation_map; - - -# This keeps track of the directories for which we've already -# created dirstamp code. Keys are directories, values are stamp files. -# Several keys can share the same stamp files if they are equivalent -# (as are './/foo' and 'foo'). -my %directory_map; - -# All .P files. -my %dep_files; - -# This is a list of all targets to run during "make dist". -my @dist_targets; - -# List of all programs, libraries and ltlibraries as returned -# by am_install_var -my @proglist; -my @liblist; -my @ltliblist; -# Blacklist of targets (as canonical base name) for which object file names -# may not be automatically shortened -my @dup_shortnames; - -# Keep track of all programs declared in this Makefile, without -# $(EXEEXT). @substitutions@ are not listed. -my %known_programs; -my %known_libraries; - -# This keeps track of which extensions we've seen (that we care -# about). -my %extension_seen; - -# This is random scratch space for the language finish functions. -# Don't randomly overwrite it; examine other uses of keys first. -my %language_scratch; - -# We keep track of which objects need special (per-executable) -# handling on a per-language basis. -my %lang_specific_files; - -# List of distributed files to be put in DIST_COMMON. -my @dist_common; - -# This is set when 'handle_dist' has finished. Once this happens, -# we should no longer push on dist_common. -my $handle_dist_run; - -# Used to store a set of linkers needed to generate the sources currently -# under consideration. -my %linkers_used; - -# True if we need 'LINK' defined. This is a hack. -my $need_link; - -# Does the generated Makefile have to build some compiled object -# (for binary programs, or plain or libtool libraries)? -my $must_handle_compiled_objects; - -# Record each file processed by make_paragraphs. -my %transformed_files; - -################################################################ - -## ---------------------------------------------- ## -## Variables not reset by &initialize_per_input. ## -## ---------------------------------------------- ## - -# Cache each file processed by make_paragraphs. -# (This is different from %transformed_files because -# %transformed_files is reset for each file while %am_file_cache -# it global to the run.) -my %am_file_cache; - -################################################################ - -# var_SUFFIXES_trigger ($TYPE, $VALUE) -# ------------------------------------ -# This is called by Automake::Variable::define() when SUFFIXES -# is defined ($TYPE eq '') or appended ($TYPE eq '+'). -# The work here needs to be performed as a side-effect of the -# macro_define() call because SUFFIXES definitions impact -# on $KNOWN_EXTENSIONS_PATTERN which is used used when parsing -# the input am file. -sub var_SUFFIXES_trigger -{ - my ($type, $value) = @_; - accept_extensions (split (' ', $value)); -} -Automake::Variable::hook ('SUFFIXES', \&var_SUFFIXES_trigger); - -################################################################ - - -# initialize_per_input () -# ----------------------- -# (Re)-Initialize per-Makefile.am variables. -sub initialize_per_input () -{ - reset_local_duplicates (); - - $relative_dir = undef; - - $output_deps_greatest_timestamp = 0; - - $output_vars = ''; - $output_all = ''; - $output_header = ''; - $output_rules = ''; - $output_trailer = ''; - - Automake::Options::reset; - Automake::Variable::reset; - Automake::Rule::reset; - - @cond_stack = (); - - @include_stack = (); - - @all = (); - @check = (); - @check_tests = (); - - %clean_files = (); - %compile_clean_files = (); - - # We always include '.'. This isn't strictly correct. - %libtool_clean_directories = ('.' => 1); - - @sources = (); - @dist_sources = (); - - %object_map = (); - %object_compilation_map = (); - - %directory_map = (); - - %dep_files = (); - - @dist_targets = (); - - @dist_common = (); - $handle_dist_run = 0; - - @proglist = (); - @liblist = (); - @ltliblist = (); - @dup_shortnames = (); - - %known_programs = (); - %known_libraries = (); - - %extension_seen = (); - - %language_scratch = (); - - %lang_specific_files = (); - - $need_link = 0; - - $must_handle_compiled_objects = 0; - - %transformed_files = (); -} - - -################################################################ - -# Initialize our list of languages that are internally supported. - -my @cpplike_flags = - qw{ - $(DEFS) - $(DEFAULT_INCLUDES) - $(INCLUDES) - $(AM_CPPFLAGS) - $(CPPFLAGS) - }; - -# C. -register_language ('name' => 'c', - 'Name' => 'C', - 'config_vars' => ['CC'], - 'autodep' => '', - 'flags' => ['CFLAGS', 'CPPFLAGS'], - 'ccer' => 'CC', - 'compiler' => 'COMPILE', - 'compile' => "\$(CC) @cpplike_flags \$(AM_CFLAGS) \$(CFLAGS)", - 'lder' => 'CCLD', - 'ld' => '$(CC)', - 'linker' => 'LINK', - 'link' => '$(CCLD) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'libtool_tag' => 'CC', - 'extensions' => ['.c']); - -# C++. -register_language ('name' => 'cxx', - 'Name' => 'C++', - 'config_vars' => ['CXX'], - 'linker' => 'CXXLINK', - 'link' => '$(CXXLD) $(AM_CXXFLAGS) $(CXXFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'autodep' => 'CXX', - 'flags' => ['CXXFLAGS', 'CPPFLAGS'], - 'compile' => "\$(CXX) @cpplike_flags \$(AM_CXXFLAGS) \$(CXXFLAGS)", - 'ccer' => 'CXX', - 'compiler' => 'CXXCOMPILE', - 'libtool_tag' => 'CXX', - 'lder' => 'CXXLD', - 'ld' => '$(CXX)', - 'pure' => 1, - 'extensions' => ['.c++', '.cc', '.cpp', '.cxx', '.C']); - -# Objective C. -register_language ('name' => 'objc', - 'Name' => 'Objective C', - 'config_vars' => ['OBJC'], - 'linker' => 'OBJCLINK', - 'link' => '$(OBJCLD) $(AM_OBJCFLAGS) $(OBJCFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'autodep' => 'OBJC', - 'flags' => ['OBJCFLAGS', 'CPPFLAGS'], - 'compile' => "\$(OBJC) @cpplike_flags \$(AM_OBJCFLAGS) \$(OBJCFLAGS)", - 'ccer' => 'OBJC', - 'compiler' => 'OBJCCOMPILE', - 'lder' => 'OBJCLD', - 'ld' => '$(OBJC)', - 'pure' => 1, - 'extensions' => ['.m']); - -# Objective C++. -register_language ('name' => 'objcxx', - 'Name' => 'Objective C++', - 'config_vars' => ['OBJCXX'], - 'linker' => 'OBJCXXLINK', - 'link' => '$(OBJCXXLD) $(AM_OBJCXXFLAGS) $(OBJCXXFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'autodep' => 'OBJCXX', - 'flags' => ['OBJCXXFLAGS', 'CPPFLAGS'], - 'compile' => "\$(OBJCXX) @cpplike_flags \$(AM_OBJCXXFLAGS) \$(OBJCXXFLAGS)", - 'ccer' => 'OBJCXX', - 'compiler' => 'OBJCXXCOMPILE', - 'lder' => 'OBJCXXLD', - 'ld' => '$(OBJCXX)', - 'pure' => 1, - 'extensions' => ['.mm']); - -# Unified Parallel C. -register_language ('name' => 'upc', - 'Name' => 'Unified Parallel C', - 'config_vars' => ['UPC'], - 'linker' => 'UPCLINK', - 'link' => '$(UPCLD) $(AM_UPCFLAGS) $(UPCFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'autodep' => 'UPC', - 'flags' => ['UPCFLAGS', 'CPPFLAGS'], - 'compile' => "\$(UPC) @cpplike_flags \$(AM_UPCFLAGS) \$(UPCFLAGS)", - 'ccer' => 'UPC', - 'compiler' => 'UPCCOMPILE', - 'lder' => 'UPCLD', - 'ld' => '$(UPC)', - 'pure' => 1, - 'extensions' => ['.upc']); - -# Headers. -register_language ('name' => 'header', - 'Name' => 'Header', - 'extensions' => ['.h', '.H', '.hxx', '.h++', '.hh', - '.hpp', '.inc'], - # No output. - 'output_extensions' => sub { return () }, - # Nothing to do. - '_finish' => sub { }); - -# Vala. -register_language ('name' => 'vala', - 'Name' => 'Vala', - 'config_vars' => ['VALAC'], - 'flags' => [], - 'compile' => '$(VALAC) $(AM_VALAFLAGS) $(VALAFLAGS)', - 'ccer' => 'VALAC', - 'compiler' => 'VALACOMPILE', - 'extensions' => ['.vala', '.vapi'], - # Vala compilation must be handled in a special way, so - # nothing to do or return here. - 'output_extensions' => sub { }, - 'rule_file' => 'vala', - '_finish' => \&lang_vala_finish, - '_target_hook' => \&lang_vala_target_hook, - 'nodist_specific' => 1); - -# Yacc (C & C++). -register_language ('name' => 'yacc', - 'Name' => 'Yacc', - 'config_vars' => ['YACC'], - 'flags' => ['YFLAGS'], - 'compile' => '$(YACC) $(AM_YFLAGS) $(YFLAGS)', - 'ccer' => 'YACC', - 'compiler' => 'YACCCOMPILE', - 'extensions' => ['.y'], - 'output_extensions' => sub { (my $ext = $_[0]) =~ tr/y/c/; - return ($ext,) }, - 'rule_file' => 'yacc', - '_finish' => \&lang_yacc_finish, - '_target_hook' => \&lang_yacc_target_hook, - 'nodist_specific' => 1); -register_language ('name' => 'yaccxx', - 'Name' => 'Yacc (C++)', - 'config_vars' => ['YACC'], - 'rule_file' => 'yacc', - 'flags' => ['YFLAGS'], - 'ccer' => 'YACC', - 'compiler' => 'YACCCOMPILE', - 'compile' => '$(YACC) $(AM_YFLAGS) $(YFLAGS)', - 'extensions' => ['.y++', '.yy', '.yxx', '.ypp'], - 'output_extensions' => sub { (my $ext = $_[0]) =~ tr/y/c/; - return ($ext,) }, - '_finish' => \&lang_yacc_finish, - '_target_hook' => \&lang_yacc_target_hook, - 'nodist_specific' => 1); - -# Lex (C & C++). -register_language ('name' => 'lex', - 'Name' => 'Lex', - 'config_vars' => ['LEX'], - 'rule_file' => 'lex', - 'flags' => ['LFLAGS'], - 'compile' => '$(LEX) $(AM_LFLAGS) $(LFLAGS)', - 'ccer' => 'LEX', - 'compiler' => 'LEXCOMPILE', - 'extensions' => ['.l'], - 'output_extensions' => sub { (my $ext = $_[0]) =~ tr/l/c/; - return ($ext,) }, - '_finish' => \&lang_lex_finish, - '_target_hook' => \&lang_lex_target_hook, - 'nodist_specific' => 1); -register_language ('name' => 'lexxx', - 'Name' => 'Lex (C++)', - 'config_vars' => ['LEX'], - 'rule_file' => 'lex', - 'flags' => ['LFLAGS'], - 'compile' => '$(LEX) $(AM_LFLAGS) $(LFLAGS)', - 'ccer' => 'LEX', - 'compiler' => 'LEXCOMPILE', - 'extensions' => ['.l++', '.ll', '.lxx', '.lpp'], - 'output_extensions' => sub { (my $ext = $_[0]) =~ tr/l/c/; - return ($ext,) }, - '_finish' => \&lang_lex_finish, - '_target_hook' => \&lang_lex_target_hook, - 'nodist_specific' => 1); - -# Assembler. -register_language ('name' => 'asm', - 'Name' => 'Assembler', - 'config_vars' => ['CCAS', 'CCASFLAGS'], - - 'flags' => ['CCASFLAGS'], - # Users can set AM_CCASFLAGS to include $(DEFS), - # $(INCLUDES), or anything else required. They can also - # set CCAS. Or simply use Preprocessed Assembler. - 'compile' => '$(CCAS) $(AM_CCASFLAGS) $(CCASFLAGS)', - 'ccer' => 'CCAS', - 'compiler' => 'CCASCOMPILE', - 'extensions' => ['.s']); - -# Preprocessed Assembler. -register_language ('name' => 'cppasm', - 'Name' => 'Preprocessed Assembler', - 'config_vars' => ['CCAS', 'CCASFLAGS'], - - 'autodep' => 'CCAS', - 'flags' => ['CCASFLAGS', 'CPPFLAGS'], - 'compile' => "\$(CCAS) @cpplike_flags \$(AM_CCASFLAGS) \$(CCASFLAGS)", - 'ccer' => 'CPPAS', - 'compiler' => 'CPPASCOMPILE', - 'extensions' => ['.S', '.sx']); - -# Fortran 77 -register_language ('name' => 'f77', - 'Name' => 'Fortran 77', - 'config_vars' => ['F77'], - 'linker' => 'F77LINK', - 'link' => '$(F77LD) $(AM_FFLAGS) $(FFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'flags' => ['FFLAGS'], - 'compile' => '$(F77) $(AM_FFLAGS) $(FFLAGS)', - 'ccer' => 'F77', - 'compiler' => 'F77COMPILE', - 'libtool_tag' => 'F77', - 'lder' => 'F77LD', - 'ld' => '$(F77)', - 'pure' => 1, - 'extensions' => ['.f', '.for']); - -# Fortran -register_language ('name' => 'fc', - 'Name' => 'Fortran', - 'config_vars' => ['FC'], - 'linker' => 'FCLINK', - 'link' => '$(FCLD) $(AM_FCFLAGS) $(FCFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'flags' => ['FCFLAGS'], - 'compile' => '$(FC) $(AM_FCFLAGS) $(FCFLAGS)', - 'ccer' => 'FC', - 'compiler' => 'FCCOMPILE', - 'libtool_tag' => 'FC', - 'lder' => 'FCLD', - 'ld' => '$(FC)', - 'pure' => 1, - 'extensions' => ['.f90', '.f95', '.f03', '.f08']); - -# Preprocessed Fortran -register_language ('name' => 'ppfc', - 'Name' => 'Preprocessed Fortran', - 'config_vars' => ['FC'], - 'linker' => 'FCLINK', - 'link' => '$(FCLD) $(AM_FCFLAGS) $(FCFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'lder' => 'FCLD', - 'ld' => '$(FC)', - 'flags' => ['FCFLAGS', 'CPPFLAGS'], - 'ccer' => 'PPFC', - 'compiler' => 'PPFCCOMPILE', - 'compile' => "\$(FC) @cpplike_flags \$(AM_FCFLAGS) \$(FCFLAGS)", - 'libtool_tag' => 'FC', - 'pure' => 1, - 'extensions' => ['.F90','.F95', '.F03', '.F08']); - -# Preprocessed Fortran 77 -# -# The current support for preprocessing Fortran 77 just involves -# passing "$(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) -# $(CPPFLAGS)" as additional flags to the Fortran 77 compiler, since -# this is how GNU Make does it; see the "GNU Make Manual, Edition 0.51 -# for 'make' Version 3.76 Beta" (specifically, from info file -# '(make)Catalogue of Rules'). -# -# A better approach would be to write an Autoconf test -# (i.e. AC_PROG_FPP) for a Fortran 77 preprocessor, because not all -# Fortran 77 compilers know how to do preprocessing. The Autoconf -# macro AC_PROG_FPP should test the Fortran 77 compiler first for -# preprocessing capabilities, and then fall back on cpp (if cpp were -# available). -register_language ('name' => 'ppf77', - 'Name' => 'Preprocessed Fortran 77', - 'config_vars' => ['F77'], - 'linker' => 'F77LINK', - 'link' => '$(F77LD) $(AM_FFLAGS) $(FFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'lder' => 'F77LD', - 'ld' => '$(F77)', - 'flags' => ['FFLAGS', 'CPPFLAGS'], - 'ccer' => 'PPF77', - 'compiler' => 'PPF77COMPILE', - 'compile' => "\$(F77) @cpplike_flags \$(AM_FFLAGS) \$(FFLAGS)", - 'libtool_tag' => 'F77', - 'pure' => 1, - 'extensions' => ['.F']); - -# Ratfor. -register_language ('name' => 'ratfor', - 'Name' => 'Ratfor', - 'config_vars' => ['F77'], - 'linker' => 'F77LINK', - 'link' => '$(F77LD) $(AM_FFLAGS) $(FFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'lder' => 'F77LD', - 'ld' => '$(F77)', - 'flags' => ['RFLAGS', 'FFLAGS'], - # FIXME also FFLAGS. - 'compile' => '$(F77) $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)', - 'ccer' => 'F77', - 'compiler' => 'RCOMPILE', - 'libtool_tag' => 'F77', - 'pure' => 1, - 'extensions' => ['.r']); - -# Java via gcj. -register_language ('name' => 'java', - 'Name' => 'Java', - 'config_vars' => ['GCJ'], - 'linker' => 'GCJLINK', - 'link' => '$(GCJLD) $(AM_GCJFLAGS) $(GCJFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@', - 'autodep' => 'GCJ', - 'flags' => ['GCJFLAGS'], - 'compile' => '$(GCJ) $(AM_GCJFLAGS) $(GCJFLAGS)', - 'ccer' => 'GCJ', - 'compiler' => 'GCJCOMPILE', - 'libtool_tag' => 'GCJ', - 'lder' => 'GCJLD', - 'ld' => '$(GCJ)', - 'pure' => 1, - 'extensions' => ['.java', '.class', '.zip', '.jar']); - -################################################################ - -# Error reporting functions. - -# err_am ($MESSAGE, [%OPTIONS]) -# ----------------------------- -# Uncategorized errors about the current Makefile.am. -sub err_am -{ - msg_am ('error', @_); -} - -# err_ac ($MESSAGE, [%OPTIONS]) -# ----------------------------- -# Uncategorized errors about configure.ac. -sub err_ac -{ - msg_ac ('error', @_); -} - -# msg_am ($CHANNEL, $MESSAGE, [%OPTIONS]) -# --------------------------------------- -# Messages about about the current Makefile.am. -sub msg_am -{ - my ($channel, $msg, %opts) = @_; - msg $channel, "${am_file}.am", $msg, %opts; -} - -# msg_ac ($CHANNEL, $MESSAGE, [%OPTIONS]) -# --------------------------------------- -# Messages about about configure.ac. -sub msg_ac -{ - my ($channel, $msg, %opts) = @_; - msg $channel, $configure_ac, $msg, %opts; -} - -################################################################ - -# subst ($TEXT) -# ------------- -# Return a configure-style substitution using the indicated text. -# We do this to avoid having the substitutions directly in automake.in; -# when we do that they are sometimes removed and this causes confusion -# and bugs. -sub subst -{ - my ($text) = @_; - return '@' . $text . '@'; -} - -################################################################ - - -# $BACKPATH -# backname ($RELDIR) -# ------------------- -# If I "cd $RELDIR", then to come back, I should "cd $BACKPATH". -# For instance 'src/foo' => '../..'. -# Works with non strictly increasing paths, i.e., 'src/../lib' => '..'. -sub backname -{ - my ($file) = @_; - my @res; - foreach (split (/\//, $file)) - { - next if $_ eq '.' || $_ eq ''; - if ($_ eq '..') - { - pop @res - or prog_error ("trying to reverse path '$file' pointing outside tree"); - } - else - { - push (@res, '..'); - } - } - return join ('/', @res) || '.'; -} - -################################################################ - -# Silent rules handling functions. - -# verbose_var (NAME) -# ------------------ -# The public variable stem used to implement silent rules. -sub verbose_var -{ - my ($name) = @_; - return 'AM_V_' . $name; -} - -# verbose_private_var (NAME) -# -------------------------- -# The naming policy for the private variables for silent rules. -sub verbose_private_var -{ - my ($name) = @_; - return 'am__v_' . $name; -} - -# define_verbose_var (NAME, VAL-IF-SILENT, [VAL-IF-VERBOSE]) -# ---------------------------------------------------------- -# For silent rules, setup VAR and dispatcher, to expand to -# VAL-IF-SILENT if silent, to VAL-IF-VERBOSE (defaulting to -# empty) if not. -sub define_verbose_var -{ - my ($name, $silent_val, $verbose_val) = @_; - $verbose_val = '' unless defined $verbose_val; - my $var = verbose_var ($name); - my $pvar = verbose_private_var ($name); - my $silent_var = $pvar . '_0'; - my $verbose_var = $pvar . '_1'; - # For typical 'make's, 'configure' replaces AM_V (inside @@) with $(V) - # and AM_DEFAULT_V (inside @@) with $(AM_DEFAULT_VERBOSITY). - # For strict POSIX 2008 'make's, it replaces them with 0 or 1 instead. - # See AM_SILENT_RULES in m4/silent.m4. - define_variable ($var, '$(' . $pvar . '_@'.'AM_V'.'@)', INTERNAL); - define_variable ($pvar . '_', '$(' . $pvar . '_@'.'AM_DEFAULT_V'.'@)', - INTERNAL); - Automake::Variable::define ($silent_var, VAR_AUTOMAKE, '', TRUE, - $silent_val, '', INTERNAL, VAR_ASIS) - if (! vardef ($silent_var, TRUE)); - Automake::Variable::define ($verbose_var, VAR_AUTOMAKE, '', TRUE, - $verbose_val, '', INTERNAL, VAR_ASIS) - if (! vardef ($verbose_var, TRUE)); -} - -# verbose_flag (NAME) -# ------------------- -# Contents of '%VERBOSE%' variable to expand before rule command. -sub verbose_flag -{ - my ($name) = @_; - return '$(' . verbose_var ($name) . ')'; -} - -sub verbose_nodep_flag -{ - my ($name) = @_; - return '$(' . verbose_var ($name) . subst ('am__nodep') . ')'; -} - -# silent_flag -# ----------- -# Contents of %SILENT%: variable to expand to '@' when silent. -sub silent_flag () -{ - return verbose_flag ('at'); -} - -# define_verbose_tagvar (NAME) -# ---------------------------- -# Engage the needed silent rules machinery for tag NAME. -sub define_verbose_tagvar -{ - my ($name) = @_; - define_verbose_var ($name, '@echo " '. $name . ' ' x (8 - length ($name)) . '" $@;'); -} - -# Engage the needed silent rules machinery for assorted texinfo commands. -sub define_verbose_texinfo () -{ - my @tagvars = ('DVIPS', 'MAKEINFO', 'INFOHTML', 'TEXI2DVI', 'TEXI2PDF'); - foreach my $tag (@tagvars) - { - define_verbose_tagvar($tag); - } - define_verbose_var('texinfo', '-q'); - define_verbose_var('texidevnull', '> /dev/null'); -} - -# Engage the needed silent rules machinery for 'libtool --silent'. -sub define_verbose_libtool () -{ - define_verbose_var ('lt', '--silent'); - return verbose_flag ('lt'); -} - -sub handle_silent () -{ - # Define "$(AM_V_P)", expanding to a shell conditional that can be - # used in make recipes to determine whether we are being run in - # silent mode or not. The choice of the name derives from the LISP - # convention of appending the letter 'P' to denote a predicate (see - # also "the '-P' convention" in the Jargon File); we do so for lack - # of a better convention. - define_verbose_var ('P', 'false', ':'); - # *Always* provide the user with '$(AM_V_GEN)', unconditionally. - define_verbose_tagvar ('GEN'); - define_verbose_var ('at', '@'); -} - - -################################################################ - - -# Handle AUTOMAKE_OPTIONS variable. Return 0 on error, 1 otherwise. -sub handle_options () -{ - my $var = var ('AUTOMAKE_OPTIONS'); - if ($var) - { - if ($var->has_conditional_contents) - { - msg_var ('unsupported', $var, - "'AUTOMAKE_OPTIONS' cannot have conditional contents"); - } - my @options = map { { option => $_->[1], where => $_->[0] } } - $var->value_as_list_recursive (cond_filter => TRUE, - location => 1); - return 0 unless process_option_list (@options); - } - - if ($strictness == GNITS) - { - set_option ('readme-alpha', INTERNAL); - set_option ('std-options', INTERNAL); - set_option ('check-news', INTERNAL); - } - - return 1; -} - -# shadow_unconditionally ($varname, $where) -# ----------------------------------------- -# Return a $(variable) that contains all possible values -# $varname can take. -# If the VAR wasn't defined conditionally, return $(VAR). -# Otherwise we create an am__VAR_DIST variable which contains -# all possible values, and return $(am__VAR_DIST). -sub shadow_unconditionally -{ - my ($varname, $where) = @_; - my $var = var $varname; - if ($var->has_conditional_contents) - { - $varname = "am__${varname}_DIST"; - my @files = uniq ($var->value_as_list_recursive); - define_pretty_variable ($varname, TRUE, $where, @files); - } - return "\$($varname)" -} - -# check_user_variables (@LIST) -# ---------------------------- -# Make sure each variable VAR in @LIST does not exist, suggest using AM_VAR -# otherwise. -sub check_user_variables -{ - my @dont_override = @_; - foreach my $flag (@dont_override) - { - my $var = var $flag; - if ($var) - { - for my $cond ($var->conditions->conds) - { - if ($var->rdef ($cond)->owner == VAR_MAKEFILE) - { - msg_cond_var ('gnu', $cond, $flag, - "'$flag' is a user variable, " - . "you should not override it;\n" - . "use 'AM_$flag' instead"); - } - } - } - } -} - -# Call finish function for each language that was used. -sub handle_languages () -{ - if (! option 'no-dependencies') - { - # Include auto-dep code. Don't include it if DEP_FILES would - # be empty. - if (keys %extension_seen && keys %dep_files) - { - my @dep_files = sort keys %dep_files; - # Set location of depcomp. - define_variable ('depcomp', - "\$(SHELL) $am_config_aux_dir/depcomp", - INTERNAL); - define_variable ('am__maybe_remake_depfiles', 'depfiles', INTERNAL); - define_variable ('am__depfiles_remade', "@dep_files", INTERNAL); - $output_rules .= "\n"; - my @dist_rms; - foreach my $depfile (@dep_files) - { - push @dist_rms, "\t-rm -f $depfile"; - # Generate each 'include' directive individually. Several - # make implementations (IRIX 6, Solaris 10, FreeBSD 8) will - # fail to properly include several files resulting from a - # variable expansion. Just Generating many separate includes - # seems thus safest. - $output_rules .= subst ('AMDEP_TRUE') . - subst ('am__include') . - " " . - subst('am__quote') . - $depfile . - subst('am__quote') . - " " . - "# am--include-marker\n"; - } - - require_conf_file ("$am_file.am", FOREIGN, 'depcomp'); - - $output_rules .= file_contents ( - 'depend', new Automake::Location, - 'DISTRMS' => join ("\n", @dist_rms)); - } - } - else - { - define_variable ('depcomp', '', INTERNAL); - define_variable ('am__maybe_remake_depfiles', '', INTERNAL); - } - - my %done; - - # Is the C linker needed? - my $needs_c = 0; - foreach my $ext (sort keys %extension_seen) - { - next unless $extension_map{$ext}; - - my $lang = $languages{$extension_map{$ext}}; - - my $rule_file = $lang->rule_file || 'depend2'; - - # Get information on $LANG. - my $pfx = $lang->autodep; - my $fpfx = ($pfx eq '') ? 'CC' : $pfx; - - my ($AMDEP, $FASTDEP) = - (option 'no-dependencies' || $lang->autodep eq 'no') - ? ('FALSE', 'FALSE') : ('AMDEP', "am__fastdep$fpfx"); - - my $verbose = verbose_flag ($lang->ccer || 'GEN'); - my $verbose_nodep = ($AMDEP eq 'FALSE') - ? $verbose : verbose_nodep_flag ($lang->ccer || 'GEN'); - my $silent = silent_flag (); - - my %transform = ('EXT' => $ext, - 'PFX' => $pfx, - 'FPFX' => $fpfx, - 'AMDEP' => $AMDEP, - 'FASTDEP' => $FASTDEP, - # These are not used, but they need to be defined - # so transform() does not complain. - 'DERIVED-EXT' => 'BUG', - DIST_SOURCE => 1, - VERBOSE => $verbose, - 'VERBOSE-NODEP' => $verbose_nodep, - SILENT => $silent, - ); - - # Generate the appropriate rules for this extension. - if (((! option 'no-dependencies') && $lang->autodep ne 'no') - || defined $lang->compile) - { - # Compute a possible derived extension. - # This is not used by depend2.am. - my $der_ext = ($lang->output_extensions->($ext))[0]; - - # Even when subdir sources are present, an inference rule - # like '.c.o:' can be used to build corresponding objects - # in the sane subdirectory too. We should be careful to also - # place dependency files into the appropriate subdirectory, - # e.g., 'sub/$(DEPDIR)/'. The value of this directory needs - # to be computed on-the-fly (that is done by our makefile - # recipes in 'depend2.am'). - $output_rules .= - file_contents ($rule_file, - new Automake::Location, - %transform, - GENERIC => 1, - - 'DERIVED-EXT' => $der_ext, - - BASE => '$*', - SOURCE => '$<', - XSOURCE => '$<', - SOURCEFLAG => $sourceflags{$ext} || '', - OBJ => '$@', - OBJOBJ => '$@', - LTOBJ => '$@', - - COMPILE => '$(' . $lang->compiler . ')', - LTCOMPILE => '$(LT' . $lang->compiler . ')', - ); - } - - # Now include code for each specially handled object with this - # language. - my %seen_files = (); - foreach my $file (@{$lang_specific_files{$lang->name}}) - { - my ($derived, $source, $obj, $myext, $srcext, %file_transform) = @$file; - - # We might see a given object twice, for instance if it is - # used under different conditions. - next if defined $seen_files{$obj}; - $seen_files{$obj} = 1; - - prog_error ("found " . $lang->name . - " in handle_languages, but compiler not defined") - unless defined $lang->compile; - - my $obj_compile = $lang->compile; - - # Rewrite each occurrence of 'AM_$flag' in the compile - # rule into '${derived}_$flag' if it exists. - for my $flag (@{$lang->flags}) - { - my $val = "${derived}_$flag"; - $obj_compile =~ s/\(AM_$flag\)/\($val\)/ - if set_seen ($val); - } - - my $libtool_tag = ''; - if ($lang->libtool_tag && exists $libtool_tags{$lang->libtool_tag}) - { - $libtool_tag = '--tag=' . $lang->libtool_tag . ' ' - } - - my $ptltflags = "${derived}_LIBTOOLFLAGS"; - $ptltflags = 'AM_LIBTOOLFLAGS' unless set_seen $ptltflags; - - my $ltverbose = define_verbose_libtool (); - my $obj_ltcompile = - "\$(LIBTOOL) $ltverbose $libtool_tag\$($ptltflags) \$(LIBTOOLFLAGS) " - . "--mode=compile $obj_compile"; - - # For non-suffix rules, we must emulate a VPATH search. - my $xsource = "`test -f '$source' || echo '\$(srcdir)/'`$source"; - - $output_rules .= - file_contents ($rule_file, - new Automake::Location, - %transform, - GENERIC => 0, - - BASE => $obj, - SOURCE => $source, - XSOURCE => $xsource, - SOURCEFLAG => $sourceflags{$srcext} || '', - # Use $myext and not '.o' here, in case - # we are actually building a new source - # file -- e.g. via yacc. - OBJ => "$obj$myext", - OBJOBJ => "$obj.obj", - LTOBJ => "$obj.lo", - - VERBOSE => $verbose, - 'VERBOSE-NODEP' => $verbose_nodep, - SILENT => $silent, - COMPILE => $obj_compile, - LTCOMPILE => $obj_ltcompile, - %file_transform); - } - - # The rest of the loop is done once per language. - next if defined $done{$lang}; - $done{$lang} = 1; - - # Load the language dependent Makefile chunks. - my %lang = map { uc ($_) => 0 } keys %languages; - $lang{uc ($lang->name)} = 1; - $output_rules .= file_contents ('lang-compile', - new Automake::Location, - %transform, %lang); - - # If the source to a program consists entirely of code from a - # 'pure' language, for instance C++ or Fortran 77, then we - # don't need the C compiler code. However if we run into - # something unusual then we do generate the C code. There are - # probably corner cases here that do not work properly. - # People linking Java code to Fortran code deserve pain. - $needs_c ||= ! $lang->pure; - - define_compiler_variable ($lang) - if ($lang->compile); - - define_linker_variable ($lang) - if ($lang->link); - - require_variables ("$am_file.am", $lang->Name . " source seen", - TRUE, @{$lang->config_vars}); - - # Call the finisher. - $lang->finish; - - # Flags listed in '->flags' are user variables (per GNU Standards), - # they should not be overridden in the Makefile... - my @dont_override = @{$lang->flags}; - # ... and so is LDFLAGS. - push @dont_override, 'LDFLAGS' if $lang->link; - - check_user_variables @dont_override; - } - - # If the project is entirely C++ or entirely Fortran 77 (i.e., 1 - # suffix rule was learned), don't bother with the C stuff. But if - # anything else creeps in, then use it. - my @languages_seen = map { $languages{$extension_map{$_}}->name } - (keys %extension_seen); - @languages_seen = uniq (@languages_seen); - $needs_c = 1 if @languages_seen > 1; - if ($need_link || $needs_c) - { - define_compiler_variable ($languages{'c'}) - unless defined $done{$languages{'c'}}; - define_linker_variable ($languages{'c'}); - } -} - - -# append_exeext { PREDICATE } $MACRO -# ---------------------------------- -# Append $(EXEEXT) to each filename in $F appearing in the Makefile -# variable $MACRO if &PREDICATE($F) is true. @substitutions@ are -# ignored. -# -# This is typically used on all filenames of *_PROGRAMS, and filenames -# of TESTS that are programs. -sub append_exeext (&$) -{ - my ($pred, $macro) = @_; - - transform_variable_recursively - ($macro, $macro, 'am__EXEEXT', 0, INTERNAL, - sub { - my ($subvar, $val, $cond, $full_cond) = @_; - # Append $(EXEEXT) unless the user did it already, or it's a - # @substitution@. - $val .= '$(EXEEXT)' - if $val !~ /(?:\$\(EXEEXT\)$|^[@]\w+[@]$)/ && &$pred ($val); - return $val; - }); -} - - -# Check to make sure a source defined in LIBOBJS is not explicitly -# mentioned. This is a separate function (as opposed to being inlined -# in handle_source_transform) because it isn't always appropriate to -# do this check. -sub check_libobjs_sources -{ - my ($one_file, $unxformed) = @_; - - foreach my $prefix ('', 'EXTRA_', 'dist_', 'nodist_', - 'dist_EXTRA_', 'nodist_EXTRA_') - { - my @files; - my $varname = $prefix . $one_file . '_SOURCES'; - my $var = var ($varname); - if ($var) - { - @files = $var->value_as_list_recursive; - } - elsif ($prefix eq '') - { - @files = ($unxformed . '.c'); - } - else - { - next; - } - - foreach my $file (@files) - { - err_var ($prefix . $one_file . '_SOURCES', - "automatically discovered file '$file' should not" . - " be explicitly mentioned") - if defined $libsources{$file}; - } - } -} - - -# @OBJECTS -# handle_single_transform ($VAR, $TOPPARENT, $DERIVED, $OBJ, $FILE, %TRANSFORM) -# ----------------------------------------------------------------------------- -# Does much of the actual work for handle_source_transform. -# Arguments are: -# $VAR is the name of the variable that the source filenames come from -# $TOPPARENT is the name of the _SOURCES variable which is being processed -# $DERIVED is the name of resulting executable or library -# $OBJ is the object extension (e.g., '.lo') -# $FILE the source file to transform -# %TRANSFORM contains extras arguments to pass to file_contents -# when producing explicit rules -# Result is a list of the names of objects -# %linkers_used will be updated with any linkers needed -sub handle_single_transform -{ - my ($var, $topparent, $derived, $obj, $_file, %transform) = @_; - my @files = ($_file); - my @result = (); - - # Turn sources into objects. We use a while loop like this - # because we might add to @files in the loop. - while (scalar @files > 0) - { - $_ = shift @files; - - # Configure substitutions in _SOURCES variables are errors. - if (/^\@.*\@$/) - { - my $parent_msg = ''; - $parent_msg = "\nand is referred to from '$topparent'" - if $topparent ne $var->name; - err_var ($var, - "'" . $var->name . "' includes configure substitution '$_'" - . $parent_msg . ";\nconfigure " . - "substitutions are not allowed in _SOURCES variables"); - next; - } - - # Split file name into base and extension. - next if ! /^(?:(.*)\/)?([^\/]*)($KNOWN_EXTENSIONS_PATTERN)$/; - my $full = $_; - my $directory = $1 || ''; - my $base = $2; - my $extension = $3; - - # We must generate a rule for the object if it requires its own flags. - my $renamed = 0; - my ($linker, $object); - - # This records whether we've seen a derived source file (e.g., yacc - # or lex output). - my $derived_source; - - # This holds the 'aggregate context' of the file we are - # currently examining. If the file is compiled with - # per-object flags, then it will be the name of the object. - # Otherwise it will be 'AM'. This is used by the target hook - # language function. - my $aggregate = 'AM'; - - $extension = derive_suffix ($extension, $obj); - my $lang; - if ($extension_map{$extension} && - ($lang = $languages{$extension_map{$extension}})) - { - # Found the language, so see what it says. - saw_extension ($extension); - - # Do we have per-executable flags for this executable? - my $have_per_exec_flags = 0; - my @peflags = @{$lang->flags}; - push @peflags, 'LIBTOOLFLAGS' if $obj eq '.lo'; - foreach my $flag (@peflags) - { - if (set_seen ("${derived}_$flag")) - { - $have_per_exec_flags = 1; - last; - } - } - - # NOTE: computed subr calls here. - - # The language ignore function can ask not to preprocess - # a source file further. - my $subr_ignore = \&{'lang_' . $lang->name . '_ignore'}; - next if defined &$subr_ignore - and &$subr_ignore ($directory, $base, $extension); - # The language rewrite function can return a new source - # extension which should be applied. This means this - # particular language generates another source file which - # we must then process further. This happens, for example, - # with yacc and lex. - my $subr_rewrite = \&{'lang_' . $lang->name . '_rewrite'}; - $subr_rewrite = sub { } unless defined &$subr_rewrite; - my $source_extension = &$subr_rewrite ($directory, $base, - $extension, $obj, - $have_per_exec_flags, - $var); - - # Now extract linker and other info. - $linker = $lang->linker; - - my $this_obj_ext; - if (defined $source_extension) - { - $this_obj_ext = $source_extension; - $derived_source = 1; - } - else - { - $this_obj_ext = $obj; - $derived_source = 0; - # Don't ever place built object files in $(srcdir), - # even when sources are specified explicitly as (say) - # '$(srcdir)/foo.c' or '$(top_srcdir)/foo.c'. - # See automake bug#13928. - my @d = split '/', $directory; - if (@d > 0 && option 'subdir-objects') - { - my $d = $d[0]; - if ($d eq '$(srcdir)' or $d eq '${srcdir}') - { - shift @d; - } - elsif ($d eq '$(top_srcdir)' or $d eq '${top_srcdir}') - { - $d[0] = '$(top_builddir)'; - } - $directory = join '/', @d; - } - } - $object = $base . $this_obj_ext; - - if ($have_per_exec_flags) - { - # We have a per-executable flag in effect for this - # object. In this case we rewrite the object's - # name to ensure it is unique. - - # We choose the name 'DERIVED_OBJECT' to ensure (1) uniqueness, - # and (2) continuity between invocations. However, this will - # result in a name that is too long for losing systems, in some - # situations. So we attempt to shorten automatically, and - # provide _SHORTNAME to override as a last resort. If - # subdir-object is in effect, it's usually unnecessary to use - # the complete 'DERIVED_OBJECT' (that is often the result from - # %canon_reldir%/%C% usage) since objects are placed next to - # their source file. Generally, this means it is already - # unique within that directory (see below for an exception). - # Thus, we try to avoid unnecessarily long file names by - # stripping the directory components of 'DERIVED_OBJECT'. - # This allows avoiding explicit _SHORTNAME usage in many - # cases. EXCEPTION: If two (or more) targets in different - # directories but with the same base name (after - # canonicalization), using target-specific FLAGS, link the - # same object, then this logic clashes. Thus, we don't strip - # if this is detected. - my $dname = $derived; - if ($directory ne '' - && none { $dname =~ /$_$/ } @dup_shortnames) - { - # At this point, we don't clear information about what - # parts of $derived are truly file name components. We can - # determine that by comparing against the canonicalization - # of $directory. - my $dir = $directory . "/"; - my $cdir = canonicalize ($dir); - my $dir_len = length ($dir); - # Make sure we only strip full file name components. This - # is done by repeatedly trying to find cdir at the - # beginning. Each iteration removes one file name - # component from the end of cdir. - while ($dir_len > 0 && index ($derived, $cdir) != 0) - { - # Eventually $dir_len becomes 0. - $dir_len = rindex ($dir, "/", $dir_len - 2) + 1; - $cdir = substr ($cdir, 0, $dir_len); - } - $dname = substr ($derived, $dir_len); - } - my $var = var ($derived . '_SHORTNAME'); - if ($var) - { - # FIXME: should use the same Condition as - # the _SOURCES variable. But this is really - # silly overkill -- nobody should have - # conditional shortnames. - $dname = $var->variable_value; - } - $object = $dname . '-' . $object; - - prog_error ($lang->name . " flags defined without compiler") - if ! defined $lang->compile; - - $renamed = 1; - } - - # If rewrite said it was ok, put the object into a subdir. - $object = $directory . '/' . $object - unless $directory eq ''; - - # If the object file has been renamed (because per-target - # flags are used) we cannot compile the file with an - # inference rule: we need an explicit rule. - # - # If both source and object files are in a subdirectory - # then the inference will work. - # - # The latter case deserves a historical note. When the - # subdir-objects option was added on 1999-04-11 it was - # thought that inferences rules would work for - # subdirectory objects too. Later, on 1999-11-22, - # automake was changed to output explicit rules even for - # subdir-objects. Nobody remembers why, but this occurred - # soon after the merge of the user-dep-gen-branch so it - # might be related. In late 2003 people complained about - # the size of the generated Makefile.ins (libgcj, with - # 2200+ subdir objects was reported to have a 9MB - # Makefile), so we now rely on inference rules again. - # Maybe we'll run across the same issue as in the past, - # but at least this time we can document it. However since - # dependency tracking has evolved it is possible that - # our old problem no longer exists. - # Using inference rules for subdir-objects has been tested - # with GNU make, Solaris make, Ultrix make, BSD make, - # HP-UX make, and OSF1 make successfully. - if ($renamed - # We must also use specific rules for a nodist_ source - # if its language requests it. - || ($lang->nodist_specific && ! $transform{'DIST_SOURCE'})) - { - my $obj_sans_ext = substr ($object, 0, - - length ($this_obj_ext)); - my $full_ansi; - if ($directory ne '') - { - $full_ansi = $directory . '/' . $base . $extension; - } - else - { - $full_ansi = $base . $extension; - } - - my @specifics = ($full_ansi, $obj_sans_ext, - # Only use $this_obj_ext in the derived - # source case because in the other case we - # *don't* want $(OBJEXT) to appear here. - ($derived_source ? $this_obj_ext : '.o'), - $extension); - - # If we renamed the object then we want to use the - # per-executable flag name. But if this is simply a - # subdir build then we still want to use the AM_ flag - # name. - if ($renamed) - { - unshift @specifics, $derived; - $aggregate = $derived; - } - else - { - unshift @specifics, 'AM'; - } - - # Each item on this list is a reference to a list consisting - # of four values followed by additional transform flags for - # file_contents. The four values are the derived flag prefix - # (e.g. for 'foo_CFLAGS', it is 'foo'), the name of the - # source file, the base name of the output file, and - # the extension for the object file. - push (@{$lang_specific_files{$lang->name}}, - [@specifics, %transform]); - } - } - elsif ($extension eq $obj) - { - # This is probably the result of a direct suffix rule. - # In this case we just accept the rewrite. - $object = "$base$extension"; - $object = "$directory/$object" if $directory ne ''; - $linker = ''; - } - else - { - # No error message here. Used to have one, but it was - # very unpopular. - # FIXME: we could potentially do more processing here, - # perhaps treating the new extension as though it were a - # new source extension (as above). This would require - # more restructuring than is appropriate right now. - next; - } - - # FIXME: this is likely an internal error now that we use - # FIXME: subdir-objects unconditionally ... - err_am "object '$object' created by '$full' and '$object_map{$object}'" - if (defined $object_map{$object} - && $object_map{$object} ne $full); - - my $comp_val = (($object =~ /\.lo$/) - ? COMPILE_LIBTOOL : COMPILE_ORDINARY); - (my $comp_obj = $object) =~ s/\.lo$/.\$(OBJEXT)/; - if (defined $object_compilation_map{$comp_obj} - && $object_compilation_map{$comp_obj} != 0 - # Only see the error once. - && ($object_compilation_map{$comp_obj} - != (COMPILE_LIBTOOL | COMPILE_ORDINARY)) - && $object_compilation_map{$comp_obj} != $comp_val) - { - err_am "object '$comp_obj' created both with libtool and without"; - } - $object_compilation_map{$comp_obj} |= $comp_val; - - if (defined $lang) - { - # Let the language do some special magic if required. - $lang->target_hook ($aggregate, $object, $full, %transform); - } - - if ($derived_source) - { - prog_error ($lang->name . " has automatic dependency tracking") - if $lang->autodep ne 'no'; - # Make sure this new source file is handled next. That will - # make it appear to be at the right place in the list. - unshift (@files, $object); - # Distribute derived sources unless the source they are - # derived from is not. - push_dist_common ($object) - unless ($topparent =~ /^(?:nobase_)?nodist_/); - next; - } - - $linkers_used{$linker} = 1; - - push (@result, $object); - - if (! defined $object_map{$object}) - { - my @dep_list = (); - $object_map{$object} = $full; - - # If resulting object is in subdir, we need to make - # sure the subdir exists at build time. - if ($object =~ /\//) - { - # FIXME: check that $DIRECTORY is somewhere in the - # project - - # For Java, the way we're handling it right now, a - # '..' component doesn't make sense. - if ($lang && $lang->name eq 'java' && $object =~ /(\/|^)\.\.\//) - { - err_am "'$full' should not contain a '..' component"; - } - - # Make sure *all* objects files in the subdirectory are - # removed by "make mostlyclean". Not only this is more - # efficient than listing the object files to be removed - # individually (which would cause an 'rm' invocation for - # each of them -- very inefficient, see bug#10697), it - # would also leave stale object files in the subdirectory - # whenever a source file there is removed or renamed. - $compile_clean_files{"$directory/*.\$(OBJEXT)"} = MOSTLY_CLEAN; - if ($object =~ /\.lo$/) - { - # If we have a libtool object, then we also must remove - # any '.lo' objects in its same subdirectory. - $compile_clean_files{"$directory/*.lo"} = MOSTLY_CLEAN; - # Remember to cleanup .libs/ in this directory. - $libtool_clean_directories{$directory} = 1; - } - - push (@dep_list, require_build_directory ($directory)); - - # If we're generating dependencies, we also want - # to make sure that the appropriate subdir of the - # .deps directory is created. - push (@dep_list, - require_build_directory ($directory . '/$(DEPDIR)')) - unless option 'no-dependencies'; - } - - pretty_print_rule ($object . ':', "\t", @dep_list) - if scalar @dep_list > 0; - } - - # Transform .o or $o file into .P file (for automatic - # dependency code). - # Properly flatten multiple adjacent slashes, as Solaris 10 make - # might fail over them in an include statement. - # Leading double slashes may be special, as per Posix, so deal - # with them carefully. - if ($lang && $lang->autodep ne 'no') - { - my $depfile = $object; - $depfile =~ s/\.([^.]*)$/.P$1/; - $depfile =~ s/\$\(OBJEXT\)$/o/; - my $maybe_extra_leading_slash = ''; - $maybe_extra_leading_slash = '/' if $depfile =~ m,^//[^/],; - $depfile =~ s,/+,/,g; - my $basename = basename ($depfile); - # This might make $dirname empty, but we account for that below. - (my $dirname = dirname ($depfile)) =~ s/\/*$//; - $dirname = $maybe_extra_leading_slash . $dirname; - $dep_files{$dirname . '/$(DEPDIR)/' . $basename} = 1; - } - } - - return @result; -} - - -# $LINKER -# define_objects_from_sources ($VAR, $OBJVAR, $NODEFINE, $ONE_FILE, -# $OBJ, $PARENT, $TOPPARENT, $WHERE, %TRANSFORM) -# --------------------------------------------------------------------------- -# Define an _OBJECTS variable for a _SOURCES variable (or subvariable) -# -# Arguments are: -# $VAR is the name of the _SOURCES variable -# $OBJVAR is the name of the _OBJECTS variable if known (otherwise -# it will be generated and returned). -# $NODEFINE is a boolean: if true, $OBJVAR will not be defined (but -# work done to determine the linker will be). -# $ONE_FILE is the canonical (transformed) name of object to build -# $OBJ is the object extension (i.e. either '.o' or '.lo'). -# $TOPPARENT is the _SOURCES variable being processed. -# $WHERE context into which this definition is done -# %TRANSFORM extra arguments to pass to file_contents when producing -# rules -# -# Result is a pair ($LINKER, $OBJVAR): -# $LINKER is a boolean, true if a linker is needed to deal with the objects -sub define_objects_from_sources -{ - my ($var, $objvar, $nodefine, $one_file, - $obj, $topparent, $where, %transform) = @_; - - my $needlinker = ""; - - transform_variable_recursively - ($var, $objvar, 'am__objects', $nodefine, $where, - # The transform code to run on each filename. - sub { - my ($subvar, $val, $cond, $full_cond) = @_; - my @trans = handle_single_transform ($subvar, $topparent, - $one_file, $obj, $val, - %transform); - $needlinker = "true" if @trans; - return @trans; - }); - - return $needlinker; -} - - -# handle_source_transform ($CANON_TARGET, $TARGET, $OBJEXT, $WHERE, %TRANSFORM) -# ----------------------------------------------------------------------------- -# Handle SOURCE->OBJECT transform for one program or library. -# Arguments are: -# canonical (transformed) name of target to build -# actual target of object to build -# object extension (i.e., either '.o' or '$o') -# location of the source variable -# extra arguments to pass to file_contents when producing rules -# Return the name of the linker variable that must be used. -# Empty return means just use 'LINK'. -sub handle_source_transform -{ - # one_file is canonical name. unxformed is given name. obj is - # object extension. - my ($one_file, $unxformed, $obj, $where, %transform) = @_; - - my $linker = ''; - - # No point in continuing if _OBJECTS is defined. - return if reject_var ($one_file . '_OBJECTS', - $one_file . '_OBJECTS should not be defined'); - - my %used_pfx = (); - my $needlinker; - %linkers_used = (); - foreach my $prefix ('', 'EXTRA_', 'dist_', 'nodist_', - 'dist_EXTRA_', 'nodist_EXTRA_') - { - my $varname = $prefix . $one_file . "_SOURCES"; - my $var = var $varname; - next unless $var; - - # We are going to define _OBJECTS variables using the prefix. - # Then we glom them all together. So we can't use the null - # prefix here as we need it later. - my $xpfx = ($prefix eq '') ? 'am_' : $prefix; - - # Keep track of which prefixes we saw. - $used_pfx{$xpfx} = 1 - unless $prefix =~ /EXTRA_/; - - push @sources, "\$($varname)"; - push @dist_sources, shadow_unconditionally ($varname, $where) - unless (option ('no-dist') || $prefix =~ /^nodist_/); - - $needlinker |= - define_objects_from_sources ($varname, - $xpfx . $one_file . '_OBJECTS', - !!($prefix =~ /EXTRA_/), - $one_file, $obj, $varname, $where, - DIST_SOURCE => ($prefix !~ /^nodist_/), - %transform); - } - if ($needlinker) - { - $linker ||= resolve_linker (%linkers_used); - } - - my @keys = sort keys %used_pfx; - if (scalar @keys == 0) - { - # The default source for libfoo.la is libfoo.c, but for - # backward compatibility we first look at libfoo_la.c, - # if no default source suffix is given. - my $old_default_source = "$one_file.c"; - my $ext_var = var ('AM_DEFAULT_SOURCE_EXT'); - my $default_source_ext = $ext_var ? variable_value ($ext_var) : '.c'; - msg_var ('unsupported', $ext_var, $ext_var->name . " can assume at most one value") - if $default_source_ext =~ /[\t ]/; - (my $default_source = $unxformed) =~ s,(\.[^./\\]*)?$,$default_source_ext,; - # TODO: Remove this backward-compatibility hack in Automake 2.0. - if ($old_default_source ne $default_source - && !$ext_var - && (rule $old_default_source - || rule '$(srcdir)/' . $old_default_source - || rule '${srcdir}/' . $old_default_source - || -f $old_default_source)) - { - my $loc = $where->clone; - $loc->pop_context; - msg ('obsolete', $loc, - "the default source for '$unxformed' has been changed " - . "to '$default_source'.\n(Using '$old_default_source' for " - . "backward compatibility.)"); - $default_source = $old_default_source; - } - # If a rule exists to build this source with a $(srcdir) - # prefix, use that prefix in our variables too. This is for - # the sake of BSD Make. - if (rule '$(srcdir)/' . $default_source - || rule '${srcdir}/' . $default_source) - { - $default_source = '$(srcdir)/' . $default_source; - } - - define_variable ($one_file . "_SOURCES", $default_source, $where); - push (@sources, $default_source); - push (@dist_sources, $default_source); - - %linkers_used = (); - my (@result) = - handle_single_transform ($one_file . '_SOURCES', - $one_file . '_SOURCES', - $one_file, $obj, - $default_source, %transform); - $linker ||= resolve_linker (%linkers_used); - define_pretty_variable ($one_file . '_OBJECTS', TRUE, $where, @result); - } - else - { - @keys = map { '$(' . $_ . $one_file . '_OBJECTS)' } @keys; - define_pretty_variable ($one_file . '_OBJECTS', TRUE, $where, @keys); - } - - # If we want to use 'LINK' we must make sure it is defined. - if ($linker eq '') - { - $need_link = 1; - } - - return $linker; -} - - -# handle_lib_objects ($XNAME, $VAR) -# --------------------------------- -# Special-case ALLOCA and LIBOBJS substitutions in _LDADD or _LIBADD variables. -# Also, generate _DEPENDENCIES variable if appropriate. -# Arguments are: -# transformed name of object being built, or empty string if no object -# name of _LDADD/_LIBADD-type variable to examine -# Returns 1 if LIBOBJS seen, 0 otherwise. -sub handle_lib_objects -{ - my ($xname, $varname) = @_; - - my $var = var ($varname); - prog_error "'$varname' undefined" - unless $var; - prog_error "unexpected variable name '$varname'" - unless $varname =~ /^(.*)(?:LIB|LD)ADD$/; - my $prefix = $1 || 'AM_'; - - my $seen_libobjs = 0; - my $flagvar = 0; - - transform_variable_recursively - ($varname, $xname . '_DEPENDENCIES', 'am__DEPENDENCIES', - ! $xname, INTERNAL, - # Transformation function, run on each filename. - sub { - my ($subvar, $val, $cond, $full_cond) = @_; - - if ($val =~ /^-/) - { - # Skip -lfoo and -Ldir silently; these are explicitly allowed. - if ($val !~ /^-[lL]/ && - # Skip -dlopen and -dlpreopen; these are explicitly allowed - # for Libtool libraries or programs. (Actually we are a bit - # lax here since this code also applies to non-libtool - # libraries or programs, for which -dlopen and -dlopreopen - # are pure nonsense. Diagnosing this doesn't seem very - # important: the developer will quickly get complaints from - # the linker.) - $val !~ /^-dl(?:pre)?open$/ && - # Only get this error once. - ! $flagvar) - { - $flagvar = 1; - # FIXME: should display a stack of nested variables - # as context when $var != $subvar. - err_var ($var, "linker flags such as '$val' belong in " - . "'${prefix}LDFLAGS'"); - } - return (); - } - elsif ($val !~ /^\@.*\@$/) - { - # Assume we have a file of some sort, and output it into the - # dependency variable. Autoconf substitutions are not output; - # rarely is a new dependency substituted into e.g. foo_LDADD - # -- but bad things (e.g. -lX11) are routinely substituted. - # Note that LIBOBJS and ALLOCA are exceptions to this rule, - # and handled specially below. - return $val; - } - elsif ($val =~ /^\@(LT)?LIBOBJS\@$/) - { - handle_LIBOBJS ($subvar, $cond, $1); - $seen_libobjs = 1; - return $val; - } - elsif ($val =~ /^\@(LT)?ALLOCA\@$/) - { - handle_ALLOCA ($subvar, $cond, $1); - return $val; - } - else - { - return (); - } - }); - - return $seen_libobjs; -} - -# handle_LIBOBJS_or_ALLOCA ($VAR, $BASE) -# -------------------------------------- -# Definitions common to LIBOBJS and ALLOCA. -# VAR should be one of LIBOBJS, LTLIBOBJS, ALLOCA, or LTALLOCA. -# BASE should be one base file name from AC_LIBSOURCE, or alloca. -sub handle_LIBOBJS_or_ALLOCA -{ - my ($var, $base) = @_; - - my $dir = ''; - - # If LIBOBJS files must be built in another directory we have - # to define LIBOBJDIR and ensure the files get cleaned. - # Otherwise LIBOBJDIR can be left undefined, and the cleaning - # is achieved by 'rm -f *.$(OBJEXT)' in compile.am. - if ($config_libobj_dir && $relative_dir ne $config_libobj_dir) - { - # In the top-level Makefile we do not use $(top_builddir), because - # we are already there, and since the targets are built without - # a $(top_builddir), it helps BSD Make to match them with - # dependencies. - $dir = "$config_libobj_dir/" - if $config_libobj_dir ne '.'; - $dir = backname ($relative_dir) . "/$dir" - if $relative_dir ne '.'; - define_variable ('LIBOBJDIR', "$dir", INTERNAL); - if ($dir && !defined $clean_files{"$dir$base.\$(OBJEXT)"}) - { - my $dirstamp = require_build_directory ($dir); - $output_rules .= "$dir$base.\$(OBJEXT): $dirstamp\n"; - $output_rules .= "$dir$base.lo: $dirstamp\n" - if ($var =~ /^LT/); - } - # libtool might create .$(OBJEXT) as a side-effect of using - # LTLIBOBJS or LTALLOCA. - $clean_files{"$dir$base.\$(OBJEXT)"} = MOSTLY_CLEAN; - $clean_files{"$dir$base.lo"} = MOSTLY_CLEAN - if ($var =~ /^LT/); - } - - return $dir; -} - -sub handle_LIBOBJS -{ - my ($var, $cond, $lt) = @_; - my $myobjext = $lt ? 'lo' : 'o'; - $lt ||= ''; - - $var->requires_variables ("\@${lt}LIBOBJS\@ used", $lt . 'LIBOBJS') - if ! keys %libsources; - - foreach my $iter (keys %libsources) - { - my $dir = ''; - if ($iter =~ /^(.*)(\.[cly])$/) - { - saw_extension ($2); - saw_extension ('.c'); - $dir = handle_LIBOBJS_or_ALLOCA ("${lt}LIBOBJS", $1); - } - - if ($iter =~ /\.h$/) - { - require_libsource_with_macro ($cond, $var, FOREIGN, $iter); - } - elsif ($iter ne 'alloca.c') - { - my $rewrite = $iter; - $rewrite =~ s/\.c$/.P$myobjext/; - $dep_files{$dir . '$(DEPDIR)/' . $rewrite} = 1; - $rewrite = "^" . quotemeta ($iter) . "\$"; - # Only require the file if it is not a built source. - my $bs = var ('BUILT_SOURCES'); - if (! $bs || ! grep (/$rewrite/, $bs->value_as_list_recursive)) - { - require_libsource_with_macro ($cond, $var, FOREIGN, $iter); - } - } - } -} - -sub handle_ALLOCA -{ - my ($var, $cond, $lt) = @_; - my $myobjext = $lt ? 'lo' : 'o'; - $lt ||= ''; - my $dir = handle_LIBOBJS_or_ALLOCA ("${lt}ALLOCA", "alloca"); - - $dir eq '' and $dir = './'; - $var->requires_variables ("\@${lt}ALLOCA\@ used", $lt . 'ALLOCA'); - $dep_files{$dir . '$(DEPDIR)/alloca.P' . $myobjext} = 1; - require_libsource_with_macro ($cond, $var, FOREIGN, 'alloca.c'); - saw_extension ('.c'); -} - -# Canonicalize the input parameter. -sub canonicalize -{ - my ($string) = @_; - $string =~ tr/A-Za-z0-9_\@/_/c; - return $string; -} - -# Canonicalize a name, and check to make sure the non-canonical name -# is never used. Returns canonical name. Arguments are name and a -# list of suffixes to check for. -sub check_canonical_spelling -{ - my ($name, @suffixes) = @_; - - my $xname = canonicalize ($name); - if ($xname ne $name) - { - foreach my $xt (@suffixes) - { - reject_var ("$name$xt", "use '$xname$xt', not '$name$xt'"); - } - } - - return $xname; -} - -# Set up the compile suite. -sub handle_compile () -{ - return if ! $must_handle_compiled_objects; - - # Boilerplate. - my $default_includes = ''; - if (! option 'nostdinc') - { - my @incs = ('-I.', subst ('am__isrc')); - - my $var = var 'CONFIG_HEADER'; - if ($var) - { - foreach my $hdr (split (' ', $var->variable_value)) - { - push @incs, '-I' . dirname ($hdr); - } - } - # We want '-I. -I$(srcdir)', but the latter -I is redundant - # and unaesthetic in non-VPATH builds. We use `-I.@am__isrc@` - # instead. It will be replaced by '-I.' or '-I. -I$(srcdir)'. - # Items in CONFIG_HEADER are never in $(srcdir) so it is safe - # to just put @am__isrc@ right after '-I.', without a space. - ($default_includes = ' ' . uniq (@incs)) =~ s/ @/@/; - } - - my (@mostly_rms, @dist_rms); - foreach my $item (sort keys %compile_clean_files) - { - if ($compile_clean_files{$item} == MOSTLY_CLEAN) - { - push (@mostly_rms, "\t-rm -f $item"); - } - elsif ($compile_clean_files{$item} == DIST_CLEAN) - { - push (@dist_rms, "\t-rm -f $item"); - } - else - { - prog_error 'invalid entry in %compile_clean_files'; - } - } - - my ($coms, $vars, $rules) = - file_contents_internal (1, "$libdir/am/compile.am", - new Automake::Location, - 'DEFAULT_INCLUDES' => $default_includes, - 'MOSTLYRMS' => join ("\n", @mostly_rms), - 'DISTRMS' => join ("\n", @dist_rms)); - $output_vars .= $vars; - $output_rules .= "$coms$rules"; -} - -# Handle libtool rules. -sub handle_libtool () -{ - return unless var ('LIBTOOL'); - - # Libtool requires some files, but only at top level. - # (Starting with Libtool 2.0 we do not have to bother. These - # requirements are done with AC_REQUIRE_AUX_FILE.) - require_conf_file_with_macro (TRUE, 'LIBTOOL', FOREIGN, @libtool_files) - if $relative_dir eq '.' && ! $libtool_new_api; - - my @libtool_rms; - foreach my $item (sort keys %libtool_clean_directories) - { - my $dir = ($item eq '.') ? '' : "$item/"; - # .libs is for Unix, _libs for DOS. - push (@libtool_rms, "\t-rm -rf ${dir}.libs"); - } - - check_user_variables 'LIBTOOLFLAGS'; - - # Output the libtool compilation rules. - $output_rules .= file_contents ('libtool', - new Automake::Location, - LTRMS => join ("\n", @libtool_rms)); -} - -# Check for duplicate targets -sub handle_targets () -{ - my %seen = (); - my @dups = (); - @proglist = am_install_var ('progs', 'PROGRAMS', - 'bin', 'sbin', 'libexec', 'pkglibexec', - 'noinst', 'check'); - @liblist = am_install_var ('libs', 'LIBRARIES', - 'lib', 'pkglib', 'noinst', 'check'); - @ltliblist = am_install_var ('ltlib', 'LTLIBRARIES', - 'noinst', 'lib', 'pkglib', 'check'); - - # Record duplications that may arise after canonicalization of the - # base names, in order to prevent object file clashes in the presence - # of target-specific *FLAGS - my @targetlist = (@proglist, @liblist, @ltliblist); - foreach my $pair (@targetlist) - { - my $base = canonicalize (basename (@$pair[1])); - push (@dup_shortnames, $base) if ($seen{$base}); - $seen{$base} = $base; - } -} - -sub handle_programs () -{ - return if ! @proglist; - $must_handle_compiled_objects = 1; - - my $seen_global_libobjs = - var ('LDADD') && handle_lib_objects ('', 'LDADD'); - - foreach my $pair (@proglist) - { - my ($where, $one_file) = @$pair; - - my $seen_libobjs = 0; - my $obj = '.$(OBJEXT)'; - - $known_programs{$one_file} = $where; - - # Canonicalize names and check for misspellings. - my $xname = check_canonical_spelling ($one_file, '_LDADD', '_LDFLAGS', - '_SOURCES', '_OBJECTS', - '_DEPENDENCIES'); - - $where->push_context ("while processing program '$one_file'"); - $where->set (INTERNAL->get); - - my $linker = handle_source_transform ($xname, $one_file, $obj, $where, - NONLIBTOOL => 1, LIBTOOL => 0); - - if (var ($xname . "_LDADD")) - { - $seen_libobjs = handle_lib_objects ($xname, $xname . '_LDADD'); - } - else - { - # User didn't define prog_LDADD override. So do it. - define_variable ($xname . '_LDADD', '$(LDADD)', $where); - - # This does a bit too much work. But we need it to - # generate _DEPENDENCIES when appropriate. - if (var ('LDADD')) - { - $seen_libobjs = handle_lib_objects ($xname, 'LDADD'); - } - } - - reject_var ($xname . '_LIBADD', - "use '${xname}_LDADD', not '${xname}_LIBADD'"); - - set_seen ($xname . '_DEPENDENCIES'); - set_seen ('EXTRA_' . $xname . '_DEPENDENCIES'); - set_seen ($xname . '_LDFLAGS'); - - # Determine program to use for link. - my($xlink, $vlink) = define_per_target_linker_variable ($linker, $xname); - $vlink = verbose_flag ($vlink || 'GEN'); - - # If the resulting program lies in a subdirectory, - # ensure that the directory exists before we need it. - my $dirstamp = require_build_directory_maybe ($one_file); - - $libtool_clean_directories{dirname ($one_file)} = 1; - - $output_rules .= file_contents ('program', - $where, - PROGRAM => $one_file, - XPROGRAM => $xname, - XLINK => $xlink, - VERBOSE => $vlink, - DIRSTAMP => $dirstamp, - EXEEXT => '$(EXEEXT)'); - - if ($seen_libobjs || $seen_global_libobjs) - { - if (var ($xname . '_LDADD')) - { - check_libobjs_sources ($xname, $xname . '_LDADD'); - } - elsif (var ('LDADD')) - { - check_libobjs_sources ($xname, 'LDADD'); - } - } - } -} - - -sub handle_libraries () -{ - return if ! @liblist; - $must_handle_compiled_objects = 1; - - my @prefix = am_primary_prefixes ('LIBRARIES', 0, 'lib', 'pkglib', - 'noinst', 'check'); - - if (@prefix) - { - my $var = rvar ($prefix[0] . '_LIBRARIES'); - $var->requires_variables ('library used', 'RANLIB'); - } - - define_variable ('AR', 'ar', INTERNAL); - define_variable ('ARFLAGS', 'cru', INTERNAL); - define_verbose_tagvar ('AR'); - - foreach my $pair (@liblist) - { - my ($where, $onelib) = @$pair; - - my $seen_libobjs = 0; - # Check that the library fits the standard naming convention. - my $bn = basename ($onelib); - if ($bn !~ /^lib.*\.a$/) - { - $bn =~ s/^(?:lib)?(.*?)(?:\.[^.]*)?$/lib$1.a/; - my $suggestion = dirname ($onelib) . "/$bn"; - $suggestion =~ s|^\./||g; - msg ('error-gnu/warn', $where, - "'$onelib' is not a standard library name\n" - . "did you mean '$suggestion'?") - } - - ($known_libraries{$onelib} = $bn) =~ s/\.a$//; - - $where->push_context ("while processing library '$onelib'"); - $where->set (INTERNAL->get); - - my $obj = '.$(OBJEXT)'; - - # Canonicalize names and check for misspellings. - my $xlib = check_canonical_spelling ($onelib, '_LIBADD', '_SOURCES', - '_OBJECTS', '_DEPENDENCIES', - '_AR'); - - if (! var ($xlib . '_AR')) - { - define_variable ($xlib . '_AR', '$(AR) $(ARFLAGS)', $where); - } - - # Generate support for conditional object inclusion in - # libraries. - if (var ($xlib . '_LIBADD')) - { - if (handle_lib_objects ($xlib, $xlib . '_LIBADD')) - { - $seen_libobjs = 1; - } - } - else - { - define_variable ($xlib . "_LIBADD", '', $where); - } - - reject_var ($xlib . '_LDADD', - "use '${xlib}_LIBADD', not '${xlib}_LDADD'"); - - # Make sure we at look at this. - set_seen ($xlib . '_DEPENDENCIES'); - set_seen ('EXTRA_' . $xlib . '_DEPENDENCIES'); - - handle_source_transform ($xlib, $onelib, $obj, $where, - NONLIBTOOL => 1, LIBTOOL => 0); - - # If the resulting library lies in a subdirectory, - # make sure this directory will exist. - my $dirstamp = require_build_directory_maybe ($onelib); - my $verbose = verbose_flag ('AR'); - my $silent = silent_flag (); - - $output_rules .= file_contents ('library', - $where, - VERBOSE => $verbose, - SILENT => $silent, - LIBRARY => $onelib, - XLIBRARY => $xlib, - DIRSTAMP => $dirstamp); - - if ($seen_libobjs) - { - if (var ($xlib . '_LIBADD')) - { - check_libobjs_sources ($xlib, $xlib . '_LIBADD'); - } - } - - if (! $seen_ar) - { - msg ('extra-portability', $where, - "'$onelib': linking libraries using a non-POSIX\n" - . "archiver requires 'AM_PROG_AR' in '$configure_ac'") - } - } -} - - -sub handle_ltlibraries () -{ - return if ! @ltliblist; - $must_handle_compiled_objects = 1; - - my @prefix = am_primary_prefixes ('LTLIBRARIES', 0, 'lib', 'pkglib', - 'noinst', 'check'); - - if (@prefix) - { - my $var = rvar ($prefix[0] . '_LTLIBRARIES'); - $var->requires_variables ('Libtool library used', 'LIBTOOL'); - } - - my %instdirs = (); - my %instsubdirs = (); - my %instconds = (); - my %liblocations = (); # Location (in Makefile.am) of each library. - - foreach my $key (@prefix) - { - # Get the installation directory of each library. - my $dir = $key; - my $strip_subdir = 1; - if ($dir =~ /^nobase_/) - { - $dir =~ s/^nobase_//; - $strip_subdir = 0; - } - my $var = rvar ($key . '_LTLIBRARIES'); - - # We reject libraries which are installed in several places - # in the same condition, because we can only specify one - # '-rpath' option. - $var->traverse_recursively - (sub - { - my ($var, $val, $cond, $full_cond) = @_; - my $hcond = $full_cond->human; - my $where = $var->rdef ($cond)->location; - my $ldir = ''; - $ldir = '/' . dirname ($val) - if (!$strip_subdir); - # A library cannot be installed in different directories - # in overlapping conditions. - if (exists $instconds{$val}) - { - my ($msg, $acond) = - $instconds{$val}->ambiguous_p ($val, $full_cond); - - if ($msg) - { - error ($where, $msg, partial => 1); - my $dirtxt = "installed " . ($strip_subdir ? "in" : "below") . " '$dir'"; - $dirtxt = "built for '$dir'" - if $dir eq 'EXTRA' || $dir eq 'noinst' || $dir eq 'check'; - my $dircond = - $full_cond->true ? "" : " in condition $hcond"; - - error ($where, "'$val' should be $dirtxt$dircond ...", - partial => 1); - - my $hacond = $acond->human; - my $adir = $instdirs{$val}{$acond}; - my $adirtxt = "installed in '$adir'"; - $adirtxt = "built for '$adir'" - if ($adir eq 'EXTRA' || $adir eq 'noinst' - || $adir eq 'check'); - my $adircond = $acond->true ? "" : " in condition $hacond"; - - my $onlyone = ($dir ne $adir) ? - ("\nLibtool libraries can be built for only one " - . "destination") : ""; - - error ($liblocations{$val}{$acond}, - "... and should also be $adirtxt$adircond.$onlyone"); - return; - } - } - else - { - $instconds{$val} = new Automake::DisjConditions; - } - $instdirs{$val}{$full_cond} = $dir; - $instsubdirs{$val}{$full_cond} = $ldir; - $liblocations{$val}{$full_cond} = $where; - $instconds{$val} = $instconds{$val}->merge ($full_cond); - }, - sub - { - return (); - }, - skip_ac_subst => 1); - } - - foreach my $pair (@ltliblist) - { - my ($where, $onelib) = @$pair; - - my $seen_libobjs = 0; - my $obj = '.lo'; - - # Canonicalize names and check for misspellings. - my $xlib = check_canonical_spelling ($onelib, '_LIBADD', '_LDFLAGS', - '_SOURCES', '_OBJECTS', - '_DEPENDENCIES'); - - # Check that the library fits the standard naming convention. - my $libname_rx = '^lib.*\.la'; - my $ldvar = var ("${xlib}_LDFLAGS") || var ('AM_LDFLAGS'); - my $ldvar2 = var ('LDFLAGS'); - if (($ldvar && grep (/-module/, $ldvar->value_as_list_recursive)) - || ($ldvar2 && grep (/-module/, $ldvar2->value_as_list_recursive))) - { - # Relax name checking for libtool modules. - $libname_rx = '\.la'; - } - - my $bn = basename ($onelib); - if ($bn !~ /$libname_rx$/) - { - my $type = 'library'; - if ($libname_rx eq '\.la') - { - $bn =~ s/^(lib|)(.*?)(?:\.[^.]*)?$/$1$2.la/; - $type = 'module'; - } - else - { - $bn =~ s/^(?:lib)?(.*?)(?:\.[^.]*)?$/lib$1.la/; - } - my $suggestion = dirname ($onelib) . "/$bn"; - $suggestion =~ s|^\./||g; - msg ('error-gnu/warn', $where, - "'$onelib' is not a standard libtool $type name\n" - . "did you mean '$suggestion'?") - } - - ($known_libraries{$onelib} = $bn) =~ s/\.la$//; - - $where->push_context ("while processing Libtool library '$onelib'"); - $where->set (INTERNAL->get); - - # Make sure we look at these. - set_seen ($xlib . '_LDFLAGS'); - set_seen ($xlib . '_DEPENDENCIES'); - set_seen ('EXTRA_' . $xlib . '_DEPENDENCIES'); - - # Generate support for conditional object inclusion in - # libraries. - if (var ($xlib . '_LIBADD')) - { - if (handle_lib_objects ($xlib, $xlib . '_LIBADD')) - { - $seen_libobjs = 1; - } - } - else - { - define_variable ($xlib . "_LIBADD", '', $where); - } - - reject_var ("${xlib}_LDADD", - "use '${xlib}_LIBADD', not '${xlib}_LDADD'"); - - - my $linker = handle_source_transform ($xlib, $onelib, $obj, $where, - NONLIBTOOL => 0, LIBTOOL => 1); - - # Determine program to use for link. - my($xlink, $vlink) = define_per_target_linker_variable ($linker, $xlib); - $vlink = verbose_flag ($vlink || 'GEN'); - - my $rpathvar = "am_${xlib}_rpath"; - my $rpath = "\$($rpathvar)"; - foreach my $rcond ($instconds{$onelib}->conds) - { - my $val; - if ($instdirs{$onelib}{$rcond} eq 'EXTRA' - || $instdirs{$onelib}{$rcond} eq 'noinst' - || $instdirs{$onelib}{$rcond} eq 'check') - { - # It's an EXTRA_ library, so we can't specify -rpath, - # because we don't know where the library will end up. - # The user probably knows, but generally speaking automake - # doesn't -- and in fact configure could decide - # dynamically between two different locations. - $val = ''; - } - else - { - $val = ('-rpath $(' . $instdirs{$onelib}{$rcond} . 'dir)'); - $val .= $instsubdirs{$onelib}{$rcond} - if defined $instsubdirs{$onelib}{$rcond}; - } - if ($rcond->true) - { - # If $rcond is true there is only one condition and - # there is no point defining an helper variable. - $rpath = $val; - } - else - { - define_pretty_variable ($rpathvar, $rcond, INTERNAL, $val); - } - } - - # If the resulting library lies in a subdirectory, - # make sure this directory will exist. - my $dirstamp = require_build_directory_maybe ($onelib); - - # Remember to cleanup .libs/ in this directory. - my $dirname = dirname $onelib; - $libtool_clean_directories{$dirname} = 1; - - $output_rules .= file_contents ('ltlibrary', - $where, - LTLIBRARY => $onelib, - XLTLIBRARY => $xlib, - RPATH => $rpath, - XLINK => $xlink, - VERBOSE => $vlink, - DIRSTAMP => $dirstamp); - if ($seen_libobjs) - { - if (var ($xlib . '_LIBADD')) - { - check_libobjs_sources ($xlib, $xlib . '_LIBADD'); - } - } - - if (! $seen_ar) - { - msg ('extra-portability', $where, - "'$onelib': linking libtool libraries using a non-POSIX\n" - . "archiver requires 'AM_PROG_AR' in '$configure_ac'") - } - } -} - -# See if any _SOURCES variable were misspelled. -sub check_typos () -{ - # It is ok if the user sets this particular variable. - set_seen 'AM_LDFLAGS'; - - foreach my $primary ('SOURCES', 'LIBADD', 'LDADD', 'LDFLAGS', 'DEPENDENCIES') - { - foreach my $var (variables $primary) - { - my $varname = $var->name; - # A configure variable is always legitimate. - next if exists $configure_vars{$varname}; - - for my $cond ($var->conditions->conds) - { - $varname =~ /^(?:EXTRA_)?(?:nobase_)?(?:dist_|nodist_)?(.*)_[[:alnum:]]+$/; - msg_var ('syntax', $var, "variable '$varname' is defined but no" - . " program or\nlibrary has '$1' as canonical name" - . " (possible typo)") - unless $var->rdef ($cond)->seen; - } - } - } -} - - -sub handle_scripts () -{ - # NOTE we no longer automatically clean SCRIPTS, because it is - # useful to sometimes distribute scripts verbatim. This happens - # e.g. in Automake itself. - am_install_var ('-candist', 'scripts', 'SCRIPTS', - 'bin', 'sbin', 'libexec', 'pkglibexec', 'pkgdata', - 'noinst', 'check'); -} - - -## ------------------------ ## -## Handling Texinfo files. ## -## ------------------------ ## - -# ($OUTFILE, $VFILE) -# scan_texinfo_file ($FILENAME) -# ----------------------------- -# $OUTFILE - name of the info file produced by $FILENAME. -# $VFILE - name of the version.texi file used (undef if none). -sub scan_texinfo_file -{ - my ($filename) = @_; - - my $texi = new Automake::XFile "< $filename"; - verb "reading $filename"; - - my ($outfile, $vfile); - while ($_ = $texi->getline) - { - if (/^\@setfilename +(\S+)/) - { - # Honor only the first @setfilename. (It's possible to have - # more occurrences later if the manual shows examples of how - # to use @setfilename...) - next if $outfile; - - $outfile = $1; - if (index ($outfile, '.') < 0) - { - msg 'obsolete', "$filename:$.", - "use of suffix-less info files is discouraged" - } - elsif ($outfile !~ /\.info$/) - { - error ("$filename:$.", - "output '$outfile' has unrecognized extension"); - return; - } - } - # A "version.texi" file is actually any file whose name matches - # "vers*.texi". - elsif (/^\@include\s+(vers[^.]*\.texi)\s*$/) - { - $vfile = $1; - } - } - - if (! $outfile) - { - err_am "'$filename' missing \@setfilename"; - return; - } - - return ($outfile, $vfile); -} - - -# ($DIRSTAMP, @CLEAN_FILES) -# output_texinfo_build_rules ($SOURCE, $DEST, $INSRC, @DEPENDENCIES) -# ------------------------------------------------------------------ -# SOURCE - the source Texinfo file -# DEST - the destination Info file -# INSRC - whether DEST should be built in the source tree -# DEPENDENCIES - known dependencies -sub output_texinfo_build_rules -{ - my ($source, $dest, $insrc, @deps) = @_; - - # Split 'a.texi' into 'a' and '.texi'. - my ($spfx, $ssfx) = ($source =~ /^(.*?)(\.[^.]*)?$/); - my ($dpfx, $dsfx) = ($dest =~ /^(.*?)(\.[^.]*)?$/); - - $ssfx ||= ""; - $dsfx ||= ""; - - # We can output two kinds of rules: the "generic" rules use Make - # suffix rules and are appropriate when $source and $dest do not lie - # in a sub-directory; the "specific" rules are needed in the other - # case. - # - # The former are output only once (this is not really apparent here, - # but just remember that some logic deeper in Automake will not - # output the same rule twice); while the later need to be output for - # each Texinfo source. - my $generic; - my $makeinfoflags; - my $sdir = dirname $source; - if ($sdir eq '.' && dirname ($dest) eq '.') - { - $generic = 1; - $makeinfoflags = '-I $(srcdir)'; - } - else - { - $generic = 0; - $makeinfoflags = "-I $sdir -I \$(srcdir)/$sdir"; - } - - # A directory can contain two kinds of info files: some built in the - # source tree, and some built in the build tree. The rules are - # different in each case. However we cannot output two different - # set of generic rules. Because in-source builds are more usual, we - # use generic rules in this case and fall back to "specific" rules - # for build-dir builds. (It should not be a problem to invert this - # if needed.) - $generic = 0 unless $insrc; - - # We cannot use a suffix rule to build info files with an empty - # extension. Otherwise we would output a single suffix inference - # rule, with separate dependencies, as in - # - # .texi: - # $(MAKEINFO) ... - # foo.info: foo.texi - # - # which confuse Solaris make. (See the Autoconf manual for - # details.) Therefore we use a specific rule in this case. This - # applies to info files only (dvi and pdf files always have an - # extension). - my $generic_info = ($generic && $dsfx) ? 1 : 0; - - # If the resulting file lies in a subdirectory, - # make sure this directory will exist. - my $dirstamp = require_build_directory_maybe ($dest); - - my $dipfx = ($insrc ? '$(srcdir)/' : '') . $dpfx; - - $output_rules .= file_contents ('texibuild', - new Automake::Location, - AM_V_MAKEINFO => verbose_flag('MAKEINFO'), - AM_V_TEXI2DVI => verbose_flag('TEXI2DVI'), - AM_V_TEXI2PDF => verbose_flag('TEXI2PDF'), - DEPS => "@deps", - DEST_PREFIX => $dpfx, - DEST_INFO_PREFIX => $dipfx, - DEST_SUFFIX => $dsfx, - DIRSTAMP => $dirstamp, - GENERIC => $generic, - GENERIC_INFO => $generic_info, - INSRC => $insrc, - MAKEINFOFLAGS => $makeinfoflags, - SILENT => silent_flag(), - SOURCE => ($generic - ? '$<' : $source), - SOURCE_INFO => ($generic_info - ? '$<' : $source), - SOURCE_REAL => $source, - SOURCE_SUFFIX => $ssfx, - TEXIQUIET => verbose_flag('texinfo'), - TEXIDEVNULL => verbose_flag('texidevnull'), - ); - return ($dirstamp, "$dpfx.dvi", "$dpfx.pdf", "$dpfx.ps", "$dpfx.html"); -} - - -# ($MOSTLYCLEAN, $TEXICLEAN, $MAINTCLEAN) -# handle_texinfo_helper ($info_texinfos) -# -------------------------------------- -# Handle all Texinfo source; helper for 'handle_texinfo'. -sub handle_texinfo_helper -{ - my ($info_texinfos) = @_; - my (@infobase, @info_deps_list, @texi_deps); - my %versions; - my $done = 0; - my (@mostly_cleans, @texi_cleans, @maint_cleans) = ('', '', ''); - - foreach my $texi - ($info_texinfos->value_as_list_recursive (inner_expand => 1)) - { - my $infobase = $texi; - if ($infobase =~ s/\.texi$//) - { - 1; # Nothing more to do. - } - elsif ($infobase =~ s/\.(txi|texinfo)$//) - { - msg_var 'obsolete', $info_texinfos, - "suffix '.$1' for Texinfo files is discouraged;" . - " use '.texi' instead"; - } - else - { - # FIXME: report line number. - err_am "texinfo file '$texi' has unrecognized extension"; - next; - } - - push @infobase, $infobase; - - # If 'version.texi' is referenced by input file, then include - # automatic versioning capability. - my ($out_file, $vtexi) = - scan_texinfo_file ("$relative_dir/$texi") - or next; - # Directory of auxiliary files and build by-products used by texi2dvi - # and texi2pdf. - push @mostly_cleans, "$infobase.t2d"; - push @mostly_cleans, "$infobase.t2p"; - - # If the Texinfo source is in a subdirectory, create the - # resulting info in this subdirectory. If it is in the current - # directory, try hard to not prefix "./" because it breaks the - # generic rules. - my $outdir = dirname ($texi) . '/'; - $outdir = "" if $outdir eq './'; - my $src_outdir = '$(srcdir)/'. $outdir; - $out_file = $outdir . $out_file; - - # Until Automake 1.6.3, .info files were built in the - # source tree. This was an obstacle to the support of - # non-distributed .info files, and non-distributed .texi - # files. - # - # * Non-distributed .texi files is important in some packages - # where .texi files are built at make time, probably using - # other binaries built in the package itself, maybe using - # tools or information found on the build host. Because - # these files are not distributed they are always rebuilt - # at make time; they should therefore not lie in the source - # directory. One plan was to support this using - # nodist_info_TEXINFOS or something similar. (Doing this - # requires some sanity checks. For instance Automake should - # not allow: - # dist_info_TEXINFOS = foo.texi - # nodist_foo_TEXINFOS = included.texi - # because a distributed file should never depend on a - # non-distributed file.) - # - # * If .texi files are not distributed, then .info files should - # not be distributed either. There are also cases where one - # wants to distribute .texi files, but does not want to - # distribute the .info files. For instance the Texinfo package - # distributes the tool used to build these files; it would - # be a waste of space to distribute them. It's not clear - # which syntax we should use to indicate that .info files should - # not be distributed. Akim Demaille suggested that eventually - # we switch to a new syntax: - # | Maybe we should take some inspiration from what's already - # | done in the rest of Automake. Maybe there is too much - # | syntactic sugar here, and you want - # | nodist_INFO = bar.info - # | dist_bar_info_SOURCES = bar.texi - # | bar_texi_DEPENDENCIES = foo.texi - # | with a bit of magic to have bar.info represent the whole - # | bar*info set. That's a lot more verbose that the current - # | situation, but it is # not new, hence the user has less - # | to learn. - # | - # | But there is still too much room for meaningless specs: - # | nodist_INFO = bar.info - # | dist_bar_info_SOURCES = bar.texi - # | dist_PS = bar.ps something-written-by-hand.ps - # | nodist_bar_ps_SOURCES = bar.texi - # | bar_texi_DEPENDENCIES = foo.texi - # | here bar.texi is dist_ in line 2, and nodist_ in 4. - # - # Back to the point, it should be clear that in order to support - # non-distributed .info files, we need to build them in the - # build tree, not in the source tree (non-distributed .texi - # files are less of a problem, because we do not output build - # rules for them). In Automake 1.7 .info build rules have been - # largely cleaned up so that .info files get always build in the - # build tree, even when distributed. The idea was that - # (1) if during a VPATH build the .info file was found to be - # absent or out-of-date (in the source tree or in the - # build tree), Make would rebuild it in the build tree. - # If an up-to-date source-tree of the .info file existed, - # make would not rebuild it in the build tree. - # (2) having two copies of .info files, one in the source tree - # and one (newer) in the build tree is not a problem - # because 'make dist' always pick files in the build tree - # first. - # However it turned out the be a bad idea for several reasons: - # * Tru64, OpenBSD, and FreeBSD (not NetBSD) Make do not behave - # like GNU Make on point (1) above. These implementations - # of Make would always rebuild .info files in the build - # tree, even if such files were up to date in the source - # tree. Consequently, it was impossible to perform a VPATH - # build of a package containing Texinfo files using these - # Make implementations. - # (Refer to the Autoconf Manual, section "Limitation of - # Make", paragraph "VPATH", item "target lookup", for - # an account of the differences between these - # implementations.) - # * The GNU Coding Standards require these files to be built - # in the source-tree (when they are distributed, that is). - # * Keeping a fresher copy of distributed files in the - # build tree can be annoying during development because - # - if the files is kept under CVS, you really want it - # to be updated in the source tree - # - it is confusing that 'make distclean' does not erase - # all files in the build tree. - # - # Consequently, starting with Automake 1.8, .info files are - # built in the source tree again. Because we still plan to - # support non-distributed .info files at some point, we - # have a single variable ('$insrc') that controls whether - # the current .info file must be built in the source tree - # or in the build tree. Actually this variable is switched - # off when the automake option 'info-in-builddir' is given. - # This is done to allow the developers of GCC, GDB, GNU - # binutils and the GNU bfd library to force the '.info' files - # to be generated in the builddir rather than the srcdir, as - # was once done when the (now removed) 'cygnus' option was - # given. See automake bug#11034 for more discussion. - my $insrc = ! option 'info-in-builddir'; - $outdir = $src_outdir if $insrc; - - # If user specified file_TEXINFOS, then use that as explicit - # dependency list. - @texi_deps = (); - push (@texi_deps, "${src_outdir}${vtexi}") if $vtexi; - - my $canonical = canonicalize ($infobase); - if (var ($canonical . "_TEXINFOS")) - { - push (@texi_deps, '$(' . $canonical . '_TEXINFOS)'); - push_dist_common ('$(' . $canonical . '_TEXINFOS)'); - } - - my ($dirstamp, @cfiles) = - output_texinfo_build_rules ($texi, $out_file, $insrc, @texi_deps); - push (@texi_cleans, @cfiles); - - push (@info_deps_list, $out_file); - - # If a vers*.texi file is needed, emit the rule. - if ($vtexi) - { - err_am ("'$vtexi', included in '$texi', " - . "also included in '$versions{$vtexi}'") - if defined $versions{$vtexi}; - $versions{$vtexi} = $texi; - - # We number the stamp-vti files. This is doable since the - # actual names don't matter much. We only number starting - # with the second one, so that the common case looks nice. - my $vti = ($done ? $done : 'vti'); - ++$done; - - # This is ugly, but it is our historical practice. - if ($config_aux_dir_set_in_configure_ac) - { - require_conf_file_with_macro (TRUE, 'info_TEXINFOS', FOREIGN, - 'mdate-sh'); - } - else - { - require_file_with_macro (TRUE, 'info_TEXINFOS', - FOREIGN, 'mdate-sh'); - } - - my $conf_dir; - if ($config_aux_dir_set_in_configure_ac) - { - $conf_dir = "$am_config_aux_dir/"; - } - else - { - $conf_dir = '$(srcdir)/'; - } - $output_rules .= file_contents ('texi-vers', - new Automake::Location, - TEXI => $texi, - VTI => $vti, - STAMPVTI => "${src_outdir}stamp-$vti", - VTEXI => "${src_outdir}$vtexi", - MDDIR => $conf_dir, - DIRSTAMP => $dirstamp); - } - } - - # Handle location of texinfo.tex. - my $need_texi_file = 0; - my $texinfodir; - if (var ('TEXINFO_TEX')) - { - # The user defined TEXINFO_TEX so assume he knows what he is - # doing. - $texinfodir = ('$(srcdir)/' - . dirname (variable_value ('TEXINFO_TEX'))); - } - elsif ($config_aux_dir_set_in_configure_ac) - { - $texinfodir = $am_config_aux_dir; - define_variable ('TEXINFO_TEX', "$texinfodir/texinfo.tex", INTERNAL); - $need_texi_file = 2; # so that we require_conf_file later - } - else - { - $texinfodir = '$(srcdir)'; - $need_texi_file = 1; - } - define_variable ('am__TEXINFO_TEX_DIR', $texinfodir, INTERNAL); - - push (@dist_targets, 'dist-info'); - - if (! option 'no-installinfo') - { - # Make sure documentation is made and installed first. Use - # $(INFO_DEPS), not 'info', because otherwise recursive makes - # get run twice during "make all". - unshift (@all, '$(INFO_DEPS)'); - } - - define_files_variable ("DVIS", @infobase, 'dvi', INTERNAL); - define_files_variable ("PDFS", @infobase, 'pdf', INTERNAL); - define_files_variable ("PSS", @infobase, 'ps', INTERNAL); - define_files_variable ("HTMLS", @infobase, 'html', INTERNAL); - - # This next isn't strictly needed now -- the places that look here - # could easily be changed to look in info_TEXINFOS. But this is - # probably better, in case noinst_TEXINFOS is ever supported. - define_variable ("TEXINFOS", variable_value ('info_TEXINFOS'), INTERNAL); - - # Do some error checking. Note that this file is not required - # when in Cygnus mode; instead we defined TEXINFO_TEX explicitly - # up above. - if ($need_texi_file && ! option 'no-texinfo.tex') - { - if ($need_texi_file > 1) - { - require_conf_file_with_macro (TRUE, 'info_TEXINFOS', FOREIGN, - 'texinfo.tex'); - } - else - { - require_file_with_macro (TRUE, 'info_TEXINFOS', FOREIGN, - 'texinfo.tex'); - } - } - - return (makefile_wrap ("", "\t ", @mostly_cleans), - makefile_wrap ("", "\t ", @texi_cleans), - makefile_wrap ("", "\t ", @maint_cleans)); -} - - -sub handle_texinfo () -{ - reject_var 'TEXINFOS', "'TEXINFOS' is an anachronism; use 'info_TEXINFOS'"; - # FIXME: I think this is an obsolete future feature name. - reject_var 'html_TEXINFOS', "HTML generation not yet supported"; - - my $info_texinfos = var ('info_TEXINFOS'); - my ($mostlyclean, $clean, $maintclean) = ('', '', ''); - if ($info_texinfos) - { - define_verbose_texinfo; - ($mostlyclean, $clean, $maintclean) = handle_texinfo_helper ($info_texinfos); - chomp $mostlyclean; - chomp $clean; - chomp $maintclean; - } - - $output_rules .= file_contents ('texinfos', - new Automake::Location, - AM_V_DVIPS => verbose_flag('DVIPS'), - MOSTLYCLEAN => $mostlyclean, - TEXICLEAN => $clean, - MAINTCLEAN => $maintclean, - 'LOCAL-TEXIS' => !!$info_texinfos, - TEXIQUIET => verbose_flag('texinfo')); -} - - -sub handle_man_pages () -{ - reject_var 'MANS', "'MANS' is an anachronism; use 'man_MANS'"; - - # Find all the sections in use. We do this by first looking for - # "standard" sections, and then looking for any additional - # sections used in man_MANS. - my (%sections, %notrans_sections, %trans_sections, - %notrans_vars, %trans_vars, %notrans_sect_vars, %trans_sect_vars); - # We handle nodist_ for uniformity. man pages aren't distributed - # by default so it isn't actually very important. - foreach my $npfx ('', 'notrans_') - { - foreach my $pfx ('', 'dist_', 'nodist_') - { - # Add more sections as needed. - foreach my $section ('0'..'9', 'n', 'l') - { - my $varname = $npfx . $pfx . 'man' . $section . '_MANS'; - if (var ($varname)) - { - $sections{$section} = 1; - $varname = '$(' . $varname . ')'; - if ($npfx eq 'notrans_') - { - $notrans_sections{$section} = 1; - $notrans_sect_vars{$varname} = 1; - } - else - { - $trans_sections{$section} = 1; - $trans_sect_vars{$varname} = 1; - } - - push_dist_common ($varname) - if $pfx eq 'dist_'; - } - } - - my $varname = $npfx . $pfx . 'man_MANS'; - my $var = var ($varname); - if ($var) - { - foreach ($var->value_as_list_recursive) - { - # A page like 'foo.1c' goes into man1dir. - if (/\.([0-9a-z])([a-z]*)$/) - { - $sections{$1} = 1; - if ($npfx eq 'notrans_') - { - $notrans_sections{$1} = 1; - } - else - { - $trans_sections{$1} = 1; - } - } - } - - $varname = '$(' . $varname . ')'; - if ($npfx eq 'notrans_') - { - $notrans_vars{$varname} = 1; - } - else - { - $trans_vars{$varname} = 1; - } - push_dist_common ($varname) - if $pfx eq 'dist_'; - } - } - } - - return unless %sections; - - my @unsorted_deps; - - # Build section independent variables. - my $have_notrans = %notrans_vars; - my @notrans_list = sort keys %notrans_vars; - my $have_trans = %trans_vars; - my @trans_list = sort keys %trans_vars; - - # Now for each section, generate an install and uninstall rule. - # Sort sections so output is deterministic. - foreach my $section (sort keys %sections) - { - # Build section dependent variables. - my $notrans_mans = $have_notrans || exists $notrans_sections{$section}; - my $trans_mans = $have_trans || exists $trans_sections{$section}; - my (%notrans_this_sect, %trans_this_sect); - my $expr = 'man' . $section . '_MANS'; - foreach my $varname (keys %notrans_sect_vars) - { - if ($varname =~ /$expr/) - { - $notrans_this_sect{$varname} = 1; - } - } - foreach my $varname (keys %trans_sect_vars) - { - if ($varname =~ /$expr/) - { - $trans_this_sect{$varname} = 1; - } - } - my @notrans_sect_list = sort keys %notrans_this_sect; - my @trans_sect_list = sort keys %trans_this_sect; - @unsorted_deps = (keys %notrans_vars, keys %trans_vars, - keys %notrans_this_sect, keys %trans_this_sect); - my @deps = sort @unsorted_deps; - $output_rules .= file_contents ('mans', - new Automake::Location, - SECTION => $section, - DEPS => "@deps", - NOTRANS_MANS => $notrans_mans, - NOTRANS_SECT_LIST => "@notrans_sect_list", - HAVE_NOTRANS => $have_notrans, - NOTRANS_LIST => "@notrans_list", - TRANS_MANS => $trans_mans, - TRANS_SECT_LIST => "@trans_sect_list", - HAVE_TRANS => $have_trans, - TRANS_LIST => "@trans_list"); - } - - @unsorted_deps = (keys %notrans_vars, keys %trans_vars, - keys %notrans_sect_vars, keys %trans_sect_vars); - my @mans = sort @unsorted_deps; - $output_vars .= file_contents ('mans-vars', - new Automake::Location, - MANS => "@mans"); - - push (@all, '$(MANS)') - unless option 'no-installman'; -} - - -sub handle_data () -{ - am_install_var ('-noextra', '-candist', 'data', 'DATA', - 'data', 'dataroot', 'doc', 'dvi', 'html', 'pdf', - 'ps', 'sysconf', 'sharedstate', 'localstate', - 'pkgdata', 'lisp', 'noinst', 'check'); -} - - -sub handle_tags () -{ - my @config; - foreach my $spec (@config_headers) - { - my ($out, @ins) = split_config_file_spec ($spec); - foreach my $in (@ins) - { - # If the config header source is in this directory, - # require it. - push @config, basename ($in) - if $relative_dir eq dirname ($in); - } - } - - define_variable ('am__tagged_files', - '$(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)' - . "@config", INTERNAL); - - if (rvar('am__tagged_files')->value_as_list_recursive - || var ('ETAGS_ARGS') || var ('SUBDIRS')) - { - $output_rules .= file_contents ('tags', new Automake::Location); - set_seen 'TAGS_DEPENDENCIES'; - } - else - { - reject_var ('TAGS_DEPENDENCIES', - "it doesn't make sense to define 'TAGS_DEPENDENCIES'" - . " without\nsources or 'ETAGS_ARGS'"); - # Every Makefile must define some sort of TAGS rule. - # Otherwise, it would be possible for a top-level "make TAGS" - # to fail because some subdirectory failed. Ditto ctags and - # cscope. - $output_rules .= - "tags TAGS:\n\n" . - "ctags CTAGS:\n\n" . - "cscope cscopelist:\n\n"; - } -} - - -# user_phony_rule ($NAME) -# ----------------------- -# Return false if rule $NAME does not exist. Otherwise, -# declare it as phony, complete its definition (in case it is -# conditional), and return its Automake::Rule instance. -sub user_phony_rule -{ - my ($name) = @_; - my $rule = rule $name; - if ($rule) - { - depend ('.PHONY', $name); - # Define $NAME in all condition where it is not already defined, - # so that it is always OK to depend on $NAME. - for my $c ($rule->not_always_defined_in_cond (TRUE)->conds) - { - Automake::Rule::define ($name, 'internal', RULE_AUTOMAKE, - $c, INTERNAL); - $output_rules .= $c->subst_string . "$name:\n"; - } - } - return $rule; -} - - -# Handle 'dist' target. -sub handle_dist () -{ - # Substitutions for distdir.am - my %transform; - - # Define DIST_SUBDIRS. This must always be done, regardless of the - # no-dist setting: target like 'distclean' or 'maintainer-clean' use it. - my $subdirs = var ('SUBDIRS'); - if ($subdirs) - { - # If SUBDIRS is conditionally defined, then set DIST_SUBDIRS - # to all possible directories, and use it. If DIST_SUBDIRS is - # defined, just use it. - - # Note that we check DIST_SUBDIRS first on purpose, so that - # we don't call has_conditional_contents for now reason. - # (In the past one project used so many conditional subdirectories - # that calling has_conditional_contents on SUBDIRS caused - # automake to grow to 150Mb -- this should not happen with - # the current implementation of has_conditional_contents, - # but it's more efficient to avoid the call anyway.) - if (var ('DIST_SUBDIRS')) - { - } - elsif ($subdirs->has_conditional_contents) - { - define_pretty_variable - ('DIST_SUBDIRS', TRUE, INTERNAL, - uniq ($subdirs->value_as_list_recursive)); - } - else - { - # We always define this because that is what 'distclean' - # wants. - define_pretty_variable ('DIST_SUBDIRS', TRUE, INTERNAL, - '$(SUBDIRS)'); - } - } - - # The remaining definitions are only required when a dist target is used. - return if option 'no-dist'; - - # At least one of the archive formats must be enabled. - if ($relative_dir eq '.') - { - my $archive_defined = option 'no-dist-gzip' ? 0 : 1; - $archive_defined ||= - grep { option "dist-$_" } qw(zip bzip2 lzip xz); - error (option 'no-dist-gzip', - "no-dist-gzip specified but no dist-* specified,\n" - . "at least one archive format must be enabled") - unless $archive_defined; - } - - # Look for common files that should be included in distribution. - # If the aux dir is set, and it does not have a Makefile.am, then - # we check for these files there as well. - my $check_aux = 0; - if ($relative_dir eq '.' - && $config_aux_dir_set_in_configure_ac) - { - if (! is_make_dir ($config_aux_dir)) - { - $check_aux = 1; - } - } - foreach my $cfile (@common_files) - { - if (dir_has_case_matching_file ($relative_dir, $cfile) - # The file might be absent, but if it can be built it's ok. - || rule $cfile) - { - push_dist_common ($cfile); - } - - # Don't use 'elsif' here because a file might meaningfully - # appear in both directories. - if ($check_aux && dir_has_case_matching_file ($config_aux_dir, $cfile)) - { - push_dist_common ("$config_aux_dir/$cfile") - } - } - - # We might copy elements from @configure_dist_common to - # @dist_common if we think we need to. If the file appears in our - # directory, we would have discovered it already, so we don't - # check that. But if the file is in a subdir without a Makefile, - # we want to distribute it here if we are doing '.'. Ugly! - # Also, in some corner cases, it's possible that the following code - # will cause the same file to appear in the $(DIST_COMMON) variables - # of two distinct Makefiles; but this is not a problem, since the - # 'distdir' target in 'lib/am/distdir.am' can deal with the same - # file being distributed multiple times. - # See also automake bug#9651. - if ($relative_dir eq '.') - { - foreach my $file (@configure_dist_common) - { - my $dir = dirname ($file); - push_dist_common ($file) - if ($dir eq '.' || ! is_make_dir ($dir)); - } - @configure_dist_common = (); - } - - # $(am__DIST_COMMON): files to be distributed automatically. Will be - # appended to $(DIST_COMMON) in the generated Makefile. - # Use 'sort' so that the expansion of $(DIST_COMMON) in the generated - # Makefile is deterministic, in face of m4 and/or perl randomizations - # (see automake bug#17908). - define_pretty_variable ('am__DIST_COMMON', TRUE, INTERNAL, - uniq (sort @dist_common)); - - # Now that we've processed @dist_common, disallow further attempts - # to modify it. - $handle_dist_run = 1; - - $transform{'DISTCHECK-HOOK'} = !! rule 'distcheck-hook'; - $transform{'GETTEXT'} = $seen_gettext && !$seen_gettext_external; - - # If the target 'dist-hook' exists, make sure it is run. This - # allows users to do random weird things to the distribution - # before it is packaged up. - push (@dist_targets, 'dist-hook') - if user_phony_rule 'dist-hook'; - $transform{'DIST-TARGETS'} = join (' ', @dist_targets); - - my $flm = option ('filename-length-max'); - my $filename_filter = $flm ? '.' x $flm->[1] : ''; - - $output_rules .= file_contents ('distdir', - new Automake::Location, - %transform, - FILENAME_FILTER => $filename_filter); -} - - -# check_directory ($NAME, $WHERE [, $RELATIVE_DIR = "."]) -# ------------------------------------------------------- -# Ensure $NAME is a directory (in $RELATIVE_DIR), and that it uses a sane -# name. Use $WHERE as a location in the diagnostic, if any. -sub check_directory -{ - my ($dir, $where, $reldir) = @_; - $reldir = '.' unless defined $reldir; - - error $where, "required directory $reldir/$dir does not exist" - unless -d "$reldir/$dir"; - - # If an 'obj/' directory exists, BSD make will enter it before - # reading 'Makefile'. Hence the 'Makefile' in the current directory - # will not be read. - # - # % cat Makefile - # all: - # echo Hello - # % cat obj/Makefile - # all: - # echo World - # % make # GNU make - # echo Hello - # Hello - # % pmake # BSD make - # echo World - # World - msg ('portability', $where, - "naming a subdirectory 'obj' causes troubles with BSD make") - if $dir eq 'obj'; - - # 'aux' is probably the most important of the following forbidden name, - # since it's tempting to use it as an AC_CONFIG_AUX_DIR. - msg ('portability', $where, - "name '$dir' is reserved on W32 and DOS platforms") - if grep (/^\Q$dir\E$/i, qw/aux lpt1 lpt2 lpt3 com1 com2 com3 com4 con prn/); -} - -# check_directories_in_var ($VARIABLE) -# ------------------------------------ -# Recursively check all items in variables $VARIABLE as directories -sub check_directories_in_var -{ - my ($var) = @_; - $var->traverse_recursively - (sub - { - my ($var, $val, $cond, $full_cond) = @_; - check_directory ($val, $var->rdef ($cond)->location, $relative_dir); - return (); - }, - undef, - skip_ac_subst => 1); -} - - -sub handle_subdirs () -{ - my $subdirs = var ('SUBDIRS'); - return - unless $subdirs; - - check_directories_in_var $subdirs; - - my $dsubdirs = var ('DIST_SUBDIRS'); - check_directories_in_var $dsubdirs - if $dsubdirs; - - $output_rules .= file_contents ('subdirs', new Automake::Location); - rvar ('RECURSIVE_TARGETS')->rdef (TRUE)->{'pretty'} = VAR_SORTED; # Gross! -} - - -# ($REGEN, @DEPENDENCIES) -# scan_aclocal_m4 -# --------------- -# If aclocal.m4 creation is automated, return the list of its dependencies. -sub scan_aclocal_m4 () -{ - my $regen_aclocal = 0; - - set_seen 'CONFIG_STATUS_DEPENDENCIES'; - set_seen 'CONFIGURE_DEPENDENCIES'; - - if (-f 'aclocal.m4') - { - define_variable ("ACLOCAL_M4", '$(top_srcdir)/aclocal.m4', INTERNAL); - - my $aclocal = new Automake::XFile "< aclocal.m4"; - my $line = $aclocal->getline; - $regen_aclocal = $line =~ 'generated automatically by aclocal'; - } - - reject_var ('ACLOCAL_M4_SOURCES', - "'ACLOCAL_M4_SOURCES' is obsolete; just remove it"); - - # Note that it might be possible that aclocal.m4 doesn't exist but - # should be auto-generated. This case probably isn't very - # important. - return $regen_aclocal; -} - - -# Helper function for 'substitute_ac_subst_variables'. -sub substitute_ac_subst_variables_worker -{ - my ($token) = @_; - return "\@$token\@" if var $token; - return "\${$token\}"; -} - -# substitute_ac_subst_variables ($TEXT) -# ------------------------------------- -# Replace any occurrence of ${FOO} in $TEXT by @FOO@ if FOO is an AC_SUBST -# variable. -sub substitute_ac_subst_variables -{ - my ($text) = @_; - $text =~ s/\$[{]([^ \t=:+{}]+)}/substitute_ac_subst_variables_worker ($1)/ge; - return $text; -} - -# @DEPENDENCIES -# prepend_srcdir (@INPUTS) -# ------------------------ -# Prepend $(srcdir) or $(top_srcdir) to all @INPUTS. The idea is that -# if an input file has a directory part the same as the current -# directory, then the directory part is simply replaced by $(srcdir). -# But if the directory part is different, then $(top_srcdir) is -# prepended. -sub prepend_srcdir -{ - my (@inputs) = @_; - my @newinputs; - - foreach my $single (@inputs) - { - if (dirname ($single) eq $relative_dir) - { - push (@newinputs, '$(srcdir)/' . basename ($single)); - } - else - { - push (@newinputs, '$(top_srcdir)/' . $single); - } - } - return @newinputs; -} - -# @DEPENDENCIES -# rewrite_inputs_into_dependencies ($OUTPUT, @INPUTS) -# --------------------------------------------------- -# Compute a list of dependencies appropriate for the rebuild -# rule of -# AC_CONFIG_FILES($OUTPUT:$INPUT[0]:$INPUTS[1]:...) -# Also distribute $INPUTs which are not built by another AC_CONFIG_FOOs. -sub rewrite_inputs_into_dependencies -{ - my ($file, @inputs) = @_; - my @res = (); - - for my $i (@inputs) - { - # We cannot create dependencies on shell variables. - next if (substitute_ac_subst_variables $i) =~ /\$/; - - if (exists $ac_config_files_location{$i} && $i ne $file) - { - my $di = dirname $i; - if ($di eq $relative_dir) - { - $i = basename $i; - } - # In the top-level Makefile we do not use $(top_builddir), because - # we are already there, and since the targets are built without - # a $(top_builddir), it helps BSD Make to match them with - # dependencies. - elsif ($relative_dir ne '.') - { - $i = '$(top_builddir)/' . $i; - } - } - else - { - msg ('error', $ac_config_files_location{$file}, - "required file '$i' not found") - unless $i =~ /\$/ || exists $output_files{$i} || -f $i; - ($i) = prepend_srcdir ($i); - push_dist_common ($i); - } - push @res, $i; - } - return @res; -} - - - -# handle_configure ($MAKEFILE_AM, $MAKEFILE_IN, $MAKEFILE, @INPUTS) -# ----------------------------------------------------------------- -# Handle remaking and configure stuff. -# We need the name of the input file, to do proper remaking rules. -sub handle_configure -{ - my ($makefile_am, $makefile_in, $makefile, @inputs) = @_; - - prog_error 'empty @inputs' - unless @inputs; - - my ($rel_makefile_am, $rel_makefile_in) = prepend_srcdir ($makefile_am, - $makefile_in); - my $rel_makefile = basename $makefile; - - my $colon_infile = ':' . join (':', @inputs); - $colon_infile = '' if $colon_infile eq ":$makefile.in"; - my @rewritten = rewrite_inputs_into_dependencies ($makefile, @inputs); - my $regen_aclocal_m4 = scan_aclocal_m4; - define_pretty_variable ('am__aclocal_m4_deps', TRUE, INTERNAL, - @configure_deps, "\$(top_srcdir)/$configure_ac"); - my @configuredeps = ('$(am__aclocal_m4_deps)', '$(CONFIGURE_DEPENDENCIES)'); - push @configuredeps, '$(ACLOCAL_M4)' if -f 'aclocal.m4'; - define_pretty_variable ('am__configure_deps', TRUE, INTERNAL, - @configuredeps); - - my $automake_options = '--' . $strictness_name . - (global_option 'no-dependencies' ? ' --ignore-deps' : ''); - - $output_rules .= file_contents - ('configure', - new Automake::Location, - MAKEFILE => $rel_makefile, - 'MAKEFILE-DEPS' => "@rewritten", - 'CONFIG-MAKEFILE' => ($relative_dir eq '.') ? '$@' : '$(subdir)/$@', - 'MAKEFILE-IN' => $rel_makefile_in, - 'HAVE-MAKEFILE-IN-DEPS' => (@include_stack > 0), - 'MAKEFILE-IN-DEPS' => "@include_stack", - 'MAKEFILE-AM' => $rel_makefile_am, - 'AUTOMAKE-OPTIONS' => $automake_options, - 'MAKEFILE-AM-SOURCES' => "$makefile$colon_infile", - 'REGEN-ACLOCAL-M4' => $regen_aclocal_m4, - VERBOSE => verbose_flag ('GEN')); - - if ($relative_dir eq '.') - { - push_dist_common ('acconfig.h') - if -f 'acconfig.h'; - } - - # If we have a configure header, require it. - my $hdr_index = 0; - my @distclean_config; - foreach my $spec (@config_headers) - { - $hdr_index += 1; - # $CONFIG_H_PATH: config.h from top level. - my ($config_h_path, @ins) = split_config_file_spec ($spec); - my $config_h_dir = dirname ($config_h_path); - - # If the header is in the current directory we want to build - # the header here. Otherwise, if we're at the topmost - # directory and the header's directory doesn't have a - # Makefile, then we also want to build the header. - if ($relative_dir eq $config_h_dir - || ($relative_dir eq '.' && ! is_make_dir ($config_h_dir))) - { - my ($cn_sans_dir, $stamp_dir); - if ($relative_dir eq $config_h_dir) - { - $cn_sans_dir = basename ($config_h_path); - $stamp_dir = ''; - } - else - { - $cn_sans_dir = $config_h_path; - if ($config_h_dir eq '.') - { - $stamp_dir = ''; - } - else - { - $stamp_dir = $config_h_dir . '/'; - } - } - - # This will also distribute all inputs. - @ins = rewrite_inputs_into_dependencies ($config_h_path, @ins); - - # Cannot define rebuild rules for filenames with shell variables. - next if (substitute_ac_subst_variables $config_h_path) =~ /\$/; - - # Header defined in this directory. - my @files; - if (-f $config_h_path . '.top') - { - push (@files, "$cn_sans_dir.top"); - } - if (-f $config_h_path . '.bot') - { - push (@files, "$cn_sans_dir.bot"); - } - - push_dist_common (@files); - - # For now, acconfig.h can only appear in the top srcdir. - if (-f 'acconfig.h') - { - push (@files, '$(top_srcdir)/acconfig.h'); - } - - my $stamp = "${stamp_dir}stamp-h${hdr_index}"; - $output_rules .= - file_contents ('remake-hdr', - new Automake::Location, - FILES => "@files", - 'FIRST-HDR' => ($hdr_index == 1), - CONFIG_H => $cn_sans_dir, - CONFIG_HIN => $ins[0], - CONFIG_H_DEPS => "@ins", - CONFIG_H_PATH => $config_h_path, - STAMP => "$stamp"); - - push @distclean_config, $cn_sans_dir, $stamp; - } - } - - $output_rules .= file_contents ('clean-hdr', - new Automake::Location, - FILES => "@distclean_config") - if @distclean_config; - - # Distribute and define mkinstalldirs only if it is already present - # in the package, for backward compatibility (some people may still - # use $(mkinstalldirs)). - # TODO: start warning about this in Automake 1.14, and have - # TODO: Automake 2.0 drop it (and the mkinstalldirs script - # TODO: as well). - my $mkidpath = "$config_aux_dir/mkinstalldirs"; - if (-f $mkidpath) - { - # Use require_file so that any existing script gets updated - # by --force-missing. - require_conf_file ($mkidpath, FOREIGN, 'mkinstalldirs'); - define_variable ('mkinstalldirs', - "\$(SHELL) $am_config_aux_dir/mkinstalldirs", INTERNAL); - } - else - { - # Use $(install_sh), not $(MKDIR_P) because the latter requires - # at least one argument, and $(mkinstalldirs) used to work - # even without arguments (e.g. $(mkinstalldirs) $(conditional_dir)). - define_variable ('mkinstalldirs', '$(install_sh) -d', INTERNAL); - } - - reject_var ('CONFIG_HEADER', - "'CONFIG_HEADER' is an anachronism; now determined " - . "automatically\nfrom '$configure_ac'"); - - my @config_h; - foreach my $spec (@config_headers) - { - my ($out, @ins) = split_config_file_spec ($spec); - # Generate CONFIG_HEADER define. - if ($relative_dir eq dirname ($out)) - { - push @config_h, basename ($out); - } - else - { - push @config_h, "\$(top_builddir)/$out"; - } - } - define_variable ("CONFIG_HEADER", "@config_h", INTERNAL) - if @config_h; - - # Now look for other files in this directory which must be remade - # by config.status, and generate rules for them. - my @actual_other_files = (); - # These get cleaned only in a VPATH build. - my @actual_other_vpath_files = (); - foreach my $lfile (@other_input_files) - { - my $file; - my @inputs; - if ($lfile =~ /^([^:]*):(.*)$/) - { - # This is the ":" syntax of AC_OUTPUT. - $file = $1; - @inputs = split (':', $2); - } - else - { - # Normal usage. - $file = $lfile; - @inputs = $file . '.in'; - } - - # Automake files should not be stored in here, but in %MAKE_LIST. - prog_error ("$lfile in \@other_input_files\n" - . "\@other_input_files = (@other_input_files)") - if -f $file . '.am'; - - my $local = basename ($file); - - # We skip files that aren't in this directory. However, if - # the file's directory does not have a Makefile, and we are - # currently doing '.', then we create a rule to rebuild the - # file in the subdir. - my $fd = dirname ($file); - if ($fd ne $relative_dir) - { - if ($relative_dir eq '.' && ! is_make_dir ($fd)) - { - $local = $file; - } - else - { - next; - } - } - - my @rewritten_inputs = rewrite_inputs_into_dependencies ($file, @inputs); - - # Cannot output rules for shell variables. - next if (substitute_ac_subst_variables $local) =~ /\$/; - - my $condstr = ''; - my $cond = $ac_config_files_condition{$lfile}; - if (defined $cond) - { - $condstr = $cond->subst_string; - Automake::Rule::define ($local, $configure_ac, RULE_AUTOMAKE, $cond, - $ac_config_files_location{$file}); - } - $output_rules .= ($condstr . $local . ': ' - . '$(top_builddir)/config.status ' - . "@rewritten_inputs\n" - . $condstr . "\t" - . 'cd $(top_builddir) && ' - . '$(SHELL) ./config.status ' - . ($relative_dir eq '.' ? '' : '$(subdir)/') - . '$@' - . "\n"); - push (@actual_other_files, $local); - } - - # For links we should clean destinations and distribute sources. - foreach my $spec (@config_links) - { - my ($link, $file) = split /:/, $spec; - # Some people do AC_CONFIG_LINKS($computed). We only handle - # the DEST:SRC form. - next unless $file; - my $where = $ac_config_files_location{$link}; - - # Skip destinations that contain shell variables. - if ((substitute_ac_subst_variables $link) !~ /\$/) - { - # We skip links that aren't in this directory. However, if - # the link's directory does not have a Makefile, and we are - # currently doing '.', then we add the link to CONFIG_CLEAN_FILES - # in '.'s Makefile.in. - my $local = basename ($link); - my $fd = dirname ($link); - if ($fd ne $relative_dir) - { - if ($relative_dir eq '.' && ! is_make_dir ($fd)) - { - $local = $link; - } - else - { - $local = undef; - } - } - if ($file ne $link) - { - push @actual_other_files, $local if $local; - } - else - { - push @actual_other_vpath_files, $local if $local; - } - } - - # Do not process sources that contain shell variables. - if ((substitute_ac_subst_variables $file) !~ /\$/) - { - my $fd = dirname ($file); - - # We distribute files that are in this directory. - # At the top-level ('.') we also distribute files whose - # directory does not have a Makefile. - if (($fd eq $relative_dir) - || ($relative_dir eq '.' && ! is_make_dir ($fd))) - { - # The following will distribute $file as a side-effect when - # it is appropriate (i.e., when $file is not already an output). - # We do not need the result, just the side-effect. - rewrite_inputs_into_dependencies ($link, $file); - } - } - } - - # These files get removed by "make distclean". - define_pretty_variable ('CONFIG_CLEAN_FILES', TRUE, INTERNAL, - @actual_other_files); - define_pretty_variable ('CONFIG_CLEAN_VPATH_FILES', TRUE, INTERNAL, - @actual_other_vpath_files); -} - -sub handle_headers () -{ - my @r = am_install_var ('-defaultdist', 'header', 'HEADERS', 'include', - 'oldinclude', 'pkginclude', - 'noinst', 'check'); - foreach (@r) - { - next unless $_->[1] =~ /\..*$/; - saw_extension ($&); - } -} - -sub handle_gettext () -{ - return if ! $seen_gettext || $relative_dir ne '.'; - - my $subdirs = var 'SUBDIRS'; - - if (! $subdirs) - { - err_ac "AM_GNU_GETTEXT used but SUBDIRS not defined"; - return; - } - - # Perform some sanity checks to help users get the right setup. - # We disable these tests when po/ doesn't exist in order not to disallow - # unusual gettext setups. - # - # Bruno Haible: - # | The idea is: - # | - # | 1) If a package doesn't have a directory po/ at top level, it - # | will likely have multiple po/ directories in subpackages. - # | - # | 2) It is useful to warn for the absence of intl/ if AM_GNU_GETTEXT - # | is used without 'external'. It is also useful to warn for the - # | presence of intl/ if AM_GNU_GETTEXT([external]) is used. Both - # | warnings apply only to the usual layout of packages, therefore - # | they should both be disabled if no po/ directory is found at - # | top level. - - if (-d 'po') - { - my @subdirs = $subdirs->value_as_list_recursive; - - msg_var ('syntax', $subdirs, - "AM_GNU_GETTEXT used but 'po' not in SUBDIRS") - if ! grep ($_ eq 'po', @subdirs); - - # intl/ is not required when AM_GNU_GETTEXT is called with the - # 'external' option and AM_GNU_GETTEXT_INTL_SUBDIR is not called. - msg_var ('syntax', $subdirs, - "AM_GNU_GETTEXT used but 'intl' not in SUBDIRS") - if (! ($seen_gettext_external && ! $seen_gettext_intl) - && ! grep ($_ eq 'intl', @subdirs)); - - # intl/ should not be used with AM_GNU_GETTEXT([external]), except - # if AM_GNU_GETTEXT_INTL_SUBDIR is called. - msg_var ('syntax', $subdirs, - "'intl' should not be in SUBDIRS when " - . "AM_GNU_GETTEXT([external]) is used") - if ($seen_gettext_external && ! $seen_gettext_intl - && grep ($_ eq 'intl', @subdirs)); - } - - require_file ($ac_gettext_location, GNU, 'ABOUT-NLS'); -} - -# Emit makefile footer. -sub handle_footer () -{ - reject_rule ('.SUFFIXES', - "use variable 'SUFFIXES', not target '.SUFFIXES'"); - - # Note: AIX 4.1 /bin/make will fail if any suffix rule appears - # before .SUFFIXES. So we make sure that .SUFFIXES appears before - # anything else, by sticking it right after the default: target. - $output_header .= ".SUFFIXES:\n"; - my $suffixes = var 'SUFFIXES'; - my @suffixes = Automake::Rule::suffixes; - if (@suffixes || $suffixes) - { - # Make sure SUFFIXES has unique elements. Sort them to ensure - # the output remains consistent. However, $(SUFFIXES) is - # always at the start of the list, unsorted. This is done - # because make will choose rules depending on the ordering of - # suffixes, and this lets the user have some control. Push - # actual suffixes, and not $(SUFFIXES). Some versions of make - # do not like variable substitutions on the .SUFFIXES line. - my @user_suffixes = ($suffixes - ? $suffixes->value_as_list_recursive : ()); - - my %suffixes = map { $_ => 1 } @suffixes; - delete @suffixes{@user_suffixes}; - - $output_header .= (".SUFFIXES: " - . join (' ', @user_suffixes, sort keys %suffixes) - . "\n"); - } - - $output_trailer .= file_contents ('footer', new Automake::Location); -} - - -# Generate 'make install' rules. -sub handle_install () -{ - $output_rules .= file_contents - ('install', - new Automake::Location, - maybe_BUILT_SOURCES => (set_seen ('BUILT_SOURCES') - ? (" \$(BUILT_SOURCES)\n" - . "\t\$(MAKE) \$(AM_MAKEFLAGS)") - : ''), - 'installdirs-local' => (user_phony_rule ('installdirs-local') - ? ' installdirs-local' : ''), - am__installdirs => variable_value ('am__installdirs') || ''); -} - - -# handle_all ($MAKEFILE) -#----------------------- -# Deal with 'all' and 'all-am'. -sub handle_all -{ - my ($makefile) = @_; - - # Output 'all-am'. - - # Put this at the beginning for the sake of non-GNU makes. This - # is still wrong if these makes can run parallel jobs. But it is - # right enough. - unshift (@all, basename ($makefile)); - - foreach my $spec (@config_headers) - { - my ($out, @ins) = split_config_file_spec ($spec); - push (@all, basename ($out)) - if dirname ($out) eq $relative_dir; - } - - # Install 'all' hooks. - push (@all, "all-local") - if user_phony_rule "all-local"; - - pretty_print_rule ("all-am:", "\t\t", @all); - depend ('.PHONY', 'all-am', 'all'); - - - # Output 'all'. - - my @local_headers = (); - push @local_headers, '$(BUILT_SOURCES)' - if var ('BUILT_SOURCES'); - foreach my $spec (@config_headers) - { - my ($out, @ins) = split_config_file_spec ($spec); - push @local_headers, basename ($out) - if dirname ($out) eq $relative_dir; - } - - if (@local_headers) - { - # We need to make sure config.h is built before we recurse. - # We also want to make sure that built sources are built - # before any ordinary 'all' targets are run. We can't do this - # by changing the order of dependencies to the "all" because - # that breaks when using parallel makes. Instead we handle - # things explicitly. - $output_all .= ("all: @local_headers" - . "\n\t" - . '$(MAKE) $(AM_MAKEFLAGS) ' - . (var ('SUBDIRS') ? 'all-recursive' : 'all-am') - . "\n\n"); - depend ('.MAKE', 'all'); - } - else - { - $output_all .= "all: " . (var ('SUBDIRS') - ? 'all-recursive' : 'all-am') . "\n\n"; - } -} - -# Generate helper targets for user-defined recursive targets, where needed. -sub handle_user_recursion () -{ - return unless @extra_recursive_targets; - - define_pretty_variable ('am__extra_recursive_targets', TRUE, INTERNAL, - map { "$_-recursive" } @extra_recursive_targets); - my $aux = var ('SUBDIRS') ? 'recursive' : 'am'; - foreach my $target (@extra_recursive_targets) - { - # This allows the default target's rules to be overridden in - # Makefile.am. - user_phony_rule ($target); - depend ("$target", "$target-$aux"); - depend ("$target-am", "$target-local"); - # Every user-defined recursive target 'foo' *must* have a valid - # associated 'foo-local' rule; we define it as an empty rule by - # default, so that the user can transparently extend it in his - # own Makefile.am. - pretty_print_rule ("$target-local:", '', ''); - # $target-recursive might as well be undefined, so do not add - # it here; it's taken care of in subdirs.am anyway. - depend (".PHONY", "$target-am", "$target-local"); - } -} - - -# Handle check merge target specially. -sub do_check_merge_target () -{ - # Include user-defined local form of target. - push @check_tests, 'check-local' - if user_phony_rule 'check-local'; - - # The check target must depend on the local equivalent of - # 'all', to ensure all the primary targets are built. Then it - # must build the local check rules. - $output_rules .= "check-am: all-am\n"; - if (@check) - { - pretty_print_rule ("\t\$(MAKE) \$(AM_MAKEFLAGS)", "\t ", @check); - depend ('.MAKE', 'check-am'); - } - - if (@check_tests) - { - pretty_print_rule ("\t\$(MAKE) \$(AM_MAKEFLAGS)", "\t ", - @check_tests); - depend ('.MAKE', 'check-am'); - } - - depend '.PHONY', 'check', 'check-am'; - # Handle recursion. We have to honor BUILT_SOURCES like for 'all:'. - $output_rules .= ("check: " - . (var ('BUILT_SOURCES') - ? "\$(BUILT_SOURCES)\n\t\$(MAKE) \$(AM_MAKEFLAGS) " - : '') - . (var ('SUBDIRS') ? 'check-recursive' : 'check-am') - . "\n"); - depend ('.MAKE', 'check') - if var ('BUILT_SOURCES'); -} - -# Handle all 'clean' targets. -sub handle_clean -{ - my ($makefile) = @_; - - # Clean the files listed in user variables if they exist. - $clean_files{'$(MOSTLYCLEANFILES)'} = MOSTLY_CLEAN - if var ('MOSTLYCLEANFILES'); - $clean_files{'$(CLEANFILES)'} = CLEAN - if var ('CLEANFILES'); - $clean_files{'$(DISTCLEANFILES)'} = DIST_CLEAN - if var ('DISTCLEANFILES'); - $clean_files{'$(MAINTAINERCLEANFILES)'} = MAINTAINER_CLEAN - if var ('MAINTAINERCLEANFILES'); - - # Built sources are automatically removed by maintainer-clean. - $clean_files{'$(BUILT_SOURCES)'} = MAINTAINER_CLEAN - if var ('BUILT_SOURCES'); - - # Compute a list of "rm"s to run for each target. - my %rms = (MOSTLY_CLEAN, [], - CLEAN, [], - DIST_CLEAN, [], - MAINTAINER_CLEAN, []); - - foreach my $file (keys %clean_files) - { - my $when = $clean_files{$file}; - prog_error 'invalid entry in %clean_files' - unless exists $rms{$when}; - - my $rm = "rm -f $file"; - # If file is a variable, make sure when don't call 'rm -f' without args. - $rm ="test -z \"$file\" || $rm" - if ($file =~ /^\s*\$(\(.*\)|\{.*\})\s*$/); - - push @{$rms{$when}}, "\t-$rm\n"; - } - - $output_rules .= file_contents - ('clean', - new Automake::Location, - MOSTLYCLEAN_RMS => join ('', sort @{$rms{&MOSTLY_CLEAN}}), - CLEAN_RMS => join ('', sort @{$rms{&CLEAN}}), - DISTCLEAN_RMS => join ('', sort @{$rms{&DIST_CLEAN}}), - MAINTAINER_CLEAN_RMS => join ('', sort @{$rms{&MAINTAINER_CLEAN}}), - MAKEFILE => basename $makefile, - ); -} - - -# Subroutine for handle_factored_dependencies() to let '.PHONY' and -# other '.TARGETS' be last. This is meant to be used as a comparison -# subroutine passed to the sort built-int. -sub target_cmp -{ - return 0 if $a eq $b; - - my $a1 = substr ($a, 0, 1); - my $b1 = substr ($b, 0, 1); - if ($a1 ne $b1) - { - return -1 if $b1 eq '.'; - return 1 if $a1 eq '.'; - } - return $a cmp $b; -} - - -# Handle everything related to gathered targets. -sub handle_factored_dependencies () -{ - # Reject bad hooks. - foreach my $utarg ('uninstall-data-local', 'uninstall-data-hook', - 'uninstall-exec-local', 'uninstall-exec-hook', - 'uninstall-dvi-local', - 'uninstall-html-local', - 'uninstall-info-local', - 'uninstall-pdf-local', - 'uninstall-ps-local') - { - my $x = $utarg; - $x =~ s/-.*-/-/; - reject_rule ($utarg, "use '$x', not '$utarg'"); - } - - reject_rule ('install-local', - "use 'install-data-local' or 'install-exec-local', " - . "not 'install-local'"); - - reject_rule ('install-hook', - "use 'install-data-hook' or 'install-exec-hook', " - . "not 'install-hook'"); - - # Install the -local hooks. - foreach (keys %dependencies) - { - # Hooks are installed on the -am targets. - s/-am$// or next; - depend ("$_-am", "$_-local") - if user_phony_rule "$_-local"; - } - - # Install the -hook hooks. - # FIXME: Why not be as liberal as we are with -local hooks? - foreach ('install-exec', 'install-data', 'uninstall') - { - if (user_phony_rule "$_-hook") - { - depend ('.MAKE', "$_-am"); - register_action("$_-am", - ("\t\@\$(NORMAL_INSTALL)\n" - . "\t\$(MAKE) \$(AM_MAKEFLAGS) $_-hook")); - } - } - - # All the required targets are phony. - depend ('.PHONY', keys %required_targets); - - # Actually output gathered targets. - foreach (sort target_cmp keys %dependencies) - { - # If there is nothing about this guy, skip it. - next - unless (@{$dependencies{$_}} - || $actions{$_} - || $required_targets{$_}); - - # Define gathered targets in undefined conditions. - # FIXME: Right now we must handle .PHONY as an exception, - # because people write things like - # .PHONY: myphonytarget - # to append dependencies. This would not work if Automake - # refrained from defining its own .PHONY target as it does - # with other overridden targets. - # Likewise for '.MAKE' and '.PRECIOUS'. - my @undefined_conds = (TRUE,); - if ($_ ne '.PHONY' && $_ ne '.MAKE' && $_ ne '.PRECIOUS') - { - @undefined_conds = - Automake::Rule::define ($_, 'internal', - RULE_AUTOMAKE, TRUE, INTERNAL); - } - my @uniq_deps = uniq (sort @{$dependencies{$_}}); - foreach my $cond (@undefined_conds) - { - my $condstr = $cond->subst_string; - pretty_print_rule ("$condstr$_:", "$condstr\t", @uniq_deps); - $output_rules .= $actions{$_} if defined $actions{$_}; - $output_rules .= "\n"; - } - } -} - - -sub handle_tests_dejagnu () -{ - push (@check_tests, 'check-DEJAGNU'); - $output_rules .= file_contents ('dejagnu', new Automake::Location); -} - -# handle_per_suffix_test ($TEST_SUFFIX, [%TRANSFORM]) -#---------------------------------------------------- -sub handle_per_suffix_test -{ - my ($test_suffix, %transform) = @_; - my ($pfx, $generic, $am_exeext); - if ($test_suffix eq '') - { - $pfx = ''; - $generic = 0; - $am_exeext = 'FALSE'; - } - else - { - prog_error ("test suffix '$test_suffix' lacks leading dot") - unless $test_suffix =~ m/^\.(.*)/; - $pfx = uc ($1) . '_'; - $generic = 1; - $am_exeext = exists $configure_vars{'EXEEXT'} ? 'am__EXEEXT' - : 'FALSE'; - } - # The "test driver" program, deputed to handle tests protocol used by - # test scripts. By default, it's assumed that no protocol is used, so - # we fall back to the old behaviour, implemented by the 'test-driver' - # auxiliary script. - if (! var "${pfx}LOG_DRIVER") - { - require_conf_file ("parallel-tests", FOREIGN, 'test-driver'); - define_variable ("${pfx}LOG_DRIVER", - "\$(SHELL) $am_config_aux_dir/test-driver", - INTERNAL); - } - my $driver = '$(' . $pfx . 'LOG_DRIVER)'; - my $driver_flags = '$(AM_' . $pfx . 'LOG_DRIVER_FLAGS)' - . ' $(' . $pfx . 'LOG_DRIVER_FLAGS)'; - my $compile = "${pfx}LOG_COMPILE"; - define_variable ($compile, - '$(' . $pfx . 'LOG_COMPILER)' - . ' $(AM_' . $pfx . 'LOG_FLAGS)' - . ' $(' . $pfx . 'LOG_FLAGS)', - INTERNAL); - $output_rules .= file_contents ('check2', new Automake::Location, - GENERIC => $generic, - DRIVER => $driver, - DRIVER_FLAGS => $driver_flags, - COMPILE => '$(' . $compile . ')', - EXT => $test_suffix, - am__EXEEXT => $am_exeext, - %transform); -} - -# is_valid_test_extension ($EXT) -# ------------------------------ -# Return true if $EXT can appear in $(TEST_EXTENSIONS), return false -# otherwise. -sub is_valid_test_extension -{ - my $ext = shift; - return 1 - if ($ext =~ /^\.[a-zA-Z_][a-zA-Z0-9_]*$/); - return 1 - if (exists $configure_vars{'EXEEXT'} && $ext eq subst ('EXEEXT')); - return 0; -} - - -sub handle_tests () -{ - if (option 'dejagnu') - { - handle_tests_dejagnu; - } - else - { - foreach my $c ('DEJATOOL', 'RUNTEST', 'RUNTESTFLAGS') - { - reject_var ($c, "'$c' defined but 'dejagnu' not in " - . "'AUTOMAKE_OPTIONS'"); - } - } - - if (var ('TESTS')) - { - push (@check_tests, 'check-TESTS'); - my $check_deps = "@check"; - $output_rules .= file_contents ('check', new Automake::Location, - SERIAL_TESTS => !! option 'serial-tests', - CHECK_DEPS => $check_deps); - - # Tests that are known programs should have $(EXEEXT) appended. - # For matching purposes, we need to adjust XFAIL_TESTS as well. - append_exeext { exists $known_programs{$_[0]} } 'TESTS'; - append_exeext { exists $known_programs{$_[0]} } 'XFAIL_TESTS' - if (var ('XFAIL_TESTS')); - - if (! option 'serial-tests') - { - define_variable ('TEST_SUITE_LOG', 'test-suite.log', INTERNAL); - my $suff = '.test'; - my $at_exeext = ''; - my $handle_exeext = exists $configure_vars{'EXEEXT'}; - if ($handle_exeext) - { - $at_exeext = subst ('EXEEXT'); - $suff = $at_exeext . ' ' . $suff; - } - if (! var 'TEST_EXTENSIONS') - { - define_variable ('TEST_EXTENSIONS', $suff, INTERNAL); - } - my $var = var 'TEST_EXTENSIONS'; - # Currently, we are not able to deal with conditional contents - # in TEST_EXTENSIONS. - if ($var->has_conditional_contents) - { - msg_var 'unsupported', $var, - "'TEST_EXTENSIONS' cannot have conditional contents"; - } - my @test_suffixes = $var->value_as_list_recursive; - if ((my @invalid_test_suffixes = - grep { !is_valid_test_extension $_ } @test_suffixes) > 0) - { - error $var->rdef (TRUE)->location, - "invalid test extensions: @invalid_test_suffixes"; - } - @test_suffixes = grep { is_valid_test_extension $_ } @test_suffixes; - if ($handle_exeext) - { - unshift (@test_suffixes, $at_exeext) - unless $test_suffixes[0] eq $at_exeext; - } - unshift (@test_suffixes, ''); - - transform_variable_recursively - ('TESTS', 'TEST_LOGS', 'am__testlogs', 1, INTERNAL, - sub { - my ($subvar, $val, $cond, $full_cond) = @_; - my $obj = $val; - return $obj - if $val =~ /^\@.*\@$/; - $obj =~ s/\$\(EXEEXT\)$//o; - - if ($val =~ /(\$\((top_)?srcdir\))\//o) - { - msg ('error', $subvar->rdef ($cond)->location, - "using '$1' in TESTS is currently broken: '$val'"); - } - - foreach my $test_suffix (@test_suffixes) - { - next - if $test_suffix eq $at_exeext || $test_suffix eq ''; - return substr ($obj, 0, length ($obj) - length ($test_suffix)) . '.log' - if substr ($obj, - length ($test_suffix)) eq $test_suffix; - } - my $base = $obj; - $obj .= '.log'; - handle_per_suffix_test ('', - OBJ => $obj, - BASE => $base, - SOURCE => $val); - return $obj; - }); - - my $nhelper=1; - my $prev = 'TESTS'; - my $post = ''; - my $last_suffix = $test_suffixes[$#test_suffixes]; - my $cur = ''; - foreach my $test_suffix (@test_suffixes) - { - if ($test_suffix eq $last_suffix) - { - $cur = 'TEST_LOGS'; - } - else - { - $cur = 'am__test_logs' . $nhelper; - } - define_variable ($cur, - '$(' . $prev . ':' . $test_suffix . $post . '=.log)', INTERNAL); - $post = '.log'; - $prev = $cur; - $nhelper++; - if ($test_suffix ne $at_exeext && $test_suffix ne '') - { - handle_per_suffix_test ($test_suffix, - OBJ => '', - BASE => '$*', - SOURCE => '$<'); - } - } - $clean_files{'$(TEST_LOGS)'} = MOSTLY_CLEAN; - $clean_files{'$(TEST_LOGS:.log=.trs)'} = MOSTLY_CLEAN; - $clean_files{'$(TEST_SUITE_LOG)'} = MOSTLY_CLEAN; - } - } -} - -sub handle_emacs_lisp () -{ - my @elfiles = am_install_var ('-candist', 'lisp', 'LISP', - 'lisp', 'noinst'); - - return if ! @elfiles; - - define_pretty_variable ('am__ELFILES', TRUE, INTERNAL, - map { $_->[1] } @elfiles); - define_pretty_variable ('am__ELCFILES', TRUE, INTERNAL, - '$(am__ELFILES:.el=.elc)'); - # This one can be overridden by users. - define_pretty_variable ('ELCFILES', TRUE, INTERNAL, '$(LISP:.el=.elc)'); - - push @all, '$(ELCFILES)'; - - require_variables ($elfiles[0][0], "Emacs Lisp sources seen", TRUE, - 'EMACS', 'lispdir'); -} - -sub handle_python () -{ - my @pyfiles = am_install_var ('-defaultdist', 'python', 'PYTHON', - 'noinst'); - return if ! @pyfiles; - - require_variables ($pyfiles[0][0], "Python sources seen", TRUE, 'PYTHON'); - require_conf_file ($pyfiles[0][0], FOREIGN, 'py-compile'); - define_variable ('py_compile', "$am_config_aux_dir/py-compile", INTERNAL); -} - -sub handle_java () -{ - my @sourcelist = am_install_var ('-candist', - 'java', 'JAVA', - 'noinst', 'check'); - return if ! @sourcelist; - - my @prefixes = am_primary_prefixes ('JAVA', 1, - 'noinst', 'check'); - - my $dir; - my @java_sources = (); - foreach my $prefix (@prefixes) - { - (my $curs = $prefix) =~ s/^(?:nobase_)?(?:dist_|nodist_)?//; - - next - if $curs eq 'EXTRA'; - - push @java_sources, '$(' . $prefix . '_JAVA' . ')'; - - if (defined $dir) - { - err_var "${curs}_JAVA", "multiple _JAVA primaries in use" - unless $curs eq $dir; - } - - $dir = $curs; - } - - define_pretty_variable ('am__java_sources', TRUE, INTERNAL, - "@java_sources"); - - if ($dir eq 'check') - { - push (@check, "class$dir.stamp"); - } - else - { - push (@all, "class$dir.stamp"); - } -} - - -sub handle_minor_options () -{ - if (option 'readme-alpha') - { - if ($relative_dir eq '.') - { - if ($package_version !~ /^$GNITS_VERSION_PATTERN$/) - { - msg ('error-gnits', $package_version_location, - "version '$package_version' doesn't follow " . - "Gnits standards"); - } - if (defined $1 && -f 'README-alpha') - { - # This means we have an alpha release. See - # GNITS_VERSION_PATTERN for details. - push_dist_common ('README-alpha'); - } - } - } -} - -################################################################ - -# ($OUTPUT, @INPUTS) -# split_config_file_spec ($SPEC) -# ------------------------------ -# Decode the Autoconf syntax for config files (files, headers, links -# etc.). -sub split_config_file_spec -{ - my ($spec) = @_; - my ($output, @inputs) = split (/:/, $spec); - - push @inputs, "$output.in" - unless @inputs; - - return ($output, @inputs); -} - -# $input -# locate_am (@POSSIBLE_SOURCES) -# ----------------------------- -# AC_CONFIG_FILES allow specifications such as Makefile:top.in:mid.in:bot.in -# This functions returns the first *.in file for which a *.am exists. -# It returns undef otherwise. -sub locate_am -{ - my (@rest) = @_; - my $input; - foreach my $file (@rest) - { - if (($file =~ /^(.*)\.in$/) && -f "$1.am") - { - $input = $file; - last; - } - } - return $input; -} - -my %make_list; - -# scan_autoconf_config_files ($WHERE, $CONFIG-FILES) -# -------------------------------------------------- -# Study $CONFIG-FILES which is the first argument to AC_CONFIG_FILES -# (or AC_OUTPUT). -sub scan_autoconf_config_files -{ - my ($where, $config_files) = @_; - - # Look at potential Makefile.am's. - foreach (split ' ', $config_files) - { - # Must skip empty string for Perl 4. - next if $_ eq "\\" || $_ eq ''; - - # Handle $local:$input syntax. - my ($local, @rest) = split (/:/); - @rest = ("$local.in",) unless @rest; - # Keep in sync with test 'conffile-leading-dot.sh'. - msg ('unsupported', $where, - "omit leading './' from config file names such as '$local';" - . "\nremake rules might be subtly broken otherwise") - if ($local =~ /^\.\//); - my $input = locate_am @rest; - if ($input) - { - # We have a file that automake should generate. - $make_list{$input} = join (':', ($local, @rest)); - } - else - { - # We have a file that automake should cause to be - # rebuilt, but shouldn't generate itself. - push (@other_input_files, $_); - } - $ac_config_files_location{$local} = $where; - $ac_config_files_condition{$local} = - new Automake::Condition (@cond_stack) - if (@cond_stack); - } -} - - -sub scan_autoconf_traces -{ - my ($filename) = @_; - - # Macros to trace, with their minimal number of arguments. - # - # IMPORTANT: If you add a macro here, you should also add this macro - # ========= to Automake-preselection in autoconf/lib/autom4te.in. - my %traced = ( - AC_CANONICAL_BUILD => 0, - AC_CANONICAL_HOST => 0, - AC_CANONICAL_TARGET => 0, - AC_CONFIG_AUX_DIR => 1, - AC_CONFIG_FILES => 1, - AC_CONFIG_HEADERS => 1, - AC_CONFIG_LIBOBJ_DIR => 1, - AC_CONFIG_LINKS => 1, - AC_FC_SRCEXT => 1, - AC_INIT => 0, - AC_LIBSOURCE => 1, - AC_REQUIRE_AUX_FILE => 1, - AC_SUBST_TRACE => 1, - AM_AUTOMAKE_VERSION => 1, - AM_CONDITIONAL => 2, - AM_EXTRA_RECURSIVE_TARGETS => 1, - AM_GNU_GETTEXT => 0, - AM_GNU_GETTEXT_INTL_SUBDIR => 0, - AM_INIT_AUTOMAKE => 0, - AM_MAINTAINER_MODE => 0, - AM_PROG_AR => 0, - _AM_SUBST_NOTMAKE => 1, - _AM_COND_IF => 1, - _AM_COND_ELSE => 1, - _AM_COND_ENDIF => 1, - LT_SUPPORTED_TAG => 1, - _LT_AC_TAGCONFIG => 0, - m4_include => 1, - m4_sinclude => 1, - sinclude => 1, - ); - - my $traces = ($ENV{AUTOCONF} || '@am_AUTOCONF@') . " "; - - # Use a separator unlikely to be used, not ':', the default, which - # has a precise meaning for AC_CONFIG_FILES and so on. - $traces .= join (' ', - map { "--trace=$_" . ':\$f:\$l::\$d::\$n::\${::}%' } - (keys %traced)); - - my $tracefh = new Automake::XFile ("$traces $filename |"); - verb "reading $traces"; - - @cond_stack = (); - my $where; - - while ($_ = $tracefh->getline) - { - chomp; - my ($here, $depth, @args) = split (/::/); - $where = new Automake::Location $here; - my $macro = $args[0]; - - prog_error ("unrequested trace '$macro'") - unless exists $traced{$macro}; - - # Skip and diagnose malformed calls. - if ($#args < $traced{$macro}) - { - msg ('syntax', $where, "not enough arguments for $macro"); - next; - } - - # Alphabetical ordering please. - if ($macro eq 'AC_CANONICAL_BUILD') - { - if ($seen_canonical <= AC_CANONICAL_BUILD) - { - $seen_canonical = AC_CANONICAL_BUILD; - } - } - elsif ($macro eq 'AC_CANONICAL_HOST') - { - if ($seen_canonical <= AC_CANONICAL_HOST) - { - $seen_canonical = AC_CANONICAL_HOST; - } - } - elsif ($macro eq 'AC_CANONICAL_TARGET') - { - $seen_canonical = AC_CANONICAL_TARGET; - } - elsif ($macro eq 'AC_CONFIG_AUX_DIR') - { - if ($seen_init_automake) - { - error ($where, "AC_CONFIG_AUX_DIR must be called before " - . "AM_INIT_AUTOMAKE ...", partial => 1); - error ($seen_init_automake, "... AM_INIT_AUTOMAKE called here"); - } - $config_aux_dir = $args[1]; - $config_aux_dir_set_in_configure_ac = 1; - check_directory ($config_aux_dir, $where); - } - elsif ($macro eq 'AC_CONFIG_FILES') - { - # Look at potential Makefile.am's. - scan_autoconf_config_files ($where, $args[1]); - } - elsif ($macro eq 'AC_CONFIG_HEADERS') - { - foreach my $spec (split (' ', $args[1])) - { - my ($dest, @src) = split (':', $spec); - $ac_config_files_location{$dest} = $where; - push @config_headers, $spec; - } - } - elsif ($macro eq 'AC_CONFIG_LIBOBJ_DIR') - { - $config_libobj_dir = $args[1]; - check_directory ($config_libobj_dir, $where); - } - elsif ($macro eq 'AC_CONFIG_LINKS') - { - foreach my $spec (split (' ', $args[1])) - { - my ($dest, $src) = split (':', $spec); - $ac_config_files_location{$dest} = $where; - push @config_links, $spec; - } - } - elsif ($macro eq 'AC_FC_SRCEXT') - { - my $suffix = $args[1]; - $sourceflags{'.' . $suffix} = '$(FCFLAGS_' . $suffix . ')' - if ($suffix eq 'f90' || $suffix eq 'f95' || $suffix eq 'f03' || $suffix eq 'f08'); - } - elsif ($macro eq 'AC_INIT') - { - if (defined $args[2]) - { - $package_version = $args[2]; - $package_version_location = $where; - } - } - elsif ($macro eq 'AC_LIBSOURCE') - { - $libsources{$args[1]} = $here; - } - elsif ($macro eq 'AC_REQUIRE_AUX_FILE') - { - # Only remember the first time a file is required. - $required_aux_file{$args[1]} = $where - unless exists $required_aux_file{$args[1]}; - } - elsif ($macro eq 'AC_SUBST_TRACE') - { - # Just check for alphanumeric in AC_SUBST_TRACE. If you do - # AC_SUBST(5), then too bad. - $configure_vars{$args[1]} = $where - if $args[1] =~ /^\w+$/; - } - elsif ($macro eq 'AM_AUTOMAKE_VERSION') - { - error ($where, - "version mismatch. This is Automake $VERSION,\n" . - "but the definition used by this AM_INIT_AUTOMAKE\n" . - "comes from Automake $args[1]. You should recreate\n" . - "aclocal.m4 with aclocal and run automake again.\n", - # $? = 63 is used to indicate version mismatch to missing. - exit_code => 63) - if $VERSION ne $args[1]; - - $seen_automake_version = 1; - } - elsif ($macro eq 'AM_CONDITIONAL') - { - $configure_cond{$args[1]} = $where; - } - elsif ($macro eq 'AM_EXTRA_RECURSIVE_TARGETS') - { - # Empty leading/trailing fields might be produced by split, - # hence the grep is really needed. - push @extra_recursive_targets, - grep (/./, (split /\s+/, $args[1])); - } - elsif ($macro eq 'AM_GNU_GETTEXT') - { - $seen_gettext = $where; - $ac_gettext_location = $where; - $seen_gettext_external = grep ($_ eq 'external', @args); - } - elsif ($macro eq 'AM_GNU_GETTEXT_INTL_SUBDIR') - { - $seen_gettext_intl = $where; - } - elsif ($macro eq 'AM_INIT_AUTOMAKE') - { - $seen_init_automake = $where; - if (defined $args[2]) - { - msg 'obsolete', $where, <<'EOF'; -AM_INIT_AUTOMAKE: two- and three-arguments forms are deprecated. For more info, see: -https://www.gnu.org/software/automake/manual/automake.html#Modernize-AM_005fINIT_005fAUTOMAKE-invocation -EOF - $package_version = $args[2]; - $package_version_location = $where; - } - elsif (defined $args[1]) - { - my @opts = split (' ', $args[1]); - @opts = map { { option => $_, where => $where } } @opts; - exit $exit_code unless process_global_option_list (@opts); - } - } - elsif ($macro eq 'AM_MAINTAINER_MODE') - { - $seen_maint_mode = $where; - } - elsif ($macro eq 'AM_PROG_AR') - { - $seen_ar = $where; - } - elsif ($macro eq '_AM_COND_IF') - { - cond_stack_if ('', $args[1], $where); - error ($where, "missing m4 quoting, macro depth $depth") - if ($depth != 1); - } - elsif ($macro eq '_AM_COND_ELSE') - { - cond_stack_else ('!', $args[1], $where); - error ($where, "missing m4 quoting, macro depth $depth") - if ($depth != 1); - } - elsif ($macro eq '_AM_COND_ENDIF') - { - cond_stack_endif (undef, undef, $where); - error ($where, "missing m4 quoting, macro depth $depth") - if ($depth != 1); - } - elsif ($macro eq '_AM_SUBST_NOTMAKE') - { - $ignored_configure_vars{$args[1]} = $where; - } - elsif ($macro eq 'm4_include' - || $macro eq 'm4_sinclude' - || $macro eq 'sinclude') - { - # Skip missing 'sinclude'd files. - next if $macro ne 'm4_include' && ! -f $args[1]; - - # Some modified versions of Autoconf don't use - # frozen files. Consequently it's possible that we see all - # m4_include's performed during Autoconf's startup. - # Obviously we don't want to distribute Autoconf's files - # so we skip absolute filenames here. - push @configure_deps, '$(top_srcdir)/' . $args[1] - unless $here =~ m,^(?:\w:)?[\\/],; - # Keep track of the greatest timestamp. - if (-e $args[1]) - { - my $mtime = mtime $args[1]; - $configure_deps_greatest_timestamp = $mtime - if $mtime > $configure_deps_greatest_timestamp; - } - } - elsif ($macro eq 'LT_SUPPORTED_TAG') - { - $libtool_tags{$args[1]} = 1; - $libtool_new_api = 1; - } - elsif ($macro eq '_LT_AC_TAGCONFIG') - { - # _LT_AC_TAGCONFIG is an old macro present in Libtool 1.5. - # We use it to detect whether tags are supported. Our - # preferred interface is LT_SUPPORTED_TAG, but it was - # introduced in Libtool 1.6. - if (0 == keys %libtool_tags) - { - # Hardcode the tags supported by Libtool 1.5. - %libtool_tags = (CC => 1, CXX => 1, GCJ => 1, F77 => 1); - } - } - } - - error ($where, "condition stack not properly closed") - if (@cond_stack); - - $tracefh->close; -} - - -# Scan 'configure.ac' (and possibly 'aclocal.m4') for interesting things. -# We must scan aclocal.m4 because there might be AC_SUBSTs and such there. -sub scan_autoconf_files () -{ - # Reinitialize libsources here. This isn't really necessary, - # since we currently assume there is only one configure.ac. But - # that won't always be the case. - %libsources = (); - - # Keep track of the youngest configure dependency. - $configure_deps_greatest_timestamp = mtime $configure_ac; - if (-e 'aclocal.m4') - { - my $mtime = mtime 'aclocal.m4'; - $configure_deps_greatest_timestamp = $mtime - if $mtime > $configure_deps_greatest_timestamp; - } - - scan_autoconf_traces ($configure_ac); - - @configure_input_files = sort keys %make_list; - # Set input and output files if not specified by user. - if (! @input_files) - { - @input_files = @configure_input_files; - %output_files = %make_list; - } - - - if (! $seen_init_automake) - { - err_ac ("no proper invocation of AM_INIT_AUTOMAKE was found.\nYou " - . "should verify that $configure_ac invokes AM_INIT_AUTOMAKE," - . "\nthat aclocal.m4 is present in the top-level directory,\n" - . "and that aclocal.m4 was recently regenerated " - . "(using aclocal)"); - } - else - { - if (! $seen_automake_version) - { - if (-f 'aclocal.m4') - { - error ($seen_init_automake, - "your implementation of AM_INIT_AUTOMAKE comes from " . - "an\nold Automake version. You should recreate " . - "aclocal.m4\nwith aclocal and run automake again", - # $? = 63 is used to indicate version mismatch to missing. - exit_code => 63); - } - else - { - error ($seen_init_automake, - "no proper implementation of AM_INIT_AUTOMAKE was " . - "found,\nprobably because aclocal.m4 is missing.\n" . - "You should run aclocal to create this file, then\n" . - "run automake again"); - } - } - } - - locate_aux_dir (); - - # Look for some files we need. Always check for these. This - # check must be done for every run, even those where we are only - # looking at a subdir Makefile. We must set relative_dir for - # push_required_file to work. - # Sort the files for stable verbose output. - $relative_dir = '.'; - foreach my $file (sort keys %required_aux_file) - { - require_conf_file ($required_aux_file{$file}->get, FOREIGN, $file) - } - err_am "'install.sh' is an anachronism; use 'install-sh' instead" - if -f $config_aux_dir . '/install.sh'; - - # Preserve dist_common for later. - @configure_dist_common = @dist_common; -} - -################################################################ - -# Do any extra checking for GNU standards. -sub check_gnu_standards () -{ - if ($relative_dir eq '.') - { - # In top level (or only) directory. - require_file ("$am_file.am", GNU, - qw/INSTALL NEWS README AUTHORS ChangeLog/); - - # Accept one of these three licenses; default to COPYING. - # Make sure we do not overwrite an existing license. - my $license; - foreach (qw /COPYING COPYING.LIB COPYING.LESSER/) - { - if (-f $_) - { - $license = $_; - last; - } - } - require_file ("$am_file.am", GNU, 'COPYING') - unless $license; - } - - for my $opt ('no-installman', 'no-installinfo') - { - msg ('error-gnu', option $opt, - "option '$opt' disallowed by GNU standards") - if option $opt; - } -} - -# Do any extra checking for GNITS standards. -sub check_gnits_standards () -{ - if ($relative_dir eq '.') - { - # In top level (or only) directory. - require_file ("$am_file.am", GNITS, 'THANKS'); - } -} - -################################################################ -# -# Functions to handle files of each language. - -# Much of the actual processing is handled in -# handle_single_transform. These functions exist so that -# auxiliary information can be recorded for a later cleanup pass. -# Note that the calls to these functions are computed, so don't bother -# searching for their precise names in the source. - -# Header files are simply ignored. -sub lang_header_ignore { 1; } - -# Vala '.vapi' are a kind of header files as well, and should -# not be processed into compilation rules. -sub lang_vala_ignore -{ - my ($directory, $base, $ext) = @_; - return ($ext =~ m/\.vapi$/ ? 1 : 0); -} - -# Rewrite a single Vala source file. -sub lang_vala_rewrite -{ - my ($directory, $base, $ext) = @_; - $ext =~ s/vala$/c/; - return $ext; -} - -# Rewrite a single yacc/yacc++ file. -sub lang_yacc_rewrite -{ - my ($directory, $base, $ext) = @_; - $ext =~ tr/y/c/; - return $ext; -} -sub lang_yaccxx_rewrite { lang_yacc_rewrite (@_); }; - -# Rewrite a single lex/lex++ file. -sub lang_lex_rewrite -{ - my ($directory, $base, $ext) = @_; - $ext =~ tr/l/c/; - return $ext; -} -sub lang_lexxx_rewrite { lang_lex_rewrite (@_); }; - -# The lang_X_finish functions are called after all source file -# processing is done. Each should handle defining rules for the -# language, etc. A finish function is only called if a source file of -# the appropriate type has been seen. - -sub lang_vala_finish_target -{ - my ($self, $name) = @_; - - my $derived = canonicalize ($name); - my $var = var "${derived}_SOURCES"; - return unless $var; - - my @vala_sources = grep { /\.(vala|vapi)$/ } ($var->value_as_list_recursive); - - # For automake bug#11229. - return unless @vala_sources; - - foreach my $vala_file (@vala_sources) - { - my $c_file = $vala_file; - if ($c_file =~ s/(.*)\.vala$/$1.c/) - { - $c_file = "\$(srcdir)/$c_file"; - $output_rules .= "$c_file: \$(srcdir)/${derived}_vala.stamp\n" - . "\t\@if test -f \$@; then :; else rm -f \$(srcdir)/${derived}_vala.stamp; fi\n" - . "\t\@if test -f \$@; then :; else \\\n" - . "\t \$(MAKE) \$(AM_MAKEFLAGS) \$(srcdir)/${derived}_vala.stamp; \\\n" - . "\tfi\n"; - $clean_files{$c_file} = MAINTAINER_CLEAN; - } - } - - # Add rebuild rules for generated header and vapi files - my $flags = var ($derived . '_VALAFLAGS'); - if ($flags) - { - my $lastflag = ''; - foreach my $flag ($flags->value_as_list_recursive) - { - if (grep (/$lastflag/, ('-H', '-h', '--header', '--internal-header', - '--vapi', '--internal-vapi', '--gir'))) - { - my $headerfile = "\$(srcdir)/$flag"; - $output_rules .= "$headerfile: \$(srcdir)/${derived}_vala.stamp\n" - . "\t\@if test -f \$@; then :; else rm -f \$(srcdir)/${derived}_vala.stamp; fi\n" - . "\t\@if test -f \$@; then :; else \\\n" - . "\t \$(MAKE) \$(AM_MAKEFLAGS) \$(srcdir)/${derived}_vala.stamp; \\\n" - . "\tfi\n"; - - # valac is not used when building from dist tarballs - # distribute the generated files - push_dist_common ($headerfile); - $clean_files{$headerfile} = MAINTAINER_CLEAN; - } - $lastflag = $flag; - } - } - - my $compile = $self->compile; - - # Rewrite each occurrence of 'AM_VALAFLAGS' in the compile - # rule into '${derived}_VALAFLAGS' if it exists. - my $val = "${derived}_VALAFLAGS"; - $compile =~ s/\(AM_VALAFLAGS\)/\($val\)/ - if set_seen ($val); - - # VALAFLAGS is a user variable (per GNU Standards), - # it should not be overridden in the Makefile... - check_user_variables 'VALAFLAGS'; - - my $dirname = dirname ($name); - - # Only generate C code, do not run C compiler - $compile .= " -C"; - - my $verbose = verbose_flag ('VALAC'); - my $silent = silent_flag (); - my $stampfile = "\$(srcdir)/${derived}_vala.stamp"; - - $output_rules .= - "\$(srcdir)/${derived}_vala.stamp: @vala_sources\n". -# Since the C files generated from the vala sources depend on the -# ${derived}_vala.stamp file, we must ensure its timestamp is older than -# those of the C files generated by the valac invocation below (this is -# especially important on systems with sub-second timestamp resolution). -# Thus we need to create the stamp file *before* invoking valac, and to -# move it to its final location only after valac has been invoked. - "\t${silent}rm -f \$\@ && echo stamp > \$\@-t\n". - "\t${verbose}\$(am__cd) \$(srcdir) && $compile @vala_sources\n". - "\t${silent}mv -f \$\@-t \$\@\n"; - - push_dist_common ($stampfile); - - $clean_files{$stampfile} = MAINTAINER_CLEAN; -} - -# Add output rules to invoke valac and create stamp file as a witness -# to handle multiple outputs. This function is called after all source -# file processing is done. -sub lang_vala_finish () -{ - my ($self) = @_; - - foreach my $prog (keys %known_programs) - { - lang_vala_finish_target ($self, $prog); - } - - while (my ($name) = each %known_libraries) - { - lang_vala_finish_target ($self, $name); - } -} - -# The built .c files should be cleaned only on maintainer-clean -# as the .c files are distributed. This function is called for each -# .vala source file. -sub lang_vala_target_hook -{ - my ($self, $aggregate, $output, $input, %transform) = @_; - - $clean_files{$output} = MAINTAINER_CLEAN; -} - -# This is a yacc helper which is called whenever we have decided to -# compile a yacc file. -sub lang_yacc_target_hook -{ - my ($self, $aggregate, $output, $input, %transform) = @_; - - # If some relevant *YFLAGS variable contains the '-d' flag, we'll - # have to to generate special code. - my $yflags_contains_minus_d = 0; - - foreach my $pfx ("", "${aggregate}_") - { - my $yflagsvar = var ("${pfx}YFLAGS"); - next unless $yflagsvar; - # We cannot work reliably with conditionally-defined YFLAGS. - if ($yflagsvar->has_conditional_contents) - { - msg_var ('unsupported', $yflagsvar, - "'${pfx}YFLAGS' cannot have conditional contents"); - } - else - { - $yflags_contains_minus_d = 1 - if grep (/^-d$/, $yflagsvar->value_as_list_recursive); - } - } - - if ($yflags_contains_minus_d) - { - # Found a '-d' that applies to the compilation of this file. - # Add a dependency for the generated header file, and arrange - # for that file to be included in the distribution. - - # The extension of the output file (e.g., '.c' or '.cxx'). - # We'll need it to compute the name of the generated header file. - (my $output_ext = basename ($output)) =~ s/.*(\.[^.]+)$/$1/; - - # We know that a yacc input should be turned into either a C or - # C++ output file. We depend on this fact (here and in yacc.am), - # so check that it really holds. - my $lang = $languages{$extension_map{$output_ext}}; - prog_error "invalid output name '$output' for yacc file '$input'" - if (!$lang || ($lang->name ne 'c' && $lang->name ne 'cxx')); - - (my $header_ext = $output_ext) =~ s/c/h/g; - # Quote $output_ext in the regexp, so that dots in it are taken - # as literal dots, not as metacharacters. - (my $header = $output) =~ s/\Q$output_ext\E$/$header_ext/; - - foreach my $cond (Automake::Rule::define (${header}, 'internal', - RULE_AUTOMAKE, TRUE, - INTERNAL)) - { - my $condstr = $cond->subst_string; - $output_rules .= - "$condstr${header}: $output\n" - # Recover from removal of $header - . "$condstr\t\@if test ! -f \$@; then rm -f $output; else :; fi\n" - . "$condstr\t\@if test ! -f \$@; then \$(MAKE) \$(AM_MAKEFLAGS) $output; else :; fi\n"; - } - # Distribute the generated file, unless its .y source was - # listed in a nodist_ variable. (handle_source_transform() - # will set DIST_SOURCE.) - push_dist_common ($header) - if $transform{'DIST_SOURCE'}; - - # The GNU rules say that yacc/lex output files should be removed - # by maintainer-clean. However, if the files are not distributed, - # then we want to remove them with "make clean"; otherwise, - # "make distcheck" will fail. - $clean_files{$header} = $transform{'DIST_SOURCE'} ? MAINTAINER_CLEAN : CLEAN; - } - # See the comment above for $HEADER. - $clean_files{$output} = $transform{'DIST_SOURCE'} ? MAINTAINER_CLEAN : CLEAN; -} - -# This is a lex helper which is called whenever we have decided to -# compile a lex file. -sub lang_lex_target_hook -{ - my ($self, $aggregate, $output, $input, %transform) = @_; - # The GNU rules say that yacc/lex output files should be removed - # by maintainer-clean. However, if the files are not distributed, - # then we want to remove them with "make clean"; otherwise, - # "make distcheck" will fail. - $clean_files{$output} = $transform{'DIST_SOURCE'} ? MAINTAINER_CLEAN : CLEAN; -} - -# This is a helper for both lex and yacc. -sub yacc_lex_finish_helper () -{ - return if defined $language_scratch{'lex-yacc-done'}; - $language_scratch{'lex-yacc-done'} = 1; - - # FIXME: for now, no line number. - require_conf_file ($configure_ac, FOREIGN, 'ylwrap'); - define_variable ('YLWRAP', "$am_config_aux_dir/ylwrap", INTERNAL); -} - -sub lang_yacc_finish () -{ - return if defined $language_scratch{'yacc-done'}; - $language_scratch{'yacc-done'} = 1; - - reject_var 'YACCFLAGS', "'YACCFLAGS' obsolete; use 'YFLAGS' instead"; - - yacc_lex_finish_helper; -} - - -sub lang_lex_finish () -{ - return if defined $language_scratch{'lex-done'}; - $language_scratch{'lex-done'} = 1; - - yacc_lex_finish_helper; -} - - -# Given a hash table of linker names, pick the name that has the most -# precedence. This is lame, but something has to have global -# knowledge in order to eliminate the conflict. Add more linkers as -# required. -sub resolve_linker -{ - my (%linkers) = @_; - - foreach my $l (qw(GCJLINK OBJCXXLINK CXXLINK F77LINK FCLINK OBJCLINK UPCLINK)) - { - return $l if defined $linkers{$l}; - } - return 'LINK'; -} - -# Called to indicate that an extension was used. -sub saw_extension -{ - my ($ext) = @_; - $extension_seen{$ext} = 1; -} - -# register_language (%ATTRIBUTE) -# ------------------------------ -# Register a single language. -# Each %ATTRIBUTE is of the form ATTRIBUTE => VALUE. -sub register_language -{ - my (%option) = @_; - - # Set the defaults. - $option{'autodep'} = 'no' - unless defined $option{'autodep'}; - $option{'linker'} = '' - unless defined $option{'linker'}; - $option{'flags'} = [] - unless defined $option{'flags'}; - $option{'output_extensions'} = sub { return ( '.$(OBJEXT)', '.lo' ) } - unless defined $option{'output_extensions'}; - $option{'nodist_specific'} = 0 - unless defined $option{'nodist_specific'}; - - my $lang = new Automake::Language (%option); - - # Fill indexes. - $extension_map{$_} = $lang->name foreach @{$lang->extensions}; - $languages{$lang->name} = $lang; - my $link = $lang->linker; - if ($link) - { - if (exists $link_languages{$link}) - { - prog_error ("'$link' has different definitions in " - . $lang->name . " and " . $link_languages{$link}->name) - if $lang->link ne $link_languages{$link}->link; - } - else - { - $link_languages{$link} = $lang; - } - } - - # Update the pattern of known extensions. - accept_extensions (@{$lang->extensions}); - - # Update the suffix rules map. - foreach my $suffix (@{$lang->extensions}) - { - foreach my $dest ($lang->output_extensions->($suffix)) - { - register_suffix_rule (INTERNAL, $suffix, $dest); - } - } -} - -# derive_suffix ($EXT, $OBJ) -# -------------------------- -# This function is used to find a path from a user-specified suffix $EXT -# to $OBJ or to some other suffix we recognize internally, e.g. 'cc'. -sub derive_suffix -{ - my ($source_ext, $obj) = @_; - - while (!$extension_map{$source_ext} && $source_ext ne $obj) - { - my $new_source_ext = next_in_suffix_chain ($source_ext, $obj); - last if not defined $new_source_ext; - $source_ext = $new_source_ext; - } - - return $source_ext; -} - - -# Pretty-print something and append to '$output_rules'. -sub pretty_print_rule -{ - $output_rules .= makefile_wrap (shift, shift, @_); -} - - -################################################################ - - -## -------------------------------- ## -## Handling the conditional stack. ## -## -------------------------------- ## - - -# $STRING -# make_conditional_string ($NEGATE, $COND) -# ---------------------------------------- -sub make_conditional_string -{ - my ($negate, $cond) = @_; - $cond = "${cond}_TRUE" - unless $cond =~ /^TRUE|FALSE$/; - $cond = Automake::Condition::conditional_negate ($cond) - if $negate; - return $cond; -} - - -my %_am_macro_for_cond = - ( - AMDEP => "one of the compiler tests\n" - . " AC_PROG_CC, AC_PROG_CXX, AC_PROG_OBJC, AC_PROG_OBJCXX,\n" - . " AM_PROG_AS, AM_PROG_GCJ, AM_PROG_UPC", - am__fastdepCC => 'AC_PROG_CC', - am__fastdepCCAS => 'AM_PROG_AS', - am__fastdepCXX => 'AC_PROG_CXX', - am__fastdepGCJ => 'AM_PROG_GCJ', - am__fastdepOBJC => 'AC_PROG_OBJC', - am__fastdepOBJCXX => 'AC_PROG_OBJCXX', - am__fastdepUPC => 'AM_PROG_UPC' - ); - -# $COND -# cond_stack_if ($NEGATE, $COND, $WHERE) -# -------------------------------------- -sub cond_stack_if -{ - my ($negate, $cond, $where) = @_; - - if (! $configure_cond{$cond} && $cond !~ /^TRUE|FALSE$/) - { - my $text = "$cond does not appear in AM_CONDITIONAL"; - my $scope = US_LOCAL; - if (exists $_am_macro_for_cond{$cond}) - { - my $mac = $_am_macro_for_cond{$cond}; - $text .= "\n The usual way to define '$cond' is to add "; - $text .= ($mac =~ / /) ? $mac : "'$mac'"; - $text .= "\n to '$configure_ac' and run 'aclocal' and 'autoconf' again"; - # These warnings appear in Automake files (depend2.am), - # so there is no need to display them more than once: - $scope = US_GLOBAL; - } - error $where, $text, uniq_scope => $scope; - } - - push (@cond_stack, make_conditional_string ($negate, $cond)); - - return new Automake::Condition (@cond_stack); -} - - -# $COND -# cond_stack_else ($NEGATE, $COND, $WHERE) -# ---------------------------------------- -sub cond_stack_else -{ - my ($negate, $cond, $where) = @_; - - if (! @cond_stack) - { - error $where, "else without if"; - return FALSE; - } - - $cond_stack[$#cond_stack] = - Automake::Condition::conditional_negate ($cond_stack[$#cond_stack]); - - # If $COND is given, check against it. - if (defined $cond) - { - $cond = make_conditional_string ($negate, $cond); - - error ($where, "else reminder ($negate$cond) incompatible with " - . "current conditional: $cond_stack[$#cond_stack]") - if $cond_stack[$#cond_stack] ne $cond; - } - - return new Automake::Condition (@cond_stack); -} - - -# $COND -# cond_stack_endif ($NEGATE, $COND, $WHERE) -# ----------------------------------------- -sub cond_stack_endif -{ - my ($negate, $cond, $where) = @_; - my $old_cond; - - if (! @cond_stack) - { - error $where, "endif without if"; - return TRUE; - } - - # If $COND is given, check against it. - if (defined $cond) - { - $cond = make_conditional_string ($negate, $cond); - - error ($where, "endif reminder ($negate$cond) incompatible with " - . "current conditional: $cond_stack[$#cond_stack]") - if $cond_stack[$#cond_stack] ne $cond; - } - - pop @cond_stack; - - return new Automake::Condition (@cond_stack); -} - - - - - -## ------------------------ ## -## Handling the variables. ## -## ------------------------ ## - - -# define_pretty_variable ($VAR, $COND, $WHERE, @VALUE) -# ---------------------------------------------------- -# Like define_variable, but the value is a list, and the variable may -# be defined conditionally. The second argument is the condition -# under which the value should be defined; this should be the empty -# string to define the variable unconditionally. The third argument -# is a list holding the values to use for the variable. The value is -# pretty printed in the output file. -sub define_pretty_variable -{ - my ($var, $cond, $where, @value) = @_; - - if (! vardef ($var, $cond)) - { - Automake::Variable::define ($var, VAR_AUTOMAKE, '', $cond, "@value", - '', $where, VAR_PRETTY); - rvar ($var)->rdef ($cond)->set_seen; - } -} - - -# define_variable ($VAR, $VALUE, $WHERE) -# -------------------------------------- -# Define a new Automake Makefile variable VAR to VALUE, but only if -# not already defined. -sub define_variable -{ - my ($var, $value, $where) = @_; - define_pretty_variable ($var, TRUE, $where, $value); -} - - -# define_files_variable ($VAR, \@BASENAME, $EXTENSION, $WHERE) -# ------------------------------------------------------------ -# Define the $VAR which content is the list of file names composed of -# a @BASENAME and the $EXTENSION. -sub define_files_variable ($\@$$) -{ - my ($var, $basename, $extension, $where) = @_; - define_variable ($var, - join (' ', map { "$_.$extension" } @$basename), - $where); -} - - -# Like define_variable, but define a variable to be the configure -# substitution by the same name. -sub define_configure_variable -{ - my ($var) = @_; - # Some variables we do not want to output. For instance it - # would be a bad idea to output `U = @U@` when `@U@` can be - # substituted as `\`. - my $pretty = exists $ignored_configure_vars{$var} ? VAR_SILENT : VAR_ASIS; - Automake::Variable::define ($var, VAR_CONFIGURE, '', TRUE, subst ($var), - '', $configure_vars{$var}, $pretty); -} - - -# define_compiler_variable ($LANG) -# -------------------------------- -# Define a compiler variable. We also handle defining the 'LT' -# version of the command when using libtool. -sub define_compiler_variable -{ - my ($lang) = @_; - - my ($var, $value) = ($lang->compiler, $lang->compile); - my $libtool_tag = ''; - $libtool_tag = '--tag=' . $lang->libtool_tag . ' ' - if $lang->libtool_tag && exists $libtool_tags{$lang->libtool_tag}; - define_variable ($var, $value, INTERNAL); - if (var ('LIBTOOL')) - { - my $verbose = define_verbose_libtool (); - define_variable ("LT$var", - "\$(LIBTOOL) $verbose $libtool_tag\$(AM_LIBTOOLFLAGS)" - . " \$(LIBTOOLFLAGS) --mode=compile $value", - INTERNAL); - } - define_verbose_tagvar ($lang->ccer || 'GEN'); -} - - -sub define_linker_variable -{ - my ($lang) = @_; - - my $libtool_tag = ''; - $libtool_tag = '--tag=' . $lang->libtool_tag . ' ' - if $lang->libtool_tag && exists $libtool_tags{$lang->libtool_tag}; - # CCLD = $(CC). - define_variable ($lang->lder, $lang->ld, INTERNAL); - # CCLINK = $(CCLD) blah blah... - my $link = ''; - if (var ('LIBTOOL')) - { - my $verbose = define_verbose_libtool (); - $link = "\$(LIBTOOL) $verbose $libtool_tag\$(AM_LIBTOOLFLAGS) " - . "\$(LIBTOOLFLAGS) --mode=link "; - } - define_variable ($lang->linker, $link . $lang->link, INTERNAL); - define_variable ($lang->compiler, $lang, INTERNAL); - define_verbose_tagvar ($lang->lder || 'GEN'); -} - -sub define_per_target_linker_variable -{ - my ($linker, $target) = @_; - - # If the user wrote a custom link command, we don't define ours. - return "${target}_LINK" - if set_seen "${target}_LINK"; - - my $xlink = $linker ? $linker : 'LINK'; - - my $lang = $link_languages{$xlink}; - prog_error "Unknown language for linker variable '$xlink'" - unless $lang; - - my $link_command = $lang->link; - if (var 'LIBTOOL') - { - my $libtool_tag = ''; - $libtool_tag = '--tag=' . $lang->libtool_tag . ' ' - if $lang->libtool_tag && exists $libtool_tags{$lang->libtool_tag}; - - my $verbose = define_verbose_libtool (); - $link_command = - "\$(LIBTOOL) $verbose $libtool_tag\$(AM_LIBTOOLFLAGS) \$(LIBTOOLFLAGS) " - . "--mode=link " . $link_command; - } - - # Rewrite each occurrence of 'AM_$flag' in the link - # command into '${derived}_$flag' if it exists. - my $orig_command = $link_command; - my @flags = (@{$lang->flags}, 'LDFLAGS'); - push @flags, 'LIBTOOLFLAGS' if var 'LIBTOOL'; - for my $flag (@flags) - { - my $val = "${target}_$flag"; - $link_command =~ s/\(AM_$flag\)/\($val\)/ - if set_seen ($val); - } - - # If the computed command is the same as the generic command, use - # the command linker variable. - return ($lang->linker, $lang->lder) - if $link_command eq $orig_command; - - define_variable ("${target}_LINK", $link_command, INTERNAL); - return ("${target}_LINK", $lang->lder); -} - -################################################################ - -# check_trailing_slash ($WHERE, $LINE) -# ------------------------------------ -# Return 1 iff $LINE ends with a slash. -# Might modify $LINE. -sub check_trailing_slash ($\$) -{ - my ($where, $line) = @_; - - # Ignore '##' lines. - return 0 if $$line =~ /$IGNORE_PATTERN/o; - - # Catch and fix a common error. - msg "syntax", $where, "whitespace following trailing backslash" - if $$line =~ s/\\\s+\n$/\\\n/; - - return $$line =~ /\\$/; -} - - -# read_am_file ($AMFILE, $WHERE, $RELDIR) -# --------------------------------------- -# Read $AMFILE file name which is located in $RELDIR, and set up -# global variables resetted by '&generate_makefile'. Simultaneously -# copy lines from $AMFILE into '$output_trailer', or define variables -# as appropriate. -# -# NOTE: We put rules in the trailer section. We want user rules to -# come after our generated stuff. -sub read_am_file -{ - my ($amfile, $where, $reldir) = @_; - my $canon_reldir = &canonicalize ($reldir); - - my $am_file = new Automake::XFile ("< $amfile"); - verb "reading $amfile"; - - # Keep track of the youngest output dependency. - my $mtime = mtime $amfile; - $output_deps_greatest_timestamp = $mtime - if $mtime > $output_deps_greatest_timestamp; - - my $spacing = ''; - my $comment = ''; - my $blank = 0; - my $saw_bk = 0; - my $var_look = VAR_ASIS; - - use constant IN_VAR_DEF => 0; - use constant IN_RULE_DEF => 1; - use constant IN_COMMENT => 2; - my $prev_state = IN_RULE_DEF; - - while ($_ = $am_file->getline) - { - $where->set ("$amfile:$."); - if (/$IGNORE_PATTERN/o) - { - # Merely delete comments beginning with two hashes. - } - elsif (/$WHITE_PATTERN/o) - { - error $where, "blank line following trailing backslash" - if $saw_bk; - # Stick a single white line before the incoming macro or rule. - $spacing = "\n"; - $blank = 1; - # Flush all comments seen so far. - if ($comment ne '') - { - $output_vars .= $comment; - $comment = ''; - } - } - elsif (/$COMMENT_PATTERN/o) - { - # Stick comments before the incoming macro or rule. Make - # sure a blank line precedes the first block of comments. - $spacing = "\n" unless $blank; - $blank = 1; - $comment .= $spacing . $_; - $spacing = ''; - $prev_state = IN_COMMENT; - } - else - { - last; - } - $saw_bk = check_trailing_slash ($where, $_); - } - - # We save the conditional stack on entry, and then check to make - # sure it is the same on exit. This lets us conditionally include - # other files. - my @saved_cond_stack = @cond_stack; - my $cond = new Automake::Condition (@cond_stack); - - my $last_var_name = ''; - my $last_var_type = ''; - my $last_var_value = ''; - my $last_where; - # FIXME: shouldn't use $_ in this loop; it is too big. - while ($_) - { - $where->set ("$amfile:$."); - - # Make sure the line is \n-terminated. - chomp; - $_ .= "\n"; - - # Don't look at MAINTAINER_MODE_TRUE here. That shouldn't be - # used by users. @MAINT@ is an anachronism now. - $_ =~ s/\@MAINT\@//g - unless $seen_maint_mode; - - my $new_saw_bk = check_trailing_slash ($where, $_); - - if ($reldir eq '.') - { - # If present, eat the following '_' or '/', converting - # "%reldir%/foo" and "%canon_reldir%_foo" into plain "foo" - # when $reldir is '.'. - $_ =~ s,%(D|reldir)%/,,g; - $_ =~ s,%(C|canon_reldir)%_,,g; - } - $_ =~ s/%(D|reldir)%/${reldir}/g; - $_ =~ s/%(C|canon_reldir)%/${canon_reldir}/g; - - if (/$IGNORE_PATTERN/o) - { - # Merely delete comments beginning with two hashes. - - # Keep any backslash from the previous line. - $new_saw_bk = $saw_bk; - } - elsif (/$WHITE_PATTERN/o) - { - # Stick a single white line before the incoming macro or rule. - $spacing = "\n"; - error $where, "blank line following trailing backslash" - if $saw_bk; - } - elsif (/$COMMENT_PATTERN/o) - { - error $where, "comment following trailing backslash" - if $saw_bk && $prev_state != IN_COMMENT; - - # Stick comments before the incoming macro or rule. - $comment .= $spacing . $_; - $spacing = ''; - $prev_state = IN_COMMENT; - } - elsif ($saw_bk) - { - if ($prev_state == IN_RULE_DEF) - { - my $cond = new Automake::Condition @cond_stack; - $output_trailer .= $cond->subst_string; - $output_trailer .= $_; - } - elsif ($prev_state == IN_COMMENT) - { - # If the line doesn't start with a '#', add it. - # We do this because a continued comment like - # # A = foo \ - # bar \ - # baz - # is not portable. BSD make doesn't honor - # escaped newlines in comments. - s/^#?/#/; - $comment .= $spacing . $_; - } - else # $prev_state == IN_VAR_DEF - { - $last_var_value .= ' ' - unless $last_var_value =~ /\s$/; - $last_var_value .= $_; - - if (!/\\$/) - { - Automake::Variable::define ($last_var_name, VAR_MAKEFILE, - $last_var_type, $cond, - $last_var_value, $comment, - $last_where, VAR_ASIS) - if $cond != FALSE; - $comment = $spacing = ''; - } - } - } - - elsif (/$IF_PATTERN/o) - { - $cond = cond_stack_if ($1, $2, $where); - } - elsif (/$ELSE_PATTERN/o) - { - $cond = cond_stack_else ($1, $2, $where); - } - elsif (/$ENDIF_PATTERN/o) - { - $cond = cond_stack_endif ($1, $2, $where); - } - - elsif (/$RULE_PATTERN/o) - { - # Found a rule. - $prev_state = IN_RULE_DEF; - - # For now we have to output all definitions of user rules - # and can't diagnose duplicates (see the comment in - # Automake::Rule::define). So we go on and ignore the return value. - Automake::Rule::define ($1, $amfile, RULE_USER, $cond, $where); - - check_variable_expansions ($_, $where); - - $output_trailer .= $comment . $spacing; - my $cond = new Automake::Condition @cond_stack; - $output_trailer .= $cond->subst_string; - $output_trailer .= $_; - $comment = $spacing = ''; - } - elsif (/$ASSIGNMENT_PATTERN/o) - { - # Found a macro definition. - $prev_state = IN_VAR_DEF; - $last_var_name = $1; - $last_var_type = $2; - $last_var_value = $3; - $last_where = $where->clone; - if ($3 ne '' && substr ($3, -1) eq "\\") - { - # We preserve the '\' because otherwise the long lines - # that are generated will be truncated by broken - # 'sed's. - $last_var_value = $3 . "\n"; - } - # Normally we try to output variable definitions in the - # same format they were input. However, POSIX compliant - # systems are not required to support lines longer than - # 2048 bytes (most notably, some sed implementation are - # limited to 4000 bytes, and sed is used by config.status - # to rewrite Makefile.in into Makefile). Moreover nobody - # would really write such long lines by hand since it is - # hardly maintainable. So if a line is longer that 1000 - # bytes (an arbitrary limit), assume it has been - # automatically generated by some tools, and flatten the - # variable definition. Otherwise, keep the variable as it - # as been input. - $var_look = VAR_PRETTY if length ($last_var_value) >= 1000; - - if (!/\\$/) - { - Automake::Variable::define ($last_var_name, VAR_MAKEFILE, - $last_var_type, $cond, - $last_var_value, $comment, - $last_where, $var_look) - if $cond != FALSE; - $comment = $spacing = ''; - $var_look = VAR_ASIS; - } - } - elsif (/$INCLUDE_PATTERN/o) - { - my $path = $1; - - if ($path =~ s/^\$\(top_srcdir\)\///) - { - push (@include_stack, "\$\(top_srcdir\)/$path"); - # Distribute any included file. - - # Always use the $(top_srcdir) prefix in DIST_COMMON, - # otherwise OSF make will implicitly copy the included - # file in the build tree during "make distdir" to satisfy - # the dependency. - # (subdir-am-cond.sh and subdir-ac-cond.sh will fail) - push_dist_common ("\$\(top_srcdir\)/$path"); - } - else - { - $path =~ s/\$\(srcdir\)\///; - push (@include_stack, "\$\(srcdir\)/$path"); - # Always use the $(srcdir) prefix in DIST_COMMON, - # otherwise OSF make will implicitly copy the included - # file in the build tree during "make distdir" to satisfy - # the dependency. - # (subdir-am-cond.sh and subdir-ac-cond.sh will fail) - push_dist_common ("\$\(srcdir\)/$path"); - $path = $relative_dir . "/" . $path if $relative_dir ne '.'; - } - my $new_reldir = File::Spec->abs2rel ($path, $relative_dir); - $new_reldir = '.' if $new_reldir !~ s,/[^/]*$,,; - $where->push_context ("'$path' included from here"); - read_am_file ($path, $where, $new_reldir); - $where->pop_context; - } - else - { - # This isn't an error; it is probably a continued rule. - # In fact, this is what we assume. - $prev_state = IN_RULE_DEF; - check_variable_expansions ($_, $where); - $output_trailer .= $comment . $spacing; - my $cond = new Automake::Condition @cond_stack; - $output_trailer .= $cond->subst_string; - $output_trailer .= $_; - $comment = $spacing = ''; - error $where, "'#' comment at start of rule is unportable" - if $_ =~ /^\t\s*\#/; - } - - $saw_bk = $new_saw_bk; - $_ = $am_file->getline; - } - - $output_trailer .= $comment; - - error ($where, "trailing backslash on last line") - if $saw_bk; - - error ($where, (@cond_stack ? "unterminated conditionals: @cond_stack" - : "too many conditionals closed in include file")) - if "@saved_cond_stack" ne "@cond_stack"; -} - - -# A helper for read_main_am_file which initializes configure variables -# and variables from header-vars.am. -sub define_standard_variables () -{ - my $saved_output_vars = $output_vars; - my ($comments, undef, $rules) = - file_contents_internal (1, "$libdir/am/header-vars.am", - new Automake::Location); - - foreach my $var (sort keys %configure_vars) - { - define_configure_variable ($var); - } - - $output_vars .= $comments . $rules; -} - - -# read_main_am_file ($MAKEFILE_AM, $MAKEFILE_IN) -# ---------------------------------------------- -sub read_main_am_file -{ - my ($amfile, $infile) = @_; - - # This supports the strange variable tricks we are about to play. - prog_error ("variable defined before read_main_am_file\n" . variables_dump ()) - if (scalar (variables) > 0); - - # Generate copyright header for generated Makefile.in. - # We do discard the output of predefined variables, handled below. - $output_vars = ("# " . basename ($infile) . " generated by automake " - . $VERSION . " from " . basename ($amfile) . ".\n"); - $output_vars .= '# ' . subst ('configure_input') . "\n"; - $output_vars .= $gen_copyright; - - # We want to predefine as many variables as possible. This lets - # the user set them with '+=' in Makefile.am. - define_standard_variables; - - # Read user file, which might override some of our values. - read_am_file ($amfile, new Automake::Location, '.'); -} - - - -################################################################ - -# $STRING -# flatten ($ORIGINAL_STRING) -# -------------------------- -sub flatten -{ - $_ = shift; - - s/\\\n//somg; - s/\s+/ /g; - s/^ //; - s/ $//; - - return $_; -} - - -# transform_token ($TOKEN, \%PAIRS, $KEY) -# --------------------------------------- -# Return the value associated to $KEY in %PAIRS, as used on $TOKEN -# (which should be ?KEY? or any of the special %% requests).. -sub transform_token ($\%$) -{ - my ($token, $transform, $key) = @_; - my $res = $transform->{$key}; - prog_error "Unknown key '$key' in '$token'" unless defined $res; - return $res; -} - - -# transform ($TOKEN, \%PAIRS) -# --------------------------- -# If ($TOKEN, $VAL) is in %PAIRS: -# - replaces %KEY% with $VAL, -# - enables/disables ?KEY? and ?!KEY?, -# - replaces %?KEY% with TRUE or FALSE. -sub transform ($\%) -{ - my ($token, $transform) = @_; - - # %KEY%. - # Must be before the following pattern to exclude the case - # when there is neither IFTRUE nor IFFALSE. - if ($token =~ /^%([\w\-]+)%$/) - { - return transform_token ($token, %$transform, $1); - } - # %?KEY%. - elsif ($token =~ /^%\?([\w\-]+)%$/) - { - return transform_token ($token, %$transform, $1) ? 'TRUE' : 'FALSE'; - } - # ?KEY? and ?!KEY?. - elsif ($token =~ /^ \? (!?) ([\w\-]+) \? $/x) - { - my $neg = ($1 eq '!') ? 1 : 0; - my $val = transform_token ($token, %$transform, $2); - return (!!$val == $neg) ? '##%' : ''; - } - else - { - prog_error "Unknown request format: $token"; - } -} - -# $TEXT -# preprocess_file ($MAKEFILE, [%TRANSFORM]) -# ----------------------------------------- -# Load a $MAKEFILE, apply the %TRANSFORM, and return the result. -# No extra parsing or post-processing is done (i.e., recognition of -# rules declaration or of make variables definitions). -sub preprocess_file -{ - my ($file, %transform) = @_; - - # Complete %transform with global options. - # Note that %transform goes last, so it overrides global options. - %transform = ( 'MAINTAINER-MODE' - => $seen_maint_mode ? subst ('MAINTAINER_MODE_TRUE') : '', - - 'XZ' => !! option 'dist-xz', - 'LZIP' => !! option 'dist-lzip', - 'BZIP2' => !! option 'dist-bzip2', - 'GZIP' => ! option 'no-dist-gzip', - 'ZIP' => !! option 'dist-zip', - - 'INSTALL-INFO' => ! option 'no-installinfo', - 'INSTALL-MAN' => ! option 'no-installman', - 'CK-NEWS' => !! option 'check-news', - - 'SUBDIRS' => !! var ('SUBDIRS'), - 'TOPDIR_P' => $relative_dir eq '.', - - 'BUILD' => ($seen_canonical >= AC_CANONICAL_BUILD), - 'HOST' => ($seen_canonical >= AC_CANONICAL_HOST), - 'TARGET' => ($seen_canonical >= AC_CANONICAL_TARGET), - - 'LIBTOOL' => !! var ('LIBTOOL'), - 'NONLIBTOOL' => 1, - %transform); - - if (! defined ($_ = $am_file_cache{$file})) - { - verb "reading $file"; - # Swallow the whole file. - my $fc_file = new Automake::XFile "< $file"; - my $saved_dollar_slash = $/; - undef $/; - $_ = $fc_file->getline; - $/ = $saved_dollar_slash; - $fc_file->close; - # Remove ##-comments. - # Besides we don't need more than two consecutive new-lines. - s/(?:$IGNORE_PATTERN|(?<=\n\n)\n+)//gom; - # Remember the contents of the just-read file. - $am_file_cache{$file} = $_; - } - - # Substitute Automake template tokens. - s/(?: % \?? [\w\-]+ % - | \? !? [\w\-]+ \? - )/transform($&, %transform)/gex; - # transform() may have added some ##%-comments to strip. - # (we use '##%' instead of '##' so we can distinguish ##%##%##% from - # ####### and do not remove the latter.) - s/^[ \t]*(?:##%)+.*\n//gm; - - return $_; -} - - -# @PARAGRAPHS -# make_paragraphs ($MAKEFILE, [%TRANSFORM]) -# ----------------------------------------- -# Load a $MAKEFILE, apply the %TRANSFORM, and return it as a list of -# paragraphs. -sub make_paragraphs -{ - my ($file, %transform) = @_; - $transform{FIRST} = !$transformed_files{$file}; - $transformed_files{$file} = 1; - - my @lines = split /(?set ($file); - - my $result_vars = ''; - my $result_rules = ''; - my $comment = ''; - my $spacing = ''; - - # The following flags are used to track rules spanning across - # multiple paragraphs. - my $is_rule = 0; # 1 if we are processing a rule. - my $discard_rule = 0; # 1 if the current rule should not be output. - - # We save the conditional stack on entry, and then check to make - # sure it is the same on exit. This lets us conditionally include - # other files. - my @saved_cond_stack = @cond_stack; - my $cond = new Automake::Condition (@cond_stack); - - foreach (make_paragraphs ($file, %transform)) - { - # FIXME: no line number available. - $where->set ($file); - - # Sanity checks. - error $where, "blank line following trailing backslash:\n$_" - if /\\$/; - error $where, "comment following trailing backslash:\n$_" - if /\\#/; - - if (/^$/) - { - $is_rule = 0; - # Stick empty line before the incoming macro or rule. - $spacing = "\n"; - } - elsif (/$COMMENT_PATTERN/mso) - { - $is_rule = 0; - # Stick comments before the incoming macro or rule. - $comment = "$_\n"; - } - - # Handle inclusion of other files. - elsif (/$INCLUDE_PATTERN/o) - { - if ($cond != FALSE) - { - my $file = ($is_am ? "$libdir/am/" : '') . $1; - $where->push_context ("'$file' included from here"); - # N-ary '.=' fails. - my ($com, $vars, $rules) - = file_contents_internal ($is_am, $file, $where, %transform); - $where->pop_context; - $comment .= $com; - $result_vars .= $vars; - $result_rules .= $rules; - } - } - - # Handling the conditionals. - elsif (/$IF_PATTERN/o) - { - $cond = cond_stack_if ($1, $2, $file); - } - elsif (/$ELSE_PATTERN/o) - { - $cond = cond_stack_else ($1, $2, $file); - } - elsif (/$ENDIF_PATTERN/o) - { - $cond = cond_stack_endif ($1, $2, $file); - } - - # Handling rules. - elsif (/$RULE_PATTERN/mso) - { - $is_rule = 1; - $discard_rule = 0; - # Separate relationship from optional actions: the first - # `new-line tab" not preceded by backslash (continuation - # line). - my $paragraph = $_; - /^(.*?)(?:(?subst_string/gme; - $result_rules .= "$spacing$comment$condparagraph\n"; - } - if (scalar @undefined_conds == 0) - { - # Remember to discard next paragraphs - # if they belong to this rule. - # (but see also FIXME: #2 above.) - $discard_rule = 1; - } - $comment = $spacing = ''; - last; - } - } - } - - elsif (/$ASSIGNMENT_PATTERN/mso) - { - my ($var, $type, $val) = ($1, $2, $3); - error $where, "variable '$var' with trailing backslash" - if /\\$/; - - $is_rule = 0; - - Automake::Variable::define ($var, - $is_am ? VAR_AUTOMAKE : VAR_MAKEFILE, - $type, $cond, $val, $comment, $where, - VAR_ASIS) - if $cond != FALSE; - - $comment = $spacing = ''; - } - else - { - # This isn't an error; it is probably some tokens which - # configure is supposed to replace, such as '@SET-MAKE@', - # or some part of a rule cut by an if/endif. - if (! $cond->false && ! ($is_rule && $discard_rule)) - { - s/^/$cond->subst_string/gme; - $result_rules .= "$spacing$comment$_\n"; - } - $comment = $spacing = ''; - } - } - - error ($where, @cond_stack ? - "unterminated conditionals: @cond_stack" : - "too many conditionals closed in include file") - if "@saved_cond_stack" ne "@cond_stack"; - - return ($comment, $result_vars, $result_rules); -} - - -# $CONTENTS -# file_contents ($BASENAME, $WHERE, [%TRANSFORM]) -# ----------------------------------------------- -# Return contents of a file from $libdir/am, automatically skipping -# macros or rules which are already known. -sub file_contents -{ - my ($basename, $where, %transform) = @_; - my ($comments, $variables, $rules) = - file_contents_internal (1, "$libdir/am/$basename.am", $where, - %transform); - return "$comments$variables$rules"; -} - - -# @PREFIX -# am_primary_prefixes ($PRIMARY, $CAN_DIST, @PREFIXES) -# ---------------------------------------------------- -# Find all variable prefixes that are used for install directories. A -# prefix 'zar' qualifies iff: -# -# * 'zardir' is a variable. -# * 'zar_PRIMARY' is a variable. -# -# As a side effect, it looks for misspellings. It is an error to have -# a variable ending in a "reserved" suffix whose prefix is unknown, e.g. -# "bni_PROGRAMS". However, unusual prefixes are allowed if a variable -# of the same name (with "dir" appended) exists. For instance, if the -# variable "zardir" is defined, then "zar_PROGRAMS" becomes valid. -# This is to provide a little extra flexibility in those cases which -# need it. -sub am_primary_prefixes -{ - my ($primary, $can_dist, @prefixes) = @_; - - local $_; - my %valid = map { $_ => 0 } @prefixes; - $valid{'EXTRA'} = 0; - foreach my $var (variables $primary) - { - # Automake is allowed to define variables that look like primaries - # but which aren't. E.g. INSTALL_sh_DATA. - # Autoconf can also define variables like INSTALL_DATA, so - # ignore all configure variables (at least those which are not - # redefined in Makefile.am). - # FIXME: We should make sure that these variables are not - # conditionally defined (or else adjust the condition below). - my $def = $var->def (TRUE); - next if $def && $def->owner != VAR_MAKEFILE; - - my $varname = $var->name; - - if ($varname =~ /^(nobase_)?(dist_|nodist_)?(.*)_[[:alnum:]]+$/) - { - my ($base, $dist, $X) = ($1 || '', $2 || '', $3 || ''); - if ($dist ne '' && ! $can_dist) - { - err_var ($var, - "invalid variable '$varname': 'dist' is forbidden"); - } - # Standard directories must be explicitly allowed. - elsif (! defined $valid{$X} && exists $standard_prefix{$X}) - { - err_var ($var, - "'${X}dir' is not a legitimate directory " . - "for '$primary'"); - } - # A not explicitly valid directory is allowed if Xdir is defined. - elsif (! defined $valid{$X} && - $var->requires_variables ("'$varname' is used", "${X}dir")) - { - # Nothing to do. Any error message has been output - # by $var->requires_variables. - } - else - { - # Ensure all extended prefixes are actually used. - $valid{"$base$dist$X"} = 1; - } - } - else - { - prog_error "unexpected variable name: $varname"; - } - } - - # Return only those which are actually defined. - return sort grep { var ($_ . '_' . $primary) } keys %valid; -} - - -# am_install_var (-OPTION..., file, HOW, where...) -# ------------------------------------------------ -# -# Handle 'where_HOW' variable magic. Does all lookups, generates -# install code, and possibly generates code to define the primary -# variable. The first argument is the name of the .am file to munge, -# the second argument is the primary variable (e.g. HEADERS), and all -# subsequent arguments are possible installation locations. -# -# Returns list of [$location, $value] pairs, where -# $value's are the values in all where_HOW variable, and $location -# there associated location (the place here their parent variables were -# defined). -# -# FIXME: this should be rewritten to be cleaner. It should be broken -# up into multiple functions. -# -sub am_install_var -{ - my (@args) = @_; - - my $do_require = 1; - my $can_dist = 0; - my $default_dist = 0; - while (@args) - { - if ($args[0] eq '-noextra') - { - $do_require = 0; - } - elsif ($args[0] eq '-candist') - { - $can_dist = 1; - } - elsif ($args[0] eq '-defaultdist') - { - $default_dist = 1; - $can_dist = 1; - } - elsif ($args[0] !~ /^-/) - { - last; - } - shift (@args); - } - - my ($file, $primary, @prefix) = @args; - - # Now that configure substitutions are allowed in where_HOW - # variables, it is an error to actually define the primary. We - # allow 'JAVA', as it is customarily used to mean the Java - # interpreter. This is but one of several Java hacks. Similarly, - # 'PYTHON' is customarily used to mean the Python interpreter. - reject_var $primary, "'$primary' is an anachronism" - unless $primary eq 'JAVA' || $primary eq 'PYTHON'; - - # Get the prefixes which are valid and actually used. - @prefix = am_primary_prefixes ($primary, $can_dist, @prefix); - - # If a primary includes a configure substitution, then the EXTRA_ - # form is required. Otherwise we can't properly do our job. - my $require_extra; - - my @used = (); - my @result = (); - - foreach my $X (@prefix) - { - my $nodir_name = $X; - my $one_name = $X . '_' . $primary; - my $one_var = var $one_name; - - my $strip_subdir = 1; - # If subdir prefix should be preserved, do so. - if ($nodir_name =~ /^nobase_/) - { - $strip_subdir = 0; - $nodir_name =~ s/^nobase_//; - } - - # If files should be distributed, do so. - my $dist_p = 0; - if ($can_dist) - { - $dist_p = (($default_dist && $nodir_name !~ /^nodist_/) - || (! $default_dist && $nodir_name =~ /^dist_/)); - $nodir_name =~ s/^(dist|nodist)_//; - } - - - # Use the location of the currently processed variable. - # We are not processing a particular condition, so pick the first - # available. - my $tmpcond = $one_var->conditions->one_cond; - my $where = $one_var->rdef ($tmpcond)->location->clone; - - # Append actual contents of where_PRIMARY variable to - # @result, skipping @substitutions@. - foreach my $locvals ($one_var->value_as_list_recursive (location => 1)) - { - my ($loc, $value) = @$locvals; - # Skip configure substitutions. - if ($value =~ /^\@.*\@$/) - { - if ($nodir_name eq 'EXTRA') - { - error ($where, - "'$one_name' contains configure substitution, " - . "but shouldn't"); - } - # Check here to make sure variables defined in - # configure.ac do not imply that EXTRA_PRIMARY - # must be defined. - elsif (! defined $configure_vars{$one_name}) - { - $require_extra = $one_name - if $do_require; - } - } - else - { - # Strip any $(EXEEXT) suffix the user might have added, - # or this will confuse handle_source_transform() and - # check_canonical_spelling(). - # We'll add $(EXEEXT) back later anyway. - # Do it here rather than in handle_programs so the - # uniquifying at the end of this function works. - ${$locvals}[1] =~ s/\$\(EXEEXT\)$// - if $primary eq 'PROGRAMS'; - - push (@result, $locvals); - } - } - # A blatant hack: we rewrite each _PROGRAMS primary to include - # EXEEXT. - append_exeext { 1 } $one_name - if $primary eq 'PROGRAMS'; - # "EXTRA" shouldn't be used when generating clean targets, - # all, or install targets. We used to warn if EXTRA_FOO was - # defined uselessly, but this was annoying. - next - if $nodir_name eq 'EXTRA'; - - if ($nodir_name eq 'check') - { - push (@check, '$(' . $one_name . ')'); - } - else - { - push (@used, '$(' . $one_name . ')'); - } - - # Is this to be installed? - my $install_p = $nodir_name ne 'noinst' && $nodir_name ne 'check'; - - # If so, with install-exec? (or install-data?). - my $exec_p = ($nodir_name =~ /$EXEC_DIR_PATTERN/o); - - my $check_options_p = $install_p && !! option 'std-options'; - - # Use the location of the currently processed variable as context. - $where->push_context ("while processing '$one_name'"); - - # The variable containing all files to distribute. - my $distvar = "\$($one_name)"; - $distvar = shadow_unconditionally ($one_name, $where) - if ($dist_p && $one_var->has_conditional_contents); - - # Singular form of $PRIMARY. - (my $one_primary = $primary) =~ s/S$//; - $output_rules .= file_contents ($file, $where, - PRIMARY => $primary, - ONE_PRIMARY => $one_primary, - DIR => $X, - NDIR => $nodir_name, - BASE => $strip_subdir, - EXEC => $exec_p, - INSTALL => $install_p, - DIST => $dist_p, - DISTVAR => $distvar, - 'CK-OPTS' => $check_options_p); - } - - # The JAVA variable is used as the name of the Java interpreter. - # The PYTHON variable is used as the name of the Python interpreter. - if (@used && $primary ne 'JAVA' && $primary ne 'PYTHON') - { - # Define it. - define_pretty_variable ($primary, TRUE, INTERNAL, @used); - $output_vars .= "\n"; - } - - err_var ($require_extra, - "'$require_extra' contains configure substitution,\n" - . "but 'EXTRA_$primary' not defined") - if ($require_extra && ! var ('EXTRA_' . $primary)); - - # Push here because PRIMARY might be configure time determined. - push (@all, '$(' . $primary . ')') - if @used && $primary ne 'JAVA' && $primary ne 'PYTHON'; - - # Make the result unique. This lets the user use conditionals in - # a natural way, but still lets us program lazily -- we don't have - # to worry about handling a particular object more than once. - # We will keep only one location per object. - my %result = (); - for my $pair (@result) - { - my ($loc, $val) = @$pair; - $result{$val} = $loc; - } - my @l = sort keys %result; - return map { [$result{$_}->clone, $_] } @l; -} - - -################################################################ - -# Each key in this hash is the name of a directory holding a -# Makefile.in. These variables are local to 'is_make_dir'. -my %make_dirs = (); -my $make_dirs_set = 0; - -# is_make_dir ($DIRECTORY) -# ------------------------ -sub is_make_dir -{ - my ($dir) = @_; - if (! $make_dirs_set) - { - foreach my $iter (@configure_input_files) - { - $make_dirs{dirname ($iter)} = 1; - } - # We also want to notice Makefile.in's. - foreach my $iter (@other_input_files) - { - if ($iter =~ /Makefile\.in$/) - { - $make_dirs{dirname ($iter)} = 1; - } - } - $make_dirs_set = 1; - } - return defined $make_dirs{$dir}; -} - -################################################################ - -# Find the aux dir. This should match the algorithm used by -# ./configure. (See the Autoconf documentation for for -# AC_CONFIG_AUX_DIR.) -sub locate_aux_dir () -{ - if (! $config_aux_dir_set_in_configure_ac) - { - # The default auxiliary directory is the first - # of ., .., or ../.. that contains install-sh. - # Assume . if install-sh doesn't exist yet. - for my $dir (qw (. .. ../..)) - { - if (-f "$dir/install-sh") - { - $config_aux_dir = $dir; - last; - } - } - $config_aux_dir = '.' unless $config_aux_dir; - } - # Avoid unsightly '/.'s. - $am_config_aux_dir = - '$(top_srcdir)' . ($config_aux_dir eq '.' ? "" : "/$config_aux_dir"); - $am_config_aux_dir =~ s,/*$,,; -} - - -# push_required_file ($DIR, $FILE, $FULLFILE) -# ------------------------------------------- -# Push the given file onto DIST_COMMON. -sub push_required_file -{ - my ($dir, $file, $fullfile) = @_; - - # If the file to be distributed is in the same directory of the - # currently processed Makefile.am, then we want to distribute it - # from this same Makefile.am. - if ($dir eq $relative_dir) - { - push_dist_common ($file); - } - # This is needed to allow a construct in a non-top-level Makefile.am - # to require a file in the build-aux directory (see at least the test - # script 'test-driver-is-distributed.sh'). This is related to the - # automake bug#9546. Note that the use of $config_aux_dir instead - # of $am_config_aux_dir here is deliberate and necessary. - elsif ($dir eq $config_aux_dir) - { - push_dist_common ("$am_config_aux_dir/$file"); - } - # FIXME: another spacial case, for AC_LIBOBJ/AC_LIBSOURCE support. - # We probably need some refactoring of this function and its callers, - # to have a more explicit and systematic handling of all the special - # cases; but, since there are only two of them, this is low-priority - # ATM. - elsif ($config_libobj_dir && $dir eq $config_libobj_dir) - { - # Avoid unsightly '/.'s. - my $am_config_libobj_dir = - '$(top_srcdir)' . - ($config_libobj_dir eq '.' ? "" : "/$config_libobj_dir"); - $am_config_libobj_dir =~ s|/*$||; - push_dist_common ("$am_config_libobj_dir/$file"); - } - elsif ($relative_dir eq '.' && ! is_make_dir ($dir)) - { - # If we are doing the topmost directory, and the file is in a - # subdir which does not have a Makefile, then we distribute it - # here. - - # If a required file is above the source tree, it is important - # to prefix it with '$(srcdir)' so that no VPATH search is - # performed. Otherwise problems occur with Make implementations - # that rewrite and simplify rules whose dependencies are found in a - # VPATH location. Here is an example with OSF1/Tru64 Make. - # - # % cat Makefile - # VPATH = sub - # distdir: ../a - # echo ../a - # % ls - # Makefile a - # % make - # echo a - # a - # - # Dependency '../a' was found in 'sub/../a', but this make - # implementation simplified it as 'a'. (Note that the sub/ - # directory does not even exist.) - # - # This kind of VPATH rewriting seems hard to cancel. The - # distdir.am hack against VPATH rewriting works only when no - # simplification is done, i.e., for dependencies which are in - # subdirectories, not in enclosing directories. Hence, in - # the latter case we use a full path to make sure no VPATH - # search occurs. - $fullfile = '$(srcdir)/' . $fullfile - if $dir =~ m,^\.\.(?:$|/),; - - push_dist_common ($fullfile); - } - else - { - prog_error "a Makefile in relative directory $relative_dir " . - "can't add files in directory $dir to DIST_COMMON"; - } -} - - -# If a file name appears as a key in this hash, then it has already -# been checked for. This allows us not to report the same error more -# than once. -my %required_file_not_found = (); - -# required_file_check_or_copy ($WHERE, $DIRECTORY, $FILE) -# ------------------------------------------------------- -# Verify that the file must exist in $DIRECTORY, or install it. -sub required_file_check_or_copy -{ - my ($where, $dir, $file) = @_; - - my $fullfile = "$dir/$file"; - my $found_it = 0; - my $dangling_sym = 0; - - if (-l $fullfile && ! -f $fullfile) - { - $dangling_sym = 1; - } - elsif (dir_has_case_matching_file ($dir, $file)) - { - $found_it = 1; - } - - # '--force-missing' only has an effect if '--add-missing' is - # specified. - return - if $found_it && (! $add_missing || ! $force_missing); - - # If we've already looked for it, we're done. You might wonder why we - # don't do this before searching for the file. If we do that, then - # something like AC_OUTPUT([subdir/foo foo]) will fail to put 'foo.in' - # into $(DIST_COMMON). - if (! $found_it) - { - return if defined $required_file_not_found{$fullfile}; - $required_file_not_found{$fullfile} = 1; - } - if ($dangling_sym && $add_missing) - { - unlink ($fullfile); - } - - my $trailer = ''; - my $trailer2 = ''; - my $suppress = 0; - - # Only install missing files according to our desired - # strictness level. - my $message = "required file '$fullfile' not found"; - if ($add_missing) - { - if (-f "$libdir/$file") - { - $suppress = 1; - - # Install the missing file. Symlink if we - # can, copy if we must. Note: delete the file - # first, in case it is a dangling symlink. - $message = "installing '$fullfile'"; - - # The license file should not be volatile. - if ($file eq "COPYING") - { - $message .= " using GNU General Public License v3 file"; - $trailer2 = "\n Consider adding the COPYING file" - . " to the version control system" - . "\n for your code, to avoid questions" - . " about which license your project uses"; - } - - # Windows Perl will hang if we try to delete a - # file that doesn't exist. - unlink ($fullfile) if -f $fullfile; - if ($symlink_exists && ! $copy_missing) - { - if (! symlink ("$libdir/$file", $fullfile) - || ! -e $fullfile) - { - $suppress = 0; - $trailer = "; error while making link: $!"; - } - } - elsif (system ('cp', "$libdir/$file", $fullfile)) - { - $suppress = 0; - $trailer = "\n error while copying"; - } - set_dir_cache_file ($dir, $file); - } - } - else - { - $trailer = "\n 'automake --add-missing' can install '$file'" - if -f "$libdir/$file"; - } - - # If --force-missing was specified, and we have - # actually found the file, then do nothing. - return - if $found_it && $force_missing; - - # If we couldn't install the file, but it is a target in - # the Makefile, don't print anything. This allows files - # like README, AUTHORS, or THANKS to be generated. - return - if !$suppress && rule $file; - - msg ($suppress ? 'note' : 'error', $where, "$message$trailer$trailer2"); -} - - -# require_file_internal ($WHERE, $MYSTRICT, $DIRECTORY, $QUEUE, @FILES) -# --------------------------------------------------------------------- -# Verify that the file must exist in $DIRECTORY, or install it. -# $MYSTRICT is the strictness level at which this file becomes required. -# Worker threads may queue up the action to be serialized by the master, -# if $QUEUE is true -sub require_file_internal -{ - my ($where, $mystrict, $dir, $queue, @files) = @_; - - return - unless $strictness >= $mystrict; - - foreach my $file (@files) - { - push_required_file ($dir, $file, "$dir/$file"); - if ($queue) - { - queue_required_file_check_or_copy ($required_conf_file_queue, - QUEUE_CONF_FILE, $relative_dir, - $where, $mystrict, @files); - } - else - { - required_file_check_or_copy ($where, $dir, $file); - } - } -} - -# require_file ($WHERE, $MYSTRICT, @FILES) -# ---------------------------------------- -sub require_file -{ - my ($where, $mystrict, @files) = @_; - require_file_internal ($where, $mystrict, $relative_dir, 0, @files); -} - -# require_file_with_macro ($COND, $MACRO, $MYSTRICT, @FILES) -# ---------------------------------------------------------- -sub require_file_with_macro -{ - my ($cond, $macro, $mystrict, @files) = @_; - $macro = rvar ($macro) unless ref $macro; - require_file ($macro->rdef ($cond)->location, $mystrict, @files); -} - -# require_libsource_with_macro ($COND, $MACRO, $MYSTRICT, @FILES) -# --------------------------------------------------------------- -# Require an AC_LIBSOURCEd file. If AC_CONFIG_LIBOBJ_DIR was called, it -# must be in that directory. Otherwise expect it in the current directory. -sub require_libsource_with_macro -{ - my ($cond, $macro, $mystrict, @files) = @_; - $macro = rvar ($macro) unless ref $macro; - if ($config_libobj_dir) - { - require_file_internal ($macro->rdef ($cond)->location, $mystrict, - $config_libobj_dir, 0, @files); - } - else - { - require_file ($macro->rdef ($cond)->location, $mystrict, @files); - } -} - -# queue_required_file_check_or_copy ($QUEUE, $KEY, $DIR, $WHERE, -# $MYSTRICT, @FILES) -# -------------------------------------------------------------- -sub queue_required_file_check_or_copy -{ - my ($queue, $key, $dir, $where, $mystrict, @files) = @_; - my @serial_loc; - if (ref $where) - { - @serial_loc = (QUEUE_LOCATION, $where->serialize ()); - } - else - { - @serial_loc = (QUEUE_STRING, $where); - } - $queue->enqueue ($key, $dir, @serial_loc, $mystrict, 0 + @files, @files); -} - -# require_queued_file_check_or_copy ($QUEUE) -# ------------------------------------------ -sub require_queued_file_check_or_copy -{ - my ($queue) = @_; - my $where; - my $dir = $queue->dequeue (); - my $loc_key = $queue->dequeue (); - if ($loc_key eq QUEUE_LOCATION) - { - $where = Automake::Location::deserialize ($queue); - } - elsif ($loc_key eq QUEUE_STRING) - { - $where = $queue->dequeue (); - } - else - { - prog_error "unexpected key $loc_key"; - } - my $mystrict = $queue->dequeue (); - my $nfiles = $queue->dequeue (); - my @files; - push @files, $queue->dequeue () - foreach (1 .. $nfiles); - return - unless $strictness >= $mystrict; - foreach my $file (@files) - { - required_file_check_or_copy ($where, $config_aux_dir, $file); - } -} - -# require_conf_file ($WHERE, $MYSTRICT, @FILES) -# --------------------------------------------- -# Looks in configuration path, as specified by AC_CONFIG_AUX_DIR. -sub require_conf_file -{ - my ($where, $mystrict, @files) = @_; - my $queue = defined $required_conf_file_queue ? 1 : 0; - require_file_internal ($where, $mystrict, $config_aux_dir, - $queue, @files); -} - - -# require_conf_file_with_macro ($COND, $MACRO, $MYSTRICT, @FILES) -# --------------------------------------------------------------- -sub require_conf_file_with_macro -{ - my ($cond, $macro, $mystrict, @files) = @_; - require_conf_file (rvar ($macro)->rdef ($cond)->location, - $mystrict, @files); -} - -################################################################ - -# require_build_directory ($DIRECTORY) -# ------------------------------------ -# Emit rules to create $DIRECTORY if needed, and return -# the file that any target requiring this directory should be made -# dependent upon. -# We don't want to emit the rule twice, and want to reuse it -# for directories with equivalent names (e.g., 'foo/bar' and './foo//bar'). -sub require_build_directory -{ - my $directory = shift; - - return $directory_map{$directory} if exists $directory_map{$directory}; - - my $cdir = File::Spec->canonpath ($directory); - - if (exists $directory_map{$cdir}) - { - my $stamp = $directory_map{$cdir}; - $directory_map{$directory} = $stamp; - return $stamp; - } - - my $dirstamp = "$cdir/\$(am__dirstamp)"; - - $directory_map{$directory} = $dirstamp; - $directory_map{$cdir} = $dirstamp; - - # Set a variable for the dirstamp basename. - define_pretty_variable ('am__dirstamp', TRUE, INTERNAL, '.dirstamp'); - - # Directory must be removed by 'make distclean'. - $clean_files{$dirstamp} = DIST_CLEAN; - - $output_rules .= ("$dirstamp:\n" - . "\t\@\$(MKDIR_P) $directory\n" - . "\t\@: > $dirstamp\n"); - - return $dirstamp; -} - -# require_build_directory_maybe ($FILE) -# ------------------------------------- -# If $FILE lies in a subdirectory, emit a rule to create this -# directory and return the file that $FILE should be made -# dependent upon. Otherwise, just return the empty string. -sub require_build_directory_maybe -{ - my $file = shift; - my $directory = dirname ($file); - - if ($directory ne '.') - { - return require_build_directory ($directory); - } - else - { - return ''; - } -} - -################################################################ - -# Push a list of files onto '@dist_common'. -sub push_dist_common -{ - prog_error "push_dist_common run after handle_dist" - if $handle_dist_run; - push @dist_common, @_; -} - - -################################################################ - -# generate_makefile ($MAKEFILE_AM, $MAKEFILE_IN) -# ---------------------------------------------- -# Generate a Makefile.in given the name of the corresponding Makefile and -# the name of the file output by config.status. -sub generate_makefile -{ - my ($makefile_am, $makefile_in) = @_; - - # Reset all the Makefile.am related variables. - initialize_per_input; - - # AUTOMAKE_OPTIONS can contains -W flags to disable or enable - # warnings for this file. So hold any warning issued before - # we have processed AUTOMAKE_OPTIONS. - buffer_messages ('warning'); - - # $OUTPUT is encoded. If it contains a ":" then the first element - # is the real output file, and all remaining elements are input - # files. We don't scan or otherwise deal with these input files, - # other than to mark them as dependencies. See the subroutine - # 'scan_autoconf_files' for details. - my ($makefile, @inputs) = split (/:/, $output_files{$makefile_in}); - - $relative_dir = dirname ($makefile); - - read_main_am_file ($makefile_am, $makefile_in); - if (not handle_options) - { - # Process buffered warnings. - flush_messages; - # Fatal error. Just return, so we can continue with next file. - return; - } - # Process buffered warnings. - flush_messages; - - # There are a few install-related variables that you should not define. - foreach my $var ('PRE_INSTALL', 'POST_INSTALL', 'NORMAL_INSTALL') - { - my $v = var $var; - if ($v) - { - my $def = $v->def (TRUE); - prog_error "$var not defined in condition TRUE" - unless $def; - reject_var $var, "'$var' should not be defined" - if $def->owner != VAR_AUTOMAKE; - } - } - - # Catch some obsolete variables. - if (my $ovar = var ('ACLOCAL_AMFLAGS')) - { - msg_var 'obsolete', $ovar, - "'ACLOCAL_AMFLAGS' is deprecated; use 'AC_CONFIG_MACRO_DIRS'" - . " in configure.ac instead"; - } - if (my $ovar = var ('INCLUDES')) - { - msg_var 'obsolete', $ovar, - "'INCLUDES' is deprecated; you should use 'AM_CPPFLAGS'" - . " (or '*_CPPFLAGS') instead" - } - - # Must do this after reading .am file. - define_variable ('subdir', $relative_dir, INTERNAL); - - # If DIST_SUBDIRS is defined, make sure SUBDIRS is, so that - # recursive rules are enabled. - define_pretty_variable ('SUBDIRS', TRUE, INTERNAL, '') - if var 'DIST_SUBDIRS' && ! var 'SUBDIRS'; - - # Check first, because we might modify some state. - check_gnu_standards; - check_gnits_standards; - - handle_configure ($makefile_am, $makefile_in, $makefile, @inputs); - handle_gettext; - - handle_targets; - handle_libraries; - handle_ltlibraries; - handle_programs; - handle_scripts; - - handle_silent; - - # These must be run after all the sources are scanned. They use - # variables defined by handle_libraries(), handle_ltlibraries(), - # or handle_programs(). - handle_compile; - handle_languages; - handle_libtool; - - # Variables used by distdir.am and tags.am. - define_pretty_variable ('SOURCES', TRUE, INTERNAL, @sources); - if (! option 'no-dist') - { - define_pretty_variable ('DIST_SOURCES', TRUE, INTERNAL, @dist_sources); - } - - handle_texinfo; - handle_emacs_lisp; - handle_python; - handle_java; - handle_man_pages; - handle_data; - handle_headers; - handle_subdirs; - handle_user_recursion; - handle_tags; - handle_minor_options; - # Must come after handle_programs so that %known_programs is up-to-date. - handle_tests; - - # This must come after most other rules. - handle_dist; - - handle_footer; - do_check_merge_target; - handle_all ($makefile); - - # FIXME: Gross! - if (var ('lib_LTLIBRARIES') && var ('bin_PROGRAMS')) - { - $output_rules .= "install-binPROGRAMS: install-libLTLIBRARIES\n\n"; - } - if (var ('nobase_lib_LTLIBRARIES') && var ('bin_PROGRAMS')) - { - $output_rules .= "install-binPROGRAMS: install-nobase_libLTLIBRARIES\n\n"; - } - - handle_install; - handle_clean ($makefile); - handle_factored_dependencies; - - # Comes last, because all the above procedures may have - # defined or overridden variables. - $output_vars .= output_variables; - - check_typos; - - if ($exit_code != 0) - { - verb "not writing $makefile_in because of earlier errors"; - return; - } - - my $am_relative_dir = dirname ($makefile_am); - mkdir ($am_relative_dir, 0755) if ! -d $am_relative_dir; - - # We make sure that 'all:' is the first target. - my $output = - "$output_vars$output_all$output_header$output_rules$output_trailer"; - - # Decide whether we must update the output file or not. - # We have to update in the following situations. - # * $force_generation is set. - # * any of the output dependencies is younger than the output - # * the contents of the output is different (this can happen - # if the project has been populated with a file listed in - # @common_files since the last run). - # Output's dependencies are split in two sets: - # * dependencies which are also configure dependencies - # These do not change between each Makefile.am - # * other dependencies, specific to the Makefile.am being processed - # (such as the Makefile.am itself, or any Makefile fragment - # it includes). - my $timestamp = mtime $makefile_in; - if (! $force_generation - && $configure_deps_greatest_timestamp < $timestamp - && $output_deps_greatest_timestamp < $timestamp - && $output eq contents ($makefile_in)) - { - verb "$makefile_in unchanged"; - # No need to update. - return; - } - - if (-e $makefile_in) - { - unlink ($makefile_in) - or fatal "cannot remove $makefile_in: $!"; - } - - my $gm_file = new Automake::XFile "> $makefile_in"; - verb "creating $makefile_in"; - print $gm_file $output; -} - - -################################################################ - - -# Helper function for usage(). -sub print_autodist_files -{ - my @lcomm = uniq (sort @_); - - my @four; - format USAGE_FORMAT = - @<<<<<<<<<<<<<<<< @<<<<<<<<<<<<<<<< @<<<<<<<<<<<<<<<< @<<<<<<<<<<<<<<<< - $four[0], $four[1], $four[2], $four[3] -. - local $~ = "USAGE_FORMAT"; - - my $cols = 4; - my $rows = int(@lcomm / $cols); - my $rest = @lcomm % $cols; - - if ($rest) - { - $rows++; - } - else - { - $rest = $cols; - } - - for (my $y = 0; $y < $rows; $y++) - { - @four = ("", "", "", ""); - for (my $x = 0; $x < $cols; $x++) - { - last if $y + 1 == $rows && $x == $rest; - - my $idx = (($x > $rest) - ? ($rows * $rest + ($rows - 1) * ($x - $rest)) - : ($rows * $x)); - - $idx += $y; - $four[$x] = $lcomm[$idx]; - } - write; - } -} - - -sub usage () -{ - print "Usage: $0 [OPTION]... [Makefile]... - -Generate Makefile.in for configure from Makefile.am. - -Operation modes: - --help print this help, then exit - --version print version number, then exit - -v, --verbose verbosely list files processed - --no-force only update Makefile.in's that are out of date - -W, --warnings=CATEGORY report the warnings falling in CATEGORY - -Dependency tracking: - -i, --ignore-deps disable dependency tracking code - --include-deps enable dependency tracking code - -Flavors: - --foreign set strictness to foreign - --gnits set strictness to gnits - --gnu set strictness to gnu - -Library files: - -a, --add-missing add missing standard files to package - --libdir=DIR set directory storing library files - --print-libdir print directory storing library files - -c, --copy with -a, copy missing files (default is symlink) - -f, --force-missing force update of standard files - -"; - Automake::ChannelDefs::usage; - - print "\nFiles automatically distributed if found " . - "(always):\n"; - print_autodist_files @common_files; - print "\nFiles automatically distributed if found " . - "(under certain conditions):\n"; - print_autodist_files @common_sometimes; - - print ' -Report bugs to <@PACKAGE_BUGREPORT@>. -GNU Automake home page: <@PACKAGE_URL@>. -General help using GNU software: . -'; - - # --help always returns 0 per GNU standards. - exit 0; -} - - -sub version () -{ - print < -This is free software: you are free to change and redistribute it. -There is NO WARRANTY, to the extent permitted by law. - -Written by Tom Tromey - and Alexandre Duret-Lutz . -EOF - # --version always returns 0 per GNU standards. - exit 0; -} - -################################################################ - -# Parse command line. -sub parse_arguments () -{ - my $strict = 'gnu'; - my $ignore_deps = 0; - my @warnings = (); - - my %cli_options = - ( - 'version' => \&version, - 'help' => \&usage, - 'libdir=s' => \$libdir, - 'print-libdir' => sub { print "$libdir\n"; exit 0; }, - 'gnu' => sub { $strict = 'gnu'; }, - 'gnits' => sub { $strict = 'gnits'; }, - 'foreign' => sub { $strict = 'foreign'; }, - 'include-deps' => sub { $ignore_deps = 0; }, - 'i|ignore-deps' => sub { $ignore_deps = 1; }, - 'no-force' => sub { $force_generation = 0; }, - 'f|force-missing' => \$force_missing, - 'a|add-missing' => \$add_missing, - 'c|copy' => \$copy_missing, - 'v|verbose' => sub { setup_channel 'verb', silent => 0; }, - 'W|warnings=s' => \@warnings, - ); - - use Automake::Getopt (); - Automake::Getopt::parse_options %cli_options; - - set_strictness ($strict); - my $cli_where = new Automake::Location; - set_global_option ('no-dependencies', $cli_where) if $ignore_deps; - for my $warning (@warnings) - { - parse_warnings ('-W', $warning); - } - - return unless @ARGV; - - my $errspec = 0; - foreach my $arg (@ARGV) - { - fatal ("empty argument\nTry '$0 --help' for more information") - if ($arg eq ''); - - # Handle $local:$input syntax. - my ($local, @rest) = split (/:/, $arg); - @rest = ("$local.in",) unless @rest; - my $input = locate_am @rest; - if ($input) - { - push @input_files, $input; - $output_files{$input} = join (':', ($local, @rest)); - } - else - { - error "no Automake input file found for '$arg'"; - $errspec = 1; - } - } - fatal "no input file found among supplied arguments" - if $errspec && ! @input_files; -} - - -# handle_makefile ($MAKEFILE) -# --------------------------- -sub handle_makefile -{ - my ($file) = @_; - ($am_file = $file) =~ s/\.in$//; - if (! -f ($am_file . '.am')) - { - error "'$am_file.am' does not exist"; - } - else - { - # Any warning setting now local to this Makefile.am. - dup_channel_setup; - - generate_makefile ($am_file . '.am', $file); - - # Back out any warning setting. - drop_channel_setup; - } -} - -# Deal with all makefiles, without threads. -sub handle_makefiles_serial () -{ - foreach my $file (@input_files) - { - handle_makefile ($file); - } -} - -# Logic for deciding how many worker threads to use. -sub get_number_of_threads () -{ - my $nthreads = $ENV{'AUTOMAKE_JOBS'} || 0; - - $nthreads = 0 - unless $nthreads =~ /^[0-9]+$/; - - # It doesn't make sense to use more threads than makefiles, - my $max_threads = @input_files; - - if ($nthreads > $max_threads) - { - $nthreads = $max_threads; - } - return $nthreads; -} - -# handle_makefiles_threaded ($NTHREADS) -# ------------------------------------- -# Deal with all makefiles, using threads. The general strategy is to -# spawn NTHREADS worker threads, dispatch makefiles to them, and let the -# worker threads push back everything that needs serialization: -# * warning and (normal) error messages, for stable stderr output -# order and content (avoiding duplicates, for example), -# * races when installing aux files (and respective messages), -# * races when collecting aux files for distribution. -# -# The latter requires that the makefile that deals with the aux dir -# files be handled last, done by the master thread. -sub handle_makefiles_threaded -{ - my ($nthreads) = @_; - - # The file queue distributes all makefiles, the message queues - # collect all serializations needed for respective files. - my $file_queue = Thread::Queue->new; - my %msg_queues; - foreach my $file (@input_files) - { - $msg_queues{$file} = Thread::Queue->new; - } - - verb "spawning $nthreads worker threads"; - my @threads = (1 .. $nthreads); - foreach my $t (@threads) - { - $t = threads->new (sub - { - while (my $file = $file_queue->dequeue) - { - verb "handling $file"; - my $queue = $msg_queues{$file}; - setup_channel_queue ($queue, QUEUE_MESSAGE); - $required_conf_file_queue = $queue; - handle_makefile ($file); - $queue->enqueue (undef); - setup_channel_queue (undef, undef); - $required_conf_file_queue = undef; - } - return $exit_code; - }); - } - - # Queue all makefiles. - verb "queuing " . @input_files . " input files"; - $file_queue->enqueue (@input_files, (undef) x @threads); - - # Collect and process serializations. - foreach my $file (@input_files) - { - verb "dequeuing messages for " . $file; - reset_local_duplicates (); - my $queue = $msg_queues{$file}; - while (my $key = $queue->dequeue) - { - if ($key eq QUEUE_MESSAGE) - { - pop_channel_queue ($queue); - } - elsif ($key eq QUEUE_CONF_FILE) - { - require_queued_file_check_or_copy ($queue); - } - else - { - prog_error "unexpected key $key"; - } - } - } - - foreach my $t (@threads) - { - my @exit_thread = $t->join; - $exit_code = $exit_thread[0] - if ($exit_thread[0] > $exit_code); - } -} - -################################################################ - -# Parse the WARNINGS environment variable. -parse_WARNINGS; - -# Parse command line. -parse_arguments; - -fatal "$configure_ac is required" unless -f $configure_ac; - -# Do configure.ac scan only once. -scan_autoconf_files; - -if (! @input_files) - { - my $msg = ''; - $msg = "\nDid you forget AC_CONFIG_FILES([Makefile]) in $configure_ac?" - if -f 'Makefile.am'; - fatal ("no 'Makefile.am' found for any configure output$msg"); - } - -my $nthreads = get_number_of_threads (); - -if ($perl_threads && $nthreads >= 1) - { - handle_makefiles_threaded ($nthreads); - } -else - { - handle_makefiles_serial (); - } - -exit $exit_code; - - -### Setup "GNU" style for perl-mode and cperl-mode. -## Local Variables: -## perl-indent-level: 2 -## perl-continued-statement-offset: 2 -## perl-continued-brace-offset: 0 -## perl-brace-offset: 0 -## perl-brace-imaginary-offset: 0 -## perl-label-offset: -2 -## cperl-indent-level: 2 -## cperl-brace-offset: 0 -## cperl-continued-brace-offset: 0 -## cperl-label-offset: -2 -## cperl-extra-newline-before-brace: t -## cperl-merge-trailing-else: nil -## cperl-continued-statement-offset: 2 -## End: diff --git a/bin/local.mk b/bin/local.mk deleted file mode 100644 index b5617f50a..000000000 --- a/bin/local.mk +++ /dev/null @@ -1,82 +0,0 @@ -## Copyright (C) 1995-2017 Free Software Foundation, Inc. -## -## This program is free software; you can redistribute it and/or modify -## it under the terms of the GNU General Public License as published by -## the Free Software Foundation; either version 2, or (at your option) -## any later version. -## -## This program is distributed in the hope that it will be useful, -## but WITHOUT ANY WARRANTY; without even the implied warranty of -## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -## GNU General Public License for more details. -## -## You should have received a copy of the GNU General Public License -## along with this program. If not, see . - -## ----------------------------------- ## -## The automake and aclocal scripts. ## -## ----------------------------------- ## - -bin_SCRIPTS = %D%/automake %D%/aclocal -nodist_noinst_SCRIPTS += \ - %D%/aclocal-$(APIVERSION) \ - %D%/automake-$(APIVERSION) - -CLEANFILES += \ - $(bin_SCRIPTS) \ - %D%/aclocal-$(APIVERSION) \ - %D%/automake-$(APIVERSION) - -# Used by maintainer checks and such. -automake_in = $(srcdir)/%D%/automake.in -aclocal_in = $(srcdir)/%D%/aclocal.in -automake_script = %D%/automake -aclocal_script = %D%/aclocal - -AUTOMAKESOURCES = $(automake_in) $(aclocal_in) -TAGS_FILES += $(AUTOMAKESOURCES) -EXTRA_DIST += $(AUTOMAKESOURCES) - -# Make versioned links. We only run the transform on the root name; -# then we make a versioned link with the transformed base name. This -# seemed like the most reasonable approach. -install-exec-hook: - @$(POST_INSTALL) - @for p in $(bin_SCRIPTS); do \ - f=`echo $$p | sed -e 's,.*/,,' -e '$(transform)'`; \ - fv="$$f-$(APIVERSION)"; \ - rm -f "$(DESTDIR)$(bindir)/$$fv"; \ - echo " $(LN) '$(DESTDIR)$(bindir)/$$f' '$(DESTDIR)$(bindir)/$$fv'"; \ - $(LN) "$(DESTDIR)$(bindir)/$$f" "$(DESTDIR)$(bindir)/$$fv"; \ - done - -uninstall-hook: - @for p in $(bin_SCRIPTS); do \ - f=`echo $$p | sed -e 's,.*/,,' -e '$(transform)'`; \ - fv="$$f-$(APIVERSION)"; \ - rm -f "$(DESTDIR)$(bindir)/$$fv"; \ - done - -# These files depend on Makefile so they are rebuilt if $(VERSION), -# $(datadir) or other do_subst'ituted variables change. -%D%/automake: %D%/automake.in -%D%/aclocal: %D%/aclocal.in -%D%/automake %D%/aclocal: Makefile - $(AM_V_GEN)rm -f $@ $@-t $@-t2 \ - && $(MKDIR_P) $(@D) \ -## Common substitutions. - && in=$@.in && $(do_subst) <$(srcdir)/$$in >$@-t \ -## We can't use '$(generated_file_finalize)' here, because currently -## Automake contains occurrences of unexpanded @substitutions@ in -## comments, and that is perfectly legit. - && chmod a+x,a-w $@-t && mv -f $@-t $@ - -%D%/aclocal-$(APIVERSION): %D%/aclocal - $(AM_V_GEN) rm -f $@; \ - $(LN) %D%/aclocal $@ - -%D%/automake-$(APIVERSION): %D%/automake - $(AM_V_GEN) rm -f $@; \ - $(LN) %D%/automake $@ - -# vim: ft=automake noet diff --git a/bootstrap b/bootstrap deleted file mode 100755 index 28b1ace11..000000000 --- a/bootstrap +++ /dev/null @@ -1,112 +0,0 @@ -#! /bin/sh - -# This script helps bootstrap automake, when checked out from git. -# -# Copyright (C) 2002-2017 Free Software Foundation, Inc. -# Originally written by Pavel Roskin September 2002. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -# Since Automake uses itself in its build process, we can't simply run -# 'autoreconf -i' which would require Automake to already be -# installed. - -# Don't ignore failures. -set -e - -# Set program basename. -me=`echo "$0" | sed 's,^.*/,,'` - -# Let user choose which version of autoconf, autom4te and perl to use. -: ${AUTOCONF=autoconf} -export AUTOCONF # might be used by aclocal and/or automake -: ${AUTOM4TE=autom4te} -export AUTOM4TE # ditto -: ${PERL=perl} - -# Variables to substitute. -VERSION=`sed -ne '/AC_INIT/s/^[^[]*\[[^[]*\[\([^]]*\)\].*$/\1/p' configure.ac` -APIVERSION=`sed -n 's/^APIVERSION=//p' configure.ac` -PACKAGE=automake -datadir=. -# This should be automatically updated by the 'update-copyright' -# rule of our Makefile. -RELEASE_YEAR=2017 - -# Sanity checks. -if test -z "$VERSION"; then - echo "$me: cannot find VERSION" >&2 - exit 1 -fi - -if test -z "$APIVERSION"; then - echo "$me: cannot find APIVERSION" >&2 - exit 1 -fi - -# Make a dummy versioned directory for aclocal. -rm -rf aclocal-$APIVERSION -mkdir aclocal-$APIVERSION -if test -d automake-$APIVERSION; then - find automake-$APIVERSION -exec chmod u+wx '{}' ';' -fi -rm -rf automake-$APIVERSION -# Can't use "ln -s lib automake-$APIVERSION", that might not work -# properly on MinGW/MSYS. -mkdir automake-$APIVERSION -cp -rf lib/* automake-$APIVERSION - -dosubst () -{ - rm -f $2 - in=`echo $1 | sed 's,^.*/,,'` - sed -e "s%@APIVERSION@%$APIVERSION%g" \ - -e "s%@PACKAGE@%$PACKAGE%g" \ - -e "s%@PERL@%$PERL%g" \ - -e "s%@SHELL@%$BOOTSTRAP_SHELL%g" \ - -e "s%@VERSION@%$VERSION%g" \ - -e "s%@datadir@%$datadir%g" \ - -e "s%@RELEASE_YEAR@%$RELEASE_YEAR%g" \ - -e "s%@configure_input@%Generated from $in; do not edit by hand.%g" \ - $1 > $2 - chmod a-w $2 -} - -# Create temporary replacement for lib/Automake/Config.pm. -dosubst automake-$APIVERSION/Automake/Config.in \ - automake-$APIVERSION/Automake/Config.pm - -# Overwrite amversion.m4. -dosubst m4/amversion.in m4/amversion.m4 - -# Create temporary replacement for aclocal and automake. -dosubst bin/aclocal.in bin/aclocal.tmp -dosubst bin/automake.in bin/automake.tmp - -# Create required makefile snippets. -$PERL ./gen-testsuite-part > t/testsuite-part.tmp -chmod a-w t/testsuite-part.tmp -mv -f t/testsuite-part.tmp t/testsuite-part.am - -# Run the autotools. Bail out if any warning is triggered. -# Use '-I' here so that our own *.m4 files in m4/ gets included, -# not copied, in aclocal.m4. -$PERL ./bin/aclocal.tmp -Wall -Werror -I m4 \ - --automake-acdir=m4 --system-acdir=m4/acdir -$AUTOCONF -Wall -Werror -$PERL ./bin/automake.tmp -Wall -Werror - -# Remove temporary files and directories. -rm -rf aclocal-$APIVERSION automake-$APIVERSION -rm -f bin/aclocal.tmp bin/automake.tmp diff --git a/configure.ac b/configure.ac deleted file mode 100644 index 1aee6af27..000000000 --- a/configure.ac +++ /dev/null @@ -1,599 +0,0 @@ -# Process this file with autoconf to produce a configure script. - -# Copyright (C) 1995-2017 Free Software Foundation, Inc. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -AC_PREREQ([2.69]) -AC_INIT([GNU Automake], [1.99a], [bug-automake@gnu.org]) - -AC_CONFIG_SRCDIR([bin/automake.in]) -AC_CONFIG_AUX_DIR([lib]) - -AM_SILENT_RULES([yes]) - -AC_CANONICAL_HOST -AC_CANONICAL_BUILD - -# Save the AUTOCONF setting before AM_INIT_AUTOMAKE overrides it; this -# way we can run Autoconf tests from configure (or from the test -# suite) without being bothered by 'missing'. Likewise for autom4te, -# autoreconf, autoheader, and autoupdate. -AC_SUBST([am_AUTOCONF], ["${AUTOCONF-autoconf}"]) -AC_SUBST([am_AUTOM4TE], ["${AUTOM4TE-autom4te}"]) -AC_SUBST([am_AUTORECONF], ["${AUTORECONF-autoreconf}"]) -AC_SUBST([am_AUTOHEADER], ["${AUTOHEADER-autoheader}"]) -AC_SUBST([am_AUTOUPDATE], ["${AUTOUPDATE-autoupdate}"]) - -dnl We call AC_PROG_CC in an unusual way, and only for use in our -dnl testsuite, so also use 'no-dependencies' and 'no-define' among -dnl the automake options to avoid bloating and potential problems. -AM_INIT_AUTOMAKE([-Wall -Werror dist-xz filename-length-max=99 - no-define no-dependencies]) - -# Keep this on a line of its own, since it must be found and processed -# by the 'update-copyright' rule in our Makefile. -RELEASE_YEAR=2017 -AC_SUBST([RELEASE_YEAR]) - -# The API version is the base version. We must guarantee -# compatibility for all releases with the same API version. -APIVERSION=1.99a -AC_SUBST([APIVERSION]) - -AC_SUBST([pkgvdatadir], ["\${datadir}/$PACKAGE-$APIVERSION"]) -AC_SUBST([scriptdir], ["\${pkgvdatadir}"]) -AC_SUBST([amdir], ["\${pkgvdatadir}/am"]) -AC_SUBST([automake_acdir], ["\${datadir}/aclocal-$APIVERSION"]) -AC_SUBST([system_acdir], ["\${datadir}/aclocal"]) - -# Our build system is bootstrapped with the bleeding-edge versions of -# aclocal and automake, hence the remake rules must use those versions -# as well. The extra quoting is to cater to cases when the build -# directory contains whitespace or shell metacharacters. -ACLOCAL="\"`pwd`/pre-inst-env\" aclocal-$APIVERSION" -AUTOMAKE="\"`pwd`/pre-inst-env\" automake-$APIVERSION" - -AC_PROG_LN_S - -AC_PATH_PROG([PERL], [perl]) -if test -z "$PERL"; then - AC_MSG_ERROR([perl not found]) -fi -# Save details about the selected perl interpreter in config.log. -AM_RUN_LOG([$PERL --version]) -$PERL -e 'require 5.006;' || { - AC_MSG_ERROR( -[perl 5.6 or better is required; perl 5.8.2 or better -is recommended. If you have several perl versions -installed, select the one Automake should use using - ./configure PERL=/path/to/perl]) -} - -# The test suite will skip some tests if tex is absent. -AC_CHECK_PROG([TEX], [tex], [tex]) -# Save details about the selected TeX program in config.log. -# Redirect input from /dev/null, as TeX might otherwise hang waiting -# for input from the terminal. -AM_RUN_LOG([$TEX --version conftest/conftest.ac -if AM_RUN_LOG([cd conftest && $am_AUTOCONF -o /dev/null conftest.ac]); -then - am_cv_autoconf_works=yes -else - am_cv_autoconf_works=no -fi -rm -rf conftest]) -if test "$am_cv_autoconf_works" = no; then - AC_MSG_ERROR([The installed version of autoconf does not work. - Please check config.log for error messages before this one.]) -fi - -AC_CACHE_CHECK([whether autoconf is recent enough], [am_cv_autoconf_version], -[mkdir conftest -dnl Creative quoting required to avoid spurious expansion of AC_PREREQ macro -echo 'AC'"_PREREQ([[$required_autoconf_version]])" > conftest/conftest.ac -if AM_RUN_LOG([cd conftest && $am_AUTOCONF -o /dev/null conftest.ac]); -then - am_cv_autoconf_version=yes -else - am_cv_autoconf_version=no -fi -rm -rf conftest]) -if test "$am_cv_autoconf_version" = no; then - AC_MSG_ERROR([Autoconf $required_autoconf_version or better is required.]) -fi - -# Test for ln. We need use it to install the versioned binaries. -AC_MSG_CHECKING([whether ln works]) -AC_CACHE_VAL([am_cv_prog_ln], [ -rm -f conftest conftest.file -: >conftest.file -if ln conftest.file conftest 2>/dev/null; then - am_cv_prog_ln=ln -else - am_cv_prog_ln='cp -p' -fi -rm -f conftest conftest.file]) -AC_SUBST([LN], [$am_cv_prog_ln]) -result=no -test "x$am_cv_prog_ln" = xln && result=yes -AC_MSG_RESULT([$result]) - -# The amount we should wait after modifying files. -# FIXME: for file systems with sub-second timestamp resolutions, this -# FIXME: might be just one second (or even less if 'sleep' supports -# FIXME: non-integer arguments); is it worth pursuing that road? -AC_SUBST([MODIFICATION_DELAY], [2]) - -## ------------------------------------------- ## -## Test for things needed by the test suite. ## -## ------------------------------------------- ## - -AC_PROG_EGREP -AC_PROG_FGREP - -dnl FIXME: could we extract this in a simpler way through autoconf -dnl FIXME: idioms or internals? -AC_DEFUN( - [_AM_INIT_BOURNE_COMPATIBLE_VAR], - [am_bourne_compatible="AS_ESCAPE(_m4_expand([AS_BOURNE_COMPATIBLE]))"]) - -dnl -dnl Arguments to this macro: -dnl -dnl $1 - shell to test -dnl $2 - description of the tested feature -dnl $3 - shell code used to check the feature; to indicate success, -dnl it can either exit with status 77, or have the last command -dnl returning with exit status of zero -dnl $4 - shell code to execute if the check on the shell is successful -dnl (defaults to nothing) -dnl $5 - shell code to execute if the check on the shell is not -dnl successful (defaults to nothing) -dnl -AC_DEFUN([_AM_CHECK_SHELL_FEATURE], - [AC_REQUIRE([_AM_INIT_BOURNE_COMPATIBLE_VAR]) - AC_MSG_CHECKING([whether $1 $2]) - if { $1 -c "$am_bourne_compatible -AS_ESCAPE([$3]) -test \$? -eq 0 || exit 1 -# Use 77 to indicate success (rather than 0), in case some shell -# acts like Solaris 10's /bin/sh, exiting successfully on some -# syntax errors. -exit 77" >&AS_MESSAGE_LOG_FD 2>&1; test $? -eq 77; } - then - AC_MSG_RESULT([yes]) - $4 - else - AC_MSG_RESULT([no]) - $5 - fi]) - -# AM_CHECK_CANDIDATE_TEST_SHELL(SHELL-PATH) -# ----------------------------------------- -# -# Check if the given shell is good enough to run our test scripts. -# Inspired to gnulib's 'tests/init.sh'. -# -# We require POSIX and XSI features (e.g., '$(...)' for command -# substitutions, '$((...))' for shell arithmetic, and support for -# '${var#...}' and '${var%...}' parameter expansions). -# -# We require that the shell can correctly trap EXIT when 'set -e' is in -# effect (OSF1/Tru64 sh failed to do so, see commit v1.10b-52-g9fe8259). -# -# We want to able to define shell aliases with the same name of shell -# builtins. -# -# We also prefer shells that, when 'set -x' is in effect, do not also -# redirect traces upon stderr redirections. For example, -# $ set -x; echo x 2>file -# would emit "+ echo x" into file with older zsh versions. Similarly, -# $ set -x; P=1 true 2>file -# would emit "P=1" into file with /usr/xpg4/bin/sh from Solaris 10 and -# /bin/sh from SunOS 5.11 and OpenBSD 4.7. -# -# Use '$am_score' to indicate the degree of acceptability of the shell. -# A score of "10" means that the shell is good enough for our needs; -# a score of "9" means that the shell has some minor bugs or limitation, -# but is still (barely) acceptable for our uses. Any other score means -# that the shell is broken or unfit. -# -AC_DEFUN([_AM_CHECK_CANDIDATE_SHELL], - [am_score=10 - while :; do - - _AM_CHECK_SHELL_FEATURE([$1], - [supports \$(cmd)], - [test "$(echo x)" = x], - [], [am_score=1; break]) - - _AM_CHECK_SHELL_FEATURE([$1], - [supports \$((expr))], - [test $((1 + 2 * 3)) = 7], - [], [am_score=1; break]) - - _AM_CHECK_SHELL_FEATURE([$1], - [supports \${@%:@var}], - [zero='' one='x' twelve=' foobar baz!' \ - && test ${@%:@zero} -eq 0 \ - && test ${@%:@one} -eq 1 \ - && test ${@%:@twelve} -eq 12], - [], [am_score=1; break]) - - _AM_CHECK_SHELL_FEATURE([$1], - [supports \${var@%:@glob} and \${var%glob}], - [v=a/b/c \ - && test ${v@%:@*/} = b/c \ - && test ${v@%:@@%:@*/} = c \ - && test ${v%/*} = a/b \ - && test ${v%%/*} = a], - [], [am_score=1; break]) - - _AM_CHECK_SHELL_FEATURE([$1], - [preserves exit traps with "set -e"], - [set -e; trap 'exit $?' 0; (exit 77); exit 77], - [], [am_score=1; break]) - - _AM_CHECK_SHELL_FEATURE([$1], - [can define exit traps in a shell function], - [fail=0 && foo() { trap 'fail=1' 0; } && foo && test $fail = 0], - [], [am_score=1; break]) - - _AM_CHECK_SHELL_FEATURE([$1], - [corrupts stderr with "set -x"], - [(set -x; P=1 true 2>&3) 3>&1 2>/dev/null | grep P=1], - [am_score=9], []) - - echo 'return 34' > conftest-return.sh - echo 'ok=no' >> conftest-return.sh - _AM_CHECK_SHELL_FEATURE([$1], - [can return early from "dot-sourced" files], - [ok=yes; . ./conftest-return.sh; test $? -eq 34 && test $ok = yes], - [rm -f conftest-return.sh], - [rm -f conftest-return.sh; am_score=1; break]) - - echo 'alias false=echo' > conftest-alias.sh - echo 'false && test "$(false 97)" = 97' >> conftest-alias.sh - _AM_CHECK_SHELL_FEATURE([$1], - [supports alias named like shell builtins], - [. ./conftest-alias.sh], - [rm -f conftest-alias.sh], - [rm -f conftest-alias.sh; am_score=1; break]) - - _AM_CHECK_SHELL_FEATURE([$1], - [supports "test -e"], - [test -e config.log && test -e . && test ! -e nonesuch], - [], [am_score=1; break]) - - break - done]) - -# These messages only goes to the config.log file. -AC_MSG_NOTICE([will now look for a sturdy POSIX shell, for our testsuite]) - -AC_CACHE_VAL( - [ac_cv_AM_TEST_RUNNER_SHELL], - [if test "$AM_TEST_RUNNER_SHELL"; then - # Let the user override it. - ac_cv_AM_TEST_RUNNER_SHELL=$AM_TEST_RUNNER_SHELL - else - ac_cv_AM_TEST_RUNNER_SHELL=no - am_candidate_shells=${CONFIG_SHELL-} - # For the benefit of Solaris. - am_PATH=$PATH$PATH_SEPARATOR/usr/xpg6/bin$PATH_SEPARATOR/usr/xpg4/bin - for am_sh in sh sh5 dash ash bash zsh ksh pdksh; do - AC_PATH_PROG([am_candidate_sh], [$am_sh], [], [$am_PATH]) - if test -n "$am_candidate_sh"; then - am_candidate_shells="$am_candidate_shells $am_candidate_sh" - fi - AM_SUBST_NOTMAKE([am_candidate_sh]) - # Must nullify these in order not to interfere with the checks in - # the next loop. - AS_UNSET([am_candidate_sh]) - AS_UNSET([ac_cv_path_am_candidate_sh]) - done - AS_UNSET([am_PATH]) # Not required anymore - for am_sh in $am_candidate_shells; do - am_score=0 - _AM_CHECK_CANDIDATE_SHELL([$am_sh]) - if test $am_score -eq 9; then - # The shell is barely acceptable for our needs. We might - # still find one that is even better, so continue looking. - AC_MSG_NOTICE([shell $am_sh is acceptable, but we might do better]) - ac_cv_AM_TEST_RUNNER_SHELL=$am_sh - elif test $am_score -eq 10; then - AC_MSG_NOTICE([shell $am_sh is good enough, stop looking]) - ac_cv_AM_TEST_RUNNER_SHELL=$am_sh - break - fi - done - fi - AM_TEST_RUNNER_SHELL=$ac_cv_AM_TEST_RUNNER_SHELL]) - -if test $AM_TEST_RUNNER_SHELL = no; then - AC_MSG_FAILURE([m4_normalize([no POSIX shell found that is good - enough to be used in our testsuite])]) -else - AC_MSG_NOTICE([will use $AM_TEST_RUNNER_SHELL as the testsuite shell]) -fi - -AC_ARG_VAR([AM_TEST_RUNNER_SHELL], - [a sturdy POSIX shell for our testsuite]) - - -########################################################################### - -# Look for C, C++ and fortran compilers to be used in the testsuite. - -dnl We don't want to abort our configuration script if no C compiler is -dnl available, as such a compiler is only required to run part of the -dnl testsuite, not to build or install Automake. Ditto for C++, Fortran -dnl and Fortran 77 compilers. Unfortunately, autoconf does not offer an -dnl easy way to obtain this behaviour, so we'll need a few hacks. - -dnl We want the body of this macro to expand as a single shell statement, -dnl thus we wrap it into { ... } brackets. -AC_DEFUN([_AM_WRAP_MSG_ERROR], [ { - AC_MSG_WARN([$1]) - am__failed=yes - break -} ]) - -AC_DEFUN([_AM_COMPILER_CAN_FAIL], [ - m4_pushdef([AC_MSG_FAILURE], m4_defn([_AM_WRAP_MSG_ERROR])) - m4_pushdef([AC_MSG_ERROR], m4_defn([_AM_WRAP_MSG_ERROR])) - am__failed=no - while :; do - $1 - break - done - AS_IF([test $am__failed = yes], [$2]) - # We have to clear these cache variables, so that future checks on - # compilers for different languages won't be confused. - unset ac_cv_objext ac_cv_exeext - # We also need to meddle with the autoconf internals to ensure that - # checks to find object and executable extensions will be run anew. - # FIXME: In the long run, the better thing to do would be to fix - # FIXME: autoconf instead ... - m4_undefine([m4_provide(_AC_COMPILER_OBJEXT)]) - m4_undefine([m4_provide(_AC_COMPILER_EXEEXT)]) - m4_popdef([AC_MSG_FAILURE]) - m4_popdef([AC_MSG_ERROR]) -]) - -AC_DEFUN([_AM_SKIP_COMP_TESTS], - [AC_MSG_NOTICE([tests requiring the $1 compiler will be skipped])]) - -# Prefer generic compilers to GNU ones when possible. This will ensure -# more testsuite coverage "in the wild". -# Note that we don't look for the MSVC C/C++ compiler here. This is -# deliberate; for more discussion and rationale, see: -# - -AC_MSG_NOTICE([will now look for generic compilers]) - -# C compiler. -_AM_COMPILER_CAN_FAIL(dnl - [AC_PROG_CC([cc gcc])], - [CC=false; _AM_SKIP_COMP_TESTS([C])]) - -AS_IF([test x"$GCC" = x"yes"], [am_CC_is_GNU=yes], [am_CC_is_GNU=no]) - -# On case-insensitive file systems (seen e.g. on Cygwin and Mac OS X) -# we must avoid looking for 'CC', because that would be the same as -# 'cc', and could cause $CXX to point to the C compiler, instead of -# to a C++ compiler as expected (see automake bugs #11893 and #10766). -# Similarly, we must avoid looking for 'RCC', as that can point to the -# Qt4 "Resource Compiler": -if test -f /bIn/rMdIr || test -f /uSr/bIn/rMdIr; then - # Case-insensitive file system, don't look for CC. - am_CC= am_RCC= -else - am_CC=CC am_RCC=RCC -fi - -# The list of C++ compilers here has been copied, pasted and edited -# from 'lib/autoconf/c.m4:AC_PROG_CXX' in the Autoconf distribution. -# Keep it in sync, or better again, find out a way to avoid this code -# duplication. -_AM_COMPILER_CAN_FAIL([AC_PROG_CXX(dnl - [aCC $am_CC FCC KCC $am_RCC xlC_r xlC c++ cxx cc++ gpp g++])], - [CXX=false; _AM_SKIP_COMP_TESTS([C++])]) - -AS_IF([test x"$GXX" = x"yes"], [am_CXX_is_GNU=yes], [am_CXX_is_GNU=no]) - -# The lists of Fortran compilers here has been copied, pasted and edited -# from file 'lib/autoconf/fortran.m4' in the Autoconf distribution. -# Keep it in sync, or better again, find out a way to avoid this code -# duplication. - -_AM_COMPILER_CAN_FAIL([AC_PROG_FC(dnl - [xlf95 f95 fort ifort ifc efc pgfortran pgf95 lf95 ftn nagfor] dnl - [xlf90 f90 pgf90 pghpf epcf90 g95 gfortran])], - [FC=false; _AM_SKIP_COMP_TESTS([Fortran])]) - -AS_IF([test x"$GFC" = x"yes"], [am_FC_is_GNU=yes], [am_FC_is_GNU=no]) - -_AM_COMPILER_CAN_FAIL([AC_PROG_F77(dnl - [xlf f77 frt pgf77 cf77 fort77 fl32 af77 g77 gfortran])], - [F77=false; _AM_SKIP_COMP_TESTS([Fortran 77])]) - -AS_IF([test x"$G77" = x"yes"], [am_F77_is_GNU=yes], [am_F77_is_GNU=no]) - -# Some tests will need the GNU compilers. Searching for them here would -# be overkill, since our testsuite already handles their search and setup -# pretty well. But in case the compilers already found are the GNU ones, -# we want to use them in the testsuite where GNU compilers are required. -# Also, in case the compilers detected above (at configure time) are not -# the GNU ones, we cannot use the values of CFLAGS, CXXFLAGS, FCFLAGS and -# FFLAGS detected for them with the GNU compilers too, since it's likely -# they won't be compatible. So we allow the user to define variants of -# these variables for the GNU compilers separately. - -AC_MSG_NOTICE([will now look for GNU compilers]) - -# GNU C compiler. -AC_ARG_VAR([GNU_CC], [GNU C compiler]) -AC_ARG_VAR([GNU_CFLAGS], [GNU C compiler flags]) -if test $am_CC_is_GNU = yes; then - AC_MSG_NOTICE([$CC is already a GNU C compiler]) - GNU_CC=$CC GNU_CFLAGS=${GNU_CFLAGS-$CFLAGS} -else - AC_CHECK_TOOLS([GNU_CC], [gcc], [false]) -fi -if test "$GNU_CC" != false; then - AS_IF([AM_RUN_LOG([$GNU_CC --version && $GNU_CC -v])], [], - [AC_MSG_WARN([botched installation for GNU C compiler]) - _AM_SKIP_COMP_TESTS([GNU C])]) -fi - -# GNU C++ compiler. -AC_ARG_VAR([GNU_CXX], [GNU C++ compiler]) -AC_ARG_VAR([GNU_CXXFLAGS], [GNU C++ compiler flags]) -if test $am_CXX_is_GNU = yes; then - AC_MSG_NOTICE([$CXX is already a GNU C++ compiler]) - GNU_CXX=$CXX - GNU_CXXFLAGS=${GNU_CXXFLAGS-$CXXFLAGS} -else - AC_CHECK_TOOLS([GNU_CXX], [g++ gpp], [false]) -fi -if test "$GNU_CXX" != false; then - AS_IF([AM_RUN_LOG([$GNU_CXX --version && $GNU_CXX -v])], [], - [AC_MSG_WARN([botched installation for GNU C++ compiler]) - _AM_SKIP_COMP_TESTS([GNU C++])]) -fi - -# GNU Fortran compiler. -AC_ARG_VAR([GNU_FC], [GNU Fortran compiler]) -AC_ARG_VAR([GNU_FCFLAGS], [GNU Fortran compiler flags]) -if test $am_FC_is_GNU = yes; then - AC_MSG_NOTICE([$FC is already a GNU Fortran compiler]) - GNU_FC=$FC - GNU_FCFLAGS=${GNU_FCFLAGS-$FCFLAGS} -else - AC_CHECK_TOOLS([GNU_FC], [gfortran], [false]) -fi -if test "$GNU_FC" != false; then - AS_IF([AM_RUN_LOG([$GNU_FC --version && $GNU_FC -v])], [], - [AC_MSG_WARN([botched installation for GNU Fortran compiler]) - _AM_SKIP_COMP_TESTS([GNU Fortran])]) -fi - -# GNU Fortran 77 compiler. -AC_ARG_VAR([GNU_F77], [GNU Fortran 77 compiler]) -AC_ARG_VAR([GNU_FFLAGS], [GNU Fortran 77 compiler flags]) -if test $am_F77_is_GNU = yes; then - AC_MSG_NOTICE([$F77 is already a GNU Fortran 77 compiler]) - GNU_F77=$F77 - GNU_FFLAGS=${GNU_FFLAGS-$FFLAGS} -else - AC_CHECK_TOOLS([GNU_F77], [g77 gfortran], [false]) -fi -if test "$GNU_F77" != false; then - AS_IF([AM_RUN_LOG([$GNU_F77 --version && $GNU_F77 -v])], [], - [AC_MSG_WARN([botched installation for GNU Fortran 77 compiler]) - _AM_SKIP_COMP_TESTS([GNU Fortran 77])]) -fi - -# GNU Java compiler. -AC_ARG_VAR([GNU_GCJ], [GNU Java compiler]) -AC_ARG_VAR([GNU_GCJFLAGS], [GNU Java compiler flags]) -AC_CHECK_TOOLS([GNU_GCJ], [gcj], [false]) -if test "$GNU_GCJ" != false; then - AS_IF([AM_RUN_LOG([$GNU_GCJ --version && $GNU_GCJ -v])], [], - [AC_MSG_WARN([botched installation for GNU Java compiler]) - _AM_SKIP_COMP_TESTS([GNU Java])]) -fi - -# If we have been able to find at least a working compiler above, we -# know what the object and executable extensions for this platform are. -OBJEXT=${ac_cv_objext-UNKNOWN} -EXEEXT=${ac_cv_exeext-UNKNOWN} -AC_SUBST([OBJEXT]) -AC_SUBST([EXEEXT]) - -########################################################################### - -## ---------------------- ## -## Create output files. ## -## ---------------------- ## - -AC_CONFIG_FILES([Makefile]) -AC_CONFIG_LINKS([GNUmakefile:GNUmakefile]) -AC_CONFIG_FILES([pre-inst-env], [chmod +x pre-inst-env]) -AC_OUTPUT - -# Inform the user if this version of automake is a beta release or -# a development snapshot. -# According to HACKING, the version of a development snapshot should -# end with an "odd" letter (a, c, ...), the version of a test release -# should end wit an "even" letter (b, d, ...). - -am_stable_version_rx='[[1-9]\.[0-9]+(\.[0-9]+)?]' -am_beta_version_rx="[$am_stable_version_rx[bdfhjlnprtvxz]]" - -am_release_type=`AS_ECHO(["$PACKAGE_VERSION"]) | LC_ALL=C awk [" - /^$am_stable_version_rx$/ { print \"stable\"; exit(0); } - /^$am_beta_version_rx$/ { print \"beta version\"; exit(0); } - { print \"development snapshot\"; }"]` - -# '$silent' is set to yes if configure is passed the '--quiet' option. -test "$am_release_type" = stable || test "$silent" = yes || cat <. -EOF - -AS_EXIT([0]) diff --git a/contrib/README b/contrib/README deleted file mode 100644 index a4d7eeb8d..000000000 --- a/contrib/README +++ /dev/null @@ -1,26 +0,0 @@ -This is the 'contrib' directory of the GNU Automake distribution. - -Here you'll find additions to the Automake base distribution, in form of -makefile fragments, m4 macros, scripts, documentation, et cetera. Such -addition that might be useful for a significant percentage of its general -audience, but (for one reason or another) are not deemed appropriate for -inclusion into the Automake core. - -There are several reasons for which a feature can be kept in contrib: - - 1. The long-term usefulness of the feature is debatable and uncertain; - on-field and real-word testing are necessary to prove or disprove - its usefulness, before the feature can be committed into the Automake - core (as doing so too early would later force us to continue the - support for backward-compatibility, even if the features proves - flawed or fails to attract widespread use). - - 2. The APIs or overall design of the feature are still unstable, and - need on-field testing to iron warts and usability bugs, or uncover - potential flaws. - - 3. The feature was an historical one, mostly obsoleted but still used - "here and there" in the wild; so we want to to deprecate it and - remove it from the Automake core, but cannot remove it altogether, - for the sake of those still-existing usage. So it gets moved in - contrib. diff --git a/contrib/check-html.am b/contrib/check-html.am deleted file mode 100644 index a12075e1b..000000000 --- a/contrib/check-html.am +++ /dev/null @@ -1,57 +0,0 @@ -## automake - create Makefile.in from Makefile.am -## Copyright (C) 2001-2017 Free Software Foundation, Inc. -## -## This program is free software; you can redistribute it and/or modify -## it under the terms of the GNU General Public License as published by -## the Free Software Foundation; either version 2, or (at your option) -## any later version. -## -## This program is distributed in the hope that it will be useful, -## but WITHOUT ANY WARRANTY; without even the implied warranty of -## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -## GNU General Public License for more details. -## -## You should have received a copy of the GNU General Public License -## along with this program. If not, see . - -## Makefile.am fragment to produce HTML output from RST-formatted -## log files produced by the parallel-tests output. -## This fragment was part of the automake core in the 1.11.x release -## series, but has been then moved to contrib. - -TEST_SUITE_HTML = $(TEST_SUITE_LOG:.log=.html) - -mostlyclean-local: mostlyclean-check-html -.PHONY: mostlyclean-check-html -mostlyclean-check-html: -## Expand $(TEST_LOGS) only once, to avoid exceeding line length limits. - list='$(TEST_LOGS:.log=.html)'; test -z "$$list" || rm -f $$list - rm -f $(TEST_SUITE_HTML) - -.log.html: - @list='$(RST2HTML) rst2html rst2html.py'; \ - while :; do \ - for r2h in $$list; do \ - if ($$r2h --version) >/dev/null 2>&1; then break 2; \ - else :; fi; \ - done; \ - echo "cannot find rst2html, cannot create $@" >&2; \ - exit 2; \ - done; \ - $$r2h $(AM_RST2HTMLFLAGS) $(RST2HTMLFLAGS) $< >$@-t \ - && mv -f $@-t $@ - -# Be sure to run check first, and then to convert the result. -# Beware of concurrent executions. Run "check" not "check-TESTS", as -# check-SCRIPTS and other dependencies are rebuilt by the former only. -# And expect check to fail. -check-html recheck-html: - @target=`echo $@ | sed 's/-html$$//'`; \ - rv=0; $(MAKE) $(AM_MAKEFLAGS) $$target || rv=$$?; \ -## The nullification of $(TEST_LOGS) is required to ensure that -## "make recheck-html" do not try to uselessly re-run tests. - $(MAKE) $(AM_MAKEFLAGS) $(TEST_SUITE_HTML) TEST_LOGS= || exit 4; \ - exit $$rv - -.PHONY: check-html recheck-html -.MAKE: check-html recheck-html diff --git a/contrib/multilib/README b/contrib/multilib/README deleted file mode 100644 index c15d2b539..000000000 --- a/contrib/multilib/README +++ /dev/null @@ -1,9 +0,0 @@ -Minimal support for multilib builds. - -For a little more information, see: - - -The master (and probably more up-to-date) copies of the 'config-ml.in' -and 'symlink-tree' files are maintained in the GCC development tree -at . The same is probably true also for -the 'multi.m4' file. diff --git a/contrib/multilib/config-ml.in b/contrib/multilib/config-ml.in deleted file mode 100644 index cc7f79756..000000000 --- a/contrib/multilib/config-ml.in +++ /dev/null @@ -1,876 +0,0 @@ -# Configure fragment invoked in the post-target section for subdirs -# wanting multilib support. -# -# Copyright (C) 1995-2017 Free Software Foundation, Inc. -# -# This file is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, -# Boston, MA 02110-1301, USA. -# -# As a special exception to the GNU General Public License, if you -# distribute this file as part of a program that contains a -# configuration script generated by Autoconf, you may include it under -# the same distribution terms that you use for the rest of that program. -# -# Please report bugs to -# and send patches to . - -# It is advisable to support a few --enable/--disable options to let the -# user select which libraries s/he really wants. -# -# Subdirectories wishing to use multilib should put the following lines -# in the "post-target" section of configure.in. -# -# if [ "${srcdir}" = "." ] ; then -# if [ "${with_target_subdir}" != "." ] ; then -# . ${with_multisrctop}../../config-ml.in -# else -# . ${with_multisrctop}../config-ml.in -# fi -# else -# . ${srcdir}/../config-ml.in -# fi -# -# -# Things are complicated because 6 separate cases must be handled: -# 2 (native, cross) x 3 (absolute-path, relative-not-dot, dot) = 6. -# -# srcdir=. is special. It must handle make programs that don't handle VPATH. -# To implement this, a symlink tree is built for each library and for each -# multilib subdir. -# -# The build tree is laid out as -# -# ./ -# newlib -# m68020/ -# newlib -# m68881/ -# newlib -# -# The nice feature about this arrangement is that inter-library references -# in the build tree work without having to care where you are. Note that -# inter-library references also work in the source tree because symlink trees -# are built when srcdir=. -# -# Unfortunately, trying to access the libraries in the build tree requires -# the user to manually choose which library to use as GCC won't be able to -# find the right one. This is viewed as the lesser of two evils. -# -# Configure variables: -# ${with_target_subdir} = "." for native, or ${target_alias} for cross. -# Set by top level Makefile. -# ${with_multisrctop} = how many levels of multilibs there are in the source -# tree. It exists to handle the case of configuring in the source tree: -# ${srcdir} is not constant. -# ${with_multisubdir} = name of multilib subdirectory (eg: m68020/m68881). -# -# Makefile variables: -# MULTISRCTOP = number of multilib levels in source tree (+1 if cross) -# (FIXME: note that this is different than ${with_multisrctop}. Check out.). -# MULTIBUILDTOP = number of multilib levels in build tree -# MULTIDIRS = list of multilib subdirs (eg: m68000 m68020 ...) -# (only defined in each library's main Makefile). -# MULTISUBDIR = installed subdirectory name with leading '/' (eg: /m68000) -# (only defined in each multilib subdir). - -# FIXME: Multilib is currently disabled by default for everything other than -# newlib. It is up to each target to turn on multilib support for the other -# libraries as desired. - -# Autoconf incoming variables: -# srcdir, host, ac_configure_args -# -# We *could* figure srcdir and host out, but we'd have to do work that -# our caller has already done to figure them out and requiring these two -# seems reasonable. -# Note that `host' in this case is GCC's `target'. Target libraries are -# configured for a particular host. - -Makefile=${ac_file-Makefile} -ml_config_shell=${CONFIG_SHELL-/bin/sh} -ml_realsrcdir=${srcdir} - -# Scan all the arguments and set all the ones we need. - -ml_verbose=--verbose -for option in ${ac_configure_args} -do - # strip single quotes surrounding individual options - case $option in - \'*\') eval option=$option ;; - esac - - case $option in - --*) ;; - -*) option=-$option ;; - esac - - case $option in - --*=*) - optarg=`echo $option | sed -e 's/^[^=]*=//'` - ;; - esac - - case $option in - --disable-*) - enableopt=`echo ${option} | sed 's:^--disable-:enable_:;s:-:_:g'` - eval $enableopt=no - ;; - --enable-*) - case "$option" in - *=*) ;; - *) optarg=yes ;; - esac - enableopt=`echo ${option} | sed 's:^--::;s:=.*$::;s:-:_:g'` - # enable_shared and enable_static are handled by configure. - # Don't undo its work. - case $enableopt in - enable_shared | enable_static) ;; - *) eval $enableopt="$optarg" ;; - esac - ;; - --norecursion | --no-recursion) - ml_norecursion=yes - ;; - --silent | --sil* | --quiet | --q*) - ml_verbose=--silent - ;; - --verbose | --v | --verb*) - ml_verbose=--verbose - ;; - --with-*) - case "$option" in - *=*) ;; - *) optarg=yes ;; - esac - withopt=`echo ${option} | sed 's:^--::;s:=.*$::;s:-:_:g'` - eval $withopt="$optarg" - ;; - --without-*) - withopt=`echo ${option} | sed 's:^--::;s:out::;s:-:_:g'` - eval $withopt=no - ;; - esac -done - -# Only do this if --enable-multilib. -if [ "${enable_multilib}" = yes ]; then - -# Compute whether this is the library's top level directory -# (ie: not a multilib subdirectory, and not a subdirectory like newlib/src). -# ${with_multisubdir} tells us we're in the right branch, but we could be -# in a subdir of that. -# ??? The previous version could void this test by separating the process into -# two files: one that only the library's toplevel configure.in ran (to -# configure the multilib subdirs), and another that all configure.in's ran to -# update the Makefile. It seemed reasonable to collapse all multilib support -# into one file, but it does leave us with having to perform this test. -ml_toplevel_p=no -if [ -z "${with_multisubdir}" ]; then - if [ "${srcdir}" = "." ]; then - # Use ${ml_realsrcdir} instead of ${srcdir} here to account for ${subdir}. - # ${with_target_subdir} = "." for native, otherwise target alias. - if [ "${with_target_subdir}" = "." ]; then - if [ -f ${ml_realsrcdir}/../config-ml.in ]; then - ml_toplevel_p=yes - fi - else - if [ -f ${ml_realsrcdir}/../../config-ml.in ]; then - ml_toplevel_p=yes - fi - fi - else - # Use ${ml_realsrcdir} instead of ${srcdir} here to account for ${subdir}. - if [ -f ${ml_realsrcdir}/../config-ml.in ]; then - ml_toplevel_p=yes - fi - fi -fi - -# If this is the library's top level directory, set multidirs to the -# multilib subdirs to support. This lives at the top because we need -# `multidirs' set right away. - -if [ "${ml_toplevel_p}" = yes ]; then - -multidirs= -for i in `${CC-gcc} --print-multi-lib 2>/dev/null`; do - dir=`echo $i | sed -e 's/;.*$//'` - if [ "${dir}" = "." ]; then - true - else - if [ -z "${multidirs}" ]; then - multidirs="${dir}" - else - multidirs="${multidirs} ${dir}" - fi - fi -done - -# Target libraries are configured for the host they run on, so we check -# $host here, not $target. - -case "${host}" in -arm-*-*) - if [ x"$enable_fpu" = xno ] - then - old_multidirs=${multidirs} - multidirs="" - for x in ${old_multidirs}; do - case "${x}" in - *fpu*) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x"$enable_26bit" = xno ] - then - old_multidirs=${multidirs} - multidirs="" - for x in ${old_multidirs}; do - case "${x}" in - *26bit*) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x"$enable_underscore" = xno ] - then - old_multidirs=${multidirs} - multidirs="" - for x in ${old_multidirs}; do - case "${x}" in - *under*) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x"$enable_interwork" = xno ] - then - old_multidirs=${multidirs} - multidirs="" - for x in ${old_multidirs}; do - case "${x}" in - *interwork*) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_biendian = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *le* ) : ;; - *be* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x"$enable_nofmult" = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *nofmult* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - ;; -m68*-*-*) - if [ x$enable_softfloat = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *soft-float* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_m68881 = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *m68881* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_m68000 = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *m68000* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_m68020 = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *m68020* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - ;; -mips*-*-*) - if [ x$enable_single_float = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *single* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_biendian = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *el* ) : ;; - *eb* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_softfloat = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *soft-float* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - ;; -powerpc*-*-* | rs6000*-*-*) - if [ x$enable_aix64 = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *ppc64* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_pthread = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *pthread* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_softfloat = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *soft-float* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_powercpu = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - power | */power | */power/* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_powerpccpu = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *powerpc* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_powerpcos = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *mcall-linux* | *mcall-solaris* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_biendian = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *mlittle* | *mbig* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - if [ x$enable_sysv = xno ] - then - old_multidirs="${multidirs}" - multidirs="" - for x in ${old_multidirs}; do - case "$x" in - *mcall-sysv* ) : ;; - *) multidirs="${multidirs} ${x}" ;; - esac - done - fi - ;; -esac - -# Remove extraneous blanks from multidirs. -# Tests like `if [ -n "$multidirs" ]' require it. -multidirs=`echo "$multidirs" | sed -e 's/^[ ][ ]*//' -e 's/[ ][ ]*$//' -e 's/[ ][ ]*/ /g'` - -# Add code to library's top level makefile to handle building the multilib -# subdirs. - -cat > Multi.tem <<\EOF - -PWD_COMMAND=$${PWDCMD-pwd} - -# FIXME: There should be an @-sign in front of the `if'. -# Leave out until this is tested a bit more. -multi-do: - if [ -z "$(MULTIDIRS)" ]; then \ - true; \ - else \ - rootpre=`${PWD_COMMAND}`/; export rootpre; \ - srcrootpre=`cd $(srcdir); ${PWD_COMMAND}`/; export srcrootpre; \ - lib=`echo "$${rootpre}" | sed -e 's,^.*/\([^/][^/]*\)/$$,\1,'`; \ - compiler="$(CC)"; \ - for i in `$${compiler} --print-multi-lib 2>/dev/null`; do \ - dir=`echo $$i | sed -e 's/;.*$$//'`; \ - if [ "$${dir}" = "." ]; then \ - true; \ - else \ - if [ -d ../$${dir}/$${lib} ]; then \ - flags=`echo $$i | sed -e 's/^[^;]*;//' -e 's/@/ -/g'`; \ - if (cd ../$${dir}/$${lib}; $(MAKE) $(FLAGS_TO_PASS) \ - CFLAGS="$(CFLAGS) $${flags}" \ - CCASFLAGS="$(CCASFLAGS) $${flags}" \ - FCFLAGS="$(FCFLAGS) $${flags}" \ - FFLAGS="$(FFLAGS) $${flags}" \ - ADAFLAGS="$(ADAFLAGS) $${flags}" \ - prefix="$(prefix)" \ - exec_prefix="$(exec_prefix)" \ - GCJFLAGS="$(GCJFLAGS) $${flags}" \ - GOCFLAGS="$(GOCFLAGS) $${flags}" \ - CXXFLAGS="$(CXXFLAGS) $${flags}" \ - LIBCFLAGS="$(LIBCFLAGS) $${flags}" \ - LIBCXXFLAGS="$(LIBCXXFLAGS) $${flags}" \ - LDFLAGS="$(LDFLAGS) $${flags}" \ - MULTIFLAGS="$${flags}" \ - DESTDIR="$(DESTDIR)" \ - INSTALL="$(INSTALL)" \ - INSTALL_DATA="$(INSTALL_DATA)" \ - INSTALL_PROGRAM="$(INSTALL_PROGRAM)" \ - INSTALL_SCRIPT="$(INSTALL_SCRIPT)" \ - $(DO)); then \ - true; \ - else \ - exit 1; \ - fi; \ - else true; \ - fi; \ - fi; \ - done; \ - fi - -# FIXME: There should be an @-sign in front of the `if'. -# Leave out until this is tested a bit more. -multi-clean: - if [ -z "$(MULTIDIRS)" ]; then \ - true; \ - else \ - lib=`${PWD_COMMAND} | sed -e 's,^.*/\([^/][^/]*\)$$,\1,'`; \ - for dir in : $(MULTIDIRS); do \ - test $$dir != : || continue; \ -EOF -cat >>Multi.tem <>Multi.tem <<\EOF - if (cd ../$${dir}/$${lib}; $(MAKE) $(FLAGS_TO_PASS) $(DO)); \ - then true; \ - else exit 1; \ - fi; \ - else true; \ - fi; \ - done; \ - fi -EOF - -cat ${Makefile} Multi.tem > Makefile.tem -rm -f ${Makefile} Multi.tem -mv Makefile.tem ${Makefile} - -fi # ${ml_toplevel_p} = yes - -if [ "${ml_verbose}" = --verbose ]; then - echo "Adding multilib support to ${Makefile} in ${ml_realsrcdir}" - if [ "${ml_toplevel_p}" = yes ]; then - echo "multidirs=${multidirs}" - fi - echo "with_multisubdir=${with_multisubdir}" -fi - -if [ "${srcdir}" = "." ]; then - if [ "${with_target_subdir}" != "." ]; then - ml_srcdotdot="../" - else - ml_srcdotdot="" - fi -else - ml_srcdotdot="" -fi - -if [ -z "${with_multisubdir}" ]; then - ml_subdir= - ml_builddotdot= - : # ml_srcdotdot= # already set -else - ml_subdir="/${with_multisubdir}" - # The '[^/][^/]*' appears that way to work around a SunOS sed bug. - ml_builddotdot=`echo ${with_multisubdir} | sed -e 's:[^/][^/]*:..:g'`/ - if [ "$srcdir" = "." ]; then - ml_srcdotdot=${ml_srcdotdot}${ml_builddotdot} - else - : # ml_srcdotdot= # already set - fi -fi - -if [ "${ml_toplevel_p}" = yes ]; then - ml_do='$(MAKE)' - ml_clean='$(MAKE)' -else - ml_do=true - ml_clean=true -fi - -# TOP is used by newlib and should not be used elsewhere for this purpose. -# MULTI{SRC,BUILD}TOP are the proper ones to use. MULTISRCTOP is empty -# when srcdir != builddir. MULTIBUILDTOP is always some number of ../'s. -# FIXME: newlib needs to be updated to use MULTI{SRC,BUILD}TOP so we can -# delete TOP. Newlib may wish to continue to use TOP for its own purposes -# of course. -# MULTIDIRS is non-empty for the cpu top level Makefile (eg: newlib/Makefile) -# and lists the subdirectories to recurse into. -# MULTISUBDIR is non-empty in each cpu subdirectory's Makefile -# (eg: newlib/h8300h/Makefile) and is the installed subdirectory name with -# a leading '/'. -# MULTIDO is used for targets like all, install, and check where -# $(FLAGS_TO_PASS) augmented with the subdir's compiler option is needed. -# MULTICLEAN is used for the *clean targets. -# -# ??? It is possible to merge MULTIDO and MULTICLEAN into one. They are -# currently kept separate because we don't want the *clean targets to require -# the existence of the compiler (which MULTIDO currently requires) and -# therefore we'd have to record the directory options as well as names -# (currently we just record the names and use --print-multi-lib to get the -# options). - -sed -e "s:^TOP[ ]*=[ ]*\([./]*\)[ ]*$:TOP = ${ml_builddotdot}\1:" \ - -e "s:^MULTISRCTOP[ ]*=.*$:MULTISRCTOP = ${ml_srcdotdot}:" \ - -e "s:^MULTIBUILDTOP[ ]*=.*$:MULTIBUILDTOP = ${ml_builddotdot}:" \ - -e "s:^MULTIDIRS[ ]*=.*$:MULTIDIRS = ${multidirs}:" \ - -e "s:^MULTISUBDIR[ ]*=.*$:MULTISUBDIR = ${ml_subdir}:" \ - -e "s:^MULTIDO[ ]*=.*$:MULTIDO = $ml_do:" \ - -e "s:^MULTICLEAN[ ]*=.*$:MULTICLEAN = $ml_clean:" \ - ${Makefile} > Makefile.tem -rm -f ${Makefile} -mv Makefile.tem ${Makefile} - -# If this is the library's top level, configure each multilib subdir. -# This is done at the end because this is the loop that runs configure -# in each multilib subdir and it seemed reasonable to finish updating the -# Makefile before going on to configure the subdirs. - -if [ "${ml_toplevel_p}" = yes ]; then - -# We must freshly configure each subdirectory. This bit of code is -# actually partially stolen from the main configure script. FIXME. - -if [ -n "${multidirs}" ] && [ -z "${ml_norecursion}" ]; then - - if [ "${ml_verbose}" = --verbose ]; then - echo "Running configure in multilib subdirs ${multidirs}" - echo "pwd: `${PWDCMD-pwd}`" - fi - - ml_origdir=`${PWDCMD-pwd}` - ml_libdir=`echo "$ml_origdir" | sed -e 's,^.*/,,'` - # cd to top-level-build-dir/${with_target_subdir} - cd .. - - for ml_dir in ${multidirs}; do - - if [ "${ml_verbose}" = --verbose ]; then - echo "Running configure in multilib subdir ${ml_dir}" - echo "pwd: `${PWDCMD-pwd}`" - fi - - if [ -d ${ml_dir} ]; then true; else - # ``mkdir -p ${ml_dir}'' See also mkinstalldirs. - pathcomp="" - for d in `echo ":${ml_dir}" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'`; do - pathcomp="$pathcomp$d" - case "$pathcomp" in - -* ) pathcomp=./$pathcomp ;; - esac - if test ! -d "$pathcomp"; then - echo "mkdir $pathcomp" 1>&2 - mkdir "$pathcomp" > /dev/null 2>&1 || lasterr=$? - fi - if test ! -d "$pathcomp"; then - exit $lasterr - fi - pathcomp="$pathcomp/" - done - fi - if [ -d ${ml_dir}/${ml_libdir} ]; then true; else mkdir ${ml_dir}/${ml_libdir}; fi - - # Eg: if ${ml_dir} = m68000/m68881, dotdot = ../../ - dotdot=../`echo ${ml_dir} | sed -e 's|[^/]||g' -e 's|/|../|g'` - - case ${srcdir} in - ".") - echo "Building symlink tree in `${PWDCMD-pwd}`/${ml_dir}/${ml_libdir}" - if [ "${with_target_subdir}" != "." ]; then - ml_unsubdir="../" - else - ml_unsubdir="" - fi - (cd ${ml_dir}/${ml_libdir}; - ../${dotdot}${ml_unsubdir}symlink-tree ../${dotdot}${ml_unsubdir}${ml_libdir} "") - if [ -f ${ml_dir}/${ml_libdir}/${Makefile} ]; then - if [ x"${MAKE}" = x ]; then - (cd ${ml_dir}/${ml_libdir}; make distclean) - else - (cd ${ml_dir}/${ml_libdir}; ${MAKE} distclean) - fi - fi - ml_newsrcdir="." - ml_srcdiroption= - multisrctop=${dotdot} - ;; - *) - case "${srcdir}" in - /* | [A-Za-z]:[\\/]* ) # absolute path - ml_newsrcdir=${srcdir} - ;; - *) # otherwise relative - ml_newsrcdir=${dotdot}${srcdir} - ;; - esac - ml_srcdiroption="-srcdir=${ml_newsrcdir}" - multisrctop= - ;; - esac - - case "${progname}" in - /* | [A-Za-z]:[\\/]* ) ml_recprog=${progname} ;; - *) ml_recprog=${dotdot}${progname} ;; - esac - - # FIXME: POPDIR=${PWD=`pwd`} doesn't work here. - ML_POPDIR=`${PWDCMD-pwd}` - cd ${ml_dir}/${ml_libdir} - - if [ -f ${ml_newsrcdir}/configure ]; then - ml_recprog="${ml_newsrcdir}/configure" - fi - - # find compiler flag corresponding to ${ml_dir} - for i in `${CC-gcc} --print-multi-lib 2>/dev/null`; do - dir=`echo $i | sed -e 's/;.*$//'` - if [ "${dir}" = "${ml_dir}" ]; then - flags=`echo $i | sed -e 's/^[^;]*;//' -e 's/@/ -/g'` - break - fi - done - ml_config_env='CC="${CC_}$flags" CXX="${CXX_}$flags" F77="${F77_}$flags" GCJ="${GCJ_}$flags" GFORTRAN="${GFORTRAN_}$flags" GOC="${GOC_}$flags"' - - if [ "${with_target_subdir}" = "." ]; then - CC_=$CC' ' - CXX_=$CXX' ' - F77_=$F77' ' - GCJ_=$GCJ' ' - GFORTRAN_=$GFORTRAN' ' - GOC_=$GOC' ' - else - # Create a regular expression that matches any string as long - # as ML_POPDIR. - popdir_rx=`echo "${ML_POPDIR}" | sed 's,.,.,g'` - CC_= - for arg in ${CC}; do - case $arg in - -[BIL]"${ML_POPDIR}"/*) - CC_="${CC_}"`echo "X${arg}" | sed -n "s/X\\(-[BIL]${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X-[BIL]${popdir_rx}\\(.*\\)/\1/p"`' ' ;; - "${ML_POPDIR}"/*) - CC_="${CC_}"`echo "X${arg}" | sed -n "s/X\\(${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - *) - CC_="${CC_}${arg} " ;; - esac - done - - CXX_= - for arg in ${CXX}; do - case $arg in - -[BIL]"${ML_POPDIR}"/*) - CXX_="${CXX_}"`echo "X${arg}" | sed -n "s/X\\(-[BIL]${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X-[BIL]${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - "${ML_POPDIR}"/*) - CXX_="${CXX_}"`echo "X${arg}" | sed -n "s/X\\(${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - *) - CXX_="${CXX_}${arg} " ;; - esac - done - - F77_= - for arg in ${F77}; do - case $arg in - -[BIL]"${ML_POPDIR}"/*) - F77_="${F77_}"`echo "X${arg}" | sed -n "s/X\\(-[BIL]${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X-[BIL]${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - "${ML_POPDIR}"/*) - F77_="${F77_}"`echo "X${arg}" | sed -n "s/X\\(${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - *) - F77_="${F77_}${arg} " ;; - esac - done - - GCJ_= - for arg in ${GCJ}; do - case $arg in - -[BIL]"${ML_POPDIR}"/*) - GCJ_="${GCJ_}"`echo "X${arg}" | sed -n "s/X\\(-[BIL]${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X-[BIL]${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - "${ML_POPDIR}"/*) - GCJ_="${GCJ_}"`echo "X${arg}" | sed -n "s/X\\(${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - *) - GCJ_="${GCJ_}${arg} " ;; - esac - done - - GFORTRAN_= - for arg in ${GFORTRAN}; do - case $arg in - -[BIL]"${ML_POPDIR}"/*) - GFORTRAN_="${GFORTRAN_}"`echo "X${arg}" | sed -n "s/X\\(-[BIL]${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X-[BIL]${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - "${ML_POPDIR}"/*) - GFORTRAN_="${GFORTRAN_}"`echo "X${arg}" | sed -n "s/X\\(${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - *) - GFORTRAN_="${GFORTRAN_}${arg} " ;; - esac - done - - GOC_= - for arg in ${GOC}; do - case $arg in - -[BIL]"${ML_POPDIR}"/*) - GOC_="${GOC_}"`echo "X${arg}" | sed -n "s/X\\(-[BIL]${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X-[BIL]${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - "${ML_POPDIR}"/*) - GOC_="${GOC_}"`echo "X${arg}" | sed -n "s/X\\(${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X${popdir_rx}\\(.*\\)/\\1/p"`' ' ;; - *) - GOC_="${GOC_}${arg} " ;; - esac - done - - if test "x${LD_LIBRARY_PATH+set}" = xset; then - LD_LIBRARY_PATH_= - for arg in `echo "$LD_LIBRARY_PATH" | tr ':' ' '`; do - case "$arg" in - "${ML_POPDIR}"/*) - arg=`echo "X${arg}" | sed -n "s/X\\(${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X${popdir_rx}\\(.*\\)/\\1/p"` - ;; - esac - if test "x$LD_LIBRARY_PATH_" != x; then - LD_LIBRARY_PATH_=$LD_LIBRARY_PATH_:$arg - else - LD_LIBRARY_PATH_=$arg - fi - done - ml_config_env="$ml_config_env LD_LIBRARY_PATH=$LD_LIBRARY_PATH_" - fi - - if test "x${SHLIB_PATH+set}" = xset; then - SHLIB_PATH_= - for arg in `echo "$SHLIB_PATH" | tr ':' ' '`; do - case "$arg" in - "${ML_POPDIR}"/*) - arg=`echo "X${arg}" | sed -n "s/X\\(${popdir_rx}\\).*/\\1/p"`/${ml_dir}`echo "X${arg}" | sed -n "s/X${popdir_rx}\\(.*\\)/\\1/p"` - ;; - esac - if test "x$SHLIB_PATH_" != x; then - SHLIB_PATH_=$SHLIB_PATH_:$arg - else - SHLIB_PATH_=$arg - fi - done - ml_config_env="$ml_config_env SHLIB_PATH=$SHLIB_PATH_" - fi - fi - - if eval ${ml_config_env} ${ml_config_shell} ${ml_recprog} \ - --with-multisubdir=${ml_dir} --with-multisrctop=${multisrctop} \ - ${ac_configure_args} ${ml_config_env} ${ml_srcdiroption} ; then - true - else - exit 1 - fi - - cd "${ML_POPDIR}" - - done - - cd "${ml_origdir}" -fi - -fi # ${ml_toplevel_p} = yes -fi # ${enable_multilib} = yes diff --git a/contrib/multilib/multi.m4 b/contrib/multilib/multi.m4 deleted file mode 100644 index 2156e6691..000000000 --- a/contrib/multilib/multi.m4 +++ /dev/null @@ -1,64 +0,0 @@ -## -*- Autoconf -*- -# Copyright (C) 1998-2017 Free Software Foundation, Inc. -# -# This file is free software; the Free Software Foundation -# gives unlimited permission to copy and/or distribute it, -# with or without modifications, as long as this notice is preserved. - -# serial 6 - -# AM_ENABLE_MULTILIB([MAKEFILE], [REL-TO-TOP-SRCDIR]) -# --------------------------------------------------- -# Add --enable-multilib to configure. -AC_DEFUN([AM_ENABLE_MULTILIB], -[# Default to --enable-multilib -AC_ARG_ENABLE(multilib, -[ --enable-multilib build many library versions (default)], -[case "$enableval" in - yes) multilib=yes ;; - no) multilib=no ;; - *) AC_MSG_ERROR([bad value $enableval for multilib option]) ;; - esac], - [multilib=yes]) - -# We may get other options which we leave undocumented: -# --with-target-subdir, --with-multisrctop, --with-multisubdir -# See config-ml.in if you want the gory details. - -if test "$srcdir" = "."; then - if test "$with_target_subdir" != "."; then - multi_basedir="$srcdir/$with_multisrctop../$2" - else - multi_basedir="$srcdir/$with_multisrctop$2" - fi -else - multi_basedir="$srcdir/$2" -fi -AC_SUBST(multi_basedir) - -# Even if the default multilib is not a cross compilation, -# it may be that some of the other multilibs are. -if test $cross_compiling = no && test $multilib = yes \ - && test "x${with_multisubdir}" != x ; then - cross_compiling=maybe -fi - -AC_OUTPUT_COMMANDS([ -# Only add multilib support code if we just rebuilt the top-level -# Makefile. -case " $CONFIG_FILES " in - *" ]m4_default([$1],Makefile)[ "*) - ac_file=]m4_default([$1],Makefile)[ . ${multi_basedir}/config-ml.in - ;; -esac], - [ -srcdir="$srcdir" -host="$host" -target="$target" -with_multisubdir="$with_multisubdir" -with_multisrctop="$with_multisrctop" -with_target_subdir="$with_target_subdir" -ac_configure_args="${multilib_arg} ${ac_configure_args}" -multi_basedir="$multi_basedir" -CONFIG_SHELL=${CONFIG_SHELL-/bin/sh} -CC="$CC"])])dnl diff --git a/contrib/multilib/multilib.am b/contrib/multilib/multilib.am deleted file mode 100644 index 5c98b69bd..000000000 --- a/contrib/multilib/multilib.am +++ /dev/null @@ -1,45 +0,0 @@ -## automake - create Makefile.in from Makefile.am - -## Copyright (C) 1994-2017 Free Software Foundation, Inc. -## This Makefile.in is free software; the Free Software Foundation -## gives unlimited permission to copy and/or distribute it, -## with or without modifications, as long as this notice is preserved. - -## This program is distributed in the hope that it will be useful, -## but WITHOUT ANY WARRANTY; without even the implied warranty of -## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -## GNU General Public License for more details. - -MULTISRCTOP = -MULTIBUILDTOP = -MULTIDIRS = -MULTISUBDIR = -MULTIDO = true -MULTICLEAN = true - -# GNU Make needs to see an explicit $(MAKE) variable in the command it -# runs to enable its job server during parallel builds. Hence the -# comments below. -all-multi: - $(MULTIDO) $(AM_MAKEFLAGS) DO=all multi-do # $(MAKE) -install-multi: - $(MULTIDO) $(AM_MAKEFLAGS) DO=install multi-do # $(MAKE) -mostlyclean-multi: - $(MULTICLEAN) $(AM_MAKEFLAGS) DO=mostlyclean multi-clean # $(MAKE) -clean-multi: - $(MULTICLEAN) $(AM_MAKEFLAGS) DO=clean multi-clean # $(MAKE) -distclean-multi: - $(MULTICLEAN) $(AM_MAKEFLAGS) DO=distclean multi-clean # $(MAKE) -maintainer-clean-multi: - $(MULTICLEAN) $(AM_MAKEFLAGS) DO=maintainer-clean multi-clean # $(MAKE) - -.MAKE .PHONY: all-multi clean-multi distclean-multi install-am \ - install-multi maintainer-clean-multi mostlyclean-multi - -install-exec-local: install-multi - -all-local: all-multi -mostlyclean-local: mostlyclean-multi -clean-local: clean-multi -distclean-local: distclean-multi -maintainer-clean-local: maintainer-clean-multi diff --git a/contrib/multilib/symlink-tree b/contrib/multilib/symlink-tree deleted file mode 100755 index 49de9fc54..000000000 --- a/contrib/multilib/symlink-tree +++ /dev/null @@ -1,78 +0,0 @@ -#!/bin/sh -# Create a symlink tree. -# -# Copyright (C) 1995-2017 Free Software Foundation, Inc. -# -# This file is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, -# Boston, MA 02110-1301, USA. -# -# As a special exception to the GNU General Public License, if you -# distribute this file as part of a program that contains a -# configuration script generated by Autoconf, you may include it under -# the same distribution terms that you use for the rest of that program. -# -# Please report bugs to -# and send patches to . - -# Syntax: symlink-tree srcdir "ignore1 ignore2 ..." -# -# where srcdir is the directory to create a symlink tree to, -# and "ignoreN" is a list of files/directories to ignore. - -prog=$0 -srcdir=$1 -ignore="$2" - -if test $# -lt 1; then - echo "symlink-tree error: Usage: symlink-tree srcdir \"ignore1 ignore2 ...\"" - exit 1 -fi - -ignore_additional=". .. CVS" - -# If we were invoked with a relative path name, adjust ${prog} to work -# in subdirs. -case ${prog} in -/* | [A-Za-z]:[\\/]*) ;; -*) prog=../${prog} ;; -esac - -# Set newsrcdir to something subdirectories can use. -case ${srcdir} in -/* | [A-Za-z]:[\\/]*) newsrcdir=${srcdir} ;; -*) newsrcdir=../${srcdir} ;; -esac - -for f in `ls -a ${srcdir}`; do - if [ -d ${srcdir}/$f ]; then - found= - for i in ${ignore} ${ignore_additional}; do - if [ "$f" = "$i" ]; then - found=yes - fi - done - if [ -z "${found}" ]; then - echo "$f ..working in" - if [ -d $f ]; then true; else mkdir $f; fi - (cd $f; ${prog} ${newsrcdir}/$f "${ignore}") - fi - else - echo "$f ..linked" - rm -f $f - ln -s ${srcdir}/$f . - fi -done - -exit 0 diff --git a/contrib/t/help-multilib.sh b/contrib/t/help-multilib.sh deleted file mode 100755 index ead697381..000000000 --- a/contrib/t/help-multilib.sh +++ /dev/null @@ -1,32 +0,0 @@ -#! /bin/sh -# Copyright (C) 2010-2017 Free Software Foundation, Inc. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -# Make sure that our macro 'AM_ENABLE_MULTILIB' adds proper text to -# the configure help screen. - -. test-init.sh - -cat > configure.ac < aclocal.m4 -$AUTOCONF - -grep_configure_help --enable-multilib ' many library versions \(default\)' - -: diff --git a/contrib/t/local.mk b/contrib/t/local.mk deleted file mode 100644 index b5e1b699b..000000000 --- a/contrib/t/local.mk +++ /dev/null @@ -1,26 +0,0 @@ -## Included by top-level Makefile for Automake. - -## Copyright (C) 1995-2017 Free Software Foundation, Inc. -## -## This program is free software; you can redistribute it and/or modify -## it under the terms of the GNU General Public License as published by -## the Free Software Foundation; either version 2, or (at your option) -## any later version. -## -## This program is distributed in the hope that it will be useful, -## but WITHOUT ANY WARRANTY; without even the implied warranty of -## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -## GNU General Public License for more details. -## -## You should have received a copy of the GNU General Public License -## along with this program. If not, see . - -## -------------------------------- ## -## Tests for stuff in 'contrib/'. ## -## -------------------------------- ## - -contrib_TESTS = \ - %D%/parallel-tests-html.sh \ - %D%/parallel-tests-html-recursive.sh \ - %D%/help-multilib.sh \ - %D%/multilib.sh diff --git a/contrib/t/multilib.sh b/contrib/t/multilib.sh deleted file mode 100755 index 117aa93ff..000000000 --- a/contrib/t/multilib.sh +++ /dev/null @@ -1,160 +0,0 @@ -#! /bin/sh -# Copyright (C) 2003-2017 Free Software Foundation, Inc. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -# Check multilib support. -# Based on a test case from Ralf Corsepius. - -required='gcc GNUmake' -. test-init.sh - -mldir=$am_top_srcdir/contrib/multilib -mkdir m4 -cp "$mldir"/config-ml.in "$mldir"/symlink-tree . -cp "$mldir"/multi.m4 m4 - -ACLOCAL_PATH=${ACLOCAL_PATH+"$ACLOCAL_PATH:"}$(pwd)/m4 -export ACLOCAL_PATH - -cat >configure.ac <<'END' -AC_INIT([multlib], [1.0]) -AC_CONFIG_SRCDIR(libfoo/foo.c) -AC_CONFIG_AUX_DIR(.) -AM_INIT_AUTOMAKE -AC_CONFIG_FILES([Makefile]) -AC_CONFIG_SUBDIRS(libfoo) -AC_CONFIG_SUBDIRS(libbar) -AC_OUTPUT -END - -cat >mycc <<'END' -#! /bin/sh -case ${1+"$@"} in - *-print-multi-lib*) - echo ".;" - echo "debug;@g" - exit 0 ;; -esac -gcc ${1+"$@"} -END - -chmod +x mycc -PATH=$(pwd)$PATH_SEPARATOR$PATH; export PATH - -cat >Makefile.am <<'EOF' -SUBDIRS = @subdirs@ -EXTRA_DIST = config-ml.in symlink-tree -check-all: - test -f debug/libfoo/libfoo.a - test -f debug/libbar/libbar.a - test -f libfoo/libfoo.a - test -f libbar/libbar.a -EOF - -# libfoo tests multilib supports when there are no subdirectories -# libbar tests multilib supports when there are subdirectories - -mkdir libfoo -cp "$mldir"/multilib.am libfoo/ - -cat >libfoo/configure.ac <<'END' -AC_PREREQ(2.57) -AC_INIT(libfoo, 0.1, nobody@localhost) -AC_CONFIG_SRCDIR(foo.c) -# Apparently it doesn't work to have auxdir=.. when -# multilib uses symlinked trees. -AC_CONFIG_AUX_DIR(.) -AM_INIT_AUTOMAKE -AC_PROG_CC -AM_PROG_AR -AC_PROG_RANLIB -AM_ENABLE_MULTILIB(Makefile,[..]) -AC_CONFIG_FILES([Makefile]) -AC_OUTPUT -END - -cat >libfoo/Makefile.am <<'END' -noinst_LIBRARIES = libfoo.a -libfoo_a_SOURCES = foo.c -include $(top_srcdir)/multilib.am -END - -: > libfoo/foo.c - -mkdir libbar -cp "$mldir"/multilib.am libbar/ - -cat >libbar/configure.ac <<'END' -AC_PREREQ(2.57) -AC_INIT(libbar, 0.1, nobody@localhost) -# Apparently it doesn't work to have auxdir=.. when -# multilib uses symlinked trees. -AC_CONFIG_AUX_DIR(.) -AM_INIT_AUTOMAKE -AC_PROG_CC -AM_PROG_AR -AC_PROG_RANLIB -AM_ENABLE_MULTILIB(Makefile,[..]) -AC_CONFIG_FILES([Makefile sub/Makefile]) -AC_OUTPUT -END - -cat >libbar/Makefile.am <<'END' -SUBDIRS = sub -noinst_LIBRARIES = libbar.a -libbar_a_SOURCES = bar.c -include $(top_srcdir)/multilib.am -END - -mkdir libbar/sub -echo 'include $(top_srcdir)/multilib.am' >libbar/sub/Makefile.am -: > libbar/bar.c - -$ACLOCAL -$AUTOCONF -$AUTOMAKE --add-missing - -cd libfoo -$ACLOCAL -$AUTOCONF -$AUTOMAKE --add-missing -cd .. - -cd libbar -$ACLOCAL -$AUTOCONF -$AUTOMAKE --add-missing -cd .. - -# Check VPATH builds -mkdir build -cd build -../configure --enable-multilib CC=mycc -$MAKE -test -f debug/libfoo/libfoo.a -test -f debug/libbar/libbar.a -test -f libfoo/libfoo.a -test -f libbar/libbar.a -$MAKE install -$MAKE distcleancheck - -# Check standard builds. -cd .. -# Why to I have to specify --with-target-subdir? -./configure --enable-multilib --with-target-subdir=. CC=mycc -$MAKE check -DISTCHECK_CONFIGURE_FLAGS='--enable-multilib CC=mycc' $MAKE distcheck - -: diff --git a/contrib/t/parallel-tests-html-recursive.sh b/contrib/t/parallel-tests-html-recursive.sh deleted file mode 100755 index d664b8d62..000000000 --- a/contrib/t/parallel-tests-html-recursive.sh +++ /dev/null @@ -1,163 +0,0 @@ -#! /bin/sh -# Copyright (C) 2012-2017 Free Software Foundation, Inc. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -# Recursive use of 'check-html'. See Automake bug#11287. - -. test-init.sh - -# Try the variants that are tried in check-html.am. -while :; do - for r2h in $RST2HTML rst2html rst2html.py; do - echo "$me: running $r2h --version" - $r2h --version && break 2 - : For shells with busted 'set -e'. - done - skip_all_ "no proper rst2html program found" -done -unset r2h - -cp "$am_top_srcdir"/contrib/check-html.am . \ - || fatal_ "cannot fetch 'check-html.am' from contrib" - -cat >> configure.ac << 'END' -AM_EXTRA_RECURSIVE_TARGETS([check-html]) -AC_CONFIG_FILES([sub/Makefile sub/more/Makefile]) -AC_OUTPUT -END - -cat > Makefile.am << 'END' -SUBDIRS = sub -EXTRA_DIST = $(TESTS) -TEST_SUITE_LOG = mylog.log -TESTS = foo.test bar.sh mu -XFAIL_TESTS = bar.sh -check_SCRIPTS = bla -bla: - echo '#!/bin/sh' > $@-t - echo 'echo Blah Blah Blah' >> $@-t - chmod a+x,a-w $@-t - mv -f $@-t $@ -CLEANFILES = bla -include $(srcdir)/check-html.am -END - -mkdir sub -echo SUBDIRS = more > sub/Makefile.am - -mkdir sub/more -cat > sub/more/Makefile.am << 'END' -include $(top_srcdir)/check-html.am -TEST_EXTENSIONS = .test .sh -TESTS = sh.sh test.test -LOG_COMPILER = true -test.log: sh.log -nodist_check_DATA = x.txt -$(nodist_check_DATA): - echo $@ > $@ -CLEANFILES = $(nodist_check_DATA) -EXTRA_DIST = $(TESTS) -END - -cat > foo.test <<'END' -#! /bin/sh -./bla -exit 77 -END - -cat > bar.sh <<'END' -#! /bin/sh -echo "this is $0" -exit 1 -END - -cat > mu <<'END' -#! /bin/sh -set -x -test -f sub/more/test.log -test -f sub/more/sh.log -END - -cat > sub/more/test.test << 'END' -#!/bin/sh -echo "this is $0" -set -x -test -f sh.log -test -f x.txt -exit 77 -END - -cat > sub/more/sh.sh << 'END' -#!/bin/sh -set -x -test ! -f test.log -test -f x.txt -END - - -cat > sub/more/mu << 'END' -#!/bin/sh -exit 99 -END - -chmod a+x foo.test bar.sh mu sub/more/test.test sub/more/sh.sh - -$ACLOCAL -$AUTOCONF -$AUTOMAKE -a - -./configure - -$MAKE check-html -grep 'Blah Blah Blah' mylog.html -grep 'this is .*bar\.sh' mylog.html -grep 'this is .*test\.test' sub/more/test-suite.html -# check-html should cause check_SCRIPTS and check_DATA to be created. -test -f bla -test -f sub/more/x.txt - -# "make clean" should remove HTML files. -$MAKE clean -test ! -e mylog.html -test ! -e sub/more/test-suite.html -test ! -e bla -test ! -e sub/more/x.txt - -# Create HTML output for individual tests. - -$MAKE bla -$MAKE foo.html bar.sh.html -grep 'Blah Blah Blah' foo.html -grep 'this is .*bar\.sh' bar.sh.html -test ! -e mu.hml - -ocwd=$(pwd) || fatal_ "getting current workind directory" -( cd sub/more \ - && $MAKE sh.html \ - && test -f sh.html \ - && test ! -e test.html \ - && $MAKE test.html \ - && grep 'this is .*test\.test' test.html) || exit 1 - -# HTML output removed by mostlyclean. -$MAKE check-html -test -f mylog.html -test -f sub/more/test-suite.html -$MAKE mostlyclean -find . -name '*.html' | grep . && exit 1 - -$MAKE distcheck - -: diff --git a/contrib/t/parallel-tests-html.sh b/contrib/t/parallel-tests-html.sh deleted file mode 100755 index 9576b6232..000000000 --- a/contrib/t/parallel-tests-html.sh +++ /dev/null @@ -1,144 +0,0 @@ -#! /bin/sh -# Copyright (C) 2009-2017 Free Software Foundation, Inc. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -# Check parallel-tests features: -# - check-html -# - recheck-html - -. test-init.sh - -# Try the variants that are tried in check-html.am. -while :; do - for r2h in $RST2HTML rst2html rst2html.py; do - echo "$me: running $r2h --version" - $r2h --version && break 2 - : For shells with busted 'set -e'. - done - skip_all_ "no proper rst2html program found" -done -unset r2h - -cp "$am_top_srcdir"/contrib/check-html.am . \ - || fatal_ "cannot fetch 'check-html.am' from contrib" - -cat >> configure.ac << 'END' -AC_OUTPUT -END - -cat > Makefile.am << 'END' -TEST_SUITE_LOG = mylog.log -TESTS = foo.test bar.test baz.test -check_SCRIPTS = bla -bla: - echo bla > $@ -CLEANFILES = bla -include $(srcdir)/check-html.am -END - -cat > foo.test <<'END' -#! /bin/sh -echo "this is $0" -test -f bla || exit 1 -exit 0 -END - -cat > bar.test <<'END' -#! /bin/sh -echo "this is $0" -exit 99 -END - -cat > baz.test <<'END' -#! /bin/sh -echo "this is $0" -exit 1 -END - -chmod a+x foo.test bar.test baz.test - -$ACLOCAL -$AUTOCONF -$AUTOMAKE -a - -./configure - -$MAKE check-html && exit 1 -test -f mylog.html -# check-html should cause check_SCRIPTS to be created. -test -f bla - -# "make clean" should remove HTML files. -$MAKE clean -test ! -e mylog.html -test ! -e bla - -# Always create the HTML output, even if there were no failures. -rm -f mylog.html -run_make TESTS=foo.test check-html -test -f mylog.html - -# Create summarizing HTML output also with recheck-html. -rm -f mylog.html -run_make TESTS=foo.test recheck-html -test -f mylog.html - -# Create HTML output for an individual test. -$MAKE foo.html -grep 'this is .*foo\.test' foo.html -test ! -e bar.html -test ! -e baz.html - -# Create HTML output for individual tests. Since the pre-existing log -# files are expected to be used for the HTML conversion, this should -# go smoothly even for failed tests. -$MAKE bar.html baz.html -grep 'this is .*bar\.test' bar.html -grep 'this is .*baz\.test' baz.html - -# HTML output removed by mostlyclean. -$MAKE mostlyclean -test ! -e foo.html -test ! -e bar.html -test ! -e baz.html -test ! -e mylog.html - -# check-html and recheck-html should cause check_SCRIPTS to be created, -# and recheck-html should rerun no tests if check has not been run. - -$MAKE clean -test ! -e mylog.html -run_make TEST_LOGS=foo.log check-html -test -f bla -test -f foo.log -test ! -e bar.log -test ! -e baz.log -test -f mylog.html - -$MAKE clean -run_make TESTS=foo.test recheck-html -test -f bla -test ! -e foo.log -test -f mylog.html - -$MAKE clean -$MAKE recheck-html -test -f bla -test ! -e foo.log -test ! -e bar.log -test ! -e baz.log -test -f mylog.html - -: diff --git a/contrib/tap-driver.pl b/contrib/tap-driver.pl deleted file mode 100755 index d631aba91..000000000 --- a/contrib/tap-driver.pl +++ /dev/null @@ -1,563 +0,0 @@ -#! /usr/bin/env perl -# Copyright (C) 2011-2017 Free Software Foundation, Inc. -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -# As a special exception to the GNU General Public License, if you -# distribute this file as part of a program that contains a -# configuration script generated by Autoconf, you may include it under -# the same distribution terms that you use for the rest of that program. - -# This file is maintained in Automake, please report -# bugs to or send patches to -# . - -# ---------------------------------- # -# Imports, static data, and setup. # -# ---------------------------------- # - -use warnings FATAL => 'all'; -use strict; -use Getopt::Long (); -use TAP::Parser; - -my $VERSION = '2013-12-24.15'; # UTC - -my $ME = "tap-driver.pl"; - -my $USAGE = <<'END'; -Usage: - tap-driver --test-name=NAME --log-file=PATH --trs-file=PATH - [--expect-failure={yes|no}] [--color-tests={yes|no}] - [--enable-hard-errors={yes|no}] [--ignore-exit] - [--diagnostic-string=STRING] [--merge|--no-merge] - [--comments|--no-comments] [--] TEST-COMMAND -The '--test-name', '--log-file' and '--trs-file' options are mandatory. -END - -my $HELP = "$ME: TAP-aware test driver for Automake testsuite harness." . - "\n" . $USAGE; - -# Keep this in sync with 'lib/am/check.am:$(am__tty_colors)'. -my %COLOR = ( - red => "\e[0;31m", - grn => "\e[0;32m", - lgn => "\e[1;32m", - blu => "\e[1;34m", - mgn => "\e[0;35m", - brg => "\e[1m", - std => "\e[m", -); - -# It's important that NO_PLAN evaluates "false" as a boolean. -use constant NO_PLAN => 0; -use constant EARLY_PLAN => 1; -use constant LATE_PLAN => 2; - -# ------------------- # -# Global variables. # -# ------------------- # - -my $testno = 0; # Number of test results seen so far. -my $bailed_out = 0; # Whether a "Bail out!" directive has been seen. -my $parser; # TAP parser object (will be initialized later). - -# Whether the TAP plan has been seen or not, and if yes, which kind -# it is ("early" is seen before any test result, "late" otherwise). -my $plan_seen = NO_PLAN; - -# ----------------- # -# Option parsing. # -# ----------------- # - -my %cfg = ( - "color-tests" => 0, - "expect-failure" => 0, - "merge" => 0, - "comments" => 0, - "ignore-exit" => 0, -); - -my $test_script_name = undef; -my $log_file = undef; -my $trs_file = undef; -my $diag_string = "#"; - -Getopt::Long::GetOptions - ( - 'help' => sub { print $HELP; exit 0; }, - 'version' => sub { print "$ME $VERSION\n"; exit 0; }, - 'test-name=s' => \$test_script_name, - 'log-file=s' => \$log_file, - 'trs-file=s' => \$trs_file, - 'color-tests=s' => \&bool_opt, - 'expect-failure=s' => \&bool_opt, - 'enable-hard-errors=s' => sub {}, # No-op. - 'diagnostic-string=s' => \$diag_string, - 'comments' => sub { $cfg{"comments"} = 1; }, - 'no-comments' => sub { $cfg{"comments"} = 0; }, - 'merge' => sub { $cfg{"merge"} = 1; }, - 'no-merge' => sub { $cfg{"merge"} = 0; }, - 'ignore-exit' => sub { $cfg{"ignore-exit"} = 1; }, - ) or exit 1; - -# ------------- # -# Prototypes. # -# ------------- # - -sub add_test_result ($); -sub bool_opt ($$); -sub colored ($$); -sub copy_in_global_log (); -sub decorate_result ($); -sub extract_tap_comment ($); -sub finish (); -sub get_global_test_result (); -sub get_test_exit_message (); -sub get_test_results (); -sub handle_tap_bailout ($); -sub handle_tap_plan ($); -sub handle_tap_result ($); -sub is_null_string ($); -sub main (@); -sub must_recheck (); -sub report ($;$); -sub setup_io (); -sub setup_parser (@); -sub stringify_result_obj ($); -sub testsuite_error ($); -sub trap_perl_warnings_and_errors (); -sub write_test_results (); -sub yn ($); - -# -------------- # -# Subroutines. # -# -------------- # - -sub bool_opt ($$) -{ - my ($opt, $val) = @_; - if ($val =~ /^(?:y|yes)\z/i) - { - $cfg{$opt} = 1; - } - elsif ($val =~ /^(?:n|no)\z/i) - { - $cfg{$opt} = 0; - } - else - { - die "$ME: invalid argument '$val' for option '$opt'\n"; - } -} - -# If the given string is undefined or empty, return true, otherwise -# return false. This function is useful to avoid pitfalls like: -# if ($message) { print "$message\n"; } -# which wouldn't print anything if $message is the literal "0". -sub is_null_string ($) -{ - my $str = shift; - return ! (defined $str and length $str); -} - -# Convert a boolean to a "yes"/"no" string. -sub yn ($) -{ - my $bool = shift; - return $bool ? "yes" : "no"; -} - -TEST_RESULTS : -{ - my (@test_results_list, %test_results_seen); - - sub add_test_result ($) - { - my $res = shift; - push @test_results_list, $res; - $test_results_seen{$res} = 1; - } - - sub get_test_results () - { - return @test_results_list; - } - - # Whether the test script should be re-run by "make recheck". - sub must_recheck () - { - return grep { !/^(?:XFAIL|PASS|SKIP)$/ } (keys %test_results_seen); - } - - # Whether the content of the log file associated to this test should - # be copied into the "global" test-suite.log. - sub copy_in_global_log () - { - return grep { not $_ eq "PASS" } (keys %test_results_seen); - } - - sub get_global_test_result () - { - return "ERROR" - if $test_results_seen{"ERROR"}; - return "FAIL" - if $test_results_seen{"FAIL"} || $test_results_seen{"XPASS"}; - return "SKIP" - if scalar keys %test_results_seen == 1 && $test_results_seen{"SKIP"}; - return "PASS"; - } - -} - -sub write_test_results () -{ - open RES, ">", $trs_file or die "$ME: opening $trs_file: $!\n"; - print RES ":global-test-result: " . get_global_test_result . "\n"; - print RES ":recheck: " . yn (must_recheck) . "\n"; - print RES ":copy-in-global-log: " . yn (copy_in_global_log) . "\n"; - foreach my $result (get_test_results) - { - print RES ":test-result: $result\n"; - } - close RES or die "$ME: closing $trs_file: $!\n"; -} - -sub trap_perl_warnings_and_errors () -{ - $SIG{__WARN__} = $SIG{__DIE__} = sub - { - # Be sure to send the warning/error message to the original stderr - # (presumably the console), not into the log file. - open STDERR, ">&OLDERR"; - die @_; - } -} - -sub setup_io () -{ - # Redirect stderr and stdout to a temporary log file. Save the - # original stdout stream, since we need it to print testsuite - # progress output. Save original stderr stream, so that we can - # redirect warning and error messages from perl there. - open LOG, ">", $log_file or die "$ME: opening $log_file: $!\n"; - open OLDOUT, ">&STDOUT" or die "$ME: duplicating stdout: $!\n"; - open OLDERR, ">&STDERR" or die "$ME: duplicating stdout: $!\n"; - *OLDERR = *OLDERR; # To pacify a "used only once" warning. - trap_perl_warnings_and_errors; - open STDOUT, ">&LOG" or die "$ME: redirecting stdout: $!\n"; - open STDERR, ">&LOG" or die "$ME: redirecting stderr: $!\n"; -} - -sub setup_parser (@) -{ - local $@ = ''; - eval { $parser = TAP::Parser->new ({exec => \@_, merge => $cfg{merge}}) }; - if ($@ ne '') - { - # Don't use the error message in $@ as set by TAP::Parser, since - # currently it's both too generic (at the point of being basically - # useless) and quite long. - report "ERROR", "- couldn't execute test script"; - finish; - } -} - -sub get_test_exit_message () -{ - my $wstatus = $parser->wait; - # Watch out for possible internal errors. - die "$ME: couldn't get the exit status of the TAP producer" - unless defined $wstatus; - # Return an undefined value if the producer exited with success. - return unless $wstatus; - # Otherwise, determine whether it exited with error or was terminated - # by a signal. - use POSIX qw (WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG); - if (WIFEXITED ($wstatus)) - { - return sprintf "exited with status %d", WEXITSTATUS ($wstatus); - } - elsif (WIFSIGNALED ($wstatus)) - { - return sprintf "terminated by signal %d", WTERMSIG ($wstatus); - } - else - { - return "terminated abnormally"; - } -} - -sub stringify_result_obj ($) -{ - my $result_obj = shift; - my $COOKED_PASS = $cfg{"expect-failure"} ? "XPASS": "PASS"; - my $COOKED_FAIL = $cfg{"expect-failure"} ? "XFAIL": "FAIL"; - if ($result_obj->is_unplanned || $result_obj->number != $testno) - { - return "ERROR"; - } - elsif ($plan_seen == LATE_PLAN) - { - return "ERROR"; - } - elsif (!$result_obj->directive) - { - return $result_obj->is_ok ? $COOKED_PASS: $COOKED_FAIL; - } - elsif ($result_obj->has_todo) - { - return $result_obj->is_actual_ok ? "XPASS" : "XFAIL"; - } - elsif ($result_obj->has_skip) - { - return $result_obj->is_ok ? "SKIP" : $COOKED_FAIL; - } - die "$ME: INTERNAL ERROR"; # NOTREACHED -} - -sub colored ($$) -{ - my ($color_name, $text) = @_; - return $COLOR{$color_name} . $text . $COLOR{'std'}; -} - -sub decorate_result ($) -{ - my $result = shift; - return $result unless $cfg{"color-tests"}; - my %color_for_result = - ( - "ERROR" => 'mgn', - "PASS" => 'grn', - "XPASS" => 'red', - "FAIL" => 'red', - "XFAIL" => 'lgn', - "SKIP" => 'blu', - ); - if (my $color = $color_for_result{$result}) - { - return colored ($color, $result); - } - else - { - return $result; # Don't colorize unknown stuff. - } -} - -sub report ($;$) -{ - my ($msg, $result, $explanation) = (undef, @_); - if ($result =~ /^(?:X?(?:PASS|FAIL)|SKIP|ERROR)/) - { - $msg = ": $test_script_name"; - add_test_result $result; - } - elsif ($result eq "#") - { - $msg = " $test_script_name:"; - } - else - { - die "$ME: INTERNAL ERROR"; # NOTREACHED - } - $msg .= " $explanation" if defined $explanation; - $msg .= "\n"; - # Output on console might be colorized. - print OLDOUT decorate_result ($result) . $msg; - # Log the result in the log file too, to help debugging (this is - # especially true when said result is a TAP error or "Bail out!"). - print $result . $msg; -} - -sub testsuite_error ($) -{ - report "ERROR", "- $_[0]"; -} - -sub handle_tap_result ($) -{ - $testno++; - my $result_obj = shift; - - my $test_result = stringify_result_obj $result_obj; - my $string = $result_obj->number; - - my $description = $result_obj->description; - $string .= " $description" - unless is_null_string $description; - - if ($plan_seen == LATE_PLAN) - { - $string .= " # AFTER LATE PLAN"; - } - elsif ($result_obj->is_unplanned) - { - $string .= " # UNPLANNED"; - } - elsif ($result_obj->number != $testno) - { - $string .= " # OUT-OF-ORDER (expecting $testno)"; - } - elsif (my $directive = $result_obj->directive) - { - $string .= " # $directive"; - my $explanation = $result_obj->explanation; - $string .= " $explanation" - unless is_null_string $explanation; - } - - report $test_result, $string; -} - -sub handle_tap_plan ($) -{ - my $plan = shift; - if ($plan_seen) - { - # Error, only one plan per stream is acceptable. - testsuite_error "multiple test plans"; - return; - } - # The TAP plan can come before or after *all* the TAP results; we speak - # respectively of an "early" or a "late" plan. If we see the plan line - # after at least one TAP result has been seen, assume we have a late - # plan; in this case, any further test result seen after the plan will - # be flagged as an error. - $plan_seen = ($testno >= 1 ? LATE_PLAN : EARLY_PLAN); - # If $testno > 0, we have an error ("too many tests run") that will be - # automatically dealt with later, so don't worry about it here. If - # $plan_seen is true, we have an error due to a repeated plan, and that - # has already been dealt with above. Otherwise, we have a valid "plan - # with SKIP" specification, and should report it as a particular kind - # of SKIP result. - if ($plan->directive && $testno == 0) - { - my $explanation = is_null_string ($plan->explanation) ? - undef : "- " . $plan->explanation; - report "SKIP", $explanation; - } -} - -sub handle_tap_bailout ($) -{ - my ($bailout, $msg) = ($_[0], "Bail out!"); - $bailed_out = 1; - $msg .= " " . $bailout->explanation - unless is_null_string $bailout->explanation; - testsuite_error $msg; -} - -sub extract_tap_comment ($) -{ - my $line = shift; - if (index ($line, $diag_string) == 0) - { - # Strip leading '$diag_string' from '$line'. - $line = substr ($line, length ($diag_string)); - # And strip any leading and trailing whitespace left. - $line =~ s/(?:^\s*|\s*$)//g; - # Return what is left (if any). - return $line; - } - return ""; -} - -sub finish () -{ - write_test_results; - close LOG or die "$ME: closing $log_file: $!\n"; - exit 0; -} - -sub main (@) -{ - setup_io; - setup_parser @_; - - while (defined (my $cur = $parser->next)) - { - # Verbatim copy any input line into the log file. - print $cur->raw . "\n"; - # Parsing of TAP input should stop after a "Bail out!" directive. - next if $bailed_out; - - if ($cur->is_plan) - { - handle_tap_plan ($cur); - } - elsif ($cur->is_test) - { - handle_tap_result ($cur); - } - elsif ($cur->is_bailout) - { - handle_tap_bailout ($cur); - } - elsif ($cfg{comments}) - { - my $comment = extract_tap_comment ($cur->raw); - report "#", "$comment" if length $comment; - } - } - # A "Bail out!" directive should cause us to ignore any following TAP - # error, as well as a non-zero exit status from the TAP producer. - if (!$bailed_out) - { - if (!$plan_seen) - { - testsuite_error "missing test plan"; - } - elsif ($parser->tests_planned != $parser->tests_run) - { - my ($planned, $run) = ($parser->tests_planned, $parser->tests_run); - my $bad_amount = $run > $planned ? "many" : "few"; - testsuite_error (sprintf "too %s tests run (expected %d, got %d)", - $bad_amount, $planned, $run); - } - if (!$cfg{"ignore-exit"}) - { - my $msg = get_test_exit_message (); - testsuite_error $msg if $msg; - } - } - finish; -} - -# ----------- # -# Main code. # -# ----------- # - -main @ARGV; - -# Local Variables: -# perl-indent-level: 2 -# perl-continued-statement-offset: 2 -# perl-continued-brace-offset: 0 -# perl-brace-offset: 0 -# perl-brace-imaginary-offset: 0 -# perl-label-offset: -2 -# cperl-indent-level: 2 -# cperl-brace-offset: 0 -# cperl-continued-brace-offset: 0 -# cperl-label-offset: -2 -# cperl-extra-newline-before-brace: t -# cperl-merge-trailing-else: nil -# cperl-continued-statement-offset: 2 -# eval: (add-hook 'write-file-hooks 'time-stamp) -# time-stamp-start: "my $VERSION = " -# time-stamp-format: "'%:y-%02m-%02d.%02H'" -# time-stamp-time-zone: "UTC0" -# time-stamp-end: "; # UTC" -# End: diff --git a/doc/amhello/Makefile.am b/doc/amhello/Makefile.am deleted file mode 100644 index 706c2f298..000000000 --- a/doc/amhello/Makefile.am +++ /dev/null @@ -1,6 +0,0 @@ -# Copyright (C) 2006-2017 Free Software Foundation, Inc. -# This Makefile.am is free software; the Free Software Foundation -# gives unlimited permission to copy, distribute and modify it. - -SUBDIRS = src -dist_doc_DATA = README diff --git a/doc/amhello/README b/doc/amhello/README deleted file mode 100644 index d24723a81..000000000 --- a/doc/amhello/README +++ /dev/null @@ -1,2 +0,0 @@ -This is a demonstration package for GNU Automake. -Type `info Automake' to read the Automake manual. diff --git a/doc/amhello/configure.ac b/doc/amhello/configure.ac deleted file mode 100644 index 381344d7a..000000000 --- a/doc/amhello/configure.ac +++ /dev/null @@ -1,13 +0,0 @@ -# Copyright (C) 2006-2017 Free Software Foundation, Inc. -# This configure.ac script is free software; the Free Software Foundation -# gives unlimited permission to copy, distribute and modify it. - -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 diff --git a/doc/amhello/src/Makefile.am b/doc/amhello/src/Makefile.am deleted file mode 100644 index e52ff3c3b..000000000 --- a/doc/amhello/src/Makefile.am +++ /dev/null @@ -1,6 +0,0 @@ -# Copyright (C) 2006-2017 Free Software Foundation, Inc. -# This Makefile.am is free software; the Free Software Foundation -# gives unlimited permission to copy, distribute and modify it. - -bin_PROGRAMS = hello -hello_SOURCES = main.c diff --git a/doc/amhello/src/main.c b/doc/amhello/src/main.c deleted file mode 100644 index 7a7ebec77..000000000 --- a/doc/amhello/src/main.c +++ /dev/null @@ -1,14 +0,0 @@ -/* Copyright (C) 2006-2017 Free Software Foundation, Inc. - This program is free software; the Free Software Foundation - gives unlimited permission to copy, distribute and modify it. */ - -#include -#include - -int -main (void) -{ - puts ("Hello World!"); - puts ("This is " PACKAGE_STRING "."); - return 0; -} diff --git a/doc/automake-history.texi b/doc/automake-history.texi deleted file mode 100644 index 75141f97a..000000000 --- a/doc/automake-history.texi +++ /dev/null @@ -1,1214 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename automake-history.info -@settitle automake-history -@setchapternewpage on -@c %**end of header - -@copying - -This manual describes (part of) the history of GNU Automake, a program -that creates GNU standards-compliant Makefiles from template files. - -Copyright @copyright{} 1995-2017 Free Software Foundation, Inc. - -@quotation -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.'' - -@end quotation -@end copying - -@titlepage -@title Brief History of Automake -@author David MacKenzie -@author Tom Tromey -@author Alexandre Duret-Lutz -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@comment node-name, next, previous, up -@top Brief History of Automake - -@insertcopying - -@menu -* Timeline:: The Automake story. -* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking -* Releases:: Release statistics -* Copying This Manual:: How to make copies of this manual - -@detailmenu - --- The Detailed Node Listing --- - -Evolution of Automatic Dependency Tracking - -* First Take on Dependencies:: Precomputed dependency tracking -* Dependencies As Side Effects:: Update at developer compile time -* Dependencies for the User:: Update at user compile time -* Techniques for Dependencies:: Alternative approaches - -Techniques for Computing Dependencies - -* Recommendations for Tool Writers:: -* Future Directions for Dependencies:: - -Copying This Manual - -* GNU Free Documentation License:: License for copying this manual - -@end detailmenu -@end menu - -@end ifnottex - -@node Timeline -@chapter Timeline - -@table @asis -@item 1994-09-19 First CVS commit. - -If we can trust the CVS repository, David J.@tie{}MacKenzie (djm) started -working on Automake (or AutoMake, as it was spelt then) this Monday. - -The first version of the @command{automake} script looks as follows. - -@example -#!/bin/sh - -status=0 - -for makefile -do - if test ! -f $@{makefile@}.am; then - echo "automake: $@{makefile@}.am: No such honkin' file" - status=1 - continue - fi - - exec 4> $@{makefile@}.in - -done -@end example - -From this you can already see that Automake will be about reading -@file{*.am} file and producing @file{*.in} files. You cannot see -anything else, but if you also know that David is the one who created -Autoconf two years before you can guess the rest. - -Several commits follow, and by the end of the day Automake is -reported to work for GNU fileutils and GNU m4. - -The modus operandi is the one that is still used today: variable -assignments in @file{Makefile.am} files trigger injections of -precanned @file{Makefile} fragments into the generated -@file{Makefile.in}. The use of @file{Makefile} fragments was inspired -by the 4.4BSD @command{make} and include files, however Automake aims -to be portable and to conform to the GNU standards for @file{Makefile} -variables and targets. - -At this point, the most recent release of Autoconf is version 1.11, -and David is preparing to release Autoconf 2.0 in late October. As a -matter of fact, he will barely touch Automake after September. - -@item 1994-11-05 David MacKenzie's last commit. - -At this point Automake is a 200 line portable shell script, plus 332 -lines of @file{Makefile} fragments. In the @file{README}, David -states his ambivalence between ``portable shell'' and ``more -appropriate language'': - -@quotation -I wrote it keeping in mind the possibility of it becoming an Autoconf -macro, so it would run at configure-time. That would slow -configuration down a bit, but allow users to modify the Makefile.am -without needing to fetch the AutoMake package. And, the Makefile.in -files wouldn't need to be distributed. But all of AutoMake would. So -I might reimplement AutoMake in Perl, m4, or some other more -appropriate language. -@end quotation - -Automake is described as ``an experimental Makefile generator''. -There is no documentation. Adventurous users are referred to the -examples and patches needed to use Automake with GNU m4 1.3, fileutils -3.9, time 1.6, and development versions of find and indent. - -These examples seem to have been lost. However at the time of writing -(10 years later in September, 2004) the FSF still distributes a -package that uses this version of Automake: check out GNU termutils -2.0. - -@item 1995-11-12 Tom Tromey's first commit. - -After one year of inactivity, Tom Tromey takes over the package. -Tom was working on GNU cpio back then, and doing this just for fun, -having trouble finding a project to contribute to. So while hacking -he wanted to bring the @file{Makefile.in} up to GNU standards. This -was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/}, -grabbed it and tried it out. - -Tom didn't talk to djm about it until later, just to make sure he -didn't mind if he made a release. He did a bunch of early releases to -the Gnits folks. - -Gnits was (and still is) totally informal, just a few GNU friends who -Fran@,cois Pinard knew, who were all interested in making a common -infrastructure for GNU projects, and shared a similar outlook on how -to do it. So they were able to make some progress. It came along -with Autoconf and extensions thereof, and then Automake from David and -Tom (who were both gnitsians). One of their ideas was to write a -document paralleling the GNU standards, that was more strict in some -ways and more detailed. They never finished the GNITS standards, but -the ideas mostly made their way into Automake. - -@item 1995-11-23 Automake 0.20 - -Besides introducing automatic dependency tracking (@pxref{Dependency -Tracking Evolution}), this version also supplies a 9-page manual. - -At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not -exist, so many things had to be done by hand. For instance, here is -what a configure.in (this is the former name of the -@file{configure.ac} we use today) must contain in order to use -Automake 0.20: - -@example -PACKAGE=cpio -VERSION=2.3.911 -AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE") -AC_DEFINE_UNQUOTED(VERSION, "$VERSION") -AC_SUBST(PACKAGE) -AC_SUBST(VERSION) -AC_ARG_PROGRAM -AC_PROG_INSTALL -@end example - -(Today all of the above is achieved by @code{AC_INIT} and -@code{AM_INIT_AUTOMAKE}.) - -Here is how programs are specified in @file{Makefile.am}: - -@example -PROGRAMS = hello -hello_SOURCES = hello.c -@end example - -This looks pretty much like what we do today, except the -@code{PROGRAMS} variable has no directory prefix specifying where -@file{hello} should be installed: all programs are installed in -@samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs -that must be built but not installed (it is called -@code{noinst_PROGRAMS} nowadays). - -Programs can be built conditionally using @code{AC_SUBST}itutions: - -@example -PROGRAMS = @@progs@@ -AM_PROGRAMS = foo bar baz -@end example - -(@code{AM_PROGRAMS} has since then been renamed to -@code{EXTRA_PROGRAMS}.) - -Similarly scripts, static libraries, and data can be built and installed -using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables. -However @code{LIBRARIES} were treated a bit specially in that Automake -did automatically supply the @file{lib} and @file{.a} prefixes. -Therefore to build @file{libcpio.a}, one had to write - -@example -LIBRARIES = cpio -cpio_SOURCES = ... -@end example - -Extra files to distribute must be listed in @code{DIST_OTHER} (the -ancestor of @code{EXTRA_DIST}). Also extra directories that are to be -distributed should appear in @code{DIST_SUBDIRS}, but the manual -describes this as a temporary ugly hack (today extra directories should -also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used -for another purpose, @pxref{Conditional Subdirectories, , Conditional -Subdirectories, automake, GNU Automake}). - -@item 1995-11-26 Automake 0.21 - -In less time than it takes to cook a frozen pizza, Tom rewrites -Automake using Perl. At this time Perl 5 is only one year old, and -Perl 4.036 is in use at many sites. Supporting several Perl versions -has been a source of problems through the whole history of Automake. - -If you never used Perl 4, imagine Perl 5 without objects, without -@samp{my} variables (only dynamically scoped @samp{local} variables), -without function prototypes, with function calls that needs to be -prefixed with @samp{&}, etc. Traces of this old style can still be -found in today's @command{automake}. - -@item 1995-11-28 Automake 0.22 -@itemx 1995-11-29 Automake 0.23 - -Bug fixes. - -@item 1995-12-08 Automake 0.24 -@itemx 1995-12-10 Automake 0.25 - -Releases are raining. 0.24 introduces the uniform naming scheme we -use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS}, -@code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However -@code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still -in use; and @code{TEXINFOS} and @code{MANS} still have no directory -prefixes.) Adding support for prefixes like that was one of the major -ideas in @command{automake}; it has lasted pretty well. - -AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois -Pinard's doing). - -0.25 fixes a Perl 4 portability bug. - -@item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils. -@item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar. - -@item 1996-01-03 Automake 0.26 -@itemx 1996-01-03 Automake 0.27 - -Of the many changes and suggestions sent by Fran@,cois Pinard and -included in 0.26, perhaps the most important is the advice that to -ease customization a user rule or variable definition should always -override an Automake rule or definition. - -Gordon Matzigkeit and Jim Meyering are two other early contributors -that have been sending fixes. - -0.27 fixes yet another Perl 4 portability bug. - -@item 1996-01-13 Automake 0.28 - -Automake starts scanning @file{configure.in} for @code{LIBOBJS} -support. This is an important step because until this version -Automake only knew about the @file{Makefile.am}s it processed. -@file{configure.in} was Autoconf's world and the link between Autoconf -and Automake had to be done by the @file{Makefile.am} author. For -instance, if @file{config.h} was generated by @file{configure}, it was the -package maintainer's responsibility to define the @code{CONFIG_HEADER} -variable in each @file{Makefile.am}. - -Succeeding releases will rely more and more on scanning -@file{configure.in} to better automate the Autoconf integration. - -0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the -@option{--gnu} and @option{--gnits} options, the latter being stricter. - -@item 1996-02-07 Automake 0.29 - -Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone, -and rebuild rules for @file{configure}-generated file are -automatically output. - -@code{TEXINFOS} and @code{MANS} converted to the uniform naming -scheme. - -@item 1996-02-24 Automake 0.30 - -The test suite is born. It contains 9 tests. From now on test cases -will be added pretty regularly (@pxref{Releases}), and this proved to -be really helpful later on. - -@code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}. - -All the third-party Autoconf macros, written mostly by Fran@,cois -Pinard (and later Jim Meyering), are distributed in Automake's -hand-written @file{aclocal.m4} file. Package maintainers are expected -to extract the necessary macros from this file. (In previous versions -you had to copy and paste them from the manual...) - -@item 1996-03-11 Automake 0.31 - -The test suite in 0.30 was run via a long @code{check-local} rule. Upon -Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output -whenever the @code{TESTS} variable is defined. - -@code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_} -prefix is introduced. The syntax is now the same as today. - -@item 1996-03-15 Gordon Matzigkeit starts writing libtool. - -@item 1996-04-27 Automake 0.32 - -@code{-hook} targets are introduced; an idea from Dieter Baron. - -@file{*.info} files, which were output in the build directory are -now built in the source directory, because they are distributed. It -seems these files like to move back and forth as that will happen -again in future versions. - -@item 1996-05-18 Automake 0.33 - -Gord Matzigkeit's main two contributions: - -@itemize -@item very preliminary libtool support -@item the distcheck rule -@end itemize - -Although they were very basic at this point, these are probably -among the top features for Automake today. - -Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE}, since -then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its author -(@pxref{maintainer-mode, , maintainer-mode, automake, GNU Automake}). - -@item 1996-05-28 Automake 1.0 - -After only six months of heavy development, the @command{automake} script is -3134 lines long, plus 973 lines of @file{Makefile} fragments. The -package has 30 pages of documentation, and 38 test cases. -@file{aclocal.m4} contains 4 macros. - -From now on and until version 1.4, new releases will occur at a rate -of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have -been the name of beta releases for 1.2. This is the first time -Automake uses suffix letters to designate beta releases, a habit that -lasts. - -@item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux. - -@item 1996-11-26 David J.@tie{}MacKenzie releases Autoconf 2.12. - -Between June and October, the Autoconf development is almost stalled. -Roland McGrath has been working at the beginning of the year. David -comes back in November to release 2.12, but he won't touch Autoconf -anymore after this year, and Autoconf then really stagnates. The -desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits. - -@item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive - -The mailing list is announced as follows: -@smallexample -I've created the "automake" mailing list. It is -"automake@@gnu.ai.mit.edu". Administrivia, as always, to -automake-request@@gnu.ai.mit.edu. - -The charter of this list is discussion of automake, autoconf, and -other configuration/portability tools (e.g., libtool). It is expected -that discussion will range from pleas for help all the way up to -patches. - -This list is archived on the FSF machines. Offhand I don't know if -you can get the archive without an account there. - -This list is open to anybody who wants to join. Tell all your -friends! --- Tom Tromey -@end smallexample - -Before that people were discussing Automake privately, on the Gnits -mailing list (which is not public either), and less frequently on -@code{gnu.misc.discuss}. - -@code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never -noticed. The archives of the early years of the -@code{automake@@gnu.org} list have been lost, so today it is almost -impossible to find traces of discussions that occurred before 1999. -This has been annoying more than once, as such discussions can be -useful to understand the rationale behind a piece of uncommented code -that was introduced back then. - -@item 1997-06-22 Automake 1.2 - -Automake developments continues, and more and more new Autoconf macros -are required. Distributing them in @file{aclocal.m4} and requiring -people to browse this file to extract the relevant macros becomes -uncomfortable. Ideally, some of them should be contributed to -Autoconf so that they can be used directly, however Autoconf is -currently inactive. Automake 1.2 consequently introduces -@command{aclocal} (@command{aclocal} was actually started on -1996-07-28), a tool that automatically constructs an @file{aclocal.m4} -file from a repository of third-party macros. Because Autoconf has -stalled, Automake also becomes a kind of repository for such -third-party macros, even macros completely unrelated to Automake (for -instance macros that fix broken Autoconf macros). - -The 1.2 release contains 20 macros, including the -@code{AM_INIT_AUTOMAKE} macro that simplifies the creation of -@file{configure.in}. - -Libtool is fully supported using @code{*_LTLIBRARIES}. - -The missing script is introduced by Fran@,cois Pinard; it is meant -to be a better solution than @code{AM_MAINTAINER_MODE} -(@pxref{maintainer-mode, , maintainer-mode, automake, GNU Automake}). - -Conditionals support was implemented by Ian Lance Taylor. At the -time, Tom and Ian were working on an internal project at Cygnus. They -were using ILU, which is pretty similar to CORBA@. They wanted to -integrate ILU into their build, which was all @file{configure}-based, -and Ian thought that adding conditionals to @command{automake} was -simpler than doing all the work in @file{configure} (which was the -standard at the time). So this was actually funded by Cygnus. - -This very useful but tricky feature will take a lot of time to -stabilize. (At the time this text is written, there are still -primaries that have not been updated to support conditional -definitions in Automake 1.9.) - -The @command{automake} script has almost doubled: 6089 lines of Perl, -plus 1294 lines of @file{Makefile} fragments. - -@item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0. - -@item 1998-04-05 Automake 1.3 - -This is a small advance compared to 1.2. -It adds support for assembly, and preliminary support for Java. - -Perl 5.004_04 is out, but fixes to support Perl 4 are still -regularly submitted whenever Automake breaks it. - -@item 1998-09-06 @code{sourceware.cygnus.com} is on-line. - -Sourceware was setup by Jason Molenda to host open source projects. - -@item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com} -@itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake: -Automake is now hosted on @code{sourceware.cygnus.com}. It has a -publicly accessible CVS repository. This CVS repository is a copy of -the one Tom was using on his machine, which in turn is based on -a copy of the CVS repository of David MacKenzie. This is why we still -have to full source history. (Automake was on Sourceware until 2007-10-29, -when it moved to a git repository on @code{savannah.gnu.org}, -but the Sourceware host had been renamed to @code{sources.redhat.com}.) - -The oldest file in the administrative directory of the CVS repository -that was created on Sourceware is dated 1998-09-19, while the -announcement that @command{automake} and @command{autoconf} had joined -@command{sourceware} was made on 1998-10-26. They were among the -first projects to be hosted there. - -The heedful reader will have noticed Automake was exactly 4 years old -on 1998-09-19. - -@item 1999-01-05 Ben Elliston releases Autoconf 2.13. - -@item 1999-01-14 Automake 1.4 - -This release adds support for Fortran 77 and for the @code{include} -statement. Also, @samp{+=} assignments are introduced, but it is -still quite easy to fool Automake when mixing this with conditionals. - -These two releases, Automake 1.4 and Autoconf 2.13 make a duo that -will be used together for years. - -@command{automake} is 7228 lines, plus 1591 lines of Makefile -fragment, 20 macros (some 1.3 macros were finally contributed back to -Autoconf), 197 test cases, and 51 pages of documentation. - -@item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository. - -This implements a new dependency tracking schemed that should be -able to handle automatic dependency tracking using any compiler (not -just gcc) and any make (not just GNU @command{make}). In addition, -the new scheme should be more reliable than the old one, as -dependencies are generated on the end user's machine. Alexandre Oliva -creates depcomp for this purpose. - -@xref{Dependency Tracking Evolution}, for more details about the -evolution of automatic dependency tracking in Automake. - -@item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk. - -This was a huge problem since we also had patches going in on the -trunk. The merge took a long time and was very painful. - -@item 2000-05-10 - -Since September 1999 and until 2003, Akim Demaille will be zealously -revamping Autoconf. - -@quotation -I think the next release should be called "3.0".@* -Let's face it: you've basically rewritten autoconf.@* -Every weekend there are 30 new patches.@* -I don't see how we could call this "2.15" with a straight face.@* --- Tom Tromey on @email{autoconf@@gnu.org} -@end quotation - -Actually Akim works like a submarine: he will pile up patches while he -works off-line during the weekend, and flush them in batch when he -resurfaces on Monday. - -@item 2001-01-24 - -On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50 -is out, and Akim has to find something to do during his week-end :) - -@item 2001-01-28 - -Akim sends a batch of 14 patches to @email{automake@@gnu.org}. - -@quotation -Aiieeee! I was dreading the day that the Demaillator turned his -sights on automake@dots{} and now it has arrived! -- Tom Tromey -@end quotation - -It's only the beginning: in two months he will send 192 patches. Then -he would slow down so Tom can catch up and review all this. Initially -Tom actually read all of these patches, then he probably trustingly -answered OK to most of them, and finally gave up and let Akim apply -whatever he wanted. There was no way to keep up with that patch rate. - -@quotation -Anyway the patch below won't apply since it predates Akim's -sourcequake; I have yet to figure where the relevant passage has -been moved :) -- Alexandre Duret-Lutz -@end quotation - -All of these patches were sent to and discussed on -@email{automake@@gnu.org}, so subscribed users were literally drowning in -technical mails. Eventually, the @email{automake-patches@@gnu.org} -mailing list was created in May. - -Year after year, Automake had drifted away from its initial design: -construct @file{Makefile.in} by assembling various @file{Makefile} -fragments. In 1.4, lots of @file{Makefile} rules are being emitted at -various places in the @command{automake} script itself; this does not -help ensuring a consistent treatment of these rules (for instance -making sure that user-defined rules override Automake's own rules). -One of Akim's goal was moving all of these hard-coded rules to separate -@file{Makefile} fragments, so the logic could be centralized in a -@file{Makefile} fragment processor. - -Another significant contribution of Akim is the interface with the -``trace'' feature of Autoconf. The way to scan @file{configure.in} at -this time was to read the file and grep the various macro of interest -to Automake. Doing so could break in many unexpected ways; @command{automake} -could miss some definition (for instance @samp{AC_SUBST([$1], [$2])} -where the arguments are known only when M4 is run), or conversely it -could detect some macro that was not expanded (because it is called -conditionally). In the CVS version of Autoconf, Akim had implemented -the @option{--trace} option, which provides accurate information about -where macros are actually called and with what arguments. Akim will -equip Automake with a second @file{configure.in} scanner that uses -this @option{--trace} interface. Since it was not sensible to drop the -Autoconf 2.13 compatibility yet, this experimental scanner was only -used when an environment variable was set, the traditional -grep-scanner being still the default. - -@item 2001-04-25 Gary V.@tie{}Vaughan releases Libtool 1.4 - -It has been more than two years since Automake 1.4, CVS Automake has -suffered lot's of heavy changes and still is not ready for release. -Libtool 1.4 had to be distributed with a patch against Automake 1.4. - -@item 2001-05-08 Automake 1.4-p1 -@itemx 2001-05-24 Automake 1.4-p2 - -Gary V.@tie{}Vaughan, the principal Libtool maintainer, makes a ``patch -release'' of Automake: - -@quotation -The main purpose of this release is to have a stable automake -which is compatible with the latest stable libtool. -@end quotation - -The release also contains obvious fixes for bugs in Automake 1.4, -some of which were reported almost monthly. - -@item 2001-05-21 Akim Demaille releases Autoconf 2.50 - -@item 2001-06-07 Automake 1.4-p3 -@itemx 2001-06-10 Automake 1.4-p4 -@itemx 2001-07-15 Automake 1.4-p5 - -Gary continues his patch-release series. These also add support for -some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates -@file{configure.ac} over @file{configure.in}, and it introduces a new -syntax for @code{AC_OUTPUT}ing files. - -@item 2001-08-23 Automake 1.5 - -A major and long-awaited release, that comes more than two years after -1.4. It brings many changes, among which: -@itemize -@item The new dependency tracking scheme that uses @command{depcomp}. -Aside from the improvement on the dependency tracking itself -(@pxref{Dependency Tracking Evolution}), this also streamlines the use -of @command{automake}-generated @file{Makefile.in}s as the @file{Makefile.in}s -used during development are now the same as those used in -distributions. Before that the @file{Makefile.in}s generated for -maintainers required GNU @command{make} and GCC, they were different -from the portable @file{Makefile} generated for distribution; this was -causing some confusion. - -@item Support for per-target compilation flags. - -@item Support for reference to files in subdirectories in most -@file{Makefile.am} variables. - -@item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_} -prefixes. -@item Perl 4 support is finally dropped. -@end itemize - -1.5 did break several packages that worked with 1.4. Enough so that -Linux distributions could not easily install the new Automake version -without breaking many of the packages for which they had to run -@command{automake}. - -Some of these breakages were effectively bugs that would eventually be -fixed in the next release. However, a lot of damage was caused by -some changes made deliberately to render Automake stricter on some -setup we did consider bogus. For instance, @samp{make distcheck} was -improved to check that @samp{make uninstall} did remove all the files -@samp{make install} installed, that @samp{make distclean} did not omit -some file, and that a VPATH build would work even if the source -directory was read-only. Similarly, Automake now rejects multiple -definitions of the same variable (because that would mix very badly -with conditionals), and @samp{+=} assignments with no previous -definition. Because these changes all occurred suddenly after 1.4 had -been established for more than two years, it hurt users. - -To make matter worse, meanwhile Autoconf (now at version 2.52) was -facing similar troubles, for similar reasons. - -@item 2002-03-05 Automake 1.6 - -This release introduced versioned installation (@pxref{API Versioning, , -API Versioning, automake, GNU Automake}). This was mainly pushed by -Havoc Pennington, taking the GNOME source tree as motive: due to -incompatibilities between the autotools it's impossible for the GNOME -packages to switch to Autoconf 2.53 and Automake 1.5 all at once, so -they are currently stuck with Autoconf 2.13 and Automake 1.4. - -The idea was to call this version @file{automake-1.6}, call all its -bug-fix versions identically, and switch to @file{automake-1.7} for -the next release that adds new features or changes some rules. This -scheme implies maintaining a bug-fix branch in addition to the -development trunk, which means more work from the maintainer, but -providing regular bug-fix releases proved to be really worthwhile. - -Like 1.5, 1.6 also introduced a bunch of incompatibilities, intentional or -not. Perhaps the more annoying was the dependence on the newly -released Autoconf 2.53. Autoconf seemed to have stabilized enough -since its explosive 2.50 release and included changes required to fix -some bugs in Automake. In order to upgrade to Automake 1.6, people -now had to upgrade Autoconf too; for some packages it was no picnic. - -While versioned installation helped people to upgrade, it also -unfortunately allowed people not to upgrade. At the time of writing, -some Linux distributions are shipping packages for Automake 1.4, 1.5, -1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default. -Some distribution also call 1.4 the ``stable'' version, and present -``1.9'' as the development version; this does not really makes sense -since 1.9 is way more solid than 1.4. All this does not help the -newcomer. - -@item 2002-04-11 Automake 1.6.1 - -1.6, and the upcoming 1.4-p6 release were the last release by Tom. -This one and those following will be handled by Alexandre -Duret-Lutz. Tom is still around, and will be there until about 1.7, -but his interest into Automake is drifting away towards projects like -@command{gcj}. - -Alexandre has been using Automake since 2000, and started to -contribute mostly on Akim's incitement (Akim and Alexandre have been -working in the same room from 1999 to 2002). In 2001 and 2002 he had -a lot of free time to enjoy hacking Automake. - -@item 2002-06-14 Automake 1.6.2 - -@item 2002-07-28 Automake 1.6.3 -@itemx 2002-07-28 Automake 1.4-p6 - -Two releases on the same day. 1.6.3 is a bug-fix release. - -Tom Tromey backported the versioned installation mechanism on the 1.4 -branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed -side by side. Another request from the GNOME folks. - -@item 2002-09-25 Automake 1.7 - -This release switches to the new @file{configure.ac} scanner Akim -was experimenting in 1.5. - -@item 2002-10-16 Automake 1.7.1 -@itemx 2002-12-06 Automake 1.7.2 -@itemx 2003-02-20 Automake 1.7.3 -@itemx 2003-04-23 Automake 1.7.4 -@itemx 2003-05-18 Automake 1.7.5 -@itemx 2003-07-10 Automake 1.7.6 -@itemx 2003-09-07 Automake 1.7.7 -@itemx 2003-10-07 Automake 1.7.8 - -Many bug-fix releases. 1.7 lasted because the development version -(upcoming 1.8) was suffering some major internal revamping. - -@item 2003-10-26 Automake on screen - -Episode 49, `Repercussions', in the third season of the `Alias' TV -show is first aired. - -Marshall, one of the characters, is working on a computer virus that he -has to modify before it gets into the wrong hands or something like -that. The screenshots you see do not show any program code, they show -a @file{Makefile.in} generated by automake... - -@item 2003-11-09 Automake 1.7.9 - -@item 2003-12-10 Automake 1.8 - -The most striking update is probably that of @command{aclocal}. - -@command{aclocal} now uses @code{m4_include} in the produced -@file{aclocal.m4} when the included macros are already distributed -with the package (an idiom used in many packages), which reduces code -duplication. Many people liked that, but in fact this change was -really introduced to fix a bug in rebuild rules: @file{Makefile.in} -must be rebuilt whenever a dependency of @file{configure} changes, but -all the @file{m4} files included in @file{aclocal.m4} where unknown -from @command{automake}. Now @command{automake} can just trace the -@code{m4_include}s to discover the dependencies. - -@command{aclocal} also starts using the @option{--trace} Autoconf option -in order to discover used macros more accurately. This will turn out -to be very tricky (later releases will improve this) as people had -devised many ways to cope with the limitation of previous -@command{aclocal} versions, notably using handwritten -@code{m4_include}s: @command{aclocal} must make sure not to redefine a -rule that is already included by such statement. - -Automake also has seen its guts rewritten. Although this rewriting -took a lot of efforts, it is only apparent to the users in that some -constructions previously disallowed by the implementation now work -nicely. Conditionals, Locations, Variable and Rule definitions, -Options: these items on which Automake works have been rewritten as -separate Perl modules, and documented. - -@item 2004-01-11 Automake 1.8.1 -@itemx 2004-01-12 Automake 1.8.2 -@itemx 2004-03-07 Automake 1.8.3 -@itemx 2004-04-25 Automake 1.8.4 -@itemx 2004-05-16 Automake 1.8.5 - -@item 2004-07-28 Automake 1.9 - -This release tries to simplify the compilation rules it outputs to -reduce the size of the Makefile. The complaint initially come from -the libgcj developers. Their @file{Makefile.in} generated with -Automake 1.4 and custom build rules (1.4 did not support compiled -Java) is 250KB@. The one generated by 1.8 was over 9MB@! 1.9 gets it -down to 1.2MB@. - -Aside from this it contains mainly minor changes and bug-fixes. - -@item 2004-08-11 Automake 1.9.1 -@itemx 2004-09-19 Automake 1.9.2 - -Automake has ten years. This chapter of the manual was initially -written for this occasion. - -@item 2007-10-29 Automake repository moves to @code{savannah.gnu.org} -and uses git as primary repository. - -@end table - -@node Dependency Tracking Evolution -@chapter Evolution of Automatic Dependency Tracking - -Over the years Automake has deployed three different dependency -tracking methods. Each method, including the current one, has had -flaws of various sorts. Here we lay out the different dependency -tracking methods, their flaws, and their fixes. We conclude with -recommendations for tool writers, and by indicating future directions -for dependency tracking work in Automake. - -@menu -* First Take on Dependencies:: Precomputed dependency tracking -* Dependencies As Side Effects:: Update at developer compile time -* Dependencies for the User:: Update at user compile time -* Techniques for Dependencies:: Alternative approaches -@end menu - -@node First Take on Dependencies -@section First Take on Dependency Tracking -@unnumberedsubsec Description - -Our first attempt at automatic dependency tracking was based on the -method recommended by GNU @command{make}. (@pxref{Automatic -Prerequisites, , Generating Prerequisites Automatically, make, The GNU -make Manual}) - -This version worked by precomputing dependencies ahead of time. For -each source file, it had a special @file{.P} file that held the -dependencies. There was a rule to generate a @file{.P} file by -invoking the compiler appropriately. All such @file{.P} files were -included by the @file{Makefile}, thus implicitly becoming dependencies -of @file{Makefile}. - -@unnumberedsubsec Bugs - -This approach had several critical bugs. - -@itemize -@item -The code to generate the @file{.P} file relied on @command{gcc}. -(A limitation, not technically a bug.) -@item -The dependency tracking mechanism itself relied on GNU @command{make}. -(A limitation, not technically a bug.) -@item -Because each @file{.P} file was a dependency of @file{Makefile}, this -meant that dependency tracking was done eagerly by @command{make}. -For instance, @samp{make clean} would cause all the dependency files -to be updated, and then immediately removed. This eagerness also -caused problems with some configurations; if a certain source file -could not be compiled on a given architecture for some reason, -dependency tracking would fail, aborting the entire build. -@item -As dependency tracking was done as a pre-pass, compile times were -doubled--the compiler had to be run twice per source file. -@item -@samp{make dist} re-ran @command{automake} to generate a -@file{Makefile} that did not have automatic dependency tracking (and -that was thus portable to any version of @command{make}). In order to -do this portably, Automake had to scan the dependency files and remove -any reference that was to a source file not in the distribution. -This process was error-prone. Also, if @samp{make dist} was run in an -environment where some object file had a dependency on a source file -that was only conditionally created, Automake would generate a -@file{Makefile} that referred to a file that might not appear in the -end user's build. A special, hacky mechanism was required to work -around this. -@end itemize - -@unnumberedsubsec Historical Note - -The code generated by Automake is often inspired by the -@file{Makefile} style of a particular author. In the case of the first -implementation of dependency tracking, I believe the impetus and -inspiration was Jim Meyering. (I could be mistaken. If you know -otherwise feel free to correct me.) - -@node Dependencies As Side Effects -@section Dependencies As Side Effects -@unnumberedsubsec Description - -The next refinement of Automake's automatic dependency tracking scheme -was to implement dependencies as side effects of the compilation. -This was aimed at solving the most commonly reported problems with the -first approach. In particular we were most concerned with eliminating -the weird rebuilding effect associated with make clean. - -In this approach, the @file{.P} files were included using the -@code{-include} command, which let us create these files lazily. This -avoided the @samp{make clean} problem. - -We only computed dependencies when a file was actually compiled. This -avoided the performance penalty associated with scanning each file -twice. It also let us avoid the other problems associated with the -first, eager, implementation. For instance, dependencies would never -be generated for a source file that was not compilable on a given -architecture (because it in fact would never be compiled). - -@unnumberedsubsec Bugs - -@itemize -@item -This approach also relied on the existence of @command{gcc} and GNU -@command{make}. (A limitation, not technically a bug.) -@item -Dependency tracking was still done by the developer, so the problems -from the first implementation relating to massaging of dependencies by -@samp{make dist} were still in effect. -@item -This implementation suffered from the ``deleted header file'' problem. -Suppose a lazily-created @file{.P} file includes a dependency on a -given header file, like this: - -@example -maude.o: maude.c something.h -@end example - -Now suppose that you remove @file{something.h} and update @file{maude.c} -so that this include is no longer needed. If you run @command{make}, -you will get an error because there is no way to create -@file{something.h}. - -We fixed this problem in a later release by further massaging the -output of @command{gcc} to include a dummy dependency for each header -file. -@end itemize - -@node Dependencies for the User -@section Dependencies for the User -@unnumberedsubsec Description - -The bugs associated with @samp{make dist}, over time, became a real -problem. Packages using Automake were being built on a large number -of platforms, and were becoming increasingly complex. Broken -dependencies were distributed in ``portable'' @file{Makefile.in}s, -leading to user complaints. Also, the requirement for @command{gcc} -and GNU @command{make} was a constant source of bug reports. The next -implementation of dependency tracking aimed to remove these problems. - -We realized that the only truly reliable way to automatically track -dependencies was to do it when the package itself was built. This -meant discovering a method portable to any version of make and any -compiler. Also, we wanted to preserve what we saw as the best point -of the second implementation: dependency computation as a side effect -of compilation. - -In the end we found that most modern make implementations support some -form of include directive. Also, we wrote a wrapper script that let -us abstract away differences between dependency tracking methods for -compilers. For instance, some compilers cannot generate dependencies -as a side effect of compilation. In this case we simply have the -script run the compiler twice. Currently our wrapper script -(@command{depcomp}) knows about twelve different compilers (including -a "compiler" that simply invokes @command{makedepend} and then the -real compiler, which is assumed to be a standard Unix-like C compiler -with no way to do dependency tracking). - -@unnumberedsubsec Bugs - -@itemize -@item -Running a wrapper script for each compilation slows down the build. -@item -Many users don't really care about precise dependencies. -@item -This implementation, like every other automatic dependency tracking -scheme in common use today (indeed, every one we've ever heard of), -suffers from the ``duplicated new header'' bug. - -This bug occurs because dependency tracking tools, such as the -compiler, only generate dependencies on the successful opening of a -file, and not on every probe. - -Suppose for instance that the compiler searches three directories for -a given header, and that the header is found in the third directory. -If the programmer erroneously adds a header file with the same name to -the first directory, then a clean rebuild from scratch could fail -(suppose the new header file is buggy), whereas an incremental rebuild -will succeed. - -What has happened here is that people have a misunderstanding of what -a dependency is. Tool writers think a dependency encodes information -about which files were read by the compiler. However, a dependency -must actually encode information about what the compiler tried to do. - -This problem is not serious in practice. Programmers typically do not -use the same name for a header file twice in a given project. (At -least, not in C or C++. This problem may be more troublesome in -Java.) This problem is easy to fix, by modifying dependency -generators to record every probe, instead of every successful open. - -@item -Since Automake generates dependencies as a side effect of compilation, -there is a bootstrapping problem when header files are generated by -running a program. The problem is that, the first time the build is -done, there is no way by default to know that the headers are -required, so make might try to run a compilation for which the headers -have not yet been built. - -This was also a problem in the previous dependency tracking implementation. - -The current fix is to use @code{BUILT_SOURCES} to list built headers -(@pxref{Sources, , Sources, automake, GNU Automake}). This causes them -to be built before any other build rules are run. This is unsatisfactory -as a general solution, however in practice it seems sufficient for most -actual programs. -@end itemize - -This code is used since Automake 1.5. - -In GCC 3.0, we managed to convince the maintainers to add special -command-line options to help Automake more efficiently do its job. We -hoped this would let us avoid the use of a wrapper script when -Automake's automatic dependency tracking was used with @command{gcc}. - -Unfortunately, this code doesn't quite do what we want. In -particular, it removes the dependency file if the compilation fails; -we'd prefer that it instead only touch the file in any way if the -compilation succeeds. - -Nevertheless, since Automake 1.7, when a recent @command{gcc} is -detected at @command{configure} time, we inline the -dependency-generation code and do not use the @command{depcomp} -wrapper script. This makes compilations faster for those using this -compiler (probably our primary user base). The counterpart is that -because we have to encode two compilation rules in @file{Makefile} -(with or without @command{depcomp}), the produced @file{Makefile}s are -larger. - -@node Techniques for Dependencies -@section Techniques for Computing Dependencies - -There are actually several ways for a build tool like Automake to -cause tools to generate dependencies. - -@table @asis -@item @command{makedepend} -This was a commonly-used method in the past. The idea is to run a -special program over the source and have it generate dependency -information. Traditional implementations of @command{makedepend} are -not completely precise; ordinarily they were conservative and -discovered too many dependencies. -@item The tool -An obvious way to generate dependencies is to simply write the tool so -that it can generate the information needed by the build tool. This is -also the most portable method. Many compilers have an option to -generate dependencies. Unfortunately, not all tools provide such an -option. -@item The file system -It is possible to write a special file system that tracks opens, -reads, writes, etc, and then feed this information back to the build -tool. @command{clearmake} does this. This is a very powerful -technique, as it doesn't require cooperation from the -tool. Unfortunately it is also very difficult to implement and also -not practical in the general case. -@item @code{LD_PRELOAD} -Rather than use the file system, one could write a special library to -intercept @code{open} and other syscalls. This technique is also quite -powerful, but unfortunately it is not portable enough for use in -@command{automake}. -@end table - -@menu -* Recommendations for Tool Writers:: -* Future Directions for Dependencies:: -@end menu - -@node Recommendations for Tool Writers -@subsection Recommendations for Tool Writers - -We think that every compilation tool ought to be able to generate -dependencies as a side effect of compilation. Furthermore, at least -while @command{make}-based tools are nearly universally in use (at -least in the free software community), the tool itself should generate -dummy dependencies for header files, to avoid the deleted header file -bug. Finally, the tool should generate a dependency for each probe, -instead of each successful file open, in order to avoid the duplicated -new header bug. - -@node Future Directions for Dependencies -@subsection Future Directions for Dependencies - -Currently, only languages and compilers understood by Automake can -have dependency tracking enabled. We would like to see if it is -practical (and worthwhile) to let this support be extended by the user -to languages unknown to Automake. - -@node Releases -@chapter Release Statistics - -The following table (inspired by @samp{perlhist(1)}) quantifies the -evolution of Automake using these metrics: - -@table @asis -@item Date, Rel -The date and version of the release. -@item am -The number of lines of the @command{automake} script. -@item acl -The number of lines of the @command{aclocal} script. -@item pm -The number of lines of the @command{Perl} supporting modules. -@item @file{*.am} -The number of lines of the @file{Makefile} fragments. The number in -parentheses is the number of files. -@item m4 -The number of lines (and files) of Autoconf macros. -@item doc -The number of pages of the documentation (the Postscript version). -@item t -The number of test cases in the test suite. Of those, the number in -parentheses is the number of generated test cases. -@end table - -@multitable {8888-88-88} {8.8-p8} {8888} {8888} {8888} {8888 (88)} {8888 (88)} {888} {888 (88)} -@headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t -@item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab -@item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab -@item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab -@item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab -@item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab -@item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab -@item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab -@item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab -@item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab -@item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab -@item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab -@item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab -@item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9 -@item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17 -@item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26 -@item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35 -@item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38 -@item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (20) @tab 37 @tab 126 -@item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (23) @tab 39 @tab 156 -@item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197 -@item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197 -@item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197 -@item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197 -@item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 198 -@item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (20) @tab 51 @tab 198 -@item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (29) @tab 63 @tab 327 -@item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (27) @tab 66 @tab 365 -@item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (27) @tab 66 @tab 372 -@item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (27) @tab 67 @tab 386 -@item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (27) @tab 67 @tab 391 -@item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (20) @tab 49 @tab 197 -@item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (28) @tab 73 @tab 430 -@item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (28) @tab 73 @tab 437 -@item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (28) @tab 77 @tab 445 -@item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (29) @tab 84 @tab 448 -@item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (29) @tab 85 @tab 458 -@item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (29) @tab 85 @tab 459 -@item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (29) @tab 85 @tab 461 -@item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 467 -@item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 468 -@item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (29) @tab 90 @tab 468 -@item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (31) @tab 104 @tab 521 -@item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (31) @tab 104 @tab 525 -@item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (31) @tab 104 @tab 526 -@item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (31) @tab 111 @tab 530 -@item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (31) @tab 112 @tab 531 -@item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (31) @tab 112 @tab 533 -@item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (32) @tab 115 @tab 551 -@item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 115 @tab 552 -@item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 132 @tab 554 -@item 2004-11-01 @tab 1.9.3 @tab 7507 @tab 718 @tab 7804 @tab 3354 (40) @tab 1812 (32) @tab 134 @tab 556 -@item 2004-12-18 @tab 1.9.4 @tab 7508 @tab 718 @tab 7856 @tab 3361 (40) @tab 1811 (32) @tab 140 @tab 560 -@item 2005-02-13 @tab 1.9.5 @tab 7523 @tab 719 @tab 7859 @tab 3373 (40) @tab 1453 (32) @tab 142 @tab 562 -@item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570 -@item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604 -@item 2008-01-19 @tab 1.10.1 @tab 7870 @tab 1089 @tab 8025 @tab 3520 (40) @tab 1499 (34) @tab 173 @tab 617 -@item 2008-11-23 @tab 1.10.2 @tab 7882 @tab 1089 @tab 8027 @tab 3540 (40) @tab 1509 (34) @tab 176 @tab 628 -@item 2009-05-17 @tab 1.11 @tab 8721 @tab 1092 @tab 8289 @tab 4164 (42) @tab 1714 (37) @tab 181 @tab 732 (20) -@end multitable - - -@c ========================================================== Appendices - -@page -@node Copying This Manual -@appendix Copying This Manual - -@menu -* GNU Free Documentation License:: License for copying this manual -@end menu - -@node GNU Free Documentation License -@appendixsec GNU Free Documentation License -@include fdl.texi - -@bye diff --git a/doc/automake.texi b/doc/automake.texi deleted file mode 100644 index 347d74535..000000000 --- a/doc/automake.texi +++ /dev/null @@ -1,13169 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename automake.info -@settitle automake -@documentencoding UTF-8 -@documentlanguage en -@setchapternewpage off -@c %**end of header - -@include version.texi - -@c @ovar(ARG, DEFAULT) -@c ------------------- -@c The ARG is an optional argument. To be used for macro arguments in -@c their documentation (@defmac). -@macro ovar{varname} -@r{[}@var{\varname\}@r{]} -@end macro - -@set PACKAGE_BUGREPORT bug-automake@@gnu.org - -@copying - -This manual is for GNU Automake (version @value{VERSION}, -@value{UPDATED}), a program that creates GNU standards-compliant -Makefiles from template files. - -Copyright @copyright{} 1995-2017 Free Software Foundation, Inc. - -@quotation -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.'' - -@end quotation -@end copying - -@dircategory Software development -@direntry -* Automake: (automake). Making GNU standards-compliant Makefiles. -@end direntry - -@dircategory Individual utilities -@direntry -* aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4. -* automake-invocation: (automake)automake Invocation. Generating Makefile.in. -@end direntry - -@titlepage -@title GNU Automake -@subtitle For version @value{VERSION}, @value{UPDATED} -@author David MacKenzie -@author Tom Tromey -@author Alexandre Duret-Lutz -@author Ralf Wildenhues -@author Stefano Lattarini -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@c We use the following macros to define indices: -@c @cindex concepts, and anything that does not fit elsewhere -@c @vindex Makefile variables -@c @trindex targets -@c @acindex Autoconf/Automake/Libtool/M4/... macros -@c @opindex tool options - -@c Define an index of configure macros. -@defcodeindex ac -@c Define an index of options. -@defcodeindex op -@c Define an index of targets. -@defcodeindex tr -@c Define an index of commands. -@defcodeindex cm - -@c Put the macros in the function index. -@syncodeindex ac fn - -@c Put everything else into one index (arbitrarily chosen to be the -@c concept index). -@syncodeindex op cp -@syncodeindex tr cp -@syncodeindex cm cp - -@ifnottex -@node Top -@comment node-name, next, previous, up -@top GNU Automake - -@insertcopying - -@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 @command{make} -* Gnits:: The effect of @option{--gnu} and @option{--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 - -@detailmenu - --- 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 @file{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 @file{configure.ac}, using @command{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. -* Obsolete Macros:: Obsolete macros you should no longer 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 @samp{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:: @code{dist_} and @code{nodist_} prefixes -* The dist Hook:: A target for last-minute distribution changes -* Checking the Distribution:: @samp{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 @code{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 @command{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 @file{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 - -@end detailmenu -@end menu - -@end ifnottex - - -@node Introduction -@chapter Introduction - -Automake is a tool for automatically generating @file{Makefile.in}s -from files called @file{Makefile.am}. Each @file{Makefile.am} is -basically a series of @command{make} variable -definitions@footnote{These variables are also called @dfn{make macros} -in Make terminology, however in this manual we reserve the term -@dfn{macro} for Autoconf's macros.}, with rules being thrown in -occasionally. The generated @file{Makefile.in}s are compliant with -the GNU Makefile standards. - -@cindex GNU Makefile standards - -The GNU Makefile Standards Document -(@pxref{Makefile Conventions, , , standards, The GNU Coding Standards}) -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 @file{Makefile.in}. - -@cindex Constraints of Automake -@cindex Automake constraints - -Automake does constrain a project in certain ways; for instance, it -assumes that the project uses Autoconf (@pxref{Top, , Introduction, -autoconf, The Autoconf Manual}), and enforces certain restrictions on -the @file{configure.ac} contents. - -@cindex Automake requirements -@cindex Requirements, Automake - -Automake requires @command{perl} in order to generate the -@file{Makefile.in}s. However, the distributions created by Automake are -fully GNU standards-compliant, and do not require @command{perl} in order -to be built. - -@cindex Bugs, reporting -@cindex Reporting bugs -@cindex E-mail, bug reports - -For more information on bug reports, @xref{Reporting Bugs}. - -@node Autotools Introduction -@chapter An Introduction to the Autotools - -If you are new to Automake, maybe you know that it is part of a set of -tools called @emph{The Autotools}. Maybe you've already delved into a -package full of files named @file{configure}, @file{configure.ac}, -@file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{}, -some of them claiming to be @emph{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 -@command{automake}-centered continuation, some slides for this -introduction are available in Alexandre Duret-Lutz's -@uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html, -Autotools Tutorial}. -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 -@end menu - -@node GNU Build System -@section Introducing the GNU Build System -@cindex GNU Build System, introduction - -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 @command{make} (@pxref{Top, , Overview, make, The GNU Make -Manual}). You express the recipe to build your package in a -@file{Makefile}. This file is a set of rules to build the files in -the package. For instance the program @file{prog} may be built by -running the linker on the files @file{main.o}, @file{foo.o}, and -@file{bar.o}; the file @file{main.o} may be built by running the -compiler on @file{main.c}; etc. Each time @command{make} is run, it -reads @file{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 @file{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 -@file{Makefile} for the 20 platforms he had to deal with. Instead, he -handcrafted a little shell script called @file{configure} to -automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis, -autoconf, The Autoconf Manual}). Compiling his package was now -as simple as running @code{./configure && make}. - -@cindex GNU Coding Standards - -Today this process has been standardized in the GNU project. The GNU -Coding Standards (@pxref{Managing Releases, The Release Process, , -standards, The GNU Coding Standards}) explains how each package of the -GNU project should have a @file{configure} script, and the minimal -interface it should have. The @file{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 @code{./configure && make && make install}, and repeat -with the next package to install. - -We call this build system the @dfn{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. - -@cindex Autotools, introduction - -The Autotools are tools that will create a GNU Build System for your -package. Autoconf mostly focuses on @file{configure} and Automake on -@file{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. - -@node Use Cases -@section Use Cases for the GNU Build System -@cindex GNU Build System, use cases -@cindex GNU Build System, features -@cindex Features of the GNU Build System -@cindex Use Cases for the GNU Build System -@cindex @file{amhello-1.0.tar.gz}, location -@cindex @file{amhello-1.0.tar.gz}, use cases - -In this section we explore several use cases for the GNU Build System. -You can replay all of these examples on the @file{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 -@file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where -@var{prefix} is the installation prefix specified during configuration -(@var{prefix} defaults to @file{/usr/local}, however if Automake was -installed by some GNU/Linux distribution it most likely has been set -to @file{/usr}). If you do not have a copy of Automake installed, -you can find a copy of this file inside the @file{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 -@end menu - -@node Basic Installation -@subsection Basic Installation -@cindex Configuration, basics -@cindex Installation, basics -@cindex GNU Build System, basics - -The most common installation procedure looks as follows. - -@example -~ % @kbd{tar zxf amhello-1.0.tar.gz} -~ % @kbd{cd amhello-1.0} -~/amhello-1.0 % @kbd{./configure} -@dots{} -config.status: creating Makefile -config.status: creating src/Makefile -@dots{} -~/amhello-1.0 % @kbd{make} -@dots{} -~/amhello-1.0 % @kbd{make check} -@dots{} -~/amhello-1.0 % @kbd{su} -Password: -/home/adl/amhello-1.0 # @kbd{make install} -@dots{} -/home/adl/amhello-1.0 # @kbd{exit} -~/amhello-1.0 % @kbd{make installcheck} -@dots{} -@end example - -@cindex Unpacking - -The user first unpacks the package. Here, and in the following -examples, we will use the non-portable @code{tar zxf} command for -simplicity. On a system without GNU @command{tar} installed, this -command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}. - -The user then enters the newly created directory to run the -@file{configure} script. This script probes the system for various -features, and finally creates the @file{Makefile}s. In this toy -example there are only two @file{Makefile}s, but in real-world projects, -there may be many more, usually one @file{Makefile} per directory. - -It is now possible to run @code{make}. This will construct all the -programs, libraries, and scripts that need to be constructed for the -package. In our example, this compiles the @file{hello} program. -All files are constructed in place, in the source tree; we will see -later how this can be changed. - -@code{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 @code{make -check} is a no-op. - -@cindex su, before @code{make install} -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 @code{make install} will do that. However, by default -everything will be installed in subdirectories of @file{/usr/local}: -binaries will go into @file{/usr/local/bin}, libraries will end up in -@file{/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 @code{make install}. In our example, running @code{make install} -will copy the program @file{hello} into @file{/usr/local/bin} -and @file{README} into @file{/usr/local/share/doc/amhello}. - -A last and optional step is to run @code{make installcheck}. This -command may run tests on the installed files. @code{make check} tests -the files in the source tree, while @code{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 @code{make installcheck} will run the very same tests as -@code{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 @code{installcheck} tests -because the existence of @code{installcheck} is little known, and its -usefulness is neglected. Our little toy package is no better: @code{make -installcheck} does nothing. - -@node Standard Targets -@subsection Standard @file{Makefile} Targets - -So far we have come across four ways to run @command{make} in the GNU -Build System: @code{make}, @code{make check}, @code{make install}, and -@code{make installcheck}. The words @code{check}, @code{install}, and -@code{installcheck}, passed as arguments to @command{make}, are called -@dfn{targets}. @code{make} is a shorthand for @code{make all}, -@code{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. - -@table @code -@item make all -@trindex all -Build programs, libraries, documentation, etc.@: (same as @code{make}). -@item make install -@trindex install -Install what needs to be installed, copying the files from the -package's tree to system-wide directories. -@item make install-strip -@trindex install-strip -Same as @code{make install}, then strip debugging symbols. Some -users like to trade space for useful bug reports@enddots{} -@item make uninstall -@trindex uninstall -The opposite of @code{make install}: erase the installed files. -(This needs to be run from the same build tree that was installed.) -@item make clean -@trindex clean -Erase from the build tree the files built by @code{make all}. -@item make distclean -@trindex distclean -Additionally erase anything @code{./configure} created. -@item make check -@trindex check -Run the test suite, if any. -@item make installcheck -@trindex installcheck -Check the installed programs or libraries, if supported. -@item make dist -@trindex dist -Recreate @file{@var{package}-@var{version}.tar.gz} from all the source -files. -@end table - -@node Standard Directory Variables -@subsection Standard Directory Variables -@cindex directory variables - -The GNU Coding Standards also specify a hierarchy of variables to -denote installation directories. Some of these are: - -@multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}} -@headitem Directory variable @tab Default value -@item @code{prefix} @tab @code{/usr/local} -@item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}} -@item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin} -@item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib} -@item @w{@ @ @ @ @dots{}} -@item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include} -@item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share} -@item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}} -@item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man} -@item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info} -@item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}} -@item @w{@ @ @dots{}} -@end multitable - -@c We should provide a complete table somewhere, but not here. The -@c complete list of directory variables it too confusing as-is. It -@c requires some explanations that are too complicated for this -@c introduction. Besides listing directories like localstatedir -@c would make the explanations in ``Two-Part Install'' harder. - -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 @code{amhello-1.0}, the program -@file{hello} is to be installed in @var{bindir}, the directory for -binaries. The default value for this directory is -@file{/usr/local/bin}, but the user can supply a different value when -calling @command{configure}. Also the file @file{README} will be -installed into @var{docdir}, which defaults to -@file{/usr/local/share/doc/amhello}. - -@opindex --prefix - -As a user, if you wish to install a package on your own account, you -could proceed as follows: - -@example -~/amhello-1.0 % @kbd{./configure --prefix ~/usr} -@dots{} -~/amhello-1.0 % @kbd{make} -@dots{} -~/amhello-1.0 % @kbd{make install} -@dots{} -@end example - -This would install @file{~/usr/bin/hello} and -@file{~/usr/share/doc/amhello/README}. - -The list of all such directory options is shown by -@code{./configure --help}. - -@node Standard Configuration Variables -@subsection Standard Configuration Variables -@cindex configuration variables, overriding - -The GNU Coding Standards also define a set of standard configuration -variables used during the build. Here are some: - -@table @asis -@item @code{CC} -C compiler command -@item @code{CFLAGS} -C compiler flags -@item @code{CXX} -C++ compiler command -@item @code{CXXFLAGS} -C++ compiler flags -@item @code{LDFLAGS} -linker flags -@item @code{CPPFLAGS} -C/C++ preprocessor flags -@item @dots{} -@end table - -@command{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 @command{configure} to force it to use -@command{gcc-3} as C compiler, use header files from -@file{~/usr/include} when compiling, and libraries from -@file{~/usr/lib} when linking. - -@example -~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \ -CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib} -@end example - -Again, a full list of these variables appears in the output of -@code{./configure --help}. - -@node config.site -@subsection Overriding Default Configuration Setting with @file{config.site} -@cindex @file{config.site} example - -When installing several packages using the same setup, it can be -convenient to create a file to capture common settings. -If a file named @file{@var{prefix}/share/config.site} exists, -@command{configure} will source it at the beginning of its execution. - -Recall the command from the previous section: - -@example -~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \ -CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib} -@end example - -Assuming we are installing many package in @file{~/usr}, and will -always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and -@code{LDFLAGS}, we can automate this by creating the following -@file{~/usr/share/config.site} file: - -@example -test -z "$CC" && CC=gcc-3 -test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include -test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib -@end example - -Now, any time a @file{configure} script is using the @file{~/usr} -prefix, it will execute the above @file{config.site} and define -these three variables. - -@example -~/amhello-1.0 % @kbd{./configure --prefix ~/usr} -configure: loading site script /home/adl/usr/share/config.site -@dots{} -@end example - -@xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf -Manual}, for more information about this feature. - - -@node VPATH Builds -@subsection Parallel Build Trees (a.k.a.@: VPATH Builds) -@cindex Parallel build trees -@cindex VPATH builds -@cindex source tree and build tree -@cindex build tree and source tree -@cindex trees, source vs.@: build - -The GNU Build System distinguishes two trees: the source tree, and -the build tree. - -The source tree is rooted in the directory containing -@file{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 @file{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 @file{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 (@pxref{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 @file{configure} to build -everything in a subdirectory called @file{build/}. - -@example -~ % @kbd{tar zxf ~/amhello-1.0.tar.gz} -~ % @kbd{cd amhello-1.0} -~/amhello-1.0 % @kbd{mkdir build && cd build} -~/amhello-1.0/build % @kbd{../configure} -@dots{} -~/amhello-1.0/build % @kbd{make} -@dots{} -@end example - -These setups, where source and build trees are different, are often -called @dfn{parallel builds} or @dfn{VPATH builds}. The expression -@emph{parallel build} is misleading: the word @emph{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 @emph{VPATH builds} in -the following. @emph{VPATH} is the name of the @command{make} feature -used by the @file{Makefile}s to allow these builds (@pxref{General -Search, , @code{VPATH} Search Path for All Prerequisites, make, The -GNU Make Manual}). - -@cindex multiple configurations, example -@cindex debug build, example -@cindex optimized build, example - -VPATH builds have other interesting uses. One is to build the same -sources with multiple configurations. For instance: - -@c Keep in sync with amhello-cflags.sh -@example -~ % @kbd{tar zxf ~/amhello-1.0.tar.gz} -~ % @kbd{cd amhello-1.0} -~/amhello-1.0 % @kbd{mkdir debug optim && cd debug} -~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'} -@dots{} -~/amhello-1.0/debug % @kbd{make} -@dots{} -~/amhello-1.0/debug % cd ../optim -~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'} -@dots{} -~/amhello-1.0/optim % @kbd{make} -@dots{} -@end example - -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: @code{HOST1} -and @code{HOST2}, which may be different platforms. - -@example -~ % @kbd{cd /nfs/src} -/nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz} -@end example - -On the first host, you could create a local build directory: -@example -[HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh} -[HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure} -... -[HOST1] /tmp/amh % @kbd{make && sudo make install} -... -@end example - -@noindent -(Here we assume that the installer has configured @command{sudo} so it -can execute @code{make install} with root privileges; it is more convenient -than using @command{su} like in @ref{Basic Installation}). - -On the second host, you would do exactly the same, possibly at -the same time: -@example -[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh} -[HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure} -... -[HOST2] /tmp/amh % @kbd{make && sudo make install} -... -@end example - -@cindex read-only source tree -@cindex source tree, read-only - -In this scenario, nothing forbids the @file{/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.) - -@node Two-Part Install -@subsection Two-Part Installation - -In our last example (@pxref{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 @file{Makefile} -targets to install each of these classes of files. - -@trindex install-exec -@trindex install-data - -These targets are @code{install-exec} for architecture-dependent files -and @code{install-data} for architecture-independent files. -The command we used up to now, @code{make install}, can be thought of -as a shorthand for @code{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 (@pxref{Standard Directory Variables}), all the -variables based on @var{exec-prefix} designate architecture-dependent -directories whose files will be installed by @code{make install-exec}. -The others designate architecture-independent directories and will -serve files installed by @code{make install-data}. @xref{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 -@file{/usr}, and (2) the directory @file{/usr/share} is shared by the -two hosts. - -On the first host we would run -@example -[HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh} -[HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr} -... -[HOST1] /tmp/amh % @kbd{make && sudo make install} -... -@end example - -On the second host, however, we need only install the -architecture-specific files. -@example -[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh} -[HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr} -... -[HOST2] /tmp/amh % @kbd{make && sudo make install-exec} -... -@end example - -In packages that have installation checks, it would make sense to run -@code{make installcheck} (@pxref{Basic Installation}) to verify that -the package works correctly despite the apparent partial installation. - -@node Cross-Compilation -@subsection Cross-Compilation -@cindex cross-compilation - -To @dfn{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 @dfn{build platform} on which -the compilation is performed, and the @dfn{host platform} on which the -resulting executable is expected to run. The following -@command{configure} options are used to specify each of them: - -@table @option -@item --build=@var{build} -@opindex --build=@var{build} -The system on which the package is built. -@item --host=@var{host} -@opindex --host=@var{host} -The system where built programs and libraries will run. -@end table - -When the @option{--host} is used, @command{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 -@code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld}, -@code{i586-mingw32msvc-as}, etc. - -@cindex MinGW cross-compilation example -@cindex cross-compilation example - -Here is how we could build @code{amhello-1.0} for -@code{i586-mingw32msvc} on a GNU/Linux PC. - -@c Keep in sync with amhello-cross-compile.sh -@smallexample -~/amhello-1.0 % @kbd{./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... -@dots{} -~/amhello-1.0 % @kbd{make} -@dots{} -~/amhello-1.0 % @kbd{cd src; file hello.exe} -hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable -@end smallexample - -The @option{--host} and @option{--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. - -@table @option -@item --target=@var{target} -@opindex --target=@var{target} -When building compiler tools: the system for which the tools will -create output. -@end table - -For instance when installing GCC, the GNU Compiler Collection, we can -use @option{--target=@/@var{target}} to specify that we want to build -GCC as a cross-compiler for @var{target}. Mixing @option{--build} and -@option{--target}, we can actually cross-compile a cross-compiler; -such a three-way cross-compilation is known as a @dfn{Canadian cross}. - -@xref{Specifying Names, , Specifying the System Type, autoconf, The -Autoconf Manual}, for more information about these @command{configure} -options. - -@node Renaming -@subsection Renaming Programs at Install Time -@cindex Renaming programs -@cindex Transforming program names -@cindex Programs, renaming during installation - -The GNU Build System provides means to automatically rename -executables and manpages before they are installed (@pxref{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 @command{tar} as @command{gtar} so you can -distinguish it from your vendor's @command{tar}. - -This can be done using one of these three @command{configure} options. - -@table @option -@item --program-prefix=@var{prefix} -@opindex --program-prefix=@var{prefix} -Prepend @var{prefix} to installed program names. -@item --program-suffix=@var{suffix} -@opindex --program-suffix=@var{suffix} -Append @var{suffix} to installed program names. -@item --program-transform-name=@var{program} -@opindex --program-transform-name=@var{program} -Run @code{sed @var{program}} on installed program names. -@end table - -The following commands would install @file{hello} -as @file{/usr/local/bin/test-hello}, for instance. - -@example -~/amhello-1.0 % @kbd{./configure --program-prefix test-} -@dots{} -~/amhello-1.0 % @kbd{make} -@dots{} -~/amhello-1.0 % @kbd{sudo make install} -@dots{} -@end example - -@node DESTDIR -@subsection Building Binary Packages Using DESTDIR -@vindex DESTDIR - -The GNU Build System's @code{make install} and @code{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 @code{make install} is -inappropriate. - -@cindex Staged installation - -The @code{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., @code{--prefix /usr}), but -when running @code{make install}, the @code{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. - -@cindex Binary package - -For instance here is how we could create a binary package containing a -snapshot of all the files to be installed. - -@c Keep in sync with amhello-binpkg.sh -@example -~/amhello-1.0 % @kbd{./configure --prefix /usr} -@dots{} -~/amhello-1.0 % @kbd{make} -@dots{} -~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install} -@dots{} -~/amhello-1.0 % @kbd{cd ~/inst} -~/inst % @kbd{find . -type f -print > ../files.lst} -~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`} -./usr/bin/hello -./usr/share/doc/amhello/README -@end example - -After this example, @code{amhello-1.0-i686.tar.gz} is ready to be -uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`} -instead of @samp{.} as argument for @command{tar} avoids entries for -each subdirectory in the archive: we would not like @command{tar} to -restore the modification time of @file{/}, @file{/usr/}, etc.) - -Note that when building packages for several architectures, it might -be convenient to use @code{make install-data} and @code{make -install-exec} (@pxref{Two-Part Install}) to gather -architecture-independent files in a single package. - -@xref{Install}, for more information. - -@c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their -@c UNINSTALL counterparts. - -@node Preparing Distributions -@subsection Preparing Distributions -@cindex Preparing distributions -@cindex Packages, preparation -@cindex Distributions, preparation - -We have already mentioned @code{make dist}. This target collects all -your source files and the necessary parts of the build system to -create a tarball named @file{@var{package}-@var{version}.tar.gz}. - -@cindex @code{distcheck} better than @code{dist} - -Another, more useful command is @code{make distcheck}. The -@code{distcheck} target constructs -@file{@var{package}-@var{version}.tar.gz} just as well as @code{dist}, -but it additionally ensures most of the use cases presented so far -work: - -@itemize @bullet -@item -It attempts a full compilation of the package (@pxref{Basic -Installation}), unpacking the newly constructed tarball, running -@code{make}, @code{make check}, @code{make install}, as well as -@code{make installcheck}, and even @code{make dist}, -@item -it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}), -@item -it makes sure @code{make clean}, @code{make distclean}, and @code{make -uninstall} do not omit any file (@pxref{Standard Targets}), -@item -and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}). -@end itemize - -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 @code{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 @code{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 @code{distcheck} (like -@code{DESTDIR} not working because of a typo, or a distributed file -being erased by @code{make clean}, or even @code{VPATH} builds not -working). - -@xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using -@code{make distcheck}. @xref{Checking the Distribution}, for more -information about @code{distcheck}. - -@node Dependency Tracking -@subsection Automatic Dependency Tracking -@cindex 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 @command{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, -@pxref{Dependencies}. - -When @command{configure} is executed, you can see it probing each -compiler for the dependency mechanism it supports (several mechanisms -can be used): - -@example -~/amhello-1.0 % @kbd{./configure --prefix /usr} -@dots{} -checking dependency style of gcc... gcc3 -@dots{} -@end example - -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: -@code{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 @command{configure} option to disable this: - -@table @option -@item --disable-dependency-tracking -@opindex --disable-dependency-tracking -Speed up one-time builds. -@end table - -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 @option{--enable-dependency-tracking} -must be passed to @command{configure} to activate them. - -@table @option -@item --enable-dependency-tracking -@opindex --enable-dependency-tracking -Do not reject slow dependency extractors. -@end table - -@xref{Dependency Tracking Evolution, , Dependency Tracking Evolution, -automake-history, Brief History of Automake}, for some discussion about -the different dependency tracking schemes used by Automake over the years. - -@node Nested Packages -@subsection Nested Packages -@cindex Nested packages -@cindex Packages, nested -@cindex Subpackages - -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 @command{configure} script of A will -run the @command{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 @command{configure} options -given to the top-level @command{configure} are passed recursively to -nested @command{configure}s. A package that does not understand an -option will ignore it, assuming it is meaningful to some other -package. - -@opindex --help=recursive - -The command @code{configure --help=recursive} can be used to display -the options supported by all the included packages. - -@xref{Subpackages}, for an example setup. - -@node Why Autotools -@section How Autotools Help -@cindex Autotools, purpose - -There are several reasons why you may not want to implement the GNU -Build System yourself (read: write a @file{configure} script and -@file{Makefile}s yourself). - -@itemize @bullet -@item -As we have seen, the GNU Build System has a lot of -features (@pxref{Use Cases}). -Some users may expect features you have not implemented because -you did not need them. -@item -Implementing these features portably is difficult and exhausting. -Think of writing portable shell scripts, and portable -@file{Makefile}s, for systems you may not have handy. @xref{Portable -Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to -convince yourself. -@item -You will have to upgrade your setup to follow changes to the GNU -Coding Standards. -@end itemize - -The GNU Autotools take all this burden off your back and provide: - -@itemize @bullet -@item -Tools to create a portable, complete, and self-contained GNU Build -System, from simple instructions. -@emph{Self-contained} meaning the resulting build system does not -require the GNU Autotools. -@item -A central place where fixes and improvements are made: -a bug-fix for a portability issue will benefit every package. -@end itemize - -Yet there also exist reasons why you may want NOT to use the -Autotools@enddots{} 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. - -@node Hello World -@section A Small Hello World -@cindex Example Hello World -@cindex Hello World example -@cindex @file{amhello-1.0.tar.gz}, creation - -In this section we recreate the @file{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 @file{configure.ac} and @file{Makefile.am} files read -by the Autotools. - -@anchor{amhello Explained} -@menu -* Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch -* amhello's configure.ac Setup Explained:: -* amhello's Makefile.am Setup Explained:: -@end menu - -@node Creating amhello -@subsection Creating @file{amhello-1.0.tar.gz} - -Here is how we can recreate @file{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 @file{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. - -@itemize @bullet - -@item -@file{src/main.c} is the source file for the @file{hello} program. We -store it in the @file{src/} subdirectory, because later, when the package -evolves, it will ease the addition of a @file{man/} directory for man -pages, a @file{data/} directory for data files, etc. -@example -~/amhello % @kbd{cat src/main.c} -#include -#include - -int -main (void) -@{ - puts ("Hello World!"); - puts ("This is " PACKAGE_STRING "."); - return 0; -@} -@end example - -@item -@file{README} contains some very limited documentation for our little -package. -@example -~/amhello % @kbd{cat README} -This is a demonstration package for GNU Automake. -Type 'info Automake' to read the Automake manual. -@end example - -@item -@file{Makefile.am} and @file{src/Makefile.am} contain Automake -instructions for these two directories. - -@example -~/amhello % @kbd{cat src/Makefile.am} -bin_PROGRAMS = hello -hello_SOURCES = main.c -~/amhello % @kbd{cat Makefile.am} -SUBDIRS = src -dist_doc_DATA = README -@end example - -@item -Finally, @file{configure.ac} contains Autoconf instructions to -create the @command{configure} script. - -@example -~/amhello % @kbd{cat configure.ac} -AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}]) -AM_INIT_AUTOMAKE([-Wall -Werror foreign]) -AC_PROG_CC -AC_CONFIG_HEADERS([config.h]) -AC_CONFIG_FILES([ - Makefile - src/Makefile -]) -AC_OUTPUT -@end example -@end itemize - -@cindex @command{autoreconf}, example - -Once you have these five files, it is time to run the Autotools to -instantiate the build system. Do this using the @command{autoreconf} -command as follows: - -@example -~/amhello % @kbd{autoreconf --install} -configure.ac: installing './install-sh' -configure.ac: installing './missing' -configure.ac: installing './compile' -src/Makefile.am: installing './depcomp' -@end example - -At this point the build system is complete. - -In addition to the three scripts mentioned in its output, you can see -that @command{autoreconf} created four other files: @file{configure}, -@file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}. -The latter three files are templates that will be adapted to the -system by @command{configure} under the names @file{config.h}, -@file{Makefile}, and @file{src/Makefile}. Let's do this: - -@example -~/amhello % @kbd{./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 -@end example - -@trindex distcheck -@cindex @code{distcheck} example - -You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h} -being created at the end after @command{configure} has probed the -system. It is now possible to run all the targets we wish -(@pxref{Standard Targets}). For instance: - -@example -~/amhello % @kbd{make} -@dots{} -~/amhello % @kbd{src/hello} -Hello World! -This is amhello 1.0. -~/amhello % @kbd{make distcheck} -@dots{} -============================================= -amhello-1.0 archives ready for distribution: -amhello-1.0.tar.gz -============================================= -@end example - -Note that running @command{autoreconf} is only needed initially when -the GNU Build System does not exist. When you later change some -instructions in a @file{Makefile.am} or @file{configure.ac}, the -relevant part of the build system will be regenerated automatically -when you execute @command{make}. - -@command{autoreconf} is a script that calls @command{autoconf}, -@command{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 @command{autoconf} is in charge of -creating @file{configure} from @file{configure.ac}, while -@command{automake} is in charge of creating @file{Makefile.in}s from -@file{Makefile.am}s and @file{configure.ac}. This should at least -direct you to the right manual when seeking answers. - - -@node amhello's configure.ac Setup Explained -@subsection @code{amhello}'s @file{configure.ac} Setup Explained - -@cindex @file{configure.ac}, Hello World - -Let us begin with the contents of @file{configure.ac}. - -@example -AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}]) -AM_INIT_AUTOMAKE([-Wall -Werror foreign]) -AC_PROG_CC -AC_CONFIG_HEADERS([config.h]) -AC_CONFIG_FILES([ - Makefile - src/Makefile -]) -AC_OUTPUT -@end example - -This file is read by both @command{autoconf} (to create -@file{configure}) and @command{automake} (to create the various -@file{Makefile.in}s). It contains a series of M4 macros that will be -expanded as shell code to finally form the @file{configure} script. -We will not elaborate on the syntax of this file, because the Autoconf -manual has a whole section about it (@pxref{Writing Autoconf Input, , -Writing @file{configure.ac}, autoconf, The Autoconf Manual}). - -The macros prefixed with @code{AC_} are Autoconf macros, documented -in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro -Index, autoconf, The Autoconf Manual}). The macros that start with -@code{AM_} are Automake macros, documented later in this manual -(@pxref{Macro Index}). - -The first two lines of @file{configure.ac} initialize Autoconf and -Automake. @code{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 @code{./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. - -@opindex -Wall -@opindex -Werror -@opindex foreign - -The argument to @code{AM_INIT_AUTOMAKE} is a list of options for -@command{automake} (@pxref{Options}). @option{-Wall} and -@option{-Werror} ask @command{automake} to turn on all warnings and -report them as errors. We are speaking of @strong{Automake} warnings -here, such as dubious instructions in @file{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 @option{-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 @option{foreign} option tells Automake that this package -will not follow the GNU Standards. GNU packages should always -distribute additional files such as @file{ChangeLog}, @file{AUTHORS}, -etc. We do not want @command{automake} to complain about these -missing files in our small example. - -The @code{AC_PROG_CC} line causes the @command{configure} script to -search for a C compiler and define the variable @code{CC} with its -name. The @file{src/Makefile.in} file generated by Automake uses the -variable @code{CC} to build @file{hello}, so when @command{configure} -creates @file{src/Makefile} from @file{src/Makefile.in}, it will define -@code{CC} with the value it has found. If Automake is asked to create -a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does -not define it, it will suggest you add a call to @code{AC_PROG_CC}. - -The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the -@command{configure} script to create a @file{config.h} file gathering -@samp{#define}s defined by other macros in @file{configure.ac}. In our -case, the @code{AC_INIT} macro already defined a few of them. Here -is an excerpt of @file{config.h} after @command{configure} has run: - -@smallexample -@dots{} -/* Define to the address where bug reports for this package should be sent. */ -#define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}" - -/* Define to the full name and version of this package. */ -#define PACKAGE_STRING "amhello 1.0" -@dots{} -@end smallexample - -As you probably noticed, @file{src/main.c} includes @file{config.h} so -it can use @code{PACKAGE_STRING}. In a real-world project, -@file{config.h} can grow really big, with one @samp{#define} per -feature probed on the system. - -The @code{AC_CONFIG_FILES} macro declares the list of files that -@command{configure} should create from their @file{*.in} templates. -Automake also scans this list to find the @file{Makefile.am} files it must -process. (This is important to remember: when adding a new directory -to your project, you should add its @file{Makefile} to this list, -otherwise Automake will never process the new @file{Makefile.am} you -wrote in that directory.) - -Finally, the @code{AC_OUTPUT} line is a closing command that actually -produces the part of the script in charge of creating the files -registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}. - -@cindex @command{autoscan} - -When starting a new project, we suggest you start with such a simple -@file{configure.ac}, and gradually add the other tests it requires. -The command @command{autoscan} can also suggest a few of the tests -your package may need (@pxref{autoscan Invocation, , Using -@command{autoscan} to Create @file{configure.ac}, autoconf, The -Autoconf Manual}). - - -@node amhello's Makefile.am Setup Explained -@subsection @code{amhello}'s @file{Makefile.am} Setup Explained - -@cindex @file{Makefile.am}, Hello World - -We now turn to @file{src/Makefile.am}. This file contains -Automake instructions to build and install @file{hello}. - -@example -bin_PROGRAMS = hello -hello_SOURCES = main.c -@end example - -A @file{Makefile.am} has the same syntax as an ordinary -@file{Makefile}. When @command{automake} processes a -@file{Makefile.am} it copies the entire file into the output -@file{Makefile.in} (that will be later turned into @file{Makefile} by -@command{configure}) but will react to certain variable definitions -by generating some build rules and other variables. -Often @file{Makefile.am}s contain only a list of variable definitions as -above, but they can also contain other variable and rule definitions that -@command{automake} will pass along without interpretation. - -Variables that end with @code{_PROGRAMS} are special variables -that list programs that the resulting @file{Makefile} should build. -In Automake speak, this @code{_PROGRAMS} suffix is called a -@dfn{primary}; Automake recognizes other primaries such as -@code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding -to different types of files. - -The @samp{bin} part of the @code{bin_PROGRAMS} tells -@command{automake} that the resulting programs should be installed in -@var{bindir}. Recall that the GNU Build System uses a set of variables -to denote destination directories and allow users to customize these -locations (@pxref{Standard Directory Variables}). Any such directory -variable can be put in front of a primary (omitting the @code{dir} -suffix) to tell @command{automake} where to install the listed files. - -Programs need to be built from source files, so for each program -@code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable, -@command{automake} will look for another variable named -@code{@var{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 -@code{hello_SOURCES} declaration is that @file{main.c} will be -part of the tarball created by @code{make dist}. - -Finally here are some explanations regarding the top-level -@file{Makefile.am}. - -@example -SUBDIRS = src -dist_doc_DATA = README -@end example - -@code{SUBDIRS} is a special variable listing all directories that -@command{make} should recurse into before processing the current -directory. So this line is responsible for @command{make} building -@file{src/hello} even though we run it from the top-level. This line -also causes @code{make install} to install @file{src/hello} before -installing @file{README} (not that this order matters). - -The line @code{dist_doc_DATA = README} causes @file{README} to be -distributed and installed in @var{docdir}. Files listed with the -@code{_DATA} primary are not automatically part of the tarball built -with @code{make dist}, so we add the @code{dist_} prefix so they get -distributed. However, for @file{README} it would not have been -necessary: @command{automake} automatically distributes any -@file{README} file it encounters (the list of other files -automatically distributed is presented by @code{automake --help}). -The only important effect of this second line is therefore to install -@file{README} during @code{make install}. - -One thing not covered in this example is accessing the installation -directory values (@pxref{Standard Directory Variables}) from your -program code, that is, converting them into defined macros. For this, -@pxref{Defining Directories,,, autoconf, The Autoconf Manual}. - - -@node Generalities -@chapter 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 -@end menu - - -@node General Operation -@section General Operation - -Automake works by reading a @file{Makefile.am} and generating a -@file{Makefile.in}. Certain variables and rules defined in the -@file{Makefile.am} instruct Automake to generate more specialized code; -for instance, a @code{bin_PROGRAMS} variable definition will cause rules -for compiling and linking programs to be generated. - -@cindex Non-standard targets -@cindex @code{git-dist}, non-standard example -@trindex git-dist - -The variable definitions and rules in the @file{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 @file{Makefile.in}. For instance, -the Automake distribution includes a non-standard rule for the -@code{git-dist} target, which the Automake maintainer uses to make -distributions from the source control system. - -@cindex GNU make extensions - -Note that most GNU make extensions are not recognized by Automake. Using -such extensions in a @file{Makefile.am} will lead to errors or confusing -behavior. - -@cindex Append operator -@cmindex += -A special exception is that the GNU make append operator, @samp{+=}, is -supported. This operator appends its right hand argument to the variable -specified on the left. Automake will translate the operator into -an ordinary @samp{=} operator; @samp{+=} will thus work with any make program. - -Automake tries to keep comments grouped with any adjoining rules or -variable definitions. - -@cindex Limitations of automake parser -@cindex Automake parser, limitations of -@cindex indentation in Makefile.am -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. -@c Keep this in sync with doc-parsing-buglets-tabs.sh -For example, @key{TAB} characters cannot be used between a target name -and the following ``@code{:}'' character, and variable assignments -shouldn't be indented with @key{TAB} characters. -@c Keep this in sync with doc-parsing-buglets-colneq-subst.sh -Also, using more complex macro in target names can cause trouble: - -@example -% @kbd{cat Makefile.am} -$(FOO:=x): bar -% @kbd{automake} -Makefile.am:1: bad characters in variable name '$(FOO' -Makefile.am:1: ':='-style assignments are not portable -@end example - -@cindex Make targets, overriding -@cindex Make rules, overriding -@cindex Overriding make rules -@cindex Overriding make targets - -A rule defined in @file{Makefile.am} generally overrides any such -rule of a similar name that would be automatically generated by -@command{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. - -@cindex Variables, overriding -@cindex Overriding make variables - -Similarly, a variable defined in @file{Makefile.am} or -@code{AC_SUBST}ed from @file{configure.ac} will override any -definition of the variable that @command{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 -@command{automake} are considered to be for internal use only, and their -names might change in future releases. - -@cindex Recursive operation of Automake -@cindex Automake, recursive operation -@cindex Example of recursive operation - -When examining a variable definition, Automake will recursively examine -variables referenced in the definition. For example, if Automake is -looking at the content of @code{foo_SOURCES} in this snippet - -@c Keep in sync with interp.sh -@example -xs = a.c b.c -foo_SOURCES = c.c $(xs) -@end example - -it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the -contents of @code{foo_SOURCES}. - -@cindex @code{##} (special Automake comment) -@cindex Special Automake comment -@cindex Comment, special to Automake - -Automake also allows a form of comment that is @emph{not} copied into -the output; all lines beginning with @samp{##} (leading spaces allowed) -are completely ignored by Automake. - -It is customary to make the first line of @file{Makefile.am} read: - -@cindex Makefile.am, first line -@cindex First line of Makefile.am - -@example -## Process this file with automake to produce Makefile.in -@end example - -@c FIXME document customary ordering of Makefile.am here! - - -@node Strictness -@section Strictness - -@cindex Non-GNU packages - -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. - -@cindex Strictness, defined -@cindex Strictness, @option{foreign} -@cindex @option{foreign} strictness -@cindex Strictness, @option{gnu} -@cindex @option{gnu} strictness -@cindex Strictness, @option{gnits} -@cindex @option{gnits} strictness - -To this end, Automake supports three levels of @dfn{strictness}---the -strictness indicating how stringently Automake should check standards -conformance. - -The valid strictness levels are: - -@table @option -@item 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 @file{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. - -@item gnu -Automake will check---as much as possible---for compliance to the GNU -standards for packages. This is the default. - -@item gnits -Automake will check for compliance to the as-yet-unwritten @dfn{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). -@end table - -@xref{Gnits}, for more information on the precise implications of the -strictness level. - - -@node Uniform -@section The Uniform Naming Scheme - -@cindex Uniform naming scheme - -Automake variables generally follow a @dfn{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 -@command{configure} time determination of what should be built. - -@cindex @code{_PROGRAMS} primary variable -@cindex @code{PROGRAMS} primary variable -@cindex Primary variable, @code{PROGRAMS} -@cindex Primary variable, defined -@vindex _PROGRAMS - -At @command{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 @command{automake} what is being built is commonly called -the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a -list of programs that are to be compiled and linked. -@vindex PROGRAMS - -@cindex @code{pkgdatadir}, defined -@cindex @code{pkgincludedir}, defined -@cindex @code{pkglibdir}, defined -@cindex @code{pkglibexecdir}, defined - -@vindex pkgdatadir -@vindex pkgincludedir -@vindex pkglibdir -@vindex pkglibexecdir - -@cindex @code{PACKAGE}, directory -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 -(@pxref{Directory Variables, , , standards, The GNU Coding Standards}). -Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir}, -@code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the -non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance, -@code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}. - -@cindex @code{EXTRA_}, prepending -For each primary, there is one additional variable named by prepending -@samp{EXTRA_} to the primary name. This variable is used to list -objects that may or may not be built, depending on what -@command{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 @file{Makefile.in} that will work in all cases. - -@cindex @code{EXTRA_PROGRAMS}, defined -@cindex Example, @code{EXTRA_PROGRAMS} -@cindex @command{cpio} example - -For instance, @command{cpio} decides at configure time which programs -should be built. Some of the programs are installed in @code{bindir}, -and some are installed in @code{sbindir}: - -@example -EXTRA_PROGRAMS = mt rmt -bin_PROGRAMS = cpio pax -sbin_PROGRAMS = $(MORE_PROGRAMS) -@end example - -Defining a primary without a prefix as a variable, e.g., -@samp{PROGRAMS}, is an error. - -Note that the common @samp{dir} suffix is left off when constructing the -variable names; thus one writes @samp{bin_PROGRAMS} and not -@samp{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. - -@cindex Extending list of installation directories -@cindex Installation directories, extending list - -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., @samp{zar}) -is valid if a variable of the same name with @samp{dir} appended is -defined (e.g., @samp{zardir}). - -For instance, the following snippet will install @file{file.xml} into -@samp{$(datadir)/xml}. - -@c Keep in sync with primary-prefix-couples-documented-valid.sh -@example -xmldir = $(datadir)/xml -xml_DATA = file.xml -@end example - -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: - -@c Should be tested in primary-prefix-invalid-couples.sh -@example -# Forbidden directory combinations, automake will error out on this. -pkglib_PROGRAMS = foo -doc_LIBRARIES = libquux.a -@end example - -@noindent -but it will succeed with this: - -@c Keep in sync with primary-prefix-couples-documented-valid.sh -@example -# 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 -@end example - -The @samp{exec} substring of the @samp{my_execbindir} variable lets -the files be installed at the right time (@pxref{The Two Parts of -Install}). - -@cindex @samp{noinst_} primary prefix, definition -@vindex noinst_ - -The special prefix @samp{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 (@pxref{A Library}), or helper scripts. - -@cindex @samp{check_} primary prefix, definition -@vindex check_ - -The special prefix @samp{check_} indicates that the objects in question -should not be built until the @samp{make check} command is run. Those -objects are not installed either. - -The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES}, -@samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, -@samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and -@samp{TEXINFOS}. -@vindex PROGRAMS -@vindex LIBRARIES -@vindex LTLIBRARIES -@vindex LISP -@vindex PYTHON -@vindex JAVA -@vindex SCRIPTS -@vindex DATA -@vindex HEADERS -@vindex MANS -@vindex TEXINFOS - -Some primaries also allow additional prefixes that control other -aspects of @command{automake}'s behavior. The currently defined prefixes -are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}. -These prefixes are explained later (@pxref{Program and Library Variables}) -(@pxref{Man Pages}). - - -@node Length Limitations -@section Staying below the command line length limit - -@cindex command line length limit -@cindex ARG_MAX - -Traditionally, most unix-like systems have a length limitation for the -command line arguments and environment contents when creating new -processes (see for example -@uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an -overview on this issue), -which of course also applies to commands spawned by @command{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, - -@example -data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N} -@end example - -@noindent -may also be written as - -@c Keep in sync with primary-prefix-couples-documented-valid.sh -@example -data_DATA = file1 @dots{} file@var{N} -data2dir = $(datadir) -data2_DATA = file@var{N+1} @dots{} file@var{2N} -@end example - -@noindent -and will cause Automake to treat the two lists separately during -@code{make install}. See @ref{The Two Parts of Install} for choosing -directory names that will keep the ordering of the two parts of -installation Note that @code{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 @samp{$@{srcdir@}/} is prepended to file -names, as can happen with above @code{$(data_DATA)} lists, it limits -the amount of arguments passed to external commands. - -Unfortunately, some system's @command{make} commands may prepend -@code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the -source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic -Rule Rewriting, autoconf, The Autoconf Manual}). 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 -(@pxref{Libtool Convenience Libraries}). - - -@node Canonicalization -@section How derived variables are named - -@cindex canonicalizing Automake variables - -Sometimes a Makefile variable name is derived from some text the -maintainer supplies. For instance, a program name listed in -@samp{_PROGRAMS} is rewritten into the name of a @samp{_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 @file{sniff-glue}, the derived -variable name would be @samp{sniff_glue_SOURCES}, not -@samp{sniff-glue_SOURCES}. Similarly the sources for a library named -@file{libmumble++.a} should be listed in the -@samp{libmumble___a_SOURCES} variable. - -The strudel is an addition, to make the use of Autoconf substitutions in -variable names less obfuscating. - - -@node User Variables -@section Variables reserved for the user - -@cindex variables, reserved for the user -@cindex user variables - -Some @file{Makefile} variables are reserved by the GNU Coding Standards -for the use of the ``user''---the person building the package. For -instance, @code{CFLAGS} is one such variable. - -Sometimes package developers are tempted to set user variables such as -@code{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 @code{CC}, where they would make no -sense.) The shadow variable is named by prepending @samp{AM_} to the -user variable's name. For instance, the shadow variable for -@code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is, -the author(s) of the @file{Makefile.am} and @file{configure.ac} -files---may adjust these shadow variables however necessary. - -@xref{Flag Variables Ordering}, for more discussion about these -variables and how they interact with per-target variables. - -@node Auxiliary Programs -@section Programs automake might require - -@cindex Programs, auxiliary -@cindex Auxiliary programs - -Automake sometimes requires helper programs so that the generated -@file{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. - -@table @code -@item ar-lib -This is a wrapper primarily for the Microsoft lib archiver, to make -it more POSIX-like. - -@item compile -This is a wrapper for compilers that do not accept options @option{-c} -and @option{-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: @option{-I}, @option{-L}, @option{-l}, -@option{-Wl,} and @option{-Xlinker}. - -@item config.guess -@itemx 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 -@url{https://savannah.gnu.org/git/?group=config} before making a -release. - -@item 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 -(@pxref{Dependencies}). - -@item install-sh -This is a replacement for the @command{install} program that works on -platforms where @command{install} is unavailable or unusable. - -@item mdate-sh -This script is used to generate a @file{version.texi} file. It examines -a file and prints some date information about it. - -@item 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, -@command{missing} will print an informative warning before failing out, -to provide the user with more context and information. - -@item mkinstalldirs -This script used to be a wrapper around @samp{mkdir -p}, which is not -portable. Now we prefer to use @samp{install-sh -d} when @command{configure} -finds that @samp{mkdir -p} does not work, this makes one less script to -distribute. - -For backward compatibility @file{mkinstalldirs} is still used and -distributed when @command{automake} finds it in a package. But it is no -longer installed automatically, and it should be safe to remove it. - -@item py-compile -This is used to byte-compile Python scripts. - -@item test-driver -This implements the default test driver offered by the parallel -testsuite harness. - -@item texinfo.tex -Not a program, this file is required for @samp{make dvi}, @samp{make -ps} and @samp{make pdf} to work when Texinfo sources are in the -package. The latest version can be downloaded from -@url{https://www.gnu.org/software/texinfo/}. - -@item ylwrap -This program wraps @command{lex} and @command{yacc} to rename their -output files. It also ensures that, for instance, multiple -@command{yacc} instances can be invoked in a single directory in -parallel. - -@end table - - -@node Examples -@chapter Some example packages - -This section contains two small examples. - -The first example (@pxref{Complete}) assumes you have an existing -project already using Autoconf, with handcrafted @file{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 (@pxref{Hello World}). - -The second example (@pxref{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 -@end menu - - -@node Complete -@section A simple example, start to finish - -@cindex Complete example - -Let's suppose you just finished writing @code{zardoz}, a program to make -your head float from vortex to vortex. You've been using Autoconf to -provide a portability framework, but your @file{Makefile.in}s have been -ad-hoc. You want to make them bulletproof, so you turn to Automake. - -@cindex @code{AM_INIT_AUTOMAKE}, example use - -The first step is to update your @file{configure.ac} to include the -commands that @command{automake} needs. The way to do this is to add an -@code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}: - -@example -AC_INIT([zardoz], [1.0]) -AM_INIT_AUTOMAKE -@dots{} -@end example - -Since your program doesn't have any complicating factors (e.g., it -doesn't use @code{gettext}, it doesn't want to build a shared library), -you're done with this part. That was easy! - -@cindex @command{aclocal} program, introduction -@cindex @file{aclocal.m4}, preexisting -@cindex @file{acinclude.m4}, defined - -Now you must regenerate @file{configure}. But to do that, you'll need -to tell @command{autoconf} how to find the new macro you've used. The -easiest way to do this is to use the @command{aclocal} program to -generate your @file{aclocal.m4} for you. But wait@dots{} maybe you -already have an @file{aclocal.m4}, because you had to write some hairy -macros for your program. The @command{aclocal} program lets you put -your own macros into @file{acinclude.m4}, so simply rename and then -run: - -@example -mv aclocal.m4 acinclude.m4 -aclocal -autoconf -@end example - -@cindex @command{zardoz} example - -Now it is time to write your @file{Makefile.am} for @code{zardoz}. -Since @code{zardoz} is a user program, you want to install it where the -rest of the user programs go: @code{bindir}. Additionally, -@code{zardoz} has some Texinfo documentation. Your @file{configure.ac} -script uses @code{AC_REPLACE_FUNCS}, so you need to link against -@samp{$(LIBOBJS)}. So here's what you'd write: - -@example -bin_PROGRAMS = zardoz -zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c -zardoz_LDADD = $(LIBOBJS) - -info_TEXINFOS = zardoz.texi -@end example - -Now you can run @samp{automake --add-missing} to generate your -@file{Makefile.in} and grab any auxiliary files you might need, and -you're done! - - -@node true -@section Building true and false - -@cindex Example, @command{false} and @command{true} -@cindex @command{false} Example -@cindex @command{true} Example - -Here is another, trickier example. It shows how to generate two -programs (@code{true} and @code{false}) from the same source file -(@file{true.c}). The difficult part is that each compilation of -@file{true.c} requires different @code{cpp} flags. - -@example -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 -@end example - -Note that there is no @code{true_SOURCES} definition. Automake will -implicitly assume that there is a source file named @file{true.c} -(@pxref{Default _SOURCES}), and -define rules to compile @file{true.o} and link @file{true}. The -@samp{true.o: true.c} rule supplied by the above @file{Makefile.am}, -will override the Automake generated rule to build @file{true.o}. - -@code{false_SOURCES} is defined to be empty---that way no implicit value -is substituted. Because we have not listed the source of -@file{false}, we have to tell Automake how to link the program. This is -the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES} -variable, holding the dependencies of the @file{false} target will be -automatically generated by Automake from the content of -@code{false_LDADD}. - -The above rules won't work if your compiler doesn't accept both -@option{-c} and @option{-o}. The simplest fix for this is to introduce a -bogus dependency (to avoid problems with a parallel @command{make}): - -@example -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 -@end example - -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 @code{true} and -@code{false} in real life, you would probably use per-program -compilation flags, like so: - -@c Keep in sync with specflg7.sh and specflg8.sh -@example -bin_PROGRAMS = false true - -false_SOURCES = true.c -false_CPPFLAGS = -DEXIT_CODE=1 - -true_SOURCES = true.c -true_CPPFLAGS = -DEXIT_CODE=0 -@end example - -In this case Automake will cause @file{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 @file{false-true.o} and -@file{true-true.o}. (The name of the object files rarely matters.) - -@node automake Invocation -@chapter Creating a @file{Makefile.in} -@c This node used to be named "Invoking automake". This @anchor -@c allows old links to still work. -@anchor{Invoking automake} - -@cindex Multiple @file{configure.ac} files -@cindex Invoking @command{automake} -@cindex @command{automake}, invoking -@cindex Invocation of @command{automake} -@cindex @command{automake}, invocation - -To create all the @file{Makefile.in}s for a package, run the -@command{automake} program in the top level directory, with no -arguments. @command{automake} will automatically find each -appropriate @file{Makefile.am} (by scanning @file{configure.ac}; -@pxref{configure}) and generate the corresponding @file{Makefile.in}. -Note that @command{automake} has a rather simplistic view of what -constitutes a package; it assumes that a package has only one -@file{configure.ac}, at the top. If your package has multiple -@file{configure.ac}s, then you must run @command{automake} in each -directory holding a @file{configure.ac}. (Alternatively, you may rely -on Autoconf's @command{autoreconf}, which is able to recurse your -package tree and run @command{automake} where appropriate.) - -You can optionally give @command{automake} an argument; @file{.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 @file{Makefile.in}. Note that -@command{automake} must always be run from the topmost directory of a -project, even if being used to regenerate the @file{Makefile.in} in -some subdirectory. This is necessary because @command{automake} must -scan @file{configure.ac}, and because @command{automake} uses the -knowledge that a @file{Makefile.in} is in a subdirectory to change its -behavior in some cases. - -@vindex AUTOCONF -Automake will run @command{autoconf} to scan @file{configure.ac} and -its dependencies (i.e., @file{aclocal.m4} and any included file), -therefore @command{autoconf} must be in your @env{PATH}. If there is -an @env{AUTOCONF} variable in your environment it will be used -instead of @command{autoconf}, this allows you to select a particular -version of Autoconf. By the way, don't misunderstand this paragraph: -@command{automake} runs @command{autoconf} to @strong{scan} your -@file{configure.ac}, this won't build @file{configure} and you still -have to run @command{autoconf} yourself for this purpose. - -@cindex @command{automake} options -@cindex Options, @command{automake} -@cindex Strictness, command line - -@command{automake} accepts the following options: - -@cindex Extra files distributed with Automake -@cindex Files distributed with Automake -@cindex @file{config.guess} - -@table @code -@item -a -@itemx --add-missing -@opindex -a -@opindex --add-missing -Automake requires certain common files to exist in certain situations; -for instance, @file{config.guess} is required if @file{configure.ac} invokes -@code{AC_CANONICAL_HOST}. Automake is distributed with several of these -files (@pxref{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 @option{--copy}. - -Many of the potentially-missing files are common scripts whose -location may be specified via the @code{AC_CONFIG_AUX_DIR} macro. -Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a -file is considered missing, and where the missing file is added -(@pxref{Optional}). - -In some strictness modes, additional files are installed, see @ref{Gnits} -for more information. - -@item --libdir=@var{dir} -@opindex --libdir -Look for Automake data files in directory @var{dir} instead of in the -installation directory. This is typically used for debugging. - -@vindex AUTOMAKE_LIBDIR -The environment variable @env{AUTOMAKE_LIBDIR} provides another way to -set the directory containing Automake data files. However -@option{--libdir} takes precedence over it. - -@item --print-libdir -@opindex --print-libdir -Print the path of the installation directory containing Automake-provided -scripts and data files (like e.g., @file{texinfo.texi} and -@file{install-sh}). - -@item -c -@opindex -c -@itemx --copy -@opindex --copy -When used with @option{--add-missing}, causes installed files to be -copied. The default is to make a symbolic link. - -@item -f -@opindex -f -@itemx --force-missing -@opindex --force-missing -When used with @option{--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 -@option{--copy}, copying the new file). - -@item --foreign -@opindex --foreign -Set the global strictness to @option{foreign}. For more information, see -@ref{Strictness}. - -@item --gnits -@opindex --gnits -Set the global strictness to @option{gnits}. For more information, see -@ref{Gnits}. - -@item --gnu -@opindex --gnu -Set the global strictness to @option{gnu}. For more information, see -@ref{Gnits}. This is the default strictness. - -@item --help -@opindex --help -Print a summary of the command line options and exit. - -@item -i -@itemx --ignore-deps -@opindex -i -This disables the dependency tracking feature in generated -@file{Makefile}s; see @ref{Dependencies}. - -@item --include-deps -@opindex --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. - -@item --no-force -@opindex --no-force -Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in -@file{configure.ac}. This option causes it to only update those -@file{Makefile.in}s that are out of date with respect to one of their -dependents. - -@item -o @var{dir} -@itemx --output-dir=@var{dir} -@opindex -o -@opindex --output-dir -Put the generated @file{Makefile.in} in the directory @var{dir}. -Ordinarily each @file{Makefile.in} is created in the directory of the -corresponding @file{Makefile.am}. This option is deprecated and will be -removed in a future release. - -@item -v -@itemx --verbose -@opindex -v -@opindex --verbose -Cause Automake to print information about which files are being read or -created. - -@item --version -@opindex --version -Print the version number of Automake and exit. - -@item -W CATEGORY -@itemx --warnings=@var{category} -@opindex -W -@opindex --warnings -Output warnings falling in @var{category}. @var{category} can be -one of: -@table @code -@item gnu -warnings related to the GNU Coding Standards -(@pxref{Top, , , standards, The GNU Coding Standards}). -@item obsolete -obsolete features or constructions -@item override -user redefinitions of Automake rules or variables -@item portability -portability issues (e.g., use of @command{make} features that are -known to be not portable) -@item extra-portability -extra portability issues related to obscure tools. One example of such -a tool is the Microsoft @command{lib} archiver. -@item syntax -weird syntax, unused variables, typos -@item unsupported -unsupported or incomplete features -@item all -all the warnings -@item none -turn off all the warnings -@item error -treat warnings as errors -@end table - -A category can be turned off by prefixing its name with @samp{no-}. For -instance, @option{-Wno-syntax} will hide the warnings about unused -variables. - -The categories output by default are @samp{obsolete}, @samp{syntax} and -@samp{unsupported}. Additionally, @samp{gnu} and @samp{portability} -are enabled in @option{--gnu} and @option{--gnits} strictness. - -@c Checked by extra-portability.sh -Turning off @samp{portability} will also turn off @samp{extra-portability}, -and similarly turning on @samp{extra-portability} will also turn on -@samp{portability}. However, turning on @samp{portability} or turning -off @samp{extra-portability} will not affect the other category. - -@vindex WARNINGS -The environment variable @env{WARNINGS} can contain a comma separated -list of categories to enable. It will be taken into account before the -command-line switches, this way @option{-Wnone} will also ignore any -warning category enabled by @env{WARNINGS}. This variable is also used -by other tools like @command{autoconf}; unknown categories are ignored -for this reason. - -@end table - -@vindex AUTOMAKE_JOBS -If the environment variable @env{AUTOMAKE_JOBS} contains a positive -number, it is taken as the maximum number of Perl threads to use in -@command{automake} for generating multiple @file{Makefile.in} files -concurrently. This is an experimental feature. - - -@node configure -@chapter Scanning @file{configure.ac}, using @command{aclocal} - -@cindex @file{configure.ac}, scanning -@cindex Scanning @file{configure.ac} -@cindex Using @command{aclocal} -@cindex @command{aclocal}, using - -Automake scans the package's @file{configure.ac} to determine certain -information about the package. Some @command{autoconf} macros are required -and some variables must be defined in @file{configure.ac}. Automake -will also use information from @file{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 -@file{aclocal.m4} using the @command{aclocal} program. - -@menu -* Requirements:: Configuration requirements -* Optional:: Other things Automake recognizes -* aclocal Invocation:: Auto-generating aclocal.m4 -* Macros:: Autoconf macros supplied with Automake -@end menu - - -@node Requirements -@section Configuration requirements - -@cindex Automake requirements -@cindex Requirements of Automake - -@acindex AM_INIT_AUTOMAKE -The one real requirement of Automake is that your @file{configure.ac} -call @code{AM_INIT_AUTOMAKE}. This macro does several things that are -required for proper Automake operation (@pxref{Macros}). - -Here are the other macros that Automake requires but which are not run -by @code{AM_INIT_AUTOMAKE}: - -@table @code -@item AC_CONFIG_FILES -@itemx AC_OUTPUT -@acindex AC_CONFIG_FILES -@acindex AC_OUTPUT -These two macros are usually invoked as follows near the end of -@file{configure.ac}. - -@example -@dots{} -AC_CONFIG_FILES([ - Makefile - doc/Makefile - src/Makefile - src/lib/Makefile - @dots{} -]) -AC_OUTPUT -@end example - -Automake uses these to determine which files to create (@pxref{Output, , -Creating Output Files, autoconf, The Autoconf Manual}). A listed file -is considered to be an Automake generated @file{Makefile} if there -exists a file with the same name and the @file{.am} extension appended. -Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to -generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists. - -When using @code{AC_CONFIG_FILES} with multiple input files, as in - -@example -AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in]) -@end example - -@noindent -@command{automake} will generate the first @file{.in} input file for -which a @file{.am} file exists. If no such file exists the output -file is not considered to be generated by Automake. - -Files created by @code{AC_CONFIG_FILES}, be they Automake -@file{Makefile}s or not, are all removed by @samp{make distclean}. -Their inputs are automatically distributed, unless they -are the output of prior @code{AC_CONFIG_FILES} commands. -Finally, rebuild rules are generated in the Automake @file{Makefile} -existing in the subdirectory of the output file, if there is one, or -in the top-level @file{Makefile} otherwise. - -The above machinery (cleaning, distributing, and rebuilding) works -fine if the @code{AC_CONFIG_FILES} specifications contain only -literals. If part of the specification uses shell variables, -@command{automake} will not be able to fulfill this setup, and you will -have to complete the missing bits by hand. For instance, on - -@c Keep in sync with output11.sh -@example -file=input -@dots{} -AC_CONFIG_FILES([output:$file],, [file=$file]) -@end example - -@noindent -@command{automake} will output rules to clean @file{output}, and -rebuild it. However the rebuild rule will not depend on @file{input}, -and this file will not be distributed either. (You must add -@samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a -source file.) - -Similarly - -@c Keep in sync with output11.sh -@example -file=output -file2=out:in -@dots{} -AC_CONFIG_FILES([$file:input],, [file=$file]) -AC_CONFIG_FILES([$file2],, [file2=$file2]) -@end example - -@noindent -will only cause @file{input} to be distributed. No file will be -cleaned automatically (add @samp{DISTCLEANFILES = output out} -yourself), and no rebuild rule will be output. - -Obviously @command{automake} cannot guess what value @samp{$file} is -going to hold later when @file{configure} is run, and it cannot use -the shell variable @samp{$file} in a @file{Makefile}. However, if you -make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way -that is compatible with @command{make}'s syntax) and furthermore use -@code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a -@file{Makefile}, then @command{automake} will be able to use -@samp{$@{file@}} to generate all of these rules. For instance, here is -how the Automake package itself generates versioned scripts for its -test suite: - -@example -AC_SUBST([APIVERSION], @dots{}) -@dots{} -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@}]) -@end example - -@noindent -Here cleaning, distributing, and rebuilding are done automatically, -because @samp{$@{APIVERSION@}} is known at @command{make}-time. - -Note that you should not use shell variables to declare -@file{Makefile} files for which @command{automake} must create -@file{Makefile.in}. Even @code{AC_SUBST} does not help here, because -@command{automake} needs to know the file name when it runs in order -to check whether @file{Makefile.am} exists. (In the very hairy case -that your setup requires such use of variables, you will have to tell -Automake which @file{Makefile.in}s to generate on the command-line.) - -It is possible to let @command{automake} emit conditional rules for -@code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF} -(@pxref{Optional}). - -To summarize: -@itemize @bullet -@item -Use literals for @file{Makefile}s, and for other files whenever possible. -@item -Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])}) -for files that @command{automake} should ignore. -@item -Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files -that @command{automake} should not ignore. -@end itemize - -@end table - - -@node Optional -@section Other things Automake recognizes - -@cindex Macros Automake recognizes -@cindex Recognized macros by Automake - -Every time Automake is run it calls Autoconf to trace -@file{configure.ac}. This way it can recognize the use of certain -macros and tailor the generated @file{Makefile.in} appropriately. -Currently recognized macros and their effects are: - -@ftable @code -@item AC_CANONICAL_BUILD -@itemx AC_CANONICAL_HOST -@itemx AC_CANONICAL_TARGET -@vindex build_triplet -@vindex host_triplet -@vindex target_triplet -Automake will ensure that @file{config.guess} and @file{config.sub} -exist. Also, the @file{Makefile} variables @code{build_triplet}, -@code{host_triplet} and @code{target_triplet} are introduced. See -@ref{Canonicalizing, , Getting the Canonical System Type, autoconf, -The Autoconf Manual}. - -@item AC_CONFIG_AUX_DIR -Automake will look for various helper scripts, such as -@file{install-sh}, in the directory named in this macro invocation. -@c This list is accurate relative to version 1.11 -(The full list of scripts is: -@file{ar-lib}, -@file{config.guess}, -@file{config.sub}, -@file{depcomp}, -@file{compile}, -@file{install-sh}, -@file{ltmain.sh}, -@file{mdate-sh}, -@file{missing}, -@file{mkinstalldirs}, -@file{py-compile}, -@file{test-driver}, -@file{texinfo.tex}, -@file{ylwrap}.) -Not all scripts are always searched for; some scripts -will only be sought if the generated @file{Makefile.in} requires them. - -If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in -their standard locations. For @file{mdate-sh}, -@file{texinfo.tex}, and @file{ylwrap}, the standard location is the -source directory corresponding to the current @file{Makefile.am}. For -the rest, the standard location is the first one of @file{.}, @file{..}, -or @file{../..} (relative to the top source directory) that provides any -one of the helper scripts. @xref{Input, , Finding `configure' Input, -autoconf, The Autoconf Manual}. - -Required files from @code{AC_CONFIG_AUX_DIR} are automatically -distributed, even if there is no @file{Makefile.am} in this directory. - -@item AC_CONFIG_LIBOBJ_DIR -Automake will require the sources file declared with -@code{AC_LIBSOURCE} (see below) in the directory specified by this -macro. - -@item AC_CONFIG_HEADERS -Automake will generate rules to rebuild these headers from the -corresponding templates (usually, the template for a @file{foo.h} -header being @file{foo.h.in}). Older versions of Automake -required the use of @code{AM_CONFIG_HEADER}; this is no longer -the case, and that macro has indeed been removed. - -As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the -specification using shell variables will be ignored as far as -cleaning, distributing, and rebuilding is concerned. - -@item AC_CONFIG_LINKS -Automake will generate rules to remove @file{configure} generated -links on @samp{make distclean} and to distribute named source files as -part of @samp{make dist}. - -As for @code{AC_CONFIG_FILES} (@pxref{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.) - -@item AC_LIBOBJ -@itemx AC_LIBSOURCE -@itemx AC_LIBSOURCES -@vindex LIBOBJS -Automake will automatically distribute any file listed in -@code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}. - -Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if -an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then -@file{file.c} will be distributed automatically by Automake. This -encompasses many macros like @code{AC_FUNC_ALLOCA}, -@code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others. - -By the way, direct assignments to @code{LIBOBJS} are no longer -supported. You should always use @code{AC_LIBOBJ} for this purpose. -@xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, -autoconf, The Autoconf Manual}. - -@item AC_PROG_RANLIB -This is required if any libraries are built in the package. -@xref{Particular Programs, , Particular Program Checks, autoconf, The -Autoconf Manual}. - -@item AC_PROG_CXX -This is required if any C++ source is included. @xref{Particular -Programs, , Particular Program Checks, autoconf, The Autoconf Manual}. - -@item AC_PROG_OBJC -This is required if any Objective C source is included. @xref{Particular -Programs, , Particular Program Checks, autoconf, The Autoconf Manual}. - -@item AC_PROG_OBJCXX -This is required if any Objective C++ source is included. @xref{Particular -Programs, , Particular Program Checks, autoconf, The Autoconf Manual}. - -@item AC_PROG_F77 -This is required if any Fortran 77 source is included. @xref{Particular -Programs, , Particular Program Checks, autoconf, The Autoconf Manual}. - -@item AC_F77_LIBRARY_LDFLAGS -This is required for programs and shared libraries that are a mixture of -languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and -C++}). @xref{Macros, , Autoconf macros supplied with Automake}. - -@item AC_FC_SRCEXT -Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation -of files with the respective source extension (@pxref{Fortran Compiler, , -Fortran Compiler Characteristics, autoconf, The Autoconf Manual}). - -@item 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. @xref{Particular -Programs, , Particular Program Checks, autoconf, The Autoconf Manual}. - -@item AC_PROG_LIBTOOL -Automake will turn on processing for @command{libtool} (@pxref{Top, , -Introduction, libtool, The Libtool Manual}). - -@item AC_PROG_YACC -@vindex YACC -If a Yacc source file is seen, then you must either use this macro or -define the variable @code{YACC} in @file{configure.ac}. The former is -preferred (@pxref{Particular Programs, , Particular Program Checks, -autoconf, The Autoconf Manual}). - -@item AC_PROG_LEX -If a Lex source file is seen, then this macro must be used. -@xref{Particular Programs, , Particular Program Checks, autoconf, The -Autoconf Manual}. - -@item AC_REQUIRE_AUX_FILE -For each @code{AC_REQUIRE_AUX_FILE([@var{file}])}, -@command{automake} will ensure that @file{@var{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 @code{AC_CONFIG_AUX_DIR} -above. @xref{Input, , Finding @command{configure} Input, autoconf, -The Autoconf Manual}. - -@item AC_SUBST -The first argument is automatically defined as a variable in each -generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also -used for this variable. @xref{Setting Output Variables, , Setting -Output Variables, autoconf, The Autoconf Manual}. - -For every substituted variable @var{var}, @command{automake} will add -a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file. -Many Autoconf macros invoke @code{AC_SUBST} to set output variables -this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and -@code{X_LIBS}. Thus, you can access these variables as -@code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am} -if @code{AC_PATH_XTRA} is called. - -@item AM_CONDITIONAL -This introduces an Automake conditional (@pxref{Conditionals}). - -@item AM_COND_IF -This macro allows @code{automake} to detect subsequent access within -@file{configure.ac} to a conditional previously introduced with -@code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES} -(@pxref{Usage of Conditionals}). - -@item AM_GNU_GETTEXT -This macro is required for packages that use GNU gettext -(@pxref{gettext}). It is distributed with gettext. If Automake sees -this macro it ensures that the package meets some of gettext's -requirements. - -@item AM_GNU_GETTEXT_INTL_SUBDIR -This macro specifies that the @file{intl/} subdirectory is to be built, -even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument -of @samp{external}. - -@item AM_MAINTAINER_MODE(@ovar{default-mode}) -@opindex --enable-maintainer-mode -@opindex --disable-maintainer-mode -This macro adds an @option{--enable-maintainer-mode} option to -@command{configure}. If this is used, @command{automake} will cause -``maintainer-only'' rules to be turned off by default in the -generated @file{Makefile.in}s, unless @var{default-mode} is -@samp{enable}. This macro defines the @code{MAINTAINER_MODE} -conditional, which you can use in your own @file{Makefile.am}. -@xref{maintainer-mode}. - -@item AM_SUBST_NOTMAKE(@var{var}) -Prevent Automake from defining a variable @var{var}, even if it is -substituted by @command{config.status}. Normally, Automake defines a -@command{make} variable for each @command{configure} substitution, -i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that -definition from Automake. If @code{AC_SUBST} has not been called -for this variable, then @code{AM_SUBST_NOTMAKE} has no effects. -Preventing variable definitions may be useful for substitution of -multi-line values, where @code{@var{var} = @@@var{value}@@} might yield -unintended results. - -@item m4_include -Files included by @file{configure.ac} using this macro will be -detected by Automake and automatically distributed. They will also -appear as dependencies in @file{Makefile} rules. - -@code{m4_include} is seldom used by @file{configure.ac} authors, but -can appear in @file{aclocal.m4} when @command{aclocal} detects that -some required macros come from files local to your package (as opposed to -macros installed in a system-wide directory, @pxref{aclocal Invocation}). - -@end ftable - -@node aclocal Invocation -@section Auto-generating aclocal.m4 -@c This node used to be named "Invoking automake". This @anchor -@c allows old links to still work. -@anchor{Invoking aclocal} - -@cindex Invocation of @command{aclocal} -@cindex @command{aclocal}, Invocation -@cindex Invoking @command{aclocal} -@cindex @command{aclocal}, Invoking - -Automake includes a number of Autoconf macros that can be used in -your package (@pxref{Macros}); some of them are actually required by -Automake in certain situations. These macros must be defined in your -@file{aclocal.m4}; otherwise they will not be seen by -@command{autoconf}. - -The @command{aclocal} program will automatically generate -@file{aclocal.m4} files based on the contents of @file{configure.ac}. -This provides a convenient way to get Automake-provided macros, -without having to search around. The @command{aclocal} mechanism -allows other packages to supply their own macros (@pxref{Extending -aclocal}). You can also use it to maintain your own set of custom -macros (@pxref{Local Macros}). - -At startup, @command{aclocal} scans all the @file{.m4} files it can -find, looking for macro definitions (@pxref{Macro Search Path}). Then -it scans @file{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 @file{aclocal.m4}. - -@emph{Putting} the file that contains the macro definition into -@file{aclocal.m4} is usually done by copying the entire text of this -file, including unused macro definitions as well as both @samp{#} and -@samp{dnl} comments. If you want to make a comment that will be -completely ignored by @command{aclocal}, use @samp{##} as the comment -leader. - -When a file selected by @command{aclocal} is located in a subdirectory -specified as a relative search path with @command{aclocal}'s @option{-I} -argument, @command{aclocal} assumes the file belongs to the package -and uses @code{m4_include} instead of copying it into -@file{aclocal.m4}. This makes the package smaller, eases dependency -tracking, and cause the file to be distributed automatically. -(@xref{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 @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever -some relative directory should be considered outside the package. - -The contents of @file{acinclude.m4}, if this file exists, are also -automatically included in @file{aclocal.m4}. We recommend against -using @file{acinclude.m4} in new packages (@pxref{Local Macros}). - -@vindex AUTOM4TE -@cindex autom4te -While computing @file{aclocal.m4}, @command{aclocal} runs -@command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te}, -autoconf, The Autoconf Manual}) in order to trace the macros that are -really used, and omit from @file{aclocal.m4} all macros that are -mentioned but otherwise unexpanded (this can happen when a macro is -called conditionally). @command{autom4te} is expected to be in the -@env{PATH}, just as @command{autoconf}. Its location can be -overridden using the @env{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 -@end menu - -@node aclocal Options -@subsection aclocal Options - -@cindex @command{aclocal}, Options -@cindex Options, @command{aclocal} - -@command{aclocal} accepts the following options: - -@table @code -@item --automake-acdir=@var{dir} -@opindex --automake-acdir -Look for the automake-provided macro files in @var{dir} instead of -in the installation directory. This is typically used for debugging. - -@vindex ACLOCAL_AUTOMAKE_DIR -The environment variable @env{ACLOCAL_AUTOMAKE_DIR} provides another -way to set the directory containing automake-provided macro files. -However @option{--automake-acdir} takes precedence over it. - -@item --system-acdir=@var{dir} -@opindex --system-acdir -Look for the system-wide third-party macro files (and the special -@file{dirlist} file) in @var{dir} instead of in the installation -directory. This is typically used for debugging. - -@item --diff[=@var{command}] -@opindex --diff -Run @var{command} on M4 file that would be installed or overwritten -by @option{--install}. The default @var{command} is @samp{diff -u}. -This option implies @option{--install} and @option{--dry-run}. - -@item --dry-run -@opindex --dry-run -Do not actually overwrite (or create) @file{aclocal.m4} and M4 -files installed by @option{--install}. - -@item --help -@opindex --help -Print a summary of the command line options and exit. - -@item -I @var{dir} -@opindex -I -Add the directory @var{dir} to the list of directories searched for -@file{.m4} files. - -@item --install -@opindex --install -Install system-wide third-party macros into the first directory -specified with @samp{-I @var{dir}} instead of copying them in the -output file. -@c Keep in sync with aclocal-install-absdir.sh -Note that this will happen also if @var{dir} is an absolute path. - -@cindex serial number and @option{--install} -When this option is used, and only when this option is used, -@command{aclocal} will also honor @samp{#serial @var{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 (@pxref{Serials}). - -@item --force -@opindex --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 @file{aclocal.m4} (or the file -specified with @file{--output} below) and only this file, it has -absolutely no influence on files that may need to be installed by -@option{--install}. - -@item --output=@var{file} -@opindex --output -Cause the output to be put into @var{file} instead of @file{aclocal.m4}. - -@item --print-ac-dir -@opindex --print-ac-dir -Prints the name of the directory that @command{aclocal} will search to -find third-party @file{.m4} files. When this option is given, normal -processing is suppressed. This option was used @emph{in the past} by -third-party packages to determine where to install @file{.m4} macro -files, but @emph{this usage is today discouraged}, since it causes -@samp{$(prefix)} not to be thoroughly honored (which violates the -GNU Coding Standards), and a similar semantics can be better obtained -with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}. - -@item --verbose -@opindex --verbose -Print the names of the files it examines. - -@item --version -@opindex --version -Print the version number of Automake and exit. - -@item -W CATEGORY -@item --warnings=@var{category} -@opindex -W -@opindex --warnings -Output warnings falling in @var{category}. @var{category} can be -one of: -@table @code -@item syntax -dubious syntactic constructs, underquoted macros, unused macros, etc. -@item unsupported -unknown macros -@item all -all the warnings, this is the default -@item none -turn off all the warnings -@item error -treat warnings as errors -@end table - -All warnings are output by default. - -@vindex WARNINGS -The environment variable @env{WARNINGS} is honored in the same -way as it is for @command{automake} (@pxref{automake Invocation}). - -@end table - -@node Macro Search Path -@subsection Macro Search Path - -@cindex Macro search path -@cindex @command{aclocal} search path - -By default, @command{aclocal} searches for @file{.m4} files in the -following directories, in this order: - -@table @code -@item @var{acdir} -This directory is intended for third party @file{.m4} files, and is -configured when @command{automake} itself is built. This is -@file{@@datadir@@/aclocal/}, which typically -expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in -value of @var{acdir}, use the @option{--print-ac-dir} option -(@pxref{aclocal Options}). - -@item @var{acdir-APIVERSION} -This is where the @file{.m4} macros distributed with Automake itself -are stored. @var{APIVERSION} depends on the Automake release used; -for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}. -@end table - -As an example, suppose that @command{automake-1.11.2} was configured with -@option{--prefix=@-/usr/local}. Then, the search path would be: - -@enumerate -@item @file{/usr/local/share/aclocal/} -@item @file{/usr/local/share/aclocal-1.11.2/} -@end enumerate - -The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can -be changed respectively through aclocal options @option{--system-acdir} -and @option{--automake-acdir} (@pxref{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 (@pxref{aclocal Options}), there are several options that -can be used to change or extend this search path. - -@subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}} - -Any extra directories specified using @option{-I} options -(@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus, -@samp{aclocal -I /foo -I /bar} results in the following search path: - -@enumerate -@item @file{/foo} -@item @file{/bar} -@item @var{acdir} -@item @var{acdir}-@var{APIVERSION} -@end enumerate - -@subsubheading Modifying the Macro Search Path: @file{dirlist} -@cindex @file{dirlist} - -There is a third mechanism for customizing the search path. If a -@file{dirlist} file exists in @var{acdir}, then that file is assumed to -contain a list of directory patterns, one per line. @command{aclocal} -expands these patterns to directory names, and adds them to the search -list @emph{after} all other directories. @file{dirlist} entries may -use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}. - -For example, suppose -@file{@var{acdir}/dirlist} contains the following: - -@example -/test1 -/test2 -/test3* -@end example - -@noindent -and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options. -Then, the search path would be - -@c @code looks better than @file here -@c See test aclocal-dirlist.sh -@enumerate -@item @code{/foo} -@item @code{/bar} -@item @var{acdir} -@item @code{/test1} -@item @code{/test2} -@item @var{acdir}-@var{APIVERSION} -@end enumerate - -@noindent -and all directories with path names starting with @code{/test3}. - -If the @option{--system-acdir=@var{dir}} option is used, then -@command{aclocal} will search for the @file{dirlist} file in -@var{dir}; but remember the warnings above against the use of -@option{--system-acdir}. - -@file{dirlist} is useful in the following situation: suppose that -@command{automake} version @code{1.11.2} is installed with -@samp{--prefix=/usr} by the system vendor. Thus, the default search -directories are - -@c @code looks better than @file here -@c Keep in sync with aclocal-path-precedence.sh -@enumerate -@item @code{/usr/share/aclocal/} -@item @code{/usr/share/aclocal-1.11/} -@end enumerate - -However, suppose further that many packages have been manually installed -on the system, with @code{$@{prefix@}=/usr/local}, as is typical. In -that case, many of these ``extra'' @file{.m4} files are in -@file{/usr/local/share/aclocal}. A way to force @file{/usr/bin/aclocal} -to find these ``extra'' @file{.m4} files is to export @code{ACLOCAL_PATH} -to @samp{/usr/local/share/aclocal}. This is a little inconvenient, -since it requires either explicit user cooperation, or editing of the -system global shell initialization file. With @file{dirlist}, one may -create a file @file{/usr/share/aclocal/dirlist} containing only the -single line - -@example -/usr/local/share/aclocal -@end example - -Now, the ``default'' search path on the affected system is - -@c @code looks better than @file here -@c See test aclocal-dirlist.sh -@enumerate -@item @code{/usr/share/aclocal/} -@item @code{/usr/local/share/aclocal/} -@item @code{/usr/share/aclocal-1.11/} -@end enumerate - -without the need of any explicit @code{ACLOCAL_PATH} setting. - -Similarly, @file{dirlist} can be handy if you have installed a local -copy of Automake in your account and want @command{aclocal} to look -for macros installed at other places on the system. - -@anchor{ACLOCAL_PATH} -@subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH} -@cindex @env{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 @env{ACLOCAL_PATH} is added to the search path -@c Keep in sync with aclocal-path-precedence.sh -and takes precedence over system directories (including those found via -@file{dirlist}), with the exception of the versioned directory -@var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories -passed via @option{-I} will take precedence over directories in -@env{ACLOCAL_PATH}. - -@c Keep in sync with aclocal-path-installed.sh -Also note that, if the @option{--install} option is used, any @file{.m4} -file containing a required macro that is found in a directory listed in -@env{ACLOCAL_PATH} will be installed locally. -@c Keep in sync with aclocal-path-installed-serial.sh -In this case, serial numbers in @file{.m4} are honored too, -@pxref{Serials}. - -Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are -using a global copy of Automake and want @command{aclocal} to look for -macros somewhere under your home directory. - -@node Extending aclocal -@subsection Writing your own aclocal macros - -@cindex @command{aclocal}, extending -@cindex Extending @command{aclocal} - -The @command{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 @command{gettext} -library supplies a macro @code{AM_GNU_GETTEXT} that should be used by -any package using @command{gettext}. When the library is installed, it -installs this macro so that @command{aclocal} will find it. - -A macro file's name should end in @file{.m4}. Such files should be -installed in @file{$(datadir)/aclocal}. This is as simple as writing: - -@c Keep in sync with primary-prefix-couples-documented-valid.sh -@example -aclocaldir = $(datadir)/aclocal -aclocal_DATA = mymacro.m4 myothermacro.m4 -@end example - -@noindent -Please do use @file{$(datadir)/aclocal}, and not something based on -the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install -Paths}, for rationale). It might also be helpful to suggest to -the user to add the @file{$(datadir)/aclocal} directory to his -@env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that -@command{aclocal} will find the @file{.m4} files installed by your -package automatically. - -A file of macros should be a series of properly quoted -@code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The -Autoconf Manual}). The @command{aclocal} programs also understands -@code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The -Autoconf Manual}), 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 @code{AC_PREREQ} should be done inside the -defined macro, not at the beginning of the file. - -@cindex underquoted @code{AC_DEFUN} -@acindex AC_DEFUN -@acindex AC_PREREQ - -Starting with Automake 1.8, @command{aclocal} will warn about all -underquoted calls to @code{AC_DEFUN}. We realize this will annoy a -lot of people, because @command{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 @command{aclocal} (@pxref{Future of -aclocal}) will have to temporarily include all of these third party -@file{.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, - -@example -# bad style -AC_PREREQ(2.68) -AC_DEFUN(AX_FOOBAR, -[AC_REQUIRE([AX_SOMETHING])dnl -AX_FOO -AX_BAR -]) -@end example - -@noindent -should be rewritten as - -@example -AC_DEFUN([AX_FOOBAR], -[AC_PREREQ([2.68])dnl -AC_REQUIRE([AX_SOMETHING])dnl -AX_FOO -AX_BAR -]) -@end example - -Wrapping the @code{AC_PREREQ} call inside the macro ensures that -Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually -used. Most importantly, quoting the first argument of @code{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 @code{2.68} that -do not require it. - -If you have been directed here by the @command{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 @command{aclocal} is commonly used is to -manage macros that are used locally by the package, @ref{Local -Macros}. - -@node Local Macros -@subsection 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 @file{acinclude.m4}. This file will be included in -@file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will -henceforth be visible to @command{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 @file{m4/}. Then it's enough to update -@file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIRS}: - -@example -AC_CONFIG_MACRO_DIRS([m4]) -@end example - -@command{aclocal} will then take care of automatically adding @file{m4/} -to its search path for m4 files. - -When @samp{aclocal} is run, it will build an @file{aclocal.m4} -that @code{m4_include}s any file from @file{m4/} that defines a -required macro. Macros not found locally will still be searched in -system-wide directories, as explained in @ref{Macro Search Path}. - -Custom macros should be distributed for the same reason that -@file{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 @code{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 @command{aclocal} directory (@pxref{Extending -aclocal}). For instance, Guile ships with a file called -@file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can -be used to define setup compiler and linker flags appropriate for -using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will -cause @command{aclocal} to copy @file{guile.m4} into -@file{aclocal.m4}, but as @file{guile.m4} is not part of the project, -it will not be distributed. Technically, that means a user who -needs to rebuild @file{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 @file{m4/} directory so they get -distributed. - -Since Automake 1.10, @command{aclocal} offers the option @code{--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 @file{m4/} -the first time you run @command{aclocal}. Then the locally installed -macros will have precedence over the system-wide installed macros -each time @command{aclocal} is run again. - -One reason why you should keep @option{--install} in the flags even -after the first run is that when you later edit @file{configure.ac} -and depend on a new macro, this macro will be installed in your -@file{m4/} automatically. Another one is that serial numbers -(@pxref{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 - -@example -#serial @var{nnn} -@end example - -@noindent -where @var{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 @option{--install} option of @command{aclocal}: this allows -other people to use it. - - -@node Serials -@subsection Serial Numbers -@cindex serial numbers in macros -@cindex macro serial numbers -@cindex @code{#serial} syntax -@cindex @command{aclocal} and serial numbers - -Because third-party macros defined in @file{*.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 @samp{#serial} line for this. - -A serial number should be a single line of the form - -@example -# serial @var{version} -@end example - -@noindent -where @var{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 @samp{#} must be the first character on the line, -and it is OK to have extra words after the version, as in - -@example -#serial @var{version} @var{garbage} -@end example - -Normally these serial numbers are completely ignored by -@command{aclocal} and @command{autoconf}, like any genuine comment. -However when using @command{aclocal}'s @option{--install} feature, these -serial numbers will modify the way @command{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 -@samp{#serial} line, @command{aclocal} will ignore the file that has -the older @samp{#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 @option{--install} and -its interaction with serial numbers. Let's assume we maintain a -package called MyPackage, the @file{configure.ac} of which requires a -third-party macro @code{AX_THIRD_PARTY} defined in -@file{/usr/share/aclocal/thirdparty.m4} as follows: - -@example -# serial 1 -AC_DEFUN([AX_THIRD_PARTY], [...]) -@end example - -MyPackage uses an @file{m4/} directory to store local macros as -explained in @ref{Local Macros}, and has - -@example -AC_CONFIG_MACRO_DIRS([m4]) -@end example - -@noindent -in its @file{configure.ac}. - -Initially the @file{m4/} directory is empty. The first time we run -@command{aclocal --install}, it will notice that - -@itemize @bullet -@item -@file{configure.ac} uses @code{AX_THIRD_PARTY} -@item -No local macros define @code{AX_THIRD_PARTY} -@item -@file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY} -with serial 1. -@end itemize - -@noindent -Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro -and @command{aclocal} was given the @option{--install} option, it will -copy this file in @file{m4/thirdparty.m4}, and output an -@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}. - -The next time @samp{aclocal --install} is run, something different -happens. @command{aclocal} notices that - -@itemize @bullet -@item -@file{configure.ac} uses @code{AX_THIRD_PARTY} -@item -@file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY} -with serial 1. -@item -@file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY} -with serial 1. -@end itemize - -@noindent -Because both files have the same serial number, @command{aclocal} uses -the first it found in its search path order (@pxref{Macro Search -Path}). @command{aclocal} therefore ignores -@file{/usr/share/aclocal/thirdparty.m4} and outputs an -@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}. - -Local directories specified with @option{-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 @samp{aclocal --install} -is run the situation is the following: - -@itemize @bullet -@item -@file{configure.ac} uses @code{AX_THIRD_PARTY} -@item -@file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY} -with serial 1. -@item -@file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY} -with serial 2. -@end itemize - -@noindent -When @command{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 -@file{/usr/share/aclocal/thirdparty.m4} with serial 2, -@command{aclocal} will proceed as if it had never seen -@file{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. @command{aclocal} will install the new version of the -macro in @file{m4/thirdparty.m4}, in this case overriding the old -version. MyPackage just had its macro updated as a side effect of -running @command{aclocal}. - -If you are leery of letting @command{aclocal} update your local -macro, you can run @samp{aclocal --diff} to review the changes -@samp{aclocal --install} would perform on these macros. - -Finally, note that the @option{--force} option of @command{aclocal} has -absolutely no effect on the files installed by @option{--install}. For -instance, if you have modified your local macros, do not expect -@option{--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 @samp{aclocal --install}. - - -@node Future of aclocal -@subsection The Future of @command{aclocal} -@cindex @command{aclocal}'s scheduled death - -@command{aclocal} is expected to disappear. This feature really -should not be offered by Automake. Automake should focus on -generating @file{Makefile}s; dealing with M4 macros really is -Autoconf's job. The fact that some people install Automake just to use -@command{aclocal}, but do not use @command{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 @file{m4/}-style layout discussed in -@ref{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, @command{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 @command{aclocal} yourself. -Keep this guy under the exclusive control of @command{autoreconf} and -Automake's rebuild rules. Hopefully you won't need to worry about -things breaking, when @command{aclocal} disappears, because everything -will have been taken care of. If otherwise you used to call -@command{aclocal} directly yourself or from some script, you will -quickly notice the change. - -Many packages come with a script called @file{bootstrap} or -@file{autogen.sh}, that will just call @command{aclocal}, -@command{libtoolize}, @command{gettextize} or @command{autopoint}, -@command{autoconf}, @command{autoheader}, and @command{automake} in -the right order. Actually this is precisely what @command{autoreconf} -can do for you. If your package has such a @file{bootstrap} or -@file{autogen.sh} script, consider using @command{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 @command{aclocal} directly anymore. - -For the time being, third-party packages should continue to install -public macros into @file{/usr/share/aclocal/}. If @command{aclocal} -is replaced by another tool it might make sense to rename the -directory, but supporting @file{/usr/share/aclocal/} for backward -compatibility should be really easy provided all macros are properly -written (@pxref{Extending aclocal}). - - - -@node Macros -@section Autoconf macros supplied with Automake - -Automake ships with several Autoconf macros that you can use from your -@file{configure.ac}. When you use one of them it will be included by -@command{aclocal} in @file{aclocal.m4}. - -@menu -* Public Macros:: Macros that you can use. -* Obsolete Macros:: Obsolete macros you should no longer use -* Private Macros:: Macros that you should not use. -@end menu - -@c consider generating the following subsections automatically from m4 files. - -@node Public Macros -@subsection Public Macros - -@table @code - -@item AM_INIT_AUTOMAKE([OPTIONS]) -@acindex AM_INIT_AUTOMAKE -Runs many macros required for proper operation of the generated Makefiles. - -@vindex AUTOMAKE_OPTIONS -Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a -space-separated list of Automake options that should be applied to -every @file{Makefile.am} in the tree. The effect is as if -each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}). - -@acindex AC_INIT -This macro can also be called in another, @emph{deprecated} form: -@code{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 @var{package} and @var{version} -can be obtained from Autoconf's @code{AC_INIT} macro. However, -differently from what happens for @code{AC_INIT} invocations, this -@code{AM_INIT_AUTOMAKE} invocation supports shell variables' expansions -in the @code{PACKAGE} and @code{VERSION} arguments (which otherwise -defaults, respectively, to the @code{PACKAGE_TARNAME} and -@code{PACKAGE_VERSION} defined via the @code{AC_INIT} invocation; -@pxref{AC_INIT, , The @code{AC_INIT} macro, autoconf, The Autoconf Manual}); -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 @code{AM_INIT_AUTOMAKE} -invocation will likely be removed from Automake. - -@anchor{Modernize AM_INIT_AUTOMAKE invocation} -If your @file{configure.ac} has: - -@example -AC_INIT([src/foo.c]) -AM_INIT_AUTOMAKE([mumble], [1.5]) -@end example - -@noindent -you should modernize it as follows: - -@example -AC_INIT([mumble], [1.5]) -AC_CONFIG_SRCDIR([src/foo.c]) -AM_INIT_AUTOMAKE -@end example - -Note that if you're upgrading your @file{configure.ac} from an earlier -version of Automake, it is not always correct to simply move the -package and version arguments from @code{AM_INIT_AUTOMAKE} directly to -@code{AC_INIT}, as in the example above. The first argument to -@code{AC_INIT} should be the name of your package (e.g., @samp{GNU -Automake}), not the tarball name (e.g., @samp{automake}) that you used -to pass to @code{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 @code{AC_INIT} to provide the tarball name -explicitly). - -@cindex @code{PACKAGE}, prevent definition -@cindex @code{VERSION}, prevent definition -@opindex no-define -By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and -@code{VERSION}. This can be avoided by passing the @option{no-define} -option (@pxref{List of Automake options}): -@example -AM_INIT_AUTOMAKE([no-define ...]) -@end example - -@item AM_PATH_LISPDIR -@acindex AM_PATH_LISPDIR -@vindex EMACS -@vindex lispdir -Searches for the program @command{emacs}, and, if found, sets the -output variable @code{lispdir} to the full path to Emacs' site-lisp -directory. - -Note that this test assumes the @command{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 @kbd{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 @kbd{C-c} to kill the test. In -order to avoid problems, you can set @env{EMACS} to ``no'' in the -environment, or use the @option{--with-lispdir} option to -@command{configure} to explicitly set the correct path (if you're sure -you have an @command{emacs} that supports Emacs Lisp). - -@item AM_PROG_AR(@ovar{act-if-fail}) -@acindex AM_PROG_AR -@vindex AR -You must use this macro when you use the archiver in your project, if -you want support for unusual archivers such as Microsoft @command{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. - -@item AM_PROG_AS -@acindex AM_PROG_AS -@vindex CCAS -@vindex CCASFLAGS -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 -@code{CCAS}, and will also set @code{CCASFLAGS} if required. - -@item AM_PROG_CC_C_O -@acindex AM_PROG_CC_C_O -This is an obsolescent macro that checks that the C compiler supports -the @option{-c} and @option{-o} options together. Note that, since -Automake 1.14, the @code{AC_PROG_CC} is rewritten to implement such -checks itself, and thus the explicit use of @code{AM_PROG_CC_C_O} -should no longer be required. - -@item AM_PROG_LEX -@acindex AM_PROG_LEX -@acindex AC_PROG_LEX -@cindex HP-UX 10, @command{lex} problems -@cindex @command{lex} problems with HP-UX 10 -Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular -Program Checks, autoconf, The Autoconf Manual}), but uses the -@command{missing} script on systems that do not have @command{lex}. -HP-UX 10 is one such system. - -@item AM_PROG_GCJ -@acindex AM_PROG_GCJ -@vindex GCJ -@vindex GCJFLAGS -This macro finds the @command{gcj} program or causes an error. It sets -@code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the -GNU Compiler Collection. - -@item AM_PROG_UPC([@var{compiler-search-list}]) -@acindex AM_PROG_UPC -@vindex UPC -Find a compiler for Unified Parallel C and define the @code{UPC} -variable. The default @var{compiler-search-list} is @samp{upcc upc}. -This macro will abort @command{configure} if no Unified Parallel C -compiler is found. - -@item AM_MISSING_PROG(@var{name}, @var{program}) -@acindex AM_MISSING_PROG -@vindex MISSING -Find a maintainer tool @var{program} and define the @var{name} -environment variable with its location. If @var{program} is not -detected, then @var{name} will instead invoke the @command{missing} -script, in order to give useful advice to the user about the missing -maintainer tool. @xref{maintainer-mode}, for more information on when -the @command{missing} script is appropriate. - -@item AM_SILENT_RULES -@acindex AM_SILENT_RULES -Control the machinery for less verbose build output -(@pxref{Automake Silent Rules}). - -@item AM_WITH_DMALLOC -@acindex AM_WITH_DMALLOC -@cindex @command{dmalloc}, support for -@vindex WITH_DMALLOC -@opindex --with-dmalloc -Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If -the user runs @command{configure} with @option{--with-dmalloc}, then -define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}. - -@end table - - -@node Obsolete Macros -@subsection Obsolete macros you should no longer use -@cindex obsolete macros - -Although using some of the following macros was required in past -releases, you should not use any of them in new code. Also, most -of these macros will probably be @emph{removed in some future Automake -version}, so you should consider updating your @file{configure.ac} -to avoid problems in the future. - -@table @code - -@item AM_PROG_MKDIR_P -@acindex AM_PROG_MKDIR_P -@cindex @code{mkdir -p}, macro check -@vindex MKDIR_P -@vindex mkdir_p - -From Automake 1.8 to 1.9.6 this macro used to define the output -variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh --d}, or @code{mkinstalldirs}. - -Nowadays Autoconf provides a similar functionality with -@code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular -Program Checks, autoconf, The Autoconf Manual}), however this defines -the output variable @code{MKDIR_P} instead. In case you are still -using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac}, -or its provided variable @code{$(mkdir_p)} in your @file{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. - -@end table - -@node Private Macros -@subsection 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! - -@ftable @code -@item _AM_DEPENDENCIES -@itemx AM_SET_DEPDIR -@itemx AM_DEP_TRACK -@itemx 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. - -@item AM_MAKE_INCLUDE -This macro is used to discover how the user's @command{make} handles -@code{include} statements. This macro is automatically invoked when -needed; there should be no need to invoke it manually. - -@item AM_PROG_INSTALL_STRIP -This is used to find a version of @code{install} that can be used to -strip a program at installation time. This macro is automatically -included when required. - -@item 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 @code{AM_INIT_AUTOMAKE}. - -@end ftable - - -@node Directories -@chapter Directories - -For simple projects that distribute all files in the same directory -it is enough to have a single @file{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 @emph{make recursion}: each directory contains its -own @file{Makefile}, and when @command{make} is run from the top-level -directory, it enters each subdirectory in turn, and invokes there a -new @command{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 @ref{Alternative} -section below. - -@menu -* Subdirectories:: Building subdirectories recursively -* Conditional Subdirectories:: Conditionally not building directories -* Alternative:: Subdirectories without recursion -* Subpackages:: Nesting packages -@end menu - -@node Subdirectories -@section Recursing subdirectories - -@cindex @code{SUBDIRS}, explained - -In packages using make recursion, the top level @file{Makefile.am} must -tell Automake which subdirectories are to be built. This is done via -the @code{SUBDIRS} variable. -@vindex SUBDIRS - -The @code{SUBDIRS} variable holds a list of subdirectories in which -building of various sorts can occur. The rules for many targets -(e.g., @code{all}) in the generated @file{Makefile} will run commands -both locally and in all specified subdirectories. Note that the -directories listed in @code{SUBDIRS} are not required to contain -@file{Makefile.am}s; only @file{Makefile}s (after configuration). -This allows inclusion of libraries from packages that do not use -Automake (such as @code{gettext}; see also @ref{Third-Party -Makefiles}). - -In packages that use subdirectories, the top-level @file{Makefile.am} is -often very short. For instance, here is the @file{Makefile.am} from the -GNU Hello distribution: - -@example -EXTRA_DIST = BUGS ChangeLog.O README-alpha -SUBDIRS = doc intl po src tests -@end example - -When Automake invokes @command{make} in a subdirectory, it uses the value -of the @code{MAKE} variable. It passes the value of the variable -@code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in -@file{Makefile.am} if there are flags you must always pass to -@command{make}. -@vindex MAKE -@vindex AM_MAKEFLAGS - -The directories mentioned in @code{SUBDIRS} are usually direct -children of the current directory, each subdirectory containing its -own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper -subdirectories. Automake can be used to construct packages of -arbitrary depth this way. - -By default, Automake generates @file{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 @samp{.} into @code{SUBDIRS}. For instance, -putting @samp{.} first will cause a prefix ordering of -directories. - -Using - -@example -SUBDIRS = lib src . test -@end example - -@noindent -will cause @file{lib/} to be built before @file{src/}, then the -current directory will be built, finally the @file{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 -(@code{all}, @code{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 @code{AM_EXTRA_RECURSIVE_TARGETS} -in @file{configure.ac}. Automake generates rules to handle the -recursion for such targets; and the developer can define real actions -for them by defining corresponding @code{-local} targets. - -@example -% @kbd{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 -% @kbd{cat Makefile.am} -SUBDIRS = sub -foo-local: - @@echo This will be run by "make foo". -% @kbd{cat sub/Makefile.am} -SUBDIRS = src -% @kbd{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. -@end example - -@node Conditional Subdirectories -@section Conditional Subdirectories -@cindex Subdirectories, building conditionally -@cindex Conditional subdirectories -@cindex @code{SUBDIRS}, conditional -@cindex Conditional @code{SUBDIRS} - -It is possible to define the @code{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 -@file{src/} and @file{opt/}. @file{src/} should always be built, but we -want to decide in @command{configure} whether @file{opt/} will be built -or not. (For this example we will assume that @file{opt/} should be -built when the variable @samp{$want_opt} was set to @samp{yes}.) - -Running @command{make} should thus recurse into @file{src/} always, and -then maybe in @file{opt/}. - -However @samp{make dist} should always recurse into both @file{src/} -and @file{opt/}. Because @file{opt/} should be distributed even if it -is not needed in the current configuration. This means -@file{opt/Makefile} should be created @emph{unconditionally}. - -There are two ways to setup a project like this. You can use Automake -conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST} -variables (@pxref{Setting Output Variables, , Setting Output -Variables, autoconf, The Autoconf Manual}). Using Automake -conditionals is the preferred solution. Before we illustrate these -two possibilities, let's introduce @code{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 @samp{Makefile} -@end menu - -@node SUBDIRS vs DIST_SUBDIRS -@subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS} -@cindex @code{DIST_SUBDIRS}, explained - -Automake considers two sets of directories, defined by the variables -@code{SUBDIRS} and @code{DIST_SUBDIRS}. - -@code{SUBDIRS} contains the subdirectories of the current directory -that must be built (@pxref{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. - -@code{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 -@file{opt/}, but yet we want to distribute it? This is where -@code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in -@code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}. - -Precisely, @code{DIST_SUBDIRS} is used by @samp{make -maintainer-clean}, @samp{make distclean} and @samp{make dist}. All -other recursive rules use @code{SUBDIRS}. - -If @code{SUBDIRS} is defined conditionally using Automake -conditionals, Automake will define @code{DIST_SUBDIRS} automatically -from the possible values of @code{SUBDIRS} in all conditions. - -If @code{SUBDIRS} contains @code{AC_SUBST} variables, -@code{DIST_SUBDIRS} will not be defined correctly because Automake -does not know the possible values of these variables. In this case -@code{DIST_SUBDIRS} needs to be defined manually. - -@node Subdirectories with AM_CONDITIONAL -@subsection Subdirectories with @code{AM_CONDITIONAL} -@cindex @code{SUBDIRS} and @code{AM_CONDITIONAL} -@cindex @code{AM_CONDITIONAL} and @code{SUBDIRS} - -@c Keep in sync with subdir-am-cond.sh - -@file{configure} should output the @file{Makefile} for each directory -and define a condition into which @file{opt/} should be built. - -@example -@dots{} -AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes]) -AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile]) -@dots{} -@end example - -Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am} -as follows. - -@example -if COND_OPT - MAYBE_OPT = opt -endif -SUBDIRS = src $(MAYBE_OPT) -@end example - -As you can see, running @command{make} will rightly recurse into -@file{src/} and maybe @file{opt/}. - -@vindex DIST_SUBDIRS -As you can't see, running @samp{make dist} will recurse into both -@file{src/} and @file{opt/} directories because @samp{make dist}, unlike -@samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the -@code{DIST_SUBDIRS} variable. - -In this case Automake will define @samp{DIST_SUBDIRS = src opt} -automatically because it knows that @code{MAYBE_OPT} can contain -@samp{opt} in some condition. - -@node Subdirectories with AC_SUBST -@subsection Subdirectories with @code{AC_SUBST} -@cindex @code{SUBDIRS} and @code{AC_SUBST} -@cindex @code{AC_SUBST} and @code{SUBDIRS} - -@c Keep in sync with subdir-ac-subst.sh - -Another possibility is to define @code{MAYBE_OPT} from -@file{./configure} using @code{AC_SUBST}: - -@example -@dots{} -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]) -@dots{} -@end example - -In this case the top-level @file{Makefile.am} should look as follows. - -@example -SUBDIRS = src $(MAYBE_OPT) -DIST_SUBDIRS = src opt -@end example - -The drawback is that since Automake cannot guess what the possible -values of @code{MAYBE_OPT} are, it is necessary to define -@code{DIST_SUBDIRS}. - -@node Unconfigured Subdirectories -@subsection Unconfigured Subdirectories -@cindex Subdirectories, configured conditionally - -The semantics of @code{DIST_SUBDIRS} are often misunderstood by some -users that try to @emph{configure and build} subdirectories -conditionally. Here by configuring we mean creating the -@file{Makefile} (it might also involve running a nested -@command{configure} script: this is a costly operation that explains -why people want to do it conditionally, but only the @file{Makefile} -is relevant to the discussion). - -The above examples all assume that every @file{Makefile} is created, -even in directories that are not going to be built. The simple reason -is that we want @samp{make dist} to distribute even the directories -that are not being built (e.g., platform-dependent code), hence -@file{make dist} must recurse into the subdirectory, hence this -directory must be configured and appear in @code{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. - -@cartouche -@itemize -@item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}. - -It makes little sense to have a directory in @code{SUBDIRS} that -is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell -which directories listed in the latter should be built. -@item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS} -must be configured. - -I.e., the @file{Makefile} must exists or the recursive @command{make} -rules will not be able to process the directory. -@item Any configured directory must be listed in @code{DIST_SUBDIRS}. - -So that the cleaning rules remove the generated @file{Makefile}s. -It would be correct to see @code{DIST_SUBDIRS} as a variable that -lists all the directories that have been configured. -@end itemize -@end cartouche - -In order to prevent recursion in some unconfigured directory you -must therefore ensure that this directory does not appear in -@code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define -@code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define -@code{DIST_SUBDIRS} explicitly, it will be default to -@samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS -= $(SUBDIRS)}. - -Of course, directories that are omitted from @code{DIST_SUBDIRS} will -not be distributed unless you make other arrangements for this to -happen (for instance, always running @samp{make dist} in a -configuration where all directories are known to appear in -@code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to -distribute these directories). - -@cindex Subdirectories, not distributed -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 @code{SUBDIRS} or @code{DIST_SUBDIRS}, -@command{automake} will make sure the directory exists. Consequently -@command{automake} cannot be run on such a distribution when one -directory has been omitted. One way to avoid this check is to use the -@code{AC_SUBST} method to declare conditional directories; since -@command{automake} does not know the values of @code{AC_SUBST} -variables it cannot ensure the corresponding directory exists. - -@node Alternative -@section An Alternative Approach to Subdirectories - -If you've ever read Peter Miller's excellent paper, -@uref{http://miller.emu.id.au/pmiller/books/rmch/, -Recursive Make Considered Harmful}, 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 -@command{make} invocations are both slow and error-prone. - -Automake provides sufficient cross-directory support @footnote{We -believe. This work is new and there are probably warts. -@xref{Introduction}, for information on reporting bugs.} to enable you -to write a single @file{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 -@file{$(includedir)/stdio.h}: - -@example -include_HEADERS = inc/stdio.h -@end example - -@vindex nobase_ -@cindex @code{nobase_} prefix -@cindex Path stripping, avoiding -@cindex Avoiding path stripping - -However, the @samp{nobase_} prefix can be used to circumvent this path -stripping. In this example, the header file will be installed as -@file{$(includedir)/sys/types.h}: - -@example -nobase_include_HEADERS = sys/types.h -@end example - -@cindex @code{nobase_} and @code{dist_} or @code{nodist_} -@cindex @code{dist_} and @code{nobase_} -@cindex @code{nodist_} and @code{nobase_} -@vindex dist_ -@vindex nodist_ - -@samp{nobase_} should be specified first when used in conjunction with -either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution -Control}). For instance: - -@example -nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg -@end example - -Finally, note that a variable using the @samp{nobase_} prefix can -often be replaced by several variables, one for each destination -directory (@pxref{Uniform}). For instance, the last example could be -rewritten as follows: - -@c Keep in sync with primary-prefix-couples-documented-valid.sh -@example -imagesdir = $(pkgdatadir)/images -soundsdir = $(pkgdatadir)/sounds -dist_images_DATA = images/vortex.pgm -dist_sounds_DATA = sounds/whirl.ogg -@end example - -@noindent -This latter syntax makes it possible to change one destination -directory without changing the layout of the source tree. - -Currently, @samp{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 @samp{nobase_} prefix. - -@node Subpackages -@section Nesting Packages -@cindex Nesting packages -@cindex Subpackages -@acindex AC_CONFIG_SUBDIRS -@acindex AC_CONFIG_AUX_DIR - - -In the GNU Build System, packages can be nested to arbitrary depth. -This means that a package can embed other packages with their own -@file{configure}, @file{Makefile}s, etc. - -These other packages should just appear as subdirectories of their -parent package. They must be listed in @code{SUBDIRS} like other -ordinary directories. However the subpackage's @file{Makefile}s -should be output by its own @file{configure} script, not by the -parent's @file{configure}. This is achieved using the -@code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories, -AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories, -autoconf, The Autoconf Manual}). - -Here is an example package for an @code{arm} program that links with -a @code{hand} library that is a nested package in subdirectory -@file{hand/}. - -@code{arm}'s @file{configure.ac}: - -@example -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 -@end example - -@code{arm}'s @file{Makefile.am}: - -@example -# 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 -@end example - -Now here is @code{hand}'s @file{hand/configure.ac}: - -@example -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 -@end example - -@noindent -and its @file{hand/Makefile.am}: - -@example -lib_LIBRARIES = libhand.a -libhand_a_SOURCES = hand.c -@end example - -When @samp{make dist} is run from the top-level directory it will -create an archive @file{arm-1.0.tar.gz} that contains the @code{arm} -code as well as the @file{hand} subdirectory. This package can be -built and installed like any ordinary package, with the usual -@samp{./configure && make && make install} sequence (the @code{hand} -subpackage will be built and installed by the process). - -When @samp{make dist} is run from the hand directory, it will create a -self-contained @file{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 @samp{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 @file{install-sh}: one in the top-level of the @code{arm} -package, and another one in the @file{hand/} subdirectory for the -@code{hand} package. - -The historical default is to search for these auxiliary scripts in -the parent directory and the grandparent directory. So if the -@samp{AC_CONFIG_AUX_DIR([.])} line was removed from -@file{hand/configure.ac}, that subpackage would share the auxiliary -script of the @code{arm} package. This may looks like a gain in size -(a few kilobytes), but it is actually a loss of modularity as the -@code{hand} subpackage is no longer self-contained (@samp{make dist} -in the subdirectory will not work anymore). - -Packages that do not use Automake need more work to be integrated this -way. @xref{Third-Party Makefiles}. - -@node Programs -@chapter 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 -@end menu - - -@node A Program -@section 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 -(@pxref{A Library}) and libtool libraries (@pxref{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 -@end menu - -@node Program Sources -@subsection Defining program sources - -@cindex @code{PROGRAMS}, @code{bindir} -@vindex _PROGRAMS -@vindex bin_PROGRAMS -@vindex sbin_PROGRAMS -@vindex libexec_PROGRAMS -@vindex pkglibexec_PROGRAMS -@vindex noinst_PROGRAMS -@vindex check_PROGRAMS - -In a directory containing source that gets built into a program (as -opposed to a library or a script), the @code{PROGRAMS} primary is used. -Programs can be installed in @code{bindir}, @code{sbindir}, -@code{libexecdir}, @code{pkglibexecdir}, or not at all -(@code{noinst_}). They can also be built only for @samp{make check}, in -which case the prefix is @samp{check_}. - -For instance: - -@example -bin_PROGRAMS = hello -@end example - -In this simple case, the resulting @file{Makefile.in} will contain code -to generate a program named @code{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 @code{hello_SOURCES} is used to specify which source files -get built into an executable: - -@example -hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h -@end example - -This causes each mentioned @file{.c} file to be compiled into the -corresponding @file{.o}. Then all are linked to produce @file{hello}. - -@cindex @code{_SOURCES} primary, defined -@cindex @code{SOURCES} primary, defined -@cindex Primary variable, @code{SOURCES} -@vindex _SOURCES - -If @code{hello_SOURCES} is not specified, then it defaults to the single -file @file{hello.c} (@pxref{Default _SOURCES}). -@vindex _SOURCES -@vindex SOURCES - -Multiple programs can be built in a single directory. Multiple programs -can share a single source file, which must be listed in each -@code{_SOURCES} definition. - -@cindex Header files in @code{_SOURCES} -@cindex @code{_SOURCES} and header files - -Header files listed in a @code{_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 @file{configure} in a -@code{_SOURCES} variable; this file should not be distributed. Lex -(@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc -and Lex}. - - -@node Linking -@subsection Linking the program - -If you need to link against libraries that are not found by -@command{configure}, you can use @code{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 -@code{AM_LDFLAGS} for this purpose. -@vindex LDADD -@vindex AM_LDFLAGS - -@cindex @code{prog_LDADD}, defined - -Sometimes, multiple programs are built in one directory but do not share -the same link-time requirements. In this case, you can use the -@code{@var{prog}_LDADD} variable (where @var{prog} is the name of the -program as it appears in some @code{_PROGRAMS} variable, and usually -written in lowercase) to override @code{LDADD}. If this variable exists -for a given program, then that program is not linked using @code{LDADD}. -@vindex maude_LDADD - -For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are -linked against the library @file{libcpio.a}. However, @code{rmt} is -built in the same directory, and has no such link requirement. Also, -@code{mt} and @code{rmt} are only built on certain architectures. Here -is what cpio's @file{src/Makefile.am} looks like (abridged): - -@example -bin_PROGRAMS = cpio pax $(MT) -libexec_PROGRAMS = $(RMT) -EXTRA_PROGRAMS = mt rmt - -LDADD = ../lib/libcpio.a $(INTLLIBS) -rmt_LDADD = - -cpio_SOURCES = @dots{} -pax_SOURCES = @dots{} -mt_SOURCES = @dots{} -rmt_SOURCES = @dots{} -@end example - -@cindex @code{_LDFLAGS}, defined -@vindex maude_LDFLAGS -@code{@var{prog}_LDADD} is inappropriate for passing program-specific -linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and -@option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for -this purpose. - -@cindex @code{_DEPENDENCIES}, defined -@vindex maude_DEPENDENCIES -@vindex EXTRA_maude_DEPENDENCIES -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 @code{@var{prog}_DEPENDENCIES} or the -@code{EXTRA_@var{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 @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} -files. In rare cases you may need to add other kinds of files such as -linker scripts, but @emph{listing a source file in -@code{_DEPENDENCIES} is wrong}. If some source file needs to be built -before all the components of a program are built, consider using the -@code{BUILT_SOURCES} variable instead (@pxref{Sources}). - -If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by -Automake. The automatically-assigned value is the contents of -@code{@var{prog}_LDADD}, with most configure substitutions, @option{-l}, -@option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The -configure substitutions that are left in are only @samp{$(LIBOBJS)} and -@samp{$(ALLOCA)}; these are left because it is known that they will not -cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be -generated. - -@ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES} -may be used. - -The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where -you merely want to augment the @command{automake}-generated -@code{@var{prog}_DEPENDENCIES} rather than replacing it. - -@cindex @code{LDADD} and @option{-l} -@cindex @option{-l} and @code{LDADD} -We recommend that you avoid using @option{-l} options in @code{LDADD} -or @code{@var{prog}_LDADD} when referring to libraries built by your -package. Instead, write the file name of the library explicitly as in -the above @code{cpio} example. Use @option{-l} only to list -third-party libraries. If you follow this rule, the default value of -@code{@var{prog}_DEPENDENCIES} will list all your local libraries and -omit the other ones. - - -@node Conditional Sources -@subsection Conditional compilation of sources - -You can't put a configure substitution (e.g., @samp{@@FOO@@} or -@samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a -@code{_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 @code{_LDADD} variables, the other is -to use an Automake conditional. - -@subsubheading Conditional Compilation using @code{_LDADD} Substitutions - -@cindex @code{EXTRA_prog_SOURCES}, defined - -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 @code{EXTRA_} variable. For instance, if -@file{hello-linux.c} or @file{hello-generic.c} were conditionally included -in @code{hello}, the @file{Makefile.am} would contain: - -@example -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) -@end example - -@noindent -You can then setup the @samp{$(HELLO_SYSTEM)} substitution from -@file{configure.ac}: - -@example -@dots{} -case $host in - *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;; - *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;; -esac -AC_SUBST([HELLO_SYSTEM]) -@dots{} -@end example - -In this case, the variable @code{HELLO_SYSTEM} should be replaced by -either @file{hello-linux.o} or @file{hello-generic.o}, and added to -both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be -built and linked in. - -@subsubheading 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 -@file{Makefile.am} construct to build the same @file{hello} example: - -@example -bin_PROGRAMS = hello -if LINUX -hello_SOURCES = hello-linux.c hello-common.c -else -hello_SOURCES = hello-generic.c hello-common.c -endif -@end example - -In this case, @file{configure.ac} should setup the @code{LINUX} -conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}). - -When using conditionals like this you don't need to use the -@code{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 @samp{+=}. - -@example -bin_PROGRAMS = hello -hello_SOURCES = hello-common.c -if LINUX -hello_SOURCES += hello-linux.c -else -hello_SOURCES += hello-generic.c -endif -@end example - -@node Conditional Programs -@subsection Conditional compilation of programs -@cindex Conditional programs -@cindex Programs, conditional - -Sometimes it is useful to determine the programs that are to be built -at configure time. For instance, GNU @code{cpio} only builds -@code{mt} and @code{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. - -@subsubheading Conditional Programs using @command{configure} Substitutions - -@vindex EXTRA_PROGRAMS -@cindex @code{EXTRA_PROGRAMS}, defined -In this case, you must notify Automake of all the programs that can -possibly be built, but at the same time cause the generated -@file{Makefile.in} to use the programs specified by @command{configure}. -This is done by having @command{configure} substitute values into each -@code{_PROGRAMS} definition, while listing all optionally built programs -in @code{EXTRA_PROGRAMS}. - -@example -bin_PROGRAMS = cpio pax $(MT) -libexec_PROGRAMS = $(RMT) -EXTRA_PROGRAMS = mt rmt -@end example - -As explained in @ref{EXEEXT}, Automake will rewrite -@code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and -@code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary. -Obviously it cannot rewrite values obtained at run-time through -@command{configure} substitutions, therefore you should take care of -appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT], -['mt$@{EXEEXT@}'])}. - -@subsubheading Conditional Programs using Automake Conditionals - -You can also use Automake conditionals (@pxref{Conditionals}) to -select programs to be built. In this case you don't have to worry -about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}. - -@c Keep in sync with exeext.sh -@example -bin_PROGRAMS = cpio pax -if WANT_MT - bin_PROGRAMS += mt -endif -if WANT_RMT - libexec_PROGRAMS = rmt -endif -@end example - - -@node A Library -@section Building a library - -@cindex @code{_LIBRARIES} primary, defined -@cindex @code{LIBRARIES} primary, defined -@cindex Primary variable, @code{LIBRARIES} -@vindex _LIBRARIES - -@vindex lib_LIBRARIES -@vindex pkglib_LIBRARIES -@vindex noinst_LIBRARIES - -Building a library is much like building a program. In this case, the -name of the primary is @code{LIBRARIES}. Libraries can be installed in -@code{libdir} or @code{pkglibdir}. - -@xref{A Shared Library}, for information on how to build shared -libraries using libtool and the @code{LTLIBRARIES} primary. - -Each @code{_LIBRARIES} variable is a list of the libraries to be built. -For instance, to create a library named @file{libcpio.a}, but not install -it, you would write: - -@example -noinst_LIBRARIES = libcpio.a -libcpio_a_SOURCES = @dots{} -@end example - -The sources that go into a library are determined exactly as they are -for programs, via the @code{_SOURCES} variables. Note that the library -name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES} -variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES}, -not @samp{libcpio.a_SOURCES}. - -@vindex maude_LIBADD -Extra objects can be added to a library using the -@code{@var{library}_LIBADD} variable. This should be used for objects -determined by @command{configure}. Again from @code{cpio}: - -@c Keep in sync with pr401c.sh -@example -libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA) -@end example - -In addition, sources for extra objects that will not exist until -configure-time must be added to the @code{BUILT_SOURCES} variable -(@pxref{Sources}). - -Building a static library is done by compiling all object files, then -by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the -library and the list of objects, and finally by calling -@samp{$(RANLIB)} on that library. You should call -@code{AC_PROG_RANLIB} from your @file{configure.ac} to define -@code{RANLIB} (Automake will complain otherwise). You should also -call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual -archivers such as Microsoft lib. @code{ARFLAGS} will default to -@code{cru}; you can override this variable by setting it in your -@file{Makefile.am} or by @code{AC_SUBST}ing it from your -@file{configure.ac}. You can override the @code{AR} variable by -defining a per-library @code{maude_AR} variable (@pxref{Program and -Library Variables}). - -@cindex Empty libraries -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 -@code{LDADD} for this program. In the following example, the program -@file{cpio} is statically linked with the library @file{libcpio.a}. - -@example -noinst_LIBRARIES = libcpio.a -libcpio_a_SOURCES = @dots{} - -bin_PROGRAMS = cpio -cpio_SOURCES = cpio.c @dots{} -cpio_LDADD = libcpio.a -@end example - - -@node A Shared Library -@section Building a Shared Library - -@cindex Shared libraries, support for - -Building shared libraries portably is a relatively complex matter. -For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The -Libtool Manual}) 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 -@end menu - -@node Libtool Concept -@subsection The Libtool Concept - -@cindex @command{libtool}, introduction -@cindex libtool library, definition -@cindex suffix @file{.la}, defined -@cindex @file{.la} suffix, defined - -Libtool abstracts shared and static libraries into a unified concept -henceforth called @dfn{libtool libraries}. Libtool libraries are -files using the @file{.la} suffix, and can designate a static library, -a shared library, or maybe both. Their exact nature cannot be -determined until @file{./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, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL} -macro, libtool, The Libtool Manual}.) - -@cindex suffix @file{.lo}, defined -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 @dfn{libtool objects}: these are files -using the @file{.lo} suffix. Libtool libraries are built from these -libtool objects. - -You should not assume anything about the structure of @file{.la} or -@file{.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 @file{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 (@pxref{Conditional Libtool -Sources}). - -@cindex @file{libltdl}, introduction - -People considering writing a plug-in system, with dynamically loaded -modules, should look into @file{libltdl}: libtool's dlopening library -(@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}). -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 (@pxref{Using Automake, , Using Automake -with Libtool, libtool, The Libtool Manual}). - -@node Libtool Libraries -@subsection Building Libtool Libraries - -@cindex @code{_LTLIBRARIES} primary, defined -@cindex @code{LTLIBRARIES} primary, defined -@cindex Primary variable, @code{LTLIBRARIES} -@cindex Example of shared libraries -@vindex lib_LTLIBRARIES -@vindex pkglib_LTLIBRARIES -@vindex _LTLIBRARIES - -Automake uses libtool to build libraries declared with the -@code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a -list of libtool libraries to build. For instance, to create a libtool -library named @file{libgettext.la}, and install it in @code{libdir}, -write: - -@example -lib_LTLIBRARIES = libgettext.la -libgettext_la_SOURCES = gettext.c gettext.h @dots{} -@end example - -Automake predefines the variable @code{pkglibdir}, so you can use -@code{pkglib_LTLIBRARIES} to install libraries in -@samp{$(libdir)/@@PACKAGE@@/}. - -If @file{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 -@code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}. -Headers listed in the latter should be internal headers that are not -part of the public interface. - -@example -lib_LTLIBRARIES = libgettext.la -libgettext_la_SOURCES = gettext.c @dots{} -include_HEADERS = gettext.h @dots{} -@end example - -A package can build and install such a library along with other -programs that use it. This dependency should be specified using -@code{LDADD}. The following example builds a program named -@file{hello} that is linked with @file{libgettext.la}. - -@example -lib_LTLIBRARIES = libgettext.la -libgettext_la_SOURCES = gettext.c @dots{} - -bin_PROGRAMS = hello -hello_SOURCES = hello.c @dots{} -hello_LDADD = libgettext.la -@end example - -@noindent -Whether @file{hello} is statically or dynamically linked with -@file{libgettext.la} is not yet known: this will depend on the -configuration of libtool and the capabilities of the host. - - -@node Conditional Libtool Libraries -@subsection Building Libtool Libraries Conditionally -@cindex libtool libraries, conditional -@cindex conditional libtool libraries - -Like conditional programs (@pxref{Conditional Programs}), there are -two main ways to build conditional libraries: using Automake -conditionals or using Autoconf @code{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 @emph{at link-time} using the @option{-rpath} -option. - -For libraries whose destination directory is known when Automake runs, -Automake will automatically supply the appropriate @option{-rpath} -option to libtool. This is the case for libraries listed explicitly in -some installable @code{_LTLIBRARIES} variables such as -@code{lib_LTLIBRARIES}. - -However, for libraries determined at configure time (and thus -mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the -final installation directory. For such libraries you must add the -@option{-rpath} option to the appropriate @code{_LDFLAGS} variable by -hand. - -The examples below illustrate the differences between these two methods. - -Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed -variable set at @file{./configure}-time to either @file{libfoo.la}, -@file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)} -appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it -relates to @file{libfoo.la} or @file{libbar.la} at the time it creates -the link rule for these two libraries. Therefore the @option{-rpath} -argument must be explicitly supplied. - -@c Keep in sync with ltcond.sh -@example -EXTRA_LTLIBRARIES = libfoo.la libbar.la -lib_LTLIBRARIES = $(WANTEDLIBS) -libfoo_la_SOURCES = foo.c @dots{} -libfoo_la_LDFLAGS = -rpath '$(libdir)' -libbar_la_SOURCES = bar.c @dots{} -libbar_la_LDFLAGS = -rpath '$(libdir)' -@end example - -Here is how the same @file{Makefile.am} would look using Automake -conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now -Automake is able to compute the @option{-rpath} setting itself, because -it's clear that both libraries will end up in @samp{$(libdir)} if they -are installed. - -@c Keep in sync with ltcond.sh -@example -lib_LTLIBRARIES = -if WANT_LIBFOO -lib_LTLIBRARIES += libfoo.la -endif -if WANT_LIBBAR -lib_LTLIBRARIES += libbar.la -endif -libfoo_la_SOURCES = foo.c @dots{} -libbar_la_SOURCES = bar.c @dots{} -@end example - -@node Conditional Libtool Sources -@subsection 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 -(@pxref{Conditional Sources}). The only difference is that -@code{_LIBADD} should be used instead of @code{_LDADD} and that it -should mention libtool objects (@file{.lo} files). - -So, to mimic the @file{hello} example from @ref{Conditional Sources}, -we could build a @file{libhello.la} library using either -@file{hello-linux.c} or @file{hello-generic.c} with the following -@file{Makefile.am}. - -@c Keep in sync with ltcond2.sh -@example -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) -@end example - -@noindent -And make sure @command{configure} defines @code{HELLO_SYSTEM} as -either @file{hello-linux.lo} or @file{hello-@-generic.lo}. - -Or we could simply use an Automake conditional as follows. - -@c Keep in sync with ltcond2.sh -@example -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 -@end example - -@node Libtool Convenience Libraries -@subsection Libtool Convenience Libraries -@cindex convenience libraries, libtool -@cindex libtool convenience libraries -@vindex noinst_LTLIBRARIES -@vindex check_LTLIBRARIES - -Sometimes you want to build libtool libraries that should not be -installed. These are called @dfn{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 @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even -@code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do -not need an @option{-rpath} flag at link time (actually this is the only -difference). - -Convenience libraries listed in @code{noinst_LTLIBRARIES} are always -built. Those listed in @code{check_LTLIBRARIES} are built only upon -@samp{make check}. Finally, libraries listed in -@code{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 -@code{EXTRA_LTLIBRARIES} is used for conditional compilation). - -Here is a sample setup merging libtool convenience libraries from -subdirectories into one main @file{libtop.la} library. - -@c Keep in sync with ltconv.sh -@example -# -- Top-level Makefile.am -- -SUBDIRS = sub1 sub2 @dots{} -lib_LTLIBRARIES = libtop.la -libtop_la_SOURCES = -libtop_la_LIBADD = \ - sub1/libsub1.la \ - sub2/libsub2.la \ - @dots{} - -# -- sub1/Makefile.am -- -noinst_LTLIBRARIES = libsub1.la -libsub1_la_SOURCES = @dots{} - -# -- sub2/Makefile.am -- -# showing nested convenience libraries -SUBDIRS = sub2.1 sub2.2 @dots{} -noinst_LTLIBRARIES = libsub2.la -libsub2_la_SOURCES = -libsub2_la_LIBADD = \ - sub21/libsub21.la \ - sub22/libsub22.la \ - @dots{} -@end example - -When using such setup, beware that @command{automake} will assume -@file{libtop.la} is to be linked with the C linker. This is because -@code{libtop_la_SOURCES} is empty, so @command{automake} picks C as -default language. If @code{libtop_la_SOURCES} was not empty, -@command{automake} would select the linker as explained in @ref{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 @command{automake} to select the appropriate -linker. Here is the top-level @file{Makefile} of our example updated -to force C++ linking. - -@example -SUBDIRS = sub1 sub2 @dots{} -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 \ - @dots{} -@end example - -@samp{EXTRA_*_SOURCES} variables are used to keep track of source -files that might be compiled (this is mostly useful when doing -conditional compilation using @code{AC_SUBST}, @pxref{Conditional -Libtool Sources}), and the @code{nodist_} prefix means the listed -sources are not to be distributed (@pxref{Program and Library -Variables}). In effect the file @file{dummy.cxx} does not need to -exist in the source tree. Of course if you have some real source file -to list in @code{libtop_la_SOURCES} there is no point in cheating with -@code{nodist_EXTRA_libtop_la_SOURCES}. - - -@node Libtool Modules -@subsection Libtool Modules -@cindex modules, libtool -@cindex libtool modules -@cindex @option{-module}, libtool - -These are libtool libraries meant to be dlopened. They are -indicated to libtool by passing @option{-module} at link-time. - -@example -pkglib_LTLIBRARIES = mymodule.la -mymodule_la_SOURCES = doit.c -mymodule_la_LDFLAGS = -module -@end example - -Ordinarily, Automake requires that a library's name start with -@code{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 @option{-module} explicitly appears in the -library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS} -variable when no per-library @code{_LDFLAGS} variable is defined). - -As always, @code{AC_SUBST} variables are black boxes to Automake since -their values are not yet known when @command{automake} is run. -Therefore if @option{-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 @code{mymodule_la_SOURCES} is not specified, then it defaults to -the single file @file{mymodule.c} (@pxref{Default _SOURCES}). - -@node Libtool Flags -@subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS} -@cindex @code{_LIBADD}, libtool -@cindex @code{_LDFLAGS}, libtool -@cindex @code{_LIBTOOLFLAGS}, libtool -@vindex AM_LIBTOOLFLAGS -@vindex LIBTOOLFLAGS -@vindex maude_LIBTOOLFLAGS - -As shown in previous sections, the @samp{@var{library}_LIBADD} -variable should be used to list extra libtool objects (@file{.lo} -files) or libtool libraries (@file{.la}) to add to @var{library}. - -The @samp{@var{library}_LDFLAGS} variable is the place to list -additional libtool linking flags, such as @option{-version-info}, -@option{-static}, and a lot more. @xref{Link mode, , Link mode, -libtool, The Libtool Manual}. - -The @command{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 @command{libtool} (hence the use of -@samp{@var{library}_LDFLAGS} for libtool linking flags). Generic -options include @option{--tag=@var{tag}} and @option{--silent} -(@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The -Libtool Manual} for more options) should appear before the mode -selection on the command line; in @file{Makefile.am}s they should -be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable. - -If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable -@code{AM_LIBTOOLFLAGS} is used instead. - -These flags are passed to libtool after the @option{--tag=@var{tag}} -option computed by Automake (if any), so -@samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a -good place to override or supplement the @option{--tag=@var{tag}} -setting. - -The libtool rules also use a @code{LIBTOOLFLAGS} variable that should -not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag -Variables Ordering}. It allows users to run @samp{make -LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of -@command{libtool} can also be influenced by the Automake support -for silent rules (@pxref{Automake Silent Rules}). - -@node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library -@subsection @code{LTLIBOBJS} and @code{LTALLOCA} -@cindex @code{LTLIBOBJS}, special handling -@cindex @code{LIBOBJS}, and Libtool -@cindex @code{LTALLOCA}, special handling -@cindex @code{ALLOCA}, and Libtool -@vindex LTLIBOBJS -@vindex LIBOBJS -@vindex LTALLOCA -@vindex ALLOCA -@acindex AC_LIBOBJ - -Where an ordinary library might include @samp{$(LIBOBJS)} or -@samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use -@samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because -the object files that libtool operates on do not necessarily end in -@file{.o}. - -Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is -performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, , -@code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}). - -@node Libtool Issues -@subsection 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 -@end menu - -@node Error required file ltmain.sh not found -@subsubsection Error: @samp{required file `./ltmain.sh' not found} -@cindex @file{ltmain.sh} not found -@cindex @command{libtoolize}, no longer run by @command{automake} -@cindex @command{libtoolize} and @command{autoreconf} -@cindex @command{autoreconf} and @command{libtoolize} -@cindex @file{bootstrap} and @command{autoreconf} -@cindex @file{autogen.sh} and @command{autoreconf} - -Libtool comes with a tool called @command{libtoolize} that will -install libtool's supporting files into a package. Running this -command will install @file{ltmain.sh}. You should execute it before -@command{aclocal} and @command{automake}. - -People upgrading old packages to newer autotools are likely to face -this issue because older Automake versions used to call -@command{libtoolize}. Therefore old build scripts do not call -@command{libtoolize}. - -Since Automake 1.6, it has been decided that running -@command{libtoolize} was none of Automake's business. Instead, that -functionality has been moved into the @command{autoreconf} command -(@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf, -The Autoconf Manual}). If you do not want to remember what to run and -when, just learn the @command{autoreconf} command. Hopefully, -replacing existing @file{bootstrap} or @file{autogen.sh} scripts by -a call to @command{autoreconf} should also free you from any similar -incompatible change in the future. - -@node Objects created both with libtool and without -@subsubsection Objects @samp{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 @file{Makefile.am}. - -@example -bin_PROGRAMS = prog -prog_SOURCES = prog.c foo.c @dots{} - -lib_LTLIBRARIES = libfoo.la -libfoo_la_SOURCES = foo.c @dots{} -@end example - -@noindent -(In this trivial case the issue could be avoided by linking -@file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in -@code{prog_SOURCES}. But let's assume we really want to keep -@file{prog} and @file{libfoo.la} separate.) - -Technically, it means that we should build @file{foo.$(OBJEXT)} for -@file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is -that in the course of creating @file{foo.lo}, libtool may erase (or -replace) @file{foo.$(OBJEXT)}, and this cannot be avoided. - -Therefore, when Automake detects this situation it will complain -with a message such as -@example -object 'foo.$(OBJEXT)' created both with libtool and without -@end example - -A workaround for this issue is to ensure that these two objects get -different basenames. As explained in @ref{Renamed Objects}, this -happens automatically when per-targets flags are used. - -@example -bin_PROGRAMS = prog -prog_SOURCES = prog.c foo.c @dots{} -prog_CFLAGS = $(AM_CFLAGS) - -lib_LTLIBRARIES = libfoo.la -libfoo_la_SOURCES = foo.c @dots{} -@end example - -@noindent -Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because -when the @code{prog_CFLAGS} is defined, it is used instead of -@code{AM_CFLAGS}. However as a side effect it will cause -@file{prog.c} and @file{foo.c} to be compiled as -@file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves -the issue. - -@node Program and Library Variables -@section 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 @file{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. - -@vtable @code -@item 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 @file{.o} file (or -@file{.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 @code{_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 @file{.o} files, then -@command{automake} will treat this file as it will any other source file -(@pxref{Support for Other Languages}). Otherwise, the file will be -ignored as though it were a header file. - -The prefixes @code{dist_} and @code{nodist_} can be used to control -whether files listed in a @code{_SOURCES} variable are distributed. -@code{dist_} is redundant, as sources are distributed by default, but it -can be specified for clarity if desired. - -It is possible to have both @code{dist_} and @code{nodist_} variants of -a given @code{_SOURCES} variable at once; this lets you easily -distribute some files and not others, for instance: - -@example -nodist_maude_SOURCES = nodist.c -dist_maude_SOURCES = dist-me.c -@end example - -The output file (on Unix systems, the @file{.o} file) will be put into the -subdirectory named after the source file. For instance @file{file.c} will -compiled to @file{file.o}, while @file{sub/dir/file.c} will be compiled to -@file{sub/dir/file.o}. -@cindex Subdirectory, objects in -@cindex Objects in subdirectory - -@item EXTRA_maude_SOURCES -Automake needs to know the list of files you intend to compile -@emph{statically}. For one thing, this is the only way Automake has of -knowing what sort of language support a given @file{Makefile.in} -requires. @footnote{There are other, more obscure reasons for -this limitation as well.} This means that, for example, you can't put a -configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES} -variable. If you intend to conditionally compile source files and use -@file{configure} to substitute the appropriate object names into, e.g., -@code{_LDADD} (see below), then you should list the corresponding source -files in the @code{EXTRA_} variable. - -This variable also supports @code{dist_} and @code{nodist_} prefixes. -For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra -sources that may need to be built, but should not be distributed. - -@item maude_AR -A static library is created by default by invoking @samp{$(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 -@code{_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: -@example -libmaude_a_AR = $(CXX) -ar -o -@end example - -@item maude_LIBADD -Extra objects can be added to a @emph{library} using the @code{_LIBADD} -variable. For instance, this should be used for objects determined by -@command{configure} (@pxref{A Library}). - -In the case of libtool libraries, @code{maude_LIBADD} can also refer -to other libtool libraries. - -@item maude_LDADD -Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a}, -@file{*.la}) can be added to a @emph{program} by listing them in the -@code{_LDADD} variable. For instance, this should be used for objects -determined by @command{configure} (@pxref{Linking}). - -@code{_LDADD} and @code{_LIBADD} are inappropriate for passing -program-specific linker flags (except for @option{-l}, @option{-L}, -@option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable -for this purpose. - -For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you -could link your program against the X libraries like so: - -@example -maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS) -@end example - -We recommend that you use @option{-l} and @option{-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 -@code{maude_DEPENDENCIES} (see below) is correctly defined by default. - -@item maude_LDFLAGS -This variable is used to pass extra flags to the link step of a program -or a shared library. It overrides the @code{AM_LDFLAGS} variable. - -@item maude_LIBTOOLFLAGS -This variable is used to pass extra options to @command{libtool}. -It overrides the @code{AM_LIBTOOLFLAGS} variable. -These options are output before @command{libtool}'s @option{--mode=@var{mode}} -option, so they should not be mode-specific options (those belong to -the compiler or linker flags). @xref{Libtool Flags}. - -@item maude_DEPENDENCIES -@itemx 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 @code{_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 @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files -for programs; @file{*.lo} and @file{*.la} files for Libtool libraries; -and @file{*.$(OBJEXT)} files for static libraries. In rare cases you -may need to add other kinds of files such as linker scripts, but -@emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If -some source file needs to be built before all the components of a -program are built, consider using the @code{BUILT_SOURCES} variable -(@pxref{Sources}). - -If @code{_DEPENDENCIES} is not supplied, it is computed by Automake. -The automatically-assigned value is the contents of @code{_LDADD} or -@code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L}, -@option{-dlopen} and @option{-dlpreopen} options removed. The configure -substitutions that are left in are only @samp{$(LIBOBJS)} and -@samp{$(ALLOCA)}; these are left because it is known that they will not -cause an invalid value for @code{_DEPENDENCIES} to be generated. - -@code{_DEPENDENCIES} is more likely used to perform conditional -compilation using an @code{AC_SUBST} variable that contains a list of -objects. @xref{Conditional Sources}, and @ref{Conditional Libtool -Sources}. - -The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where -you merely want to augment the @command{automake}-generated -@code{_DEPENDENCIES} variable rather than replacing it. - -@item 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 @code{_LINK} variable must hold the name of a -command that can be passed all the @file{.o} file names and libraries -to link against as arguments. Note that the name of the underlying -program is @emph{not} passed to @code{_LINK}; typically one uses -@samp{$@@}: - -@example -maude_LINK = $(CCLD) -magic -o $@@ -@end example - -If a @code{_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 -@code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where -they apply. - -@item maude_CCASFLAGS -@itemx maude_CFLAGS -@itemx maude_CPPFLAGS -@itemx maude_CXXFLAGS -@itemx maude_FFLAGS -@itemx maude_GCJFLAGS -@itemx maude_LFLAGS -@itemx maude_OBJCFLAGS -@itemx maude_OBJCXXFLAGS -@itemx maude_RFLAGS -@itemx maude_UPCFLAGS -@itemx maude_YFLAGS -@cindex per-target compilation flags, defined -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 @dfn{per-target compilation flags} are -@samp{_CCASFLAGS}, -@samp{_CFLAGS}, -@samp{_CPPFLAGS}, -@samp{_CXXFLAGS}, -@samp{_FFLAGS}, -@samp{_GCJFLAGS}, -@samp{_LFLAGS}, -@samp{_OBJCFLAGS}, -@samp{_OBJCXXFLAGS}, -@samp{_RFLAGS}, -@samp{_UPCFLAGS}, and -@samp{_YFLAGS}. - -When using a per-target compilation flag, Automake will choose a -different name for the intermediate object files. Ordinarily a file -like @file{sample.c} will be compiled to produce @file{sample.o}. -However, if the program's @code{_CFLAGS} variable is set, then the -object file will be named, for instance, @file{maude-sample.o}. (See -also @ref{Renamed Objects}). - -In compilations with per-target flags, the ordinary @samp{AM_} form of -the flags variable is @emph{not} automatically included in the -compilation (however, the user form of the variable @emph{is} included). -So for instance, if you want the hypothetical @file{maude} compilations -to also use the value of @code{AM_CFLAGS}, you would need to write: - -@example -maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS) -@end example - -@xref{Flag Variables Ordering}, for more discussion about the -interaction between user variables, @samp{AM_} shadow variables, and -per-target variables. - -@item 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, - -@example -bin_PROGRAMS = maude -maude_CPPFLAGS = -DSOMEFLAG -maude_SHORTNAME = m -maude_SOURCES = sample.c @dots{} -@end example - -@noindent -the object file would be named @file{m-sample.o} rather than -@file{maude-sample.o}. - -This facility is rarely needed in practice, -and we recommend avoiding it until you find it is required. -@end vtable - -@node Default _SOURCES -@section Default @code{_SOURCES} - -@vindex _SOURCES -@vindex SOURCES -@cindex @code{_SOURCES}, default -@cindex default @code{_SOURCES} -@vindex AM_DEFAULT_SOURCE_EXT - -@code{_SOURCES} variables are used to specify source files of programs -(@pxref{A Program}), libraries (@pxref{A Library}), and Libtool -libraries (@pxref{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 -@code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}. - -For example if you have the following somewhere in your -@file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}: - -@example -lib_LIBRARIES = libfoo.a sub/libc++.a -@end example - -@noindent -@file{libfoo.a} will be built using a default source file named -@file{libfoo.c}, and @file{sub/libc++.a} will be built from -@file{sub/libc++.c}. (In older versions @file{sub/libc++.a} -would be built from @file{sub_libc___a.c}, i.e., the default source -was the canonized name of the target, with @file{.c} appended. -We believe the new behavior is more sensible, but for backward -compatibility @command{automake} will use the old name if a file or a rule -with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.) - -@cindex @code{check_PROGRAMS} example -@vindex check_PROGRAMS -Default sources are mainly useful in test suites, when building many -test programs each from a single source. For instance, in - -@example -check_PROGRAMS = test1 test2 test3 -AM_DEFAULT_SOURCE_EXT = .cpp -@end example - -@noindent -@file{test1}, @file{test2}, and @file{test3} will be built -from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}. -Without the last line, they will be built from @file{test1.c}, -@file{test2.c}, and @file{test3.c}. - -@cindex Libtool modules, default source example -@cindex default source, Libtool modules example -Another case where this is convenient is building many Libtool modules -(@file{module@var{n}.la}), each defined in its own file -(@file{module@var{n}.c}). - -@example -AM_LDFLAGS = -module -lib_LTLIBRARIES = module1.la module2.la module3.la -@end example - -@cindex empty @code{_SOURCES} -@cindex @code{_SOURCES}, empty -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 @ref{true}; this happens when all -the constituents of a target have already been compiled and just need -to be combined using a @code{_LDADD} variable. Then it is necessary -to define an empty @code{_SOURCES} variable, so that @command{automake} -does not compute a default. - -@example -bin_PROGRAMS = target -target_SOURCES = -target_LDADD = libmain.a libmisc.a -@end example - -@node LIBOBJS -@section Special handling for @code{LIBOBJS} and @code{ALLOCA} - -@cindex @code{LIBOBJS}, example -@cindex @code{ALLOCA}, example -@cindex @code{LIBOBJS}, special handling -@cindex @code{ALLOCA}, special handling -@vindex LTLIBOBJS -@vindex LIBOBJS -@vindex LTALLOCA -@vindex ALLOCA - -The @samp{$(LIBOBJS)} and @samp{$(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 @file{configure}. - -@acindex AC_LIBOBJ - -These variables are defined by Autoconf macros such as -@code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, , -Generic Function Checks, autoconf, The Autoconf Manual}), or -@code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular -Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf -macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to -populate @samp{$(LIBOBJS)}. - -@acindex AC_LIBSOURCE - -Using these variables is very similar to doing conditional compilation -using @code{AC_SUBST} variables, as described in @ref{Conditional -Sources}. That is, when building a program, @samp{$(LIBOBJS)} and -@samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD} -variable, or to the @samp{*_LIBADD} variable when building a library. -However there is no need to list the corresponding sources in -@samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake -automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the -dependencies, and it will discover the list of corresponding source -files automatically (by tracing the invocations of the -@code{AC_LIBSOURCE} Autoconf macros). If you have already defined -@samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you -either need to add these variables manually, or use -@samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_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, @file{configure.ac} contains some checks that -affect either @code{LIBOBJS} or @code{ALLOCA}. - -@example -# configure.ac -@dots{} -AC_CONFIG_LIBOBJ_DIR([lib]) -@dots{} -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 -@dots{} -AC_CONFIG_FILES([ - lib/Makefile - src/Makefile -]) -AC_OUTPUT -@end example - -@acindex AC_CONFIG_LIBOBJ_DIR - -The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files -of these object files are to be found in the @file{lib/} directory. -Automake can also use this information, otherwise it expects the -source files are to be in the directory where the @samp{$(LIBOBJS)} -and @samp{$(ALLOCA)} variables are used. - -The @file{lib/} directory should therefore contain @file{malloc.c}, -@file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its -@file{Makefile.am}: - -@example -# lib/Makefile.am - -noinst_LIBRARIES = libcompat.a -libcompat_a_SOURCES = -libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA) -@end example - -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 @code{_SOURCES} line. - -@cindex Empty libraries and @samp{$(LIBOBJS)} -@cindex @samp{$(LIBOBJS)} and empty libraries -There is a small trap here, though: @samp{$(LIBOBJS)} and -@samp{$(ALLOCA)} might be empty, and building an empty library is not -portable. You should ensure that there is always something to put in -@file{libcompat.a}. Most projects will also add some utility -functions in that directory, and list them in -@code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot -be empty. - -Finally here is how this library could be used from the @file{src/} -directory. - -@example -# src/Makefile.am - -# Link all programs in this directory with libcompat.a -LDADD = ../lib/libcompat.a - -bin_PROGRAMS = tool1 tool2 @dots{} -tool1_SOURCES = @dots{} -tool2_SOURCES = @dots{} -@end example - -The variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} are typically -used in the directory where their sources lie. However, if -@code{AC_CONFIG_LIBOBJ_DIR} is used, it is OK to use these variables -in other directories. For instance @file{src/Makefile.am} could be -changed as follows. - -@example -# src/Makefile.am - -LDADD = $(LIBOBJS) $(ALLOCA) - -bin_PROGRAMS = tool1 tool2 @dots{} -tool1_SOURCES = @dots{} -tool2_SOURCES = @dots{} -@end example - -Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object -file names that end with @samp{.$(OBJEXT)}, they are not suitable for -Libtool libraries (where the expected object extension is @file{.lo}): -@code{LTLIBOBJS} and @code{LTALLOCA} should be used instead. - -@code{LTLIBOBJS} is defined automatically by Autoconf and should not -be defined by hand (as in the past), however at the time of writing -@code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually. -@xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, -autoconf, The Autoconf Manual}. - - -@node Program Variables -@section Variables used when building a program - -Occasionally it is useful to know which @file{Makefile} variables -Automake uses for compilations, and in which order (@pxref{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 @code{CC}, -@code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and -@code{LIBS}. -@vindex CC -@vindex CFLAGS -@vindex CPPFLAGS -@vindex DEFS -@vindex LDFLAGS -@vindex LIBS - -There are some additional variables that Automake defines on its own: - -@vtable @code -@item 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, @option{-I} and @option{-D} options should be listed here. - -Automake already provides some @option{-I} options automatically, in a -separate variable that is also passed to every compilation that invokes -the C preprocessor. In particular it generates @samp{-I.}, -@samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding -@file{config.h} (if you've used @code{AC_CONFIG_HEADERS}). You can -disable the default @option{-I} options using the @option{nostdinc} -option. - -When a file to be included is generated during the build and not part -of a distribution tarball, its location is under @code{$(builddir)}, -not under @code{$(srcdir)}. This matters especially for packages that -use header files placed in sub-directories and want to allow builds -outside the source tree (@pxref{VPATH Builds}). In that case we -recommend to use a pair of @option{-I} options, such as, e.g., -@samp{-Isome/subdir -I$(srcdir)/some/subdir} or -@samp{-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. - -@code{AM_CPPFLAGS} is ignored in preference to a per-executable (or -per-library) @code{_CPPFLAGS} variable if it is defined. - -@item INCLUDES -This does the same job as @code{AM_CPPFLAGS} (or any per-target -@code{_CPPFLAGS} variable if it is used). It is an older name for the -same functionality. This variable is deprecated; we suggest using -@code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead. - -@item AM_CFLAGS -This is the variable the @file{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) -@code{_CFLAGS}. - -@item COMPILE -This is the command used to actually compile a C source file. The -file name is appended to form the complete command line. - -@item AM_LDFLAGS -This is the variable the @file{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) @code{_LDFLAGS}. - -@item LINK -This is the command used to actually link a C program. It already -includes @samp{-o $@@} and the usual variable references (for instance, -@code{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 @code{_LINK} variable or per-target flags -cause Automake to define such a @code{_LINK} variable. -@end vtable - - -@node Yacc and Lex -@section Yacc and Lex support - -Automake has somewhat idiosyncratic support for Yacc and Lex. - -Automake assumes that the @file{.c} file generated by @command{yacc} -(or @command{lex}) should be named using the basename of the input -file. That is, for a yacc source file @file{foo.y}, Automake will -cause the intermediate file to be named @file{foo.c} (as opposed to -@file{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 @option{-d} Yacc option is used; see -below for more information about this flag, and how to specify it. -Files with the extension @file{.y} will thus be turned into @file{.c} -sources and @file{.h} headers; likewise, @file{.yy} will become -@file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and -@file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx}, -and @file{.ypp} will become @file{.cpp} and @file{.hpp}. - -Similarly, lex source files can be used to generate C or C++; the -extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and -@file{.lpp} are recognized. - -You should never explicitly mention the intermediate (C or C++) file -in any @code{SOURCES} variable; only list the source file. - -The intermediate files generated by @command{yacc} (or @command{lex}) -will be included in any distribution that is made. That way the user -doesn't need to have @command{yacc} or @command{lex}. - -If a @command{yacc} source file is seen, then your @file{configure.ac} must -define the variable @code{YACC}. This is most easily done by invoking -the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular -Program Checks, autoconf, The Autoconf Manual}). - -@vindex YFLAGS -@vindex AM_YFLAGS -When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and -@code{YFLAGS}. The latter is a user variable and the former is -intended for the @file{Makefile.am} author. - -@code{AM_YFLAGS} is usually used to pass the @option{-d} option to -@command{yacc}. Automake knows what this means and will automatically -adjust its rules to update and distribute the header file built by -@samp{yacc -d}@footnote{Please note that @command{automake} recognizes -@option{-d} in @code{AM_YFLAGS} only if it is not clustered with other -options; for example, it won't be recognized if @code{AM_YFLAGS} is -@option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or -@option{-t -d}.}. -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 -@code{BUILT_SOURCES} (@pxref{Sources}) as follows. - -@example -BUILT_SOURCES = parser.h -AM_YFLAGS = -d -bin_PROGRAMS = foo -foo_SOURCES = @dots{} parser.y @dots{} -@end example - -If a @command{lex} source file is seen, then your @file{configure.ac} -must define the variable @code{LEX}. You can use @code{AC_PROG_LEX} -to do this (@pxref{Particular Programs, , Particular Program Checks, -autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro -(@pxref{Macros}) is recommended. - -@vindex LFLAGS -@vindex AM_LFLAGS -When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and -@code{LFLAGS}. The latter is a user variable and the former is -intended for the @file{Makefile.am} author. - -When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the -rebuild rule for distributed Yacc and Lex sources are only used when -@code{maintainer-mode} is enabled, or when the files have been erased. - -@cindex @command{ylwrap} -@cindex @command{yacc}, multiple parsers -@cindex Multiple @command{yacc} parsers -@cindex Multiple @command{lex} lexers -@cindex @command{lex}, multiple lexers - -When @command{lex} or @command{yacc} sources are used, @code{automake -a} -automatically installs an auxiliary program called @command{ylwrap} in -your package (@pxref{Auxiliary Programs}). -This program is used by the build rules to rename the output of these -tools, and makes it possible to include multiple @command{yacc} (or -@command{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 @command{yacc} -simultaneously.) - -For @command{yacc}, simply managing locking is insufficient. The output of -@command{yacc} always uses the same symbol names internally, so it isn't -possible to link two @command{yacc} parsers into the same executable. - -We recommend using the following renaming hack used in @command{gdb}: -@example -#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 -@end example - -For each define, replace the @samp{c_} prefix with whatever you like. -These defines work for @command{bison}, @command{byacc}, and -traditional @code{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. - - -@node C++ Support -@section C++ Support - -@cindex C++ support -@cindex Support for C++ - -Automake includes full support for C++. - -Any package including C++ code must define the output variable -@code{CXX} in @file{configure.ac}; the simplest way to do this is to use -the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular -Program Checks, autoconf, The Autoconf Manual}). - -A few additional variables are defined when a C++ source file is seen: - -@vtable @code -@item CXX -The name of the C++ compiler. - -@item CXXFLAGS -Any flags to pass to the C++ compiler. - -@item AM_CXXFLAGS -The maintainer's variant of @code{CXXFLAGS}. - -@item CXXCOMPILE -The command used to actually compile a C++ source file. The file name -is appended to form the complete command line. - -@item CXXLINK -The command used to actually link a C++ program. -@end vtable - - -@node Objective C Support -@section Objective C Support - -@cindex Objective C support -@cindex Support for Objective C - -Automake includes some support for Objective C. - -Any package including Objective C code must define the output variable -@code{OBJC} in @file{configure.ac}; the simplest way to do this is to use -the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular -Program Checks, autoconf, The Autoconf Manual}). - -A few additional variables are defined when an Objective C source file -is seen: - -@vtable @code -@item OBJC -The name of the Objective C compiler. - -@item OBJCFLAGS -Any flags to pass to the Objective C compiler. - -@item AM_OBJCFLAGS -The maintainer's variant of @code{OBJCFLAGS}. - -@item OBJCCOMPILE -The command used to actually compile an Objective C source file. The -file name is appended to form the complete command line. - -@item OBJCLINK -The command used to actually link an Objective C program. -@end vtable - - -@node Objective C++ Support -@section Objective C++ Support - -@cindex Objective C++ support -@cindex Support for Objective C++ - -Automake includes some support for Objective C++. - -Any package including Objective C++ code must define the output variable -@code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use -the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular -Program Checks, autoconf, The Autoconf Manual}). - -A few additional variables are defined when an Objective C++ source file -is seen: - -@vtable @code -@item OBJCXX -The name of the Objective C++ compiler. - -@item OBJCXXFLAGS -Any flags to pass to the Objective C++ compiler. - -@item AM_OBJCXXFLAGS -The maintainer's variant of @code{OBJCXXFLAGS}. - -@item OBJCXXCOMPILE -The command used to actually compile an Objective C++ source file. The -file name is appended to form the complete command line. - -@item OBJCXXLINK -The command used to actually link an Objective C++ program. -@end vtable - - -@node Unified Parallel C Support -@section Unified Parallel C Support - -@cindex Unified Parallel C support -@cindex Support for Unified Parallel C - -Automake includes some support for Unified Parallel C. - -Any package including Unified Parallel C code must define the output -variable @code{UPC} in @file{configure.ac}; the simplest way to do -this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}). - -A few additional variables are defined when a Unified Parallel C -source file is seen: - -@vtable @code -@item UPC -The name of the Unified Parallel C compiler. - -@item UPCFLAGS -Any flags to pass to the Unified Parallel C compiler. - -@item AM_UPCFLAGS -The maintainer's variant of @code{UPCFLAGS}. - -@item UPCCOMPILE -The command used to actually compile a Unified Parallel C source file. -The file name is appended to form the complete command line. - -@item UPCLINK -The command used to actually link a Unified Parallel C program. -@end vtable - - -@node Assembly Support -@section Assembly Support - -Automake includes some support for assembly code. There are two forms -of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP} -(@file{*.S} or @file{*.sx}). - -@vindex CCAS -@vindex CCASFLAGS -@vindex CPPFLAGS -@vindex AM_CCASFLAGS -@vindex AM_CPPFLAGS -The variable @code{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 @option{-c} and @option{-o}. The values of -@code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target -definition) is passed to the compilation. For preprocessed files, -@code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS} -and @code{AM_CPPFLAGS} are also used. - -The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and -@code{CCASFLAGS} for you (unless they are already set, it simply sets -@code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler -flags), but you are free to define these variables by other means. - -Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by -@command{automake} as being files containing assembly code. - - -@node Fortran 77 Support -@comment node-name, next, previous, up -@section Fortran 77 Support - -@cindex Fortran 77 support -@cindex Support for Fortran 77 - -Automake includes full support for Fortran 77. - -Any package including Fortran 77 code must define the output variable -@code{F77} in @file{configure.ac}; the simplest way to do this is to use -the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular -Program Checks, autoconf, The Autoconf Manual}). - -A few additional variables are defined when a Fortran 77 source file is -seen: - -@vtable @code - -@item F77 -The name of the Fortran 77 compiler. - -@item FFLAGS -Any flags to pass to the Fortran 77 compiler. - -@item AM_FFLAGS -The maintainer's variant of @code{FFLAGS}. - -@item RFLAGS -Any flags to pass to the Ratfor compiler. - -@item AM_RFLAGS -The maintainer's variant of @code{RFLAGS}. - -@item F77COMPILE -The command used to actually compile a Fortran 77 source file. The file -name is appended to form the complete command line. - -@item FLINK -The command used to actually link a pure Fortran 77 program or shared -library. - -@end vtable - -Automake can handle preprocessing Fortran 77 and Ratfor source files in -addition to compiling them@footnote{Much, if not most, of the -information in the following sections pertaining to preprocessing -Fortran 77 programs was taken almost verbatim from @ref{Catalogue of -Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake -also contains some support for creating programs and shared libraries -that are a mixture of Fortran 77 and other languages (@pxref{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++ -@end menu - - -@node Preprocessing Fortran 77 -@comment node-name, next, previous, up -@subsection Preprocessing Fortran 77 - -@cindex Preprocessing Fortran 77 -@cindex Fortran 77, Preprocessing -@cindex Ratfor programs - -@file{N.f} is made automatically from @file{N.F} or @file{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: - -@table @file - -@item .F -@code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@* -$(AM_FFLAGS) $(FFLAGS)} - -@item .r -@code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)} - -@end table - - -@node Compiling Fortran 77 Files -@comment node-name, next, previous, up -@subsection Compiling Fortran 77 Files - -@file{N.o} is made automatically from @file{N.f}, @file{N.F} or -@file{N.r} by running the Fortran 77 compiler. The precise command used -is as follows: - -@table @file - -@item .f -@code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)} - -@item .F -@code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@* -$(AM_FFLAGS) $(FFLAGS)} - -@item .r -@code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)} - -@end table - - -@node Mixing Fortran 77 With C and C++ -@comment node-name, next, previous, up -@subsection Mixing Fortran 77 With C and C++ - -@cindex Fortran 77, mixing with C and C++ -@cindex Mixing Fortran 77 with C and C++ -@cindex Linking Fortran 77 with C and C++ -@cindex cfortran -@cindex Mixing Fortran 77 with C and/or C++ - -Automake currently provides @emph{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 @emph{not} (currently) handled by Automake, but -that are handled by other packages@footnote{For example, -@uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package} -addresses all of these inter-language issues, and runs under nearly all -Fortran 77, C and C++ compilers on nearly all platforms. However, -@command{cfortran} is not yet Free Software, but it will be in the next -major release.}. - -Automake can help in two ways: - -@enumerate -@item -Automatic selection of the linker depending on which combinations of -source code. - -@item -Automatic selection of the appropriate linker flags (e.g., @option{-L} and -@option{-l}) to pass to the automatically selected linker in order to link -in the appropriate Fortran 77 intrinsic and run-time libraries. - -@cindex @code{FLIBS}, defined -@vindex FLIBS -These extra Fortran 77 linker flags are supplied in the output variable -@code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro. -@xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf, -The Autoconf Manual}. -@end enumerate - -If Automake detects that a program or shared library (as mentioned in -some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source -code that is a mixture of Fortran 77 and C and/or C++, then it requires -that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in -@file{configure.ac}, and that either @code{$(FLIBS)} -appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD} -(for shared libraries) variables. It is the responsibility of the -person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)} -appears in the appropriate @code{_LDADD} or -@code{_LIBADD} variable. - -@cindex Mixed language example -@cindex Example, mixed language - -For example, consider the following @file{Makefile.am}: - -@example -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) -@end example - -In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS} -is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't -been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then -Automake would have issued a warning. - -@menu -* How the Linker is Chosen:: Automatic linker selection -@end menu - -@node How the Linker is Chosen -@comment node-name, next, previous, up -@subsubsection How the Linker is Chosen - -@cindex Automatic linker selection -@cindex Selecting the linker automatically - -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.) - -@enumerate -@item -@vindex GCJLINK -Native Java (@code{GCJLINK}) -@item -@vindex OBJCXXLINK -Objective C++ (@code{OBJCXXLINK}) -@item -@vindex CXXLINK -C++ (@code{CXXLINK}) -@item -@vindex F77LINK -Fortran 77 (@code{F77LINK}) -@item -@vindex FCLINK -Fortran (@code{FCLINK}) -@item -@vindex OBJCLINK -Objective C (@code{OBJCLINK}) -@item -@vindex UPCLINK -Unified Parallel C (@code{UPCLINK}) -@item -@vindex LINK -C (@code{LINK}) -@end enumerate - -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 -@code{_LDADD} or @code{_LIBADD} variable by the user writing the -@file{Makefile.am}. - -Automake only looks at the file names listed in @file{_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. @xref{Libtool Convenience Libraries}, for a -trick with @code{nodist_EXTRA_@dots{}_SOURCES}. - -A per-target @code{_LINK} variable will override the above selection. -Per-target link flags will cause Automake to write a per-target -@code{_LINK} variable according to the language chosen as above. - - -@node Fortran 9x Support -@comment node-name, next, previous, up -@section Fortran 9x Support - -@cindex Fortran 9x support -@cindex Support for Fortran 9x - -Automake includes support for Fortran 9x. - -Any package including Fortran 9x code must define the output variable -@code{FC} in @file{configure.ac}; the simplest way to do this is to use -the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular -Program Checks, autoconf, The Autoconf Manual}). - -A few additional variables are defined when a Fortran 9x source file is -seen: - -@vtable @code - -@item FC -The name of the Fortran 9x compiler. - -@item FCFLAGS -Any flags to pass to the Fortran 9x compiler. - -@item AM_FCFLAGS -The maintainer's variant of @code{FCFLAGS}. - -@item FCCOMPILE -The command used to actually compile a Fortran 9x source file. The file -name is appended to form the complete command line. - -@item FCLINK -The command used to actually link a pure Fortran 9x program or shared -library. - -@end vtable - -@menu -* Compiling Fortran 9x Files:: Compiling Fortran 9x sources -@end menu - -@node Compiling Fortran 9x Files -@comment node-name, next, previous, up -@subsection Compiling Fortran 9x Files - -@file{@var{file}.o} is made automatically from @file{@var{file}.f90}, -@file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08} -by running the Fortran 9x compiler. The precise command used -is as follows: - -@table @file - -@item .f90 -@code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<} - -@item .f95 -@code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<} - -@item .f03 -@code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<} - -@item .f08 -@code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<} - -@end table - -@node Java Support with gcj -@comment node-name, next, previous, up -@section Compiling Java sources using gcj - -@cindex Java support with gcj -@cindex Support for Java with gcj -@cindex Java to native code, compilation -@cindex Compilation of Java to native code - -Automake includes support for natively compiled Java, using @command{gcj}, -the Java front end to the GNU Compiler Collection (rudimentary support -for compiling Java to bytecode using the @command{javac} compiler is -also present, @emph{albeit deprecated}; @pxref{Java}). - -Any package including Java code to be compiled must define the output -variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS} -must also be defined somehow (either in @file{configure.ac} or -@file{Makefile.am}). The simplest way to do this is to use the -@code{AM_PROG_GCJ} macro. - -@vindex GCJFLAGS - -By default, programs including Java source files are linked with -@command{gcj}. - -As always, the contents of @code{AM_GCJFLAGS} are passed to every -compilation invoking @command{gcj} (in its role as an ahead-of-time -compiler, when invoking it to create @file{.class} files, -@code{AM_JAVACFLAGS} is used instead). If it is necessary to pass -options to @command{gcj} from @file{Makefile.am}, this variable, and not -the user variable @code{GCJFLAGS}, should be used. - -@vindex AM_GCJFLAGS - -@command{gcj} can be used to compile @file{.java}, @file{.class}, -@file{.zip}, or @file{.jar} files. - -When linking, @command{gcj} requires that the main class be specified -using the @option{--main=} option. The easiest way to do this is to use -the @code{_LDFLAGS} variable for the program. - - -@node Vala Support -@comment node-name, next, previous, up -@section Vala Support - -@cindex Vala Support -@cindex Support for Vala - -Automake provides initial support for Vala -(@uref{http://www.vala-project.org/}). -This requires valac version 0.7.0 or later, and currently requires -the user to use GNU @command{make}. - -@example -foo_SOURCES = foo.vala bar.vala zardoc.c -@end example - -Any @file{.vala} file listed in a @code{_SOURCES} variable will be -compiled into C code by the Vala compiler. The generated @file{.c} files -are distributed. The end user does not need to have a Vala compiler installed. - -Automake ships with an Autoconf macro called @code{AM_PROG_VALAC} -that will locate the Vala compiler and optionally check its version -number. - -@defmac AM_PROG_VALAC (@ovar{minimum-version}, @ovar{action-if-found}, - @ovar{action-if-not-found}) -Search for a Vala compiler in @env{PATH}. If it is found, the variable -@code{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 @var{minimum-version}, -then @var{action-if-found} is run (this defaults to do nothing). -Otherwise, @var{action-if-not-found} is run. If @var{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. -@end defmac - -There are a few variables that are used when compiling Vala sources: - -@vtable @code -@item VALAC -Absolute path to the Vala compiler, or simply @samp{valac} if no -suitable compiler Vala could be found at configure runtime. - -@item VALAFLAGS -Additional arguments for the Vala compiler. - -@item AM_VALAFLAGS -The maintainer's variant of @code{VALAFLAGS}. - -@example -lib_LTLIBRARIES = libfoo.la -libfoo_la_SOURCES = foo.vala -@end example -@end vtable - -Note that currently, you cannot use per-target @code{*_VALAFLAGS} -(@pxref{Renamed Objects}) to produce different C files from one Vala -source file. - - -@node Support for Other Languages -@comment node-name, next, previous, up -@section Support for Other Languages - -Automake currently only includes full support for C, C++ (@pxref{C++ -Support}), Objective C (@pxref{Objective C Support}), -Objective C++ (@pxref{Objective C++ Support}), -Fortran 77 -(@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}), -and Java (@pxref{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 (@pxref{Suffixes}). - -@node Dependencies -@section Automatic dependency tracking - -As a developer it is often painful to continually update the -@file{Makefile.am} whenever the include-file dependencies change in a -project. Automake supplies a way to automatically track dependency -changes (@pxref{Dependency Tracking}). - -@cindex Dependency tracking -@cindex Automatic 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 @command{depcomp}. @command{depcomp} -understands how to coax many different C and C++ compilers into -generating dependency information in the format it requires. -@samp{automake -a} will install @command{depcomp} into your source -tree for you. If @command{depcomp} can't figure out how to properly -invoke your compiler, dependency tracking will simply be disabled for -your build. - -@cindex @command{depcomp} - -Experience with earlier versions of Automake (@pxref{Dependency Tracking -Evolution, , Dependency Tracking Evolution, automake-history, Brief History -of Automake}) 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 -@option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or -passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE} -(this should be the preferred way). Or, you can invoke @command{automake} -with the @option{-i} option. Dependency tracking is enabled by default. - -@vindex AUTOMAKE_OPTIONS -@opindex no-dependencies - -The person building your package also can choose to disable dependency -tracking by configuring with @option{--disable-dependency-tracking}. - -@cindex Disabling dependency tracking -@cindex Dependency tracking, disabling - - -@node EXEEXT -@section Support for executable extensions - -@cindex Executable extension -@cindex Extension, executable -@cindex Windows - -On some platforms, such as Windows, executables are expected to have an -extension such as @file{.exe}. On these platforms, some compilers (GCC -among them) will automatically generate @file{foo.exe} when asked to -generate @file{foo}. - -Automake provides mostly-transparent support for this. Unfortunately -@emph{mostly} doesn't yet mean @emph{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: - -@example -bin_PROGRAMS = liver -@end example - -to this: - -@example -bin_PROGRAMS = liver$(EXEEXT) -@end example - -The targets Automake generates are likewise given the @samp{$(EXEEXT)} -extension. - -The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests}) -are also rewritten if they contain filenames that have been declared as -programs in the same @file{Makefile}. (This is mostly useful when some -programs from @code{check_PROGRAMS} are listed in @code{TESTS}.) - -However, Automake cannot apply this rewriting to @command{configure} -substitutions. This means that if you are conditionally building a -program using such a substitution, then your @file{configure.ac} must -take care to add @samp{$(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 -@samp{$(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 @option{no-exeext} -option (@pxref{Options}) will disable this feature. This works in a -fairly ugly way; if @option{no-exeext} is seen, then the presence of a -rule for a target named @code{foo} in @file{Makefile.am} will override -an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without -the @option{no-exeext} option, this use will give a diagnostic. - - -@node Other Objects -@chapter 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 -@end menu - - -@node Scripts -@section Executable Scripts - -@cindex @code{_SCRIPTS} primary, defined -@cindex @code{SCRIPTS} primary, defined -@cindex Primary variable, @code{SCRIPTS} -@vindex _SCRIPTS -@cindex Installing scripts - -It is possible to define and install programs that are scripts. Such -programs are listed using the @code{SCRIPTS} primary name. When the -script is distributed in its final, installable form, the -@file{Makefile} usually looks as follows: -@vindex SCRIPTS - -@example -# Install my_script in $(bindir) and distribute it. -dist_bin_SCRIPTS = my_script -@end example - -Scripts are not distributed by default; as we have just seen, those -that should be distributed can be specified using a @code{dist_} -prefix as with other primaries. - -@cindex @code{SCRIPTS}, installation directories -@vindex bin_SCRIPTS -@vindex sbin_SCRIPTS -@vindex libexec_SCRIPTS -@vindex pkgdata_SCRIPTS -@vindex pkglibexec_SCRIPTS -@vindex noinst_SCRIPTS -@vindex check_SCRIPTS - -Scripts can be installed in @code{bindir}, @code{sbindir}, -@code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}. - -Scripts that need not be installed can be listed in -@code{noinst_SCRIPTS}, and among them, those which are needed only by -@samp{make check} should go in @code{check_SCRIPTS}. - -When a script needs to be built, the @file{Makefile.am} should include -the appropriate rules. For instance the @command{automake} program -itself is a Perl script that is generated from @file{automake.in}. -Here is how this is handled: - -@example -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' \ - @dots{} - -automake: automake.in Makefile - $(do_subst) < $(srcdir)/automake.in > automake - chmod +x automake -@end example - -Such scripts for which a build rule has been supplied need to be -deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their -sources have to be distributed, usually with @code{EXTRA_DIST} -(@pxref{Basics of Distribution}). - -Another common way to build scripts is to process them from -@file{configure} with @code{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 @file{configure.ac} contains - -@example -AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script]) -@end example - -@noindent -to build @file{src/my_script} from @file{src/my_script.in}, then a -@file{src/Makefile.am} to install this script in @code{$(bindir)} can -be as simple as - -@example -bin_SCRIPTS = my_script -CLEANFILES = $(bin_SCRIPTS) -@end example - -@noindent -There is no need for @code{EXTRA_DIST} or any build rule: Automake -infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}). -@code{CLEANFILES} is still useful, because by default Automake will -clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not -@code{clean}. - -Although this looks simpler, building scripts this way has one -drawback: directory variables such as @code{$(datadir)} are not fully -expanded and may refer to other directory variables. - -@node Headers -@section Header files - -@cindex @code{_HEADERS} primary, defined -@cindex @code{HEADERS} primary, defined -@cindex Primary variable, @code{HEADERS} -@vindex _HEADERS -@vindex noinst_HEADERS -@cindex @code{HEADERS}, installation directories -@cindex Installing headers -@vindex include_HEADERS -@vindex oldinclude_HEADERS -@vindex pkginclude_HEADERS - - -Header files that must be installed are specified by the -@code{HEADERS} family of variables. Headers can be installed in -@code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any -other directory you may have defined (@pxref{Uniform}). For instance, - -@example -include_HEADERS = foo.h bar/bar.h -@end example - -@noindent -will install the two files as @file{$(includedir)/foo.h} and -@file{$(includedir)/bar.h}. - -The @code{nobase_} prefix is also supported, - -@example -nobase_include_HEADERS = foo.h bar/bar.h -@end example - -@noindent -will install the two files as @file{$(includedir)/foo.h} and -@file{$(includedir)/bar/bar.h} (@pxref{Alternative}). - -@vindex noinst_HEADERS -Usually, only header files that accompany installed libraries need to -be installed. Headers used by programs or convenience libraries are -not installed. The @code{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 @code{_SOURCES} variable (@pxref{Program -Sources}) instead of in @code{noinst_HEADERS}. This is clearer for -the @file{Makefile.am} reader. @code{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 @code{_SOURCES} -variable or in a @code{_HEADERS} variable. Missing ones will not -appear in the distribution. - -For header files that are built and must not be distributed, use the -@code{nodist_} prefix as in @code{nodist_include_HEADERS} or -@code{nodist_prog_SOURCES}. If these generated headers are needed -during the build, you must also ensure they exist before they are -used (@pxref{Sources}). - - -@node Data -@section Architecture-independent data files - -@cindex @code{_DATA} primary, defined -@cindex @code{DATA} primary, defined -@cindex Primary variable, @code{DATA} -@vindex _DATA - -Automake supports the installation of miscellaneous data files using the -@code{DATA} family of variables. -@vindex DATA - -@vindex data_DATA -@vindex sysconf_DATA -@vindex sharedstate_DATA -@vindex localstate_DATA -@vindex pkgdata_DATA - -Such data can be installed in the directories @code{datadir}, -@code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or -@code{pkgdatadir}. - -By default, data files are @emph{not} included in a distribution. Of -course, you can use the @code{dist_} prefix to change this on a -per-variable basis. - -Here is how Automake declares its auxiliary data files: - -@example -dist_pkgdata_DATA = clean-kr.am clean.am @dots{} -@end example - - -@node Sources -@section Built Sources - -Because Automake's automatic dependency tracking works as a side-effect -of compilation (@pxref{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 -@file{foo.c} includes @file{foo.h}. When it first compiles -@file{foo.o}, @command{make} only knows that @file{foo.o} depends on -@file{foo.c}. As a side-effect of this compilation @command{depcomp} -records the @file{foo.h} dependency so that following invocations of -@command{make} will honor it. In these conditions, it's clear there is -no problem: either @file{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 @file{foo.o} should be rebuilt. - -It's a different story if @file{foo.h} doesn't exist by the first -@command{make} run. For instance, there might be a rule to build -@file{foo.h}. This time @file{file.o}'s build will fail because the -compiler can't find @file{foo.h}. @command{make} failed to trigger the -rule to build @file{foo.h} first by lack of dependency information. - -@vindex BUILT_SOURCES -@cindex @code{BUILT_SOURCES}, defined - -The @code{BUILT_SOURCES} variable is a workaround for this problem. A -source file listed in @code{BUILT_SOURCES} is made on @samp{make all} -or @samp{make check} (or even @samp{make install}) before other -targets are processed. However, such a source file is not -@emph{compiled} unless explicitly requested by mentioning it in some -other @code{_SOURCES} variable. - -So, to conclude our introductory example, we could use -@samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before -any other target (including @file{foo.o}) during @samp{make all} or -@samp{make check}. - -@code{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 @code{BUILT_SOURCES}. For instance, a generated @file{.c} file -doesn't need to appear in @code{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 @code{BUILT_SOURCES} is -honored only by @samp{make all}, @samp{make check} and @samp{make -install}. This means you cannot build a specific target (e.g., -@samp{make foo}) in a clean tree if it depends on a built source. -However it will succeed if you have run @samp{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. -@end menu - -@node Built Sources Example -@subsection Built Sources Example - -Suppose that @file{foo.c} includes @file{bindir.h}, which is -installation-dependent and not distributed: it needs to be built. Here -@file{bindir.h} defines the preprocessor macro @code{bindir} to the -value of the @command{make} variable @code{bindir} (inherited from -@file{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. - -@subsubheading First Try - -This first implementation will illustrate the bootstrap issue mentioned -in the previous section (@pxref{Sources}). - -Here is a tentative @file{Makefile.am}. - -@example -# 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)"' >$@@ -@end example - -This setup doesn't work, because Automake doesn't know that @file{foo.c} -includes @file{bindir.h}. Remember, automatic dependency tracking works -as a side-effect of compilation, so the dependencies of @file{foo.o} will -be known only after @file{foo.o} has been compiled (@pxref{Dependencies}). -The symptom is as follows. - -@example -% 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 -@end example - -In this example @file{bindir.h} is not distributed nor installed, and -it is not even being built on-time. One may wonder if the -@samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This -line simply states that @file{bindir.h} is a source of @code{foo}, so -for instance, it should be inspected while generating tags -(@pxref{Tags}). In other words, it does not help our present problem, -and the build would fail identically without it. - -@subsubheading Using @code{BUILT_SOURCES} - -A solution is to require @file{bindir.h} to be built before anything -else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}). - -@example -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)"' >$@@ -@end example - -See how @file{bindir.h} gets built first: - -@example -% 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' -@end example - -However, as said earlier, @code{BUILT_SOURCES} applies only to the -@code{all}, @code{check}, and @code{install} targets. It still fails -if you try to run @samp{make foo} explicitly: - -@example -% 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 -@end example - -@subsubheading Recording Dependencies manually - -Usually people are happy enough with @code{BUILT_SOURCES} because they -never build targets such as @samp{make foo} before @samp{make all}, as -in the previous example. However if this matters to you, you can -avoid @code{BUILT_SOURCES} and record such dependencies explicitly in -the @file{Makefile.am}. - -@example -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)"' >$@@ -@end example - -You don't have to list @emph{all} the dependencies of @file{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 @file{foo.o} and -@file{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). -@samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to -output to build @samp{foo.$(OBJEXT)}. It happens to work in this case -because Automake doesn't have to output any @samp{foo.$(OBJEXT):} -target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}). -Always check the generated @file{Makefile.in} if you do this. - -@subsubheading Build @file{bindir.h} from @file{configure} - -It's possible to define this preprocessor macro from @file{configure}, -either in @file{config.h} (@pxref{Defining Directories, , Defining -Directories, autoconf, The Autoconf Manual}), or by processing a -@file{bindir.h.in} file using @code{AC_CONFIG_FILES} -(@pxref{Configuration Actions, ,Configuration Actions, autoconf, The -Autoconf Manual}). - -At this point it should be clear that building @file{bindir.h} from -@file{configure} works well for this example. @file{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 -@file{bindir.h}. - -@example -bin_PROGRAMS = foo -foo_SOURCES = foo.c -@end example - -However, it's not always possible to build sources from -@file{configure}, especially when these sources are generated by a tool -that needs to be built first. - -@subsubheading Build @file{bindir.c}, not @file{bindir.h}. - -Another attractive idea is to define @code{bindir} as a variable or -function exported from @file{bindir.o}, and build @file{bindir.c} -instead of @file{bindir.h}. - -@example -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)";' >$@@ -@end example - -@file{bindir.h} contains just the variable's declaration and doesn't -need to be built, so it won't cause any trouble. @file{bindir.o} is -always dependent on @file{bindir.c}, so @file{bindir.c} will get built -first. - -@subsubheading Which is best? - -There is no panacea, of course. Each solution has its merits and -drawbacks. - -You cannot use @code{BUILT_SOURCES} if the ability to run @samp{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 @file{./configure} is not always possible, neither -is converting @file{.h} files into @file{.c} files. - - -@node Other GNU Tools -@chapter Other GNU Tools - -Since Automake is primarily intended to generate @file{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 -@end menu - - -@node Emacs Lisp -@section Emacs Lisp - -@cindex @code{_LISP} primary, defined -@cindex @code{LISP} primary, defined -@cindex Primary variable, @code{LISP} - -@vindex _LISP -@vindex lisp_LISP -@vindex noinst_LISP - -Automake provides some support for Emacs Lisp. The @code{LISP} primary -is used to hold a list of @file{.el} files. Possible prefixes for this -primary are @code{lisp_} and @code{noinst_}. Note that if -@code{lisp_LISP} is defined, then @file{configure.ac} must run -@code{AM_PATH_LISPDIR} (@pxref{Macros}). - -@vindex dist_lisp_LISP -@vindex dist_noinst_LISP -Lisp sources are not distributed by default. You can prefix the -@code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or -@code{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 @code{AM_PATH_LISPDIR}, if any was found. When performing such -byte-compilation, the flags specified in the (developer-reserved) -@code{AM_ELCFLAGS} and (user-reserved) @code{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. - -@example -lisp_LISP = file1.el file2.el -ELCFILES = -@end example - -@noindent -@code{ELCFILES} is an internal Automake variable that normally lists -all @file{.elc} files that must be byte-compiled. Automake defines -@code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this -variable explicitly prevents byte-compilation. - -Since Automake 1.8, we now recommend using @code{lisp_DATA} instead: - -@c Keep in sync with primary-prefix-couples-documented-valid.sh -@example -lisp_DATA = file1.el file2.el -@end example - -Note that these two constructs are not equivalent. @code{_LISP} will -not install a file if Emacs is not installed, while @code{_DATA} will -always install its files. - -@node gettext -@section Gettext - -@cindex GNU Gettext support -@cindex Gettext support -@cindex Support for GNU Gettext - -If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake -turns on support for GNU gettext, a message catalog system for -internationalization -(@pxref{Top, , Introduction, gettext, GNU gettext utilities}). - -The @code{gettext} support in Automake requires the addition of one or -two subdirectories to the package: @file{po} and possibly also @file{intl}. -The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the -@samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used. -Automake ensures that these directories exist and are mentioned in -@code{SUBDIRS}. - -@node Libtool -@section Libtool - -Automake provides support for GNU Libtool (@pxref{Top, , Introduction, -libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary. -@xref{A Shared Library}. - - -@node Java -@section Java bytecode compilation (deprecated) - -@cindex @code{_JAVA} primary, defined -@cindex @code{JAVA} primary, defined -@cindex Primary variable, @code{JAVA} -@cindex Java to bytecode, compilation -@cindex Compilation of Java to bytecode - -Automake provides some minimal support for Java bytecode compilation with -the @code{JAVA} primary (in addition to the support for compiling Java to -native machine code; @pxref{Java Support with gcj}). Note however that -@emph{the interface and most features described here are deprecated}. -Future Automake releases will strive to provide a better and cleaner -interface, which however @emph{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 @code{JAVA} primary features are frozen and will no -longer be developed, not even to take bug fixes. - -Any @file{.java} files listed in a @code{_JAVA} variable will be -compiled with @code{JAVAC} at build time. By default, @file{.java} -files are not included in the distribution, you should use the -@code{dist_} prefix to distribute them. - -Here is a typical setup for distributing @file{.java} files and -installing the @file{.class} files resulting from their compilation. - -@c Keep in sync with primary-prefix-couples-documented-valid.sh -@example -javadir = $(datadir)/java -dist_java_JAVA = a.java b.java @dots{} -@end example - -@cindex @code{JAVA} restrictions -@cindex Restrictions for @code{JAVA} - -Currently Automake enforces the restriction that only one @code{_JAVA} -primary can be used in a given @file{Makefile.am}. The reason for this -restriction is that, in general, it isn't possible to know which -@file{.class} files were generated from which @file{.java} files, so -it would be impossible to know which files to install where. For -instance, a @file{.java} file can define multiple classes; the resulting -@file{.class} file names cannot be predicted without parsing the -@file{.java} file. - -There are a few variables that are used when compiling Java sources: - -@vtable @code -@item JAVAC -The name of the Java compiler. This defaults to @samp{javac}. - -@item JAVACFLAGS -The flags to pass to the compiler. This is considered to be a user -variable (@pxref{User Variables}). - -@item AM_JAVACFLAGS -More flags to pass to the Java compiler. This, and not -@code{JAVACFLAGS}, should be used when it is necessary to put Java -compiler flags into @file{Makefile.am}. - -@item JAVAROOT -The value of this variable is passed to the @option{-d} option to -@code{javac}. It defaults to @samp{$(top_builddir)}. - -@item CLASSPATH_ENV -This variable is a shell expression that is used to set the -@env{CLASSPATH} environment variable on the @code{javac} command line. -(In the future we will probably handle class path setting differently.) -@end vtable - - -@node Python -@section Python - -@cindex @code{_PYTHON} primary, defined -@cindex @code{PYTHON} primary, defined -@cindex Primary variable, @code{PYTHON} -@vindex _PYTHON - -Automake provides support for Python compilation with the -@code{PYTHON} primary. A typical setup is to call -@code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the -following in @file{Makefile.am}: - -@example -python_PYTHON = tree.py leave.py -@end example - -Any files listed in a @code{_PYTHON} variable will be byte-compiled -with @command{py-compile} at install time. @command{py-compile} -actually creates both standard (@file{.pyc}) and optimized -(@file{.pyo}) byte-compiled versions of the source files. Note that -because byte-compilation occurs at install time, any files listed in -@code{noinst_PYTHON} will not be compiled. Python source files are -included in the distribution by default, prepend @code{nodist_} (as in -@code{nodist_python_PYTHON}) to omit them. - -Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} -that will determine some Python-related directory variables (see -below). If you have called @code{AM_PATH_PYTHON} from -@file{configure.ac}, then you may use the variables -@c Keep in sync with primary-prefix-couples-documented-valid.sh -@code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source -files in your @file{Makefile.am}, depending on where you want your files -installed (see the definitions of @code{pythondir} and -@code{pkgpythondir} below). - -@defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found}, - @ovar{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: @code{AM_PATH_PYTHON} -will skip any Python interpreter that is older than @var{version}. -If an interpreter is found and satisfies @var{version}, then -@var{action-if-found} is run. Otherwise, @var{action-if-not-found} is -run. - -If @var{action-if-not-found} is not specified, as in the following -example, the default is to abort @command{configure}. - -@example -AM_PATH_PYTHON([2.2]) -@end example - -@noindent -This is fine when Python is an absolute requirement for the package. -If Python >= 2.5 was only @emph{optional} to the package, -@code{AM_PATH_PYTHON} could be called as follows. - -@example -AM_PATH_PYTHON([2.5],, [:]) -@end example - -If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is -called, then that will be the only Python interpreter that is tried. - -@code{AM_PATH_PYTHON} creates the following output variables based on -the Python installation found during configuration. -@end defmac - -@vtable @code -@item PYTHON -The name of the Python executable, or @samp{:} if no suitable -interpreter could be found. - -Assuming @var{action-if-not-found} is used (otherwise @file{./configure} -will abort if Python is absent), the value of @code{PYTHON} can be used -to setup a conditional in order to disable the relevant part of a build -as follows. - -@example -AM_PATH_PYTHON(,, [:]) -AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :]) -@end example - -@item PYTHON_VERSION -The Python version number, in the form @var{major}.@var{minor} -(e.g., @samp{2.5}). This is currently the value of -@samp{sys.version[:3]}. - -@item PYTHON_PREFIX -The string @samp{$@{prefix@}}. This term may be used in future work -that needs the contents of Python's @samp{sys.prefix}, but general -consensus is to always use the value from @command{configure}. - -@item PYTHON_EXEC_PREFIX -The string @samp{$@{exec_prefix@}}. This term may be used in future work -that needs the contents of Python's @samp{sys.exec_prefix}, but general -consensus is to always use the value from @command{configure}. - -@item PYTHON_PLATFORM -The canonical name used by Python to describe the operating system, as -given by @samp{sys.platform}. This value is sometimes needed when -building Python extensions. - -@item pythondir -The directory name for the @file{site-packages} subdirectory of the -standard Python install tree. - -@item pkgpythondir -This is the directory under @code{pythondir} that is named after the -package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided -as a convenience. - -@item 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: - -@c Keep in sync with primary-prefix-couples-documented-valid.sh -@example -pyexec_LTLIBRARIES = quaternion.la -quaternion_la_SOURCES = quaternion.c support.c support.h -quaternion_la_LDFLAGS = -avoid-version -module -@end example - -@item pkgpyexecdir -This is a convenience variable that is defined as -@samp{$(pyexecdir)/$(PACKAGE)}. -@end vtable - -All of these directory variables have values that start with either -@samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works -fine in @file{Makefiles}, but it makes these variables hard to use in -@file{configure}. This is mandated by the GNU coding standards, so -that the user can run @samp{make prefix=/foo install}. The Autoconf -manual has a section with more details on this topic -(@pxref{Installation Directory Variables, , Installation Directory -Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded -Install Paths}. - - -@node Documentation -@chapter Building documentation - -Currently Automake provides support for Texinfo and man pages. - -@menu -* Texinfo:: Texinfo -* Man Pages:: Man pages -@end menu - - -@node Texinfo -@section Texinfo - -@cindex @code{_TEXINFOS} primary, defined -@cindex @code{TEXINFOS} primary, defined -@cindex Primary variable, @code{TEXINFOS} -@cindex HTML output using Texinfo -@cindex PDF output using Texinfo -@cindex PS output using Texinfo -@cindex DVI output using Texinfo -@vindex _TEXINFOS -@vindex info_TEXINFOS - -If the current directory contains Texinfo source, you must declare it -with the @code{TEXINFOS} primary. Generally Texinfo files are converted -into info, and thus the @code{info_TEXINFOS} variable is most commonly used -here. Any Texinfo source file should have the @file{.texi} extension. -Automake also accepts @file{.txi} or @file{.texinfo} extensions, but their -use is discouraged now, and will elicit runtime warnings. - -Automake generates rules to build @file{.info}, @file{.dvi}, -@file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo -sources. Following the GNU Coding Standards, only the @file{.info} -files are built by @samp{make all} and installed by @samp{make -install} (unless you use @option{no-installinfo}, see below). -Furthermore, @file{.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 @file{.info} files are by default placed in @code{srcdir} -rather than in the @code{builddir}. This can be changed with the -@option{info-in-builddir} option. - -@trindex dvi -@trindex html -@trindex pdf -@trindex ps -@trindex install-dvi -@trindex install-html -@trindex install-pdf -@trindex install-ps -Other documentation formats can be built on request by @samp{make -dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they -can be installed with @samp{make install-dvi}, @samp{make install-ps}, -@samp{make install-pdf} and @samp{make install-html} explicitly. -@samp{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 @samp{-local} rules -(@pxref{Extending}). - -@cindex Texinfo flag, @code{VERSION} -@cindex Texinfo flag, @code{UPDATED} -@cindex Texinfo flag, @code{EDITION} -@cindex Texinfo flag, @code{UPDATED-MONTH} - -@cindex @code{VERSION} Texinfo flag -@cindex @code{UPDATED} Texinfo flag -@cindex @code{EDITION} Texinfo flag -@cindex @code{UPDATED-MONTH} Texinfo flag - -@cindex @file{mdate-sh} - -If the @file{.texi} file @code{@@include}s @file{version.texi}, then -that file will be automatically generated. The file @file{version.texi} -defines four Texinfo flags you can reference using -@code{@@value@{EDITION@}}, @code{@@value@{VERSION@}}, -@code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}. - -@table @code -@item EDITION -@itemx VERSION -Both of these flags hold the version number of your program. They are -kept separate for clarity. - -@item UPDATED -This holds the date the primary @file{.texi} file was last modified. - -@item UPDATED-MONTH -This holds the name of the month in which the primary @file{.texi} file -was last modified. -@end table - -The @file{version.texi} support requires the @command{mdate-sh} -script; this script is supplied with Automake and automatically -included when @command{automake} is invoked with the -@option{--add-missing} option. - -If you have multiple Texinfo files, and you want to use the -@file{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 @file{vers*.texi} just as an automatically -generated version file. - -Sometimes an info file actually depends on more than one @file{.texi} -file. For instance, in GNU Hello, @file{hello.texi} includes the file -@file{fdl.texi}. You can tell Automake about these dependencies using -the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it: -@vindex TEXINFOS -@vindex _TEXINFOS - -@example -info_TEXINFOS = hello.texi -hello_TEXINFOS = fdl.texi -@end example - -@cindex @file{texinfo.tex} - -By default, Automake requires the file @file{texinfo.tex} to appear in -the same directory as the @file{Makefile.am} file that lists the -@file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in -@file{configure.ac} (@pxref{Input, , Finding `configure' Input, -autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for -there. In both cases, @command{automake} then supplies @file{texinfo.tex} if -@option{--add-missing} is given, and takes care of its distribution. -However, if you set the @code{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 @option{no-texinfo.tex} can be used to eliminate the -requirement for the file @file{texinfo.tex}. Use of the variable -@code{TEXINFO_TEX} is preferable, however, because that allows the -@code{dvi}, @code{ps}, and @code{pdf} targets to still work. - -@cindex Option, @code{no-installinfo} -@cindex Target, @code{install-info} -@cindex @code{install-info} target -@cindex @code{no-installinfo} option - -@opindex no-installinfo -@trindex install-info - -Automake generates an @code{install-info} rule; some people apparently -use this. By default, info pages are installed by @samp{make -install}, so running @code{make install-info} is pointless. This can -be prevented via the @code{no-installinfo} option. In this case, -@file{.info} files are not installed by default, and user must -request this explicitly using @samp{make install-info}. - -@vindex AM_UPDATE_INFO_DIR -By default, @code{make install-info} and @code{make uninstall-info} -will try to run the @command{install-info} program (if available) to -update (or create/remove) the @file{@code{$@{infodir@}}/dir} index. -If this is undesired, it can be prevented by exporting the -@code{AM_UPDATE_INFO_DIR} variable to "@code{no}". - -The following variables are used by the Texinfo build rules. - -@vtable @code -@item MAKEINFO -The name of the program invoked to build @file{.info} files. This -variable is defined by Automake. If the @command{makeinfo} program is -found on the system then it will be used by default; otherwise -@command{missing} will be used instead. - -@item MAKEINFOHTML -The command invoked to build @file{.html} files. Automake -defines this to @samp{$(MAKEINFO) --html}. - -@item MAKEINFOFLAGS -User flags passed to each invocation of @samp{$(MAKEINFO)} and -@samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is -not expected to be defined in any @file{Makefile}; it can be used by -users to pass extra flags to suit their needs. - -@item AM_MAKEINFOFLAGS -@itemx AM_MAKEINFOHTMLFLAGS -Maintainer flags passed to each @command{makeinfo} invocation. Unlike -@code{MAKEINFOFLAGS}, these variables are meant to be defined by -maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is -passed to @code{makeinfo} when building @file{.info} files; and -@samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html} -files. - -@c Keep in sync with txinfo-many-output-formats.sh -For instance, the following setting can be used to obtain one single -@file{.html} file per manual, without node separators. -@example -AM_MAKEINFOHTMLFLAGS = --no-headers --no-split -@end example - -@code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}. -This means that defining @code{AM_MAKEINFOFLAGS} without defining -@code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info} -and @file{.html} files. - -@item TEXI2DVI -The name of the command that converts a @file{.texi} file into a -@file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships -with the Texinfo package. - -@item TEXI2PDF -The name of the command that translates a @file{.texi} file into a -@file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}. - -@item DVIPS -The name of the command that builds a @file{.ps} file out of a -@file{.dvi} file. This defaults to @samp{dvips}. - -@item TEXINFO_TEX - -If your package has Texinfo files in many directories, you can use the -variable @code{TEXINFO_TEX} to tell Automake where to find the canonical -@file{texinfo.tex} for your package. The value of this variable should -be the relative path from the current @file{Makefile.am} to -@file{texinfo.tex}: - -@example -TEXINFO_TEX = ../doc/texinfo.tex -@end example -@end vtable - - -@node Man Pages -@section Man Pages - -@cindex @code{_MANS} primary, defined -@cindex @code{MANS} primary, defined -@cindex Primary variable, @code{MANS} - -@vindex _MANS -@vindex man_MANS -A package can also include man pages (but see the GNU standards on this -matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man -pages are declared using the @code{MANS} primary. Generally the -@code{man_MANS} variable is used. Man pages are automatically installed in -the correct subdirectory of @code{mandir}, based on the file extension. - -File extensions such as @file{.1c} are handled by looking for the valid -part of the extension and using that to determine the correct -subdirectory of @code{mandir}. Valid section names are the digits -@samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}. - -Sometimes developers prefer to name a man page something like -@file{foo.man} in the source, and then rename it to have the correct -suffix, for example @file{foo.1}, when installing the file. Automake -also supports this mode. For a valid section named @var{section}, -there is a corresponding directory named @samp{man@var{section}dir}, -and a corresponding @code{_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: -@example -man1_MANS = rename.man thesame.1 alsothesame.1c -@end example - -@noindent -In this case, @file{rename.man} will be renamed to @file{rename.1} when -installed, but the other files will keep their names. - -@cindex Target, @code{install-man} -@cindex Option, @option{no-installman} -@cindex @code{install-man} target -@cindex @option{no-installman} option -@opindex no-installman -@trindex install-man - -By default, man pages are installed by @samp{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 -@option{no-installman} option will prevent the man pages from being -installed by default. The user can still explicitly install them via -@samp{make install-man}. - -For fast installation, with many files it is preferable to use -@samp{man@var{section}_MANS} over @samp{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 @code{dist_} prefix. For instance here is -how to distribute and install the two man pages of GNU @command{cpio} -(which includes both Texinfo documentation and man pages): - -@example -dist_man_MANS = cpio.1 mt.1 -@end example - -The @code{nobase_} prefix is meaningless for man pages and is -disallowed. - -@vindex notrans_ -@cindex @code{notrans_} prefix -@cindex Man page renaming, avoiding -@cindex Avoiding man page renaming - -Executables and manpages may be renamed upon installation -(@pxref{Renaming}). For manpages this can be avoided by use of the -@code{notrans_} prefix. For instance, suppose an executable @samp{foo} -allowing to access a library function @samp{foo} from the command line. -The way to avoid renaming of the @file{foo.3} manpage is: - -@example -man_MANS = foo.1 -notrans_man_MANS = foo.3 -@end example - -@cindex @code{notrans_} and @code{dist_} or @code{nodist_} -@cindex @code{dist_} and @code{notrans_} -@cindex @code{nodist_} and @code{notrans_} - -@samp{notrans_} must be specified first when used in conjunction with -either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution -Control}). For instance: - -@example -notrans_dist_man3_MANS = bar.3 -@end example - -@node Install -@chapter What Gets Installed - -@cindex Installation support -@cindex @samp{make install} support - -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 @samp{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 -@end menu - -@node Basics of Installation -@section 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. - -@example -bin_PROGRAMS = hello subdir/goodbye -@end example - -In this example, both @samp{hello} and @samp{goodbye} will be installed -in @samp{$(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 @code{nobase_} prefix to -suppress the base name step. For example: - -@example -nobase_include_HEADERS = stdio.h sys/types.h -@end example - -@noindent -will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h} -in @samp{$(includedir)/sys}. - -For most file types, Automake will install multiple files at once, while -avoiding command line length issues (@pxref{Length Limitations}). Since -some @command{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 @samp{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). - - -@node The Two Parts of Install -@section The Two Parts of Install - -Automake generates separate @code{install-data} and @code{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. @code{install-exec} installs -platform-dependent files, and @code{install-data} installs -platform-independent files. The @code{install} target depends on both -of these targets. While Automake tries to automatically segregate -objects into the correct category, the @file{Makefile.am} author is, in -the end, responsible for making sure this is done correctly. -@trindex install-data -@trindex install-exec -@trindex install -@cindex Install, two parts of - -Variables using the standard directory prefixes @samp{data}, -@samp{info}, @samp{man}, @samp{include}, @samp{oldinclude}, -@samp{pkgdata}, or @samp{pkginclude} are installed by -@code{install-data}. - -Variables using the standard directory prefixes @samp{bin}, -@samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate}, -@samp{lib}, or @samp{pkglib} are installed by @code{install-exec}. - -For instance, @code{data_DATA} files are installed by @code{install-data}, -while @code{bin_PROGRAMS} files are installed by @code{install-exec}. - -Any variable using a user-defined directory prefix with -@samp{exec} in the name (e.g., -@c Keep in sync with primary-prefix-couples-documented-valid.sh -@code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All -other user-defined prefixes are installed by @code{install-data}. - -@node Extending Installation -@section Extending Installation - -It is possible to extend this mechanism by defining an -@code{install-exec-local} or @code{install-data-local} rule. If these -rules exist, they will be run at @samp{make install} time. These -rules can do almost anything; care is required. -@trindex install-exec-local -@trindex install-data-local - -Automake also supports two install hooks, @code{install-exec-hook} and -@code{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. @xref{Extending}, for some examples. -@cindex Install hook - -@node Staged Installs -@section Staged Installs - -@vindex DESTDIR -Automake generates support for the @code{DESTDIR} variable in all -install rules. @code{DESTDIR} is used during the @samp{make install} -step to relocate install objects into a staging area. Each object and -path is prefixed with the value of @code{DESTDIR} before being copied -into the install area. Here is an example of typical DESTDIR usage: - -@example -mkdir /tmp/staging && -make DESTDIR=/tmp/staging install -@end example - -The @command{mkdir} command avoids a security problem if the attacker -creates a symbolic link from @file{/tmp/staging} to a victim area; -then @command{make} places install objects in a directory tree built under -@file{/tmp/staging}. If @file{/gnu/bin/foo} and -@file{/gnu/share/aclocal/foo.m4} are to be installed, the above command -would install @file{/tmp/staging/gnu/bin/foo} and -@file{/tmp/staging/gnu/share/aclocal/foo.m4}. - -This feature is commonly used to build install images and packages -(@pxref{DESTDIR}). - -Support for @code{DESTDIR} is implemented by coding it directly into -the install rules. If your @file{Makefile.am} uses a local install -rule (e.g., @code{install-exec-local}) or an install hook, then you -must write that code to respect @code{DESTDIR}. - -@xref{Makefile Conventions, , , standards, The GNU Coding Standards}, -for another usage example. - -@node Install Rules for the User -@section Install Rules for the User - -Automake also generates rules for targets @code{uninstall}, -@code{installdirs}, and @code{install-strip}. -@trindex uninstall -@trindex installdirs -@trindex install-strip - -Automake supports @code{uninstall-local} and @code{uninstall-hook}. -There is no notion of separate uninstalls for ``exec'' and ``data'', as -these features would not provide additional functionality. - -Note that @code{uninstall} is not meant as a replacement for a real -packaging tool. - - -@node Clean -@chapter What Gets Cleaned - -@cindex @samp{make clean} support - -The GNU Makefile Standards specify a number of different clean rules. -@xref{Standard Targets, , Standard Targets for Users, standards, -The GNU Coding Standards}. - -Generally the files that can be cleaned are determined automatically by -Automake. Of course, Automake also recognizes some variables that can -be defined to specify additional files to clean. These variables are -@code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and -@code{MAINTAINERCLEANFILES}. -@vindex MOSTLYCLEANFILES -@vindex CLEANFILES -@vindex DISTCLEANFILES -@vindex MAINTAINERCLEANFILES - -@trindex mostlyclean-local -@trindex clean-local -@trindex distclean-local -@trindex maintainer-clean-local -When cleaning involves more than deleting some hard-coded list of -files, it is also possible to supplement the cleaning rules with your -own commands. Simply define a rule for any of the -@code{mostlyclean-local}, @code{clean-local}, @code{distclean-local}, -or @code{maintainer-clean-local} targets (@pxref{Extending}). A common -case is deleting a directory, for instance, a directory created by the -test suite: - -@example -clean-local: - -rm -rf testSubDir -@end example - -Since @command{make} allows only one set of rules for a given target, -a more extensible way of writing this is to use a separate target -listed as a dependency: - -@example -clean-local: clean-local-check -.PHONY: clean-local-check -clean-local-check: - -rm -rf testSubDir -@end example - -As the GNU Standards aren't always explicit as to which files should -be removed by which rule, we've adopted a heuristic that we believe -was first formulated by Fran@,{c}ois Pinard: - -@itemize @bullet -@item -If @command{make} built it, and it is commonly something that one would -want to rebuild (for instance, a @file{.o} file), then -@code{mostlyclean} should delete it. - -@item -Otherwise, if @command{make} built it, then @code{clean} should delete it. - -@item -If @command{configure} built it, then @code{distclean} should delete it. - -@item -If the maintainer built it (for instance, a @file{.info} file), then -@code{maintainer-clean} should delete it. However -@code{maintainer-clean} should not delete anything that needs to exist -in order to run @samp{./configure && make}. -@end itemize - -We recommend that you follow this same set of heuristics in your -@file{Makefile.am}. - - -@node Dist -@chapter What Goes in a Distribution - -@menu -* Basics of Distribution:: Files distributed by default -* Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes -* The dist Hook:: A target for last-minute distribution changes -* Checking the Distribution:: @samp{make distcheck} explained -* The Types of Distributions:: A variety of formats and compression methods -@end menu - -@node Basics of Distribution -@section Basics of Distribution - -@cindex @samp{make dist} - -@vindex PACKAGE -@vindex VERSION -@trindex dist -The @code{dist} rule in the generated @file{Makefile.in} can be used -to generate a gzipped @code{tar} file and other flavors of archive for -distribution. The file is named based on the @code{PACKAGE} and -@code{VERSION} variables automatically defined by either the -@code{AC_INIT} invocation or by a @emph{deprecated} two-arguments -invocation of the @code{AM_INIT_AUTOMAKE} macro (see @ref{Public Macros} -for how these variables get their values, from either defaults or explicit -values -- it's slightly trickier than one would expect). -More precisely the gzipped @code{tar} file is named -@samp{$@{PACKAGE@}-$@{VERSION@}.tar.gz}. -@vindex GZIP_ENV -You can use the @command{make} variable @code{GZIP_ENV} to control how gzip -is run. The default setting is @option{--best}. - -@cindex @code{m4_include}, distribution -@cindex @code{include}, distribution -@acindex m4_include -@cmindex include -For the most part, the files to distribute are automatically found by -Automake: all source files are automatically included in a distribution, -as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also -has a built-in list of commonly used files that are automatically -included if they are found in the current directory (either physically, -or as the target of a @file{Makefile.am} rule); this list is printed by -@samp{automake --help}. Note that some files in this list are actually -distributed only if other certain conditions hold (for example, -@c Keep in sync with autodist-config-headers.sh -the @file{config.h.top} and @file{config.h.bot} files are automatically -distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used -in @file{configure.ac}). Also, files that are read by @command{configure} -(i.e.@: the source files corresponding to the files specified in various -Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are -automatically distributed. Files included in a @file{Makefile.am} (using -@code{include}) or in @file{configure.ac} (using @code{m4_include}), and -helper scripts installed with @samp{automake --add-missing} are also -distributed. - -@vindex EXTRA_DIST -Still, sometimes there are files that must be distributed, but which -are not covered in the automatic rules. These files should be listed in -the @code{EXTRA_DIST} variable. You can mention files from -subdirectories in @code{EXTRA_DIST}. - -You can also mention a directory in @code{EXTRA_DIST}; in this case the -entire directory will be recursively copied into the distribution. -Please note that this will also copy @emph{everything} in the directory, -including, e.g., Subversion's @file{.svn} private directories or CVS/RCS -version control files; thus we recommend against using this feature -as-is. However, you can use the @code{dist-hook} feature to -ameliorate the problem; @pxref{The dist Hook}. - -@vindex SUBDIRS -@vindex DIST_SUBDIRS -If you define @code{SUBDIRS}, Automake will recursively include the -subdirectories in the distribution. If @code{SUBDIRS} is defined -conditionally (@pxref{Conditionals}), Automake will normally include -all directories that could possibly appear in @code{SUBDIRS} in the -distribution. If you need to specify the set of directories -conditionally, you can set the variable @code{DIST_SUBDIRS} to the -exact list of subdirectories to include in the distribution -(@pxref{Conditional Subdirectories}). - - -@node Fine-grained Distribution Control -@section Fine-grained Distribution Control - -@vindex dist_ -@vindex nodist_ -Sometimes you need tighter control over what does @emph{not} go into the -distribution; for instance, you might have source files that are -generated and that you do not want to distribute. In this case -Automake gives fine-grained control using the @code{dist} and -@code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be -prefixed with @code{dist_} to add the listed files to the distribution. -Similarly, @code{nodist_} can be used to omit the files from the -distribution. - -As an example, here is how you would cause some data to be distributed -while leaving some source code out of the distribution: - -@example -dist_data_DATA = distribute-this -bin_PROGRAMS = foo -nodist_foo_SOURCES = do-not-distribute.c -@end example - -@node The dist Hook -@section The dist Hook - -@trindex dist-hook - -Occasionally it is useful to be able to change the distribution before -it is packaged up. If the @code{dist-hook} rule exists, it is run -after the distribution directory is filled, but before the actual -distribution archives are created. One way to use this is for -removing unnecessary files that get recursively included by specifying -a directory in @code{EXTRA_DIST}: - -@example -EXTRA_DIST = doc -dist-hook: - rm -rf `find $(distdir)/doc -type d -name .svn` -@end example - -@c The caveats described here should be documented in 'disthook.sh'. -@noindent -Note that the @code{dist-hook} recipe shouldn't assume that the regular -files in the distribution directory are writable; this might not be the -case if one is packaging from a read-only source tree, or when a -@code{make distcheck} is being done. For similar reasons, the recipe -shouldn't assume that the subdirectories put into the distribution -directory as effect of having them listed in @code{EXTRA_DIST} are -writable. So, if the @code{dist-hook} recipe wants to modify the -content of an existing file (or @code{EXTRA_DIST} subdirectory) in the -distribution directory, it should explicitly to make it writable first: - -@example -EXTRA_DIST = README doc -dist-hook: - chmod u+w $(distdir)/README $(distdir)/doc - echo "Distribution date: `date`" >> README - rm -f $(distdir)/doc/HACKING -@end example - -@vindex distdir -@vindex top_distdir -Two variables that come handy when writing @code{dist-hook} rules are -@samp{$(distdir)} and @samp{$(top_distdir)}. - -@samp{$(distdir)} points to the directory where the @code{dist} rule -will copy files from the current directory before creating the -tarball. If you are at the top-level directory, then @samp{distdir = -$(PACKAGE)-$(VERSION)}. When used from subdirectory named -@file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}. -@samp{$(distdir)} can be a relative or absolute path, do not assume -any form. - -@samp{$(top_distdir)} always points to the root directory of the -distributed tree. At the top-level it's equal to @samp{$(distdir)}. -In the @file{foo/} subdirectory -@samp{top_distdir = ../$(PACKAGE)-$(VERSION)}. -@samp{$(top_distdir)} too can be a relative or absolute path. - -Note that when packages are nested using @code{AC_CONFIG_SUBDIRS} -(@pxref{Subpackages}), then @samp{$(distdir)} and -@samp{$(top_distdir)} are relative to the package where @samp{make -dist} was run, not to any sub-packages involved. - -@node Checking the Distribution -@section Checking the Distribution - -@cindex @samp{make distcheck} -@trindex distcheck -Automake also generates a @code{distcheck} rule that can be of help -to ensure that a given distribution will actually work. Simplifying -a bit, we can say this rule first makes a distribution, and then, -@emph{operating from it}, takes the following steps: -@itemize -@item -tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the -@code{srcdir} and all its content made @emph{read-only}; -@item -runs the test suite (with @command{make check}) on this fresh build; -@item -installs the package in a temporary directory (with @command{make -install}), and tries runs the test suite on the resulting installation -(with @command{make installcheck}); -@item -checks that the package can be correctly uninstalled (by @command{make -uninstall}) and cleaned (by @code{make distclean}); -@item -finally, makes another tarball to ensure the distribution is -self-contained. -@end itemize - -All of these actions are performed in a temporary directory. Please -note that the exact location and the exact structure of such a directory -(where the read-only 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 reply on it. - -@vindex AM_DISTCHECK_CONFIGURE_FLAGS -@vindex DISTCHECK_CONFIGURE_FLAGS -@subheading DISTCHECK_CONFIGURE_FLAGS -Building the package involves running @samp{./configure}. If you need -to supply additional flags to @command{configure}, define them in the -@code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level -@file{Makefile.am}. The user can still extend or override the flags -provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable, -on the command line when invoking @command{make}. -@c See automake bug#14991 for more details about how the following holds. -It's worth noting that @command{make distcheck} needs complete control -over the @command{configure} options @option{--srcdir} and -@option{--prefix}, so those options cannot be overridden by -@code{AM_DISTCHECK_CONFIGURE_FLAGS} nor by -@code{DISTCHECK_CONFIGURE_FLAGS}. - -Also note that developers are encouraged to strive to make their code -buildable without requiring any special configure option; thus, in -general, you shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. -However, there might be few scenarios in which the use of this variable -is justified. -GNU @command{m4} offers an example. GNU @command{m4} configures by -default with its experimental and seldom used "changeword" feature -disabled; so in its case it is useful to have @command{make distcheck} -run configure with the @option{--with-changeword} option, to ensure that -the code for changeword support still compiles correctly. -GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS} -variable to stress-test the use of @option{--program-prefix=g}, since at -one point the @command{m4} build system had a bug where @command{make -installcheck} was wrongly assuming it could blindly test "@command{m4}", -rather than the just-installed "@command{gm4}". - -@trindex distcheck-hook -@subheading distcheck-hook -If the @code{distcheck-hook} rule is defined in your top-level -@file{Makefile.am}, then it will be invoked by @code{distcheck} after -the new distribution has been unpacked, but before the unpacked copy -is configured and built. Your @code{distcheck-hook} can do almost -anything, though as always caution is advised. Generally this hook is -used to check for potential distribution errors not caught by the -standard mechanism. Note that @code{distcheck-hook} as well as -@code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS} -are not honored in a subpackage @file{Makefile.am}, but the flags from -@code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS} -are passed down to the @command{configure} script of the subpackage. - -@cindex @samp{make distcleancheck} -@trindex distcleancheck -@vindex DISTCLEANFILES -@vindex distcleancheck_listfiles - -@subheading distcleancheck -Speaking of potential distribution errors, @code{distcheck} also -ensures that the @code{distclean} rule actually removes all built -files. This is done by running @samp{make distcleancheck} at the end of -the @code{VPATH} build. By default, @code{distcleancheck} will run -@code{distclean} and then make sure the build tree has been emptied by -running @samp{$(distcleancheck_listfiles)}. Usually this check will -find generated files that you forgot to add to the @code{DISTCLEANFILES} -variable (@pxref{Clean}). - -The @code{distcleancheck} behavior should be OK for most packages, -otherwise you have the possibility to override the definition of -either the @code{distcleancheck} rule, or the -@samp{$(distcleancheck_listfiles)} variable. For instance, to disable -@code{distcleancheck} completely, add the following rule to your -top-level @file{Makefile.am}: - -@example -distcleancheck: - @@: -@end example - -If you want @code{distcleancheck} to ignore built files that have not -been cleaned because they are also part of the distribution, add the -following definition instead: - -@c Keep in sync with distcleancheck.sh -@example -distcleancheck_listfiles = \ - find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \ - sh '@{@}' ';' -@end example - -The above definition is not the default because it's usually an error if -your Makefiles cause some distributed files to be rebuilt when the user -build the package. (Think about the user missing the tool required to -build the file; or if the required tool is built by your package, -consider the cross-compilation case where it can't be run.) There is -an entry in the FAQ about this (@pxref{Errors with distclean}), make -sure you read it before playing with @code{distcleancheck_listfiles}. - -@cindex @samp{make distuninstallcheck} -@trindex distuninstallcheck -@vindex distuninstallcheck_listfiles - -@subheading distuninstallcheck -@code{distcheck} also checks that the @code{uninstall} rule works -properly, both for ordinary and @code{DESTDIR} builds. It does this -by invoking @samp{make uninstall}, and then it checks the install tree -to see if any files are left over. This check will make sure that you -correctly coded your @code{uninstall}-related rules. - -By default, the checking is done by the @code{distuninstallcheck} rule, -and the list of files in the install tree is generated by -@samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is -a shell command to run that prints the list of files to stdout). - -Either of these can be overridden to modify the behavior of -@code{distcheck}. For instance, to disable this check completely, you -would write: - -@example -distuninstallcheck: - @@: -@end example - -@node The Types of Distributions -@section The Types of Distributions - -Automake generates rules to provide archives of the project for -distributions in various formats. Their targets are: - -@table @asis -@item @code{dist-gzip} -Generate a @samp{gzip} tar archive of the distribution. This is the -only format enabled by default. -@trindex dist-gzip - -@vindex BZIP2 -@item @code{dist-bzip2} -Generate a @samp{bzip2} tar archive of the distribution. bzip2 archives -are frequently smaller than gzipped archives. -By default, this rule makes @samp{bzip2} use a compression option of @option{-9}. -To make it use a different one, set the @env{BZIP2} environment variable. -For example, @samp{make dist-bzip2 BZIP2=-7}. -@trindex dist-bzip2 - -@item @code{dist-lzip} -Generate an @samp{lzip} tar archive of the distribution. @command{lzip} -archives are frequently smaller than @command{bzip2}-compressed archives. -@trindex dist-lzip - -@vindex XZ_OPT -@item @code{dist-xz} -Generate an @samp{xz} tar archive of the distribution. @command{xz} -archives are frequently smaller than @command{bzip2}-compressed archives. -By default, this rule makes @samp{xz} use a compression option of -@option{-e}. To make it use a different one, set the @env{XZ_OPT} -environment variable. For example, run this command to use the -default compression ratio, but with a progress indicator: -@samp{make dist-xz XZ_OPT=-ve}. -@trindex dist-xz - -@item @code{dist-zip} -Generate a @samp{zip} archive of the distribution. -@trindex dist-zip - -@end table - -The rule @code{dist} (and its historical synonym @code{dist-all}) -will create archives in all the enabled formats (@pxref{List of -Automake options} for how to change this list). By default, only -the @code{dist-gzip} target is hooked to @code{dist}. - - -@node Tests -@chapter Support for test suites - -@cindex Test suites -@cindex @code{make check} -@trindex check - -Automake can generate code to handle two kinds of test suites. One is -based on integration with the @command{dejagnu} framework. The other -(and most used) form is based on the use of generic test scripts, and -its activation is triggered by the definition of the special @code{TESTS} -variable. This second form allows for various degrees of sophistication -and customization; in particular, it allows for concurrent execution -of test scripts, use of established test protocols such as TAP, and -definition of custom test drivers and test runners. - -@noindent -In either case, the testsuite is invoked via @samp{make check}. - -@menu -* Generalities about Testing:: Concepts and terminology about testing -* Simple Tests:: Listing test scripts in @code{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 @command{dejagnu} testing framework -* Install Tests:: Running tests on installed packages -@end menu - -@node Generalities about Testing -@section Generalities about Testing - -The purpose of testing is to determine whether a program or system behaves -as expected (e.g., known inputs produce the expected outputs, error -conditions are correctly handled or reported, and older bugs do not -resurface). - -@cindex test case -The minimal unit of testing is usually called @emph{test case}, or simply -@emph{test}. How a test case is defined or delimited, and even what -exactly @emph{constitutes} a test case, depends heavily on the testing -paradigm and/or framework in use, so we won't attempt any more precise -definition. The set of the test cases for a given program or system -constitutes its @emph{testsuite}. - -@cindex test harness -@cindex testsuite harness -A @emph{test harness} (also @emph{testsuite harness}) is a program or -software component that executes all (or part of) the defined test cases, -analyzes their outcomes, and report or register these outcomes -appropriately. Again, the details of how this is accomplished (and how -the developer and user can influence it or interface with it) varies -wildly, and we'll attempt no precise definition. - -@cindex test pass -@cindex test failure -A test is said to @emph{pass} when it can determine that the condition or -behaviour it means to verify holds, and is said to @emph{fail} when it can -determine that such condition of behaviour does @emph{not} hold. - -@cindex test skip -Sometimes, tests can rely on non-portable tools or prerequisites, or -simply make no sense on a given system (for example, a test checking a -Windows-specific feature makes no sense on a GNU/Linux system). In this -case, accordingly to the definition above, the tests can neither be -considered passed nor failed; instead, they are @emph{skipped} -- i.e., -they are not run, or their result is anyway ignored for what concerns -the count of failures an successes. Skips are usually explicitly -reported though, so that the user will be aware that not all of the -testsuite has really run. - -@cindex xfail -@cindex expected failure -@cindex expected test failure -@cindex xpass -@cindex unexpected pass -@cindex unexpected test pass -It's not uncommon, especially during early development stages, that some -tests fail for known reasons, and that the developer doesn't want to -tackle these failures immediately (this is especially true when the -failing tests deal with corner cases). In this situation, the better -policy is to declare that each of those failures is an @emph{expected -failure} (or @emph{xfail}). In case a test that is expected to fail ends -up passing instead, many testing environments will flag the result as a -special kind of failure called @emph{unexpected pass} (or @emph{xpass}). - -@cindex hard error -@cindex Distinction between errors and failures in testsuites -Many testing environments and frameworks distinguish between test failures -and hard errors. As we've seen, a test failure happens when some invariant -or expected behaviour of the software under test is not met. An @emph{hard -error} happens when e.g., the set-up of a test case scenario fails, or when -some other unexpected or highly undesirable condition is encountered (for -example, the program under test experiences a segmentation fault). - -@node Simple Tests -@section Simple Tests - -@menu -* Scripts-based Testsuites:: Automake-specific concepts and terminology -* Serial Test Harness:: Older (and discouraged) serial test harness -* Parallel Test Harness:: Generic concurrent test harness -@end menu - -@node Scripts-based Testsuites -@subsection Scripts-based Testsuites - -If the special variable @code{TESTS} is defined, its value is taken to be -a list of programs or scripts to run in order to do the testing. Under -the appropriate circumstances, it's possible for @code{TESTS} to list -also data files to be passed to one or more test scripts defined by -different means (the so-called ``log compilers'', @pxref{Parallel Test -Harness}). - -Test scripts can be executed serially or concurrently. Automake supports -both these kinds of test execution, with the parallel test harness being -the default. The concurrent test harness relies on the concurrence -capabilities (if any) offered by the underlying @command{make} -implementation, and can thus only be as good as those are. - -By default, only the exit statuses of the test scripts are considered when -determining the testsuite outcome. But Automake allows also the use of -more complex test protocols, either standard (@pxref{Using the TAP test -protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can't -enable such protocols when the serial harness is used, though. -In the rest of this section we are going to concentrate mostly on -protocol-less tests, since we cover test protocols in a later section -(again, @pxref{Custom Test Drivers}). - -@cindex Exit status 77, special interpretation -@cindex Exit status 99, special interpretation -When no test protocol is in use, an exit status of 0 from a test script will -denote a success, an exit status of 77 a skipped test, an exit status of 99 -an hard error, and any other exit status will denote a failure. - -@cindex Tests, expected failure -@cindex Expected test failure -@vindex XFAIL_TESTS -@vindex DISABLE_HARD_ERRORS -@cindex Disabling hard errors -You may define the variable @code{XFAIL_TESTS} to a list of tests -(usually a subset of @code{TESTS}) that are expected to fail; this will -effectively reverse the result of those tests (with the provision that -skips and hard errors remain untouched). You may also instruct the -testsuite harness to treat hard errors like simple failures, by defining -the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value. - -Note however that, for tests based on more complex test protocols, -the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS} -might change, or they might even have no effect at all (for example, -@c Keep this in sync with tap-no-disable-hard-errors.sh -in tests using TAP, there is no way to disable hard errors, and the -@code{DISABLE_HARD_ERRORS} variable has no effect on them). - -@anchor{Testsuite progress on console} -@cindex Testsuite progress on console -The result of each test case run by the scripts in @code{TESTS} will be -printed on standard output, along with the test name. For test protocols -that allow more test cases per test script (such as TAP), a number, -identifier and/or brief description specific for the single test case is -expected to be printed in addition to the name of the test script. The -possible results (whose meanings should be clear from the previous -@ref{Generalities about Testing}) are @code{PASS}, @code{FAIL}, -@code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an -example of output from an hypothetical testsuite that uses both plain -and TAP tests: -@c Keep in sync with tap-doc.sh -@example -PASS: foo.sh -PASS: zardoz.tap 1 - Daemon started -PASS: zardoz.tap 2 - Daemon responding -SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted -PASS: zardoz.tap 4 - Daemon stopped -SKIP: bar.sh -PASS: mu.tap 1 -XFAIL: mu.tap 2 # TODO frobnication not yet implemented -@end example - -@noindent -A testsuite summary (expected to report at least the number of run, -skipped and failed tests) will be printed at the end of the testsuite -run. - -@anchor{Simple tests and color-tests} -@vindex AM_COLOR_TESTS -@cindex Colorized testsuite output -If the standard output is connected to a capable terminal, then the test -results and the summary are colored appropriately. The developer and the -user can disable colored output by setting the @command{make} variable -@samp{AM_COLOR_TESTS=no}; the user can in addition force colored output -even without a connecting terminal with @samp{AM_COLOR_TESTS=always}. -It's also worth noting that some @command{make} implementations, -when used in parallel mode, have slightly different semantics -(@pxref{Parallel make,,, autoconf, The Autoconf Manual}), which can -break the automatic detection of a connection to a capable terminal. -If this is the case, the user will have to resort to the use of -@samp{AM_COLOR_TESTS=always} in order to have the testsuite output -colorized. - -Test programs that need data files should look for them in @code{srcdir} -(which is both a make variable and an environment variable made available -to the tests), so that they work when building in a separate directory -(@pxref{Build Directories, , Build Directories , autoconf, -The Autoconf Manual}), and in particular for the @code{distcheck} rule -(@pxref{Checking the Distribution}). - -@vindex TESTS -@vindex TESTS_ENVIRONMENT -@vindex AM_TESTS_ENVIRONMENT -The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can -be used to run initialization code and set environment variables for the -test scripts. The former variable is developer-reserved, and can be -defined in the @file{Makefile.am}, while the latter is reserved for the -user, which can employ it to extend or override the settings in the -former; for this to work portably, however, the contents of a non-empty -@code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon. - -@vindex AM_TESTS_FD_REDIRECT -The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file -descriptor redirections for the test scripts. One might think that -@code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience -has shown that doing so portably is practically impossible. The main -hurdle is constituted by Korn shells, which usually set the close-on-exec -flag on file descriptors opened with the @command{exec} builtin, thus -rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;} -ineffectual. This issue also affects some Bourne shells, such as the -HP-UX's @command{/bin/sh}, - -@c Keep in sync with tests-environment-backcompat.sh -@example -AM_TESTS_ENVIRONMENT = \ -## Some environment initializations are kept in a separate shell -## file 'tests-env.sh', which can make it easier to also run tests -## from the command line. - . $(srcdir)/tests-env.sh; \ -## On Solaris, prefer more POSIX-compliant versions of the standard -## tools by default. - if test -d /usr/xpg4/bin; then \ - PATH=/usr/xpg4/bin:$$PATH; export PATH; \ - fi; -@c $$ restore font-lock -## With this, the test scripts will be able to print diagnostic -## messages to the original standard error stream, even if the test -## driver redirects the stderr of the test scripts to a log file -## before executing them. -AM_TESTS_FD_REDIRECT = 9>&2 -@end example - -@noindent -Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and -implementation reasons, @emph{not} supported by the serial harness -(@pxref{Serial Test Harness}). - -Automake ensures that each file listed in @code{TESTS} is built before -it is run; you can list both source and derived programs (or scripts) -in @code{TESTS}; the generated rule will look both in @code{srcdir} and -@file{.}. For instance, you might want to run a C program as a test. -To do this you would list its name in @code{TESTS} and also in -@code{check_PROGRAMS}, and then specify it as you would any other -program. - -Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES}, -@code{check_LTLIBRARIES}...) are only built during @code{make check}, -not during @code{make all}. You should list there any program needed -by your tests that does not need to be built by @code{make all}. Note -that @code{check_PROGRAMS} are @emph{not} automatically added to -@code{TESTS} because @code{check_PROGRAMS} usually lists programs used -by the tests, not the tests themselves. Of course you can set -@code{TESTS = $(check_PROGRAMS)} if all your programs are test cases. - -@node Serial Test Harness -@subsection Older (and discouraged) serial test harness -@cindex @option{serial-tests}, Using - -First, note that today the use of this harness is strongly discouraged in -favour of the parallel test harness (@pxref{Parallel Test Harness}). -Still, there are @emph{few} situations when the advantages offered by -the parallel harness are irrelevant, and when test concurrency can -even cause tricky problems. In those cases, it might make sense to -still use the serial harness, for simplicity and reliability (we still -suggest trying to give the parallel harness a shot though). - -The serial test harness is enabled by the Automake option -@option{serial-tests}. It operates by simply running the tests serially, -one at the time, without any I/O redirection. It's up to the user to -implement logging of tests' output, if that's required or desired. - -For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT} -variable is @emph{not} supported by this harness (it will be silently -ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be -considered a developer-reserved variable. This is done so that, when -using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an -invocation of an interpreter through which the tests are to be run. -For instance, the following setup may be used to run tests with Perl: - -@example -TESTS_ENVIRONMENT = $(PERL) -Mstrict -w -TESTS = foo.pl bar.pl baz.pl -@end example - -@noindent -It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed -here would be @emph{invalid} with the parallel harness. That harness -provides a more elegant way to achieve the same effect, with the further -benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user -(@pxref{Parallel Test Harness}). - -Another, less serious limit of the serial harness is that it doesn't -really distinguish between simple failures and hard errors; this is -due to historical reasons only, and might be fixed in future Automake -versions. - -@node Parallel Test Harness -@subsection Parallel Test Harness - -By default, Automake generated a parallel (concurrent) test harness. It -features automatic collection of the test scripts output in @file{.log} -files, concurrent execution of tests with @code{make -j}, specification -of inter-test dependencies, lazy reruns of tests that have not completed -in a prior run, and hard errors for exceptional failures. - -@anchor{Basics of test metadata} -@vindex TEST_SUITE_LOG -@vindex TESTS -@cindex @file{.log} files -@cindex @file{.trs} files -@cindex test metadata -The parallel test harness operates by defining a set of @command{make} -rules that run the test scripts listed in @code{TESTS}, and, for each -such script, save its output in a corresponding @file{.log} file and -its results (and other ``metadata'', @pxref{API for Custom Test Drivers}) -in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file. -@c We choose the '.trs' extension also because, at the time of writing, -@c it isn't already used for other significant purposes; see e.g.: -@c - http://filext.com/file-extension/trs -@c - http://www.file-extensions.org/search/?searchstring=trs -The @file{.log} file will contain all the output emitted by the test on -its standard output and its standard error. The @file{.trs} file will -contain, among the other things, the results of the test cases run by -the script. - -The parallel test harness will also create a summary log file, -@code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires -a @file{.log} suffix. This file depends upon all the @file{.log} and -@file{.trs} files created for the test scripts listed in @code{TESTS}. - -@vindex VERBOSE -As with the serial harness above, by default one status line is printed -per completed test, and a short summary after the suite has completed. -However, standard output and standard error of the test are redirected -to a per-test log file, so that parallel execution does not produce -intermingled output. The output from failed tests is collected in the -@file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this -file is output after the summary. - -@vindex TEST_EXTENSIONS -@vindex TEST_LOGS -Each couple of @file{.log} and @file{.trs} files is created when the -corresponding test has completed. The set of log files is listed in -the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS}, -with the executable extension if any (@pxref{EXEEXT}), as well as any -suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended. -Results are undefined if a test file name ends in several concatenated -suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be -overridden by the user, in which case any extension listed in it must be -constituted by a dot, followed by a non-digit alphabetic character, -followed by any number of alphabetic characters. -@c Keep in sync with test-extensions.sh -For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions, -while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not. - -@cindex Configure substitutions in @code{TESTS} -It is important to note that, due to current limitations (unlikely to be -lifted), configure substitutions in the definition of @code{TESTS} can -only work if they will expand to a list of tests that have a suffix listed -in @code{TEST_EXTENSIONS}. - -@vindex _LOG_COMPILE -@vindex _LOG_COMPILER -@vindex _LOG_FLAGS -@vindex LOG_COMPILE -@vindex LOG_COMPILER -@vindex LOG_FLAGS -@vindex @var{ext}_LOG_COMPILE -@vindex @var{ext}_LOG_COMPILER -@vindex @var{ext}_LOG_FLAGS -@vindex AM_@var{ext}_LOG_FLAGS -@vindex AM_LOG_FLAGS -For tests that match an extension @code{.@var{ext}} listed in -@code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using -the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case -extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow -the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause -all tests with this extension to be called with this runner. For all -tests without a registered extension, the variables @code{LOG_COMPILER}, -@code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example, - -@c Keep in sync with parallel-tests-log-compiler-example.sh -@example -TESTS = foo.pl bar.py baz -TEST_EXTENSIONS = .pl .py -PL_LOG_COMPILER = $(PERL) -AM_PL_LOG_FLAGS = -w -PY_LOG_COMPILER = $(PYTHON) -AM_PY_LOG_FLAGS = -v -LOG_COMPILER = ./wrapper-script -AM_LOG_FLAGS = -d -@end example - -@noindent -will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py}, -and @samp{./wrapper-script -d baz} to produce @file{foo.log}, -@file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs}, -@file{bar.trs} and @file{baz.trs} files will be automatically produced -as a side-effect. - -It's important to note that, differently from what we've seen for the -serial test harness (@pxref{Serial Test Harness}), the -@code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables -@emph{cannot} be used to define a custom test runner; the -@code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific -counterparts) should be used instead: - -@example -## This is WRONG! -AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w -@end example - -@example -## Do this instead. -AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB; -LOG_COMPILER = $(PERL) -AM_LOG_FLAGS = -Mstrict -w -@end example - -By default, the test suite harness will run all tests, but there are -several ways to limit the set of tests that are run: - -@itemize @bullet -@item -You can set the @code{TESTS} variable. For example, you can use a -command like this to run only a subset of the tests: - -@example -env TESTS="foo.test bar.test" make -e check -@end example - -Note however that the command above will unconditionally overwrite the -@file{test-suite.log} file, thus clobbering the recorded results -of any previous testsuite run. This might be undesirable for packages -whose testsuite takes long time to execute. Luckily, this problem can -easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime; -for example, - -@c Keep in sync with parallel-tests-log-override-2.sh -@example -env TEST_SUITE_LOG=partial.log TESTS="..." make -e check -@end example - -will write the result of the partial testsuite runs to the -@file{partial.log}, without touching @file{test-suite.log}. - -@item -You can set the @code{TEST_LOGS} variable. By default, this variable is -computed at @command{make} run time from the value of @code{TESTS} as -described above. For example, you can use the following: - -@example -set x subset*.log; shift -env TEST_LOGS="foo.log $*" make -e check -@end example - -The comments made above about @code{TEST_SUITE_LOG} overriding applies -here too. - -@item -@vindex RECHECK_LOGS -@cindex lazy test execution -By default, the test harness removes all old per-test @file{.log} and -@file{.trs} files before it starts running tests to regenerate them. The -variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by -implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS} -defaults to @code{TEST_LOGS}, which means all tests need to be rechecked. -By overriding this variable, you can choose which tests need to be -reconsidered. For example, you can lazily rerun only those tests which -are outdated, i.e., older than their prerequisite test files, by setting -this variable to the empty value: - -@example -env RECHECK_LOGS= make -e check -@end example - -@item -@trindex recheck -You can ensure that all tests are rerun which have failed or passed -unexpectedly, by running @code{make recheck} in the test directory. -This convenience target will set @code{RECHECK_LOGS} appropriately -before invoking the main test harness. -@end itemize - -@noindent -In order to guarantee an ordering between tests even with @code{make --j@var{N}}, dependencies between the corresponding @file{.log} files -may be specified through usual @command{make} dependencies. For example, -the following snippet lets the test named @file{foo-execute.test} depend -upon completion of the test @file{foo-compile.test}: - -@example -TESTS = foo-compile.test foo-execute.test -foo-execute.log: foo-compile.log -@end example - -@noindent -Please note that this ordering ignores the @emph{results} of required -tests, thus the test @file{foo-execute.test} is run even if the test -@file{foo-compile.test} failed or was skipped beforehand. Further, -please note that specifying such dependencies currently works only for -tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}. - -Tests without such specified dependencies may be run concurrently with -parallel @command{make -j@var{N}}, so be sure they are prepared for -concurrent execution. - -@cindex Unit tests -@c Keep in sync with 'parallel-tests-extra-programs.sh'. -The combination of lazy test execution and correct dependencies between -tests and their sources may be exploited for efficient unit testing -during development. To further speed up the edit-compile-test cycle, it -may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS} -instead of with @code{check_PROGRAMS}, as the former allows intertwined -compilation and test execution (but note that @code{EXTRA_PROGRAMS} are -not cleaned automatically, @pxref{Uniform}). - -The variables @code{TESTS} and @code{XFAIL_TESTS} may contain -conditional parts as well as configure substitutions. In the latter -case, however, certain restrictions apply: substituted test names -must end with a nonempty test suffix like @file{.test}, so that one of -the inference rules generated by @command{automake} can apply. For -literal test names, @command{automake} can generate per-target rules -to avoid this limitation. - -Please note that it is currently not possible to use @code{$(srcdir)/} -or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical -limitation is necessary to avoid generating test logs in the source tree -and has the unfortunate consequence that it is not possible to specify -distributed tests that are themselves generated by means of explicit -rules, in a way that is portable to all @command{make} implementations -(@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the -semantics of FreeBSD and OpenBSD @command{make} conflict with this). -In case of doubt you may want to require to use GNU @command{make}, -or work around the issue with inference rules to generate the tests. - -@node Custom Test Drivers -@section Custom Test Drivers - -@menu -* Overview of Custom Test Drivers Support:: -* Declaring Custom Test Drivers:: -* API for Custom Test Drivers:: -@end menu - -@node Overview of Custom Test Drivers Support -@subsection Overview of Custom Test Drivers Support - -Starting from Automake version 1.12, the parallel test harness allows -the package authors to use third-party custom test drivers, in case the -default ones are inadequate for their purposes, or do not support their -testing protocol of choice. - -A custom test driver is expected to properly run the test programs passed -to it (including the command-line arguments passed to those programs, if -any), to analyze their execution and outcome, to create the @file{.log} -and @file{.trs} files associated to these test runs, and to display the test -results on the console. It is responsibility of the author of the test -driver to ensure that it implements all the above steps meaningfully and -correctly; Automake isn't and can't be of any help here. On the other -hand, the Automake-provided code for testsuite summary generation offers -support for test drivers allowing several test results per test script, -if they take care to register such results properly (@pxref{Log files -generation and test results recording}). - -The exact details of how test scripts' results are to be determined and -analyzed is left to the individual drivers. Some drivers might only -consider the test script exit status (this is done for example by the -default test driver used by the parallel test harness, described -in the previous section). Other drivers might implement more complex and -advanced test protocols, which might require them to parse and interpreter -the output emitted by the test script they're running (examples of such -protocols are TAP and SubUnit). - -It's very important to note that, even when using custom test drivers, -most of the infrastructure described in the previous section about the -parallel harness remains in place; this includes: - -@itemize -@item -list of test scripts defined in @code{TESTS}, and overridable at -runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS}; -@item -concurrency through the use of @command{make}'s option @option{-j}; -@item -per-test @file{.log} and @file{.trs} files, and generation of a summary -@file{.log} file from them; -@item -@code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns -of tests; -@item -inter-test dependencies; -@item -support for @code{check_*} variables (@code{check_PROGRAMS}, -@code{check_LIBRARIES}, ...); -@item -use of @code{VERBOSE} environment variable to get verbose output on -testsuite failures; -@item -definition and honoring of @code{TESTS_ENVIRONMENT}, -@code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT} -variables; -@item -definition of generic and extension-specific @code{LOG_COMPILER} and -@code{LOG_FLAGS} variables. -@end itemize - -@noindent -On the other hand, the exact semantics of how (and if) testsuite output -colorization, @code{XFAIL_TESTS}, and hard errors are supported and -handled is left to the individual test drivers. - -@c TODO: We should really add a working example in the doc/ directory, -@c TODO: and reference if from here. - -@node Declaring Custom Test Drivers -@subsection Declaring Custom Test Drivers - -@vindex _LOG_DRIVER -@vindex _LOG_DRIVER_FLAGS -@vindex LOG_DRIVER -@vindex LOG_DRIVER_FLAGS -@vindex @var{ext}_LOG_DRIVER -@vindex @var{ext}_LOG_DRIVER_FLAGS -@vindex AM_@var{ext}_LOG_DRIVER_FLAGS -@vindex AM_LOG_DRIVER_FLAGS -Custom testsuite drivers are declared by defining the make variables -@code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must -be declared in @code{TEST_EXTENSIONS}). They must be defined to -programs or scripts that will be used to drive the execution, logging, -and outcome report of the tests with corresponding extensions (or of -those with no registered extension in the case of @code{LOG_DRIVER}). -Clearly, multiple distinct test drivers can be declared in the same -@file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables -are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the -two sets of variables can, and often do, usefully and legitimately -coexist. - -@c TODO: We should really be able to point to a clarifying example here! - -The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the -user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define -flags that will be passed to each invocation of @code{LOG_DRIVER}, -with the user-defined flags obviously taking precedence over the -developer-reserved ones. Similarly, for each extension @var{ext} -declared in @code{TEST_EXTENSIONS}, flags listed in -@code{AM_@var{ext}_LOG_DRIVER_FLAGS} and -@code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to -invocations of @code{@var{ext}_LOG_DRIVER}. - -@node API for Custom Test Drivers -@subsection API for Custom Test Drivers - -Note that @emph{the APIs described here are still highly experimental}, -and will very likely undergo tightenings and likely also extensive changes -in the future, to accommodate for new features or to satisfy additional -portability requirements. - -The main characteristic of these APIs is that they are designed to share -as much infrastructure, semantics, and implementation details as possible -with the parallel test harness and its default driver. - -@menu -* Command-line arguments for test drivers:: -* Log files generation and test results recording:: -* Testsuite progress output:: -@end menu - -@node Command-line arguments for test drivers -@subsubsection Command-line arguments for test drivers - -A custom driver can rely on various command-line options and arguments -being passed to it automatically by the Automake-generated test harness. -It is @emph{mandatory} that it understands all of them (even if the exact -interpretation of the associated semantics can legitimately change -between a test driver and another, and even be a no-op in some drivers). - -@noindent -Here is the list of options: - -@table @option -@item --test-name=@var{NAME} -The name of the test, with VPATH prefix (if any) removed. This can have a -suffix and a directory component (as in e.g., @file{sub/foo.test}), and is -mostly meant to be used in console reports about testsuite advancements and -results (@pxref{Testsuite progress output}). -@item --log-file=@file{@var{PATH}.log} -The @file{.log} file the test driver must create (@pxref{Basics of -test metadata}). If it has a directory component (as in e.g., -@file{sub/foo.log}), the test harness will ensure that such directory -exists @emph{before} the test driver is called. -@item --trs-file=@file{@var{PATH}.trs} -The @file{.trs} file the test driver must create (@pxref{Basics of -test metadata}). If it has a directory component (as in e.g., -@file{sub/foo.trs}), the test harness will ensure that such directory -exists @emph{before} the test driver is called. -@item --color-tests=@{yes|no@} -Whether the console output should be colorized or not (@pxref{Simple -tests and color-tests}, to learn when this option gets activated and -when it doesn't). -@item --expect-failure=@{yes|no@} -Whether the tested program is expected to fail. -@item --enable-hard-errors=@{yes|no@} -Whether ``hard errors'' in the tested program should be treated differently -from normal failures or not (the default should be @code{yes}). The exact -meaning of ``hard error'' is highly dependent from the test protocols or -conventions in use. -@item -- -Explicitly terminate the list of options. -@end table - -@noindent -The first non-option argument passed to the test driver is the program to -be run, and all the following ones are command-line options and arguments -for this program. - -Note that the exact semantics attached to the @option{--color-tests}, -@option{--expect-failure} and @option{--enable-hard-errors} options are -left up to the individual test drivers. Still, having a behaviour -compatible or at least similar to that provided by the default driver -is advised, as that would offer a better consistency and a more pleasant -user experience. - -@node Log files generation and test results recording -@subsubsection Log files generation and test results recording - -The test driver must correctly generate the files specified by the -@option{--log-file} and @option{--trs-file} option (even when the tested -program fails or crashes). - -The @file{.log} file should ideally contain all the output produced by the -tested program, plus optionally other information that might facilitate -debugging or analysis of bug reports. Apart from that, its format is -basically free. - -The @file{.trs} file is used to register some metadata through the use -of custom reStructuredText fields. This metadata is expected to be -employed in various ways by the parallel test harness; for example, to -count the test results when printing the testsuite summary, or to decide -which tests to re-run upon @command{make recheck}. Unrecognized metadata -in a @file{.trs} file is currently ignored by the harness, but this might -change in the future. The list of currently recognized metadata follows. - -@table @code - -@item :test-result: -@cindex Register test result -@cindex Register test case result -@cindex Test result, registering -@cindex Test case result, registering -@cindex @code{:test-result:} -@cindex reStructuredText field, @code{:test-result:} -The test driver must use this field to register the results of @emph{each} -test case run by a test script file. Several @code{:test-result:} fields -can be present in the same @file{.trs} file; this is done in order to -support test protocols that allow a single test script to run more test -cases. - -@c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG). -The only recognized test results are currently @code{PASS}, @code{XFAIL}, -@code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results, -when declared with @code{:test-result:}, can be optionally followed by -text holding the name and/or a brief description of the corresponding -test; the harness will ignore such extra text when generating -@file{test-suite.log} and preparing the testsuite summary. - -@c Keep in sync with 'test-metadata-recheck.sh'. -@item @code{:recheck:} -@cindex :recheck: -@cindex reStructuredText field, @code{:recheck:} -If this field is present and defined to @code{no}, then the corresponding -test script will @emph{not} be run upon a @command{make recheck}. What -happens when two or more @code{:recheck:} fields are present in the same -@file{.trs} file is undefined behaviour. - -@c Keep in sync with 'test-metadata-global-log.sh'. -@item @code{:copy-in-global-log:} -@cindex :copy-in-global-log: -@cindex reStructuredText field, @code{:copy-in-global-log:} -If this field is present and defined to @code{no}, then the content -of the @file{.log} file will @emph{not} be copied into the global -@file{test-suite.log}. We allow to forsake such copying because, while -it can be useful in debugging and analysis of bug report, it can also be -just a waste of space in normal situations, e.g., when a test script is -successful. What happens when two or more @code{:copy-in-global-log:} -fields are present in the same @file{.trs} file is undefined behaviour. - -@c Keep in sync with 'test-metadata-global-result.sh'. -@item @code{:test-global-result:} -@cindex :test-global-result: -@cindex reStructuredText field, @code{:test-global-result:} -This is used to declare the "global result" of the script. Currently, -the value of this field is needed only to be reported (more or less -verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)}, -so it's quite free-form. For example, a test script which run 10 test -cases, 6 of which pass and 4 of which are skipped, could reasonably have -a @code{PASS/SKIP} value for this field, while a test script which run -19 successful tests and one failed test could have an @code{ALMOST -PASSED} value. What happens when two or more @code{:test-global-result:} -fields are present in the same @file{.trs} file is undefined behaviour. -@end table - -@noindent -Let's see a small example. Assume a @file{.trs} file contains the -following lines: - -@example -:test-result: PASS server starts -:global-log-copy: no -:test-result: PASS HTTP/1.1 request -:test-result: FAIL HTTP/1.0 request -:recheck: yes -:test-result: SKIP HTTPS request (TLS library wasn't available) -:test-result: PASS server stops -@end example - -@noindent -Then the corresponding test script will be re-run by @command{make check}, -will contribute with @emph{five} test results to the testsuite summary -(three of these tests being successful, one failed, and one skipped), and -the content of the corresponding @file{.log} file will @emph{not} be -copied in the global log file @file{test-suite.log}. - -@node Testsuite progress output -@subsubsection Testsuite progress output - -A custom test driver also has the task of displaying, on the standard -output, the test results as soon as they become available. Depending on -the protocol in use, it can also display the reasons for failures and -skips, and, more generally, any useful diagnostic output (but remember -that each line on the screen is precious, so that cluttering the screen -with overly verbose information is bad idea). The exact format of this -progress output is left up to the test driver; in fact, a custom test -driver might @emph{theoretically} even decide not to do any such report, -leaving it all to the testsuite summary (that would be a very lousy idea, -of course, and serves only to illustrate the flexibility that is -granted here). - -Remember that consistency is good; so, if possible, try to be consistent -with the output of the built-in Automake test drivers, providing a similar -``look & feel''. In particular, the testsuite progress output should be -colorized when the @option{--color-tests} is passed to the driver. On the -other end, if you are using a known and widespread test protocol with -well-established implementations, being consistent with those -implementations' output might be a good idea too. - -@node Using the TAP test protocol -@section Using the TAP test protocol - -@menu -* Introduction to TAP:: -* Use TAP with the Automake test harness:: -* Incompatibilities with other TAP parsers and drivers:: -* Links and external resources on TAP:: -@end menu - -@node Introduction to TAP -@subsection Introduction to TAP - -TAP, the Test Anything Protocol, is a simple text-based interface between -testing modules or programs and a test harness. The tests (also called -``TAP producers'' in this context) write test results in a simple format -on standard output; a test harness (also called ``TAP consumer'') will -parse and interpret these results, and properly present them to the user, -and/or register them for later analysis. The exact details of how this -is accomplished can vary among different test harnesses. The Automake -harness will present the results on the console in the usual -fashion (@pxref{Testsuite progress on console}), and will use the -@file{.trs} files (@pxref{Basics of test metadata}) to store the test -results and related metadata. Apart from that, it will try to remain -as much compatible as possible with pre-existing and widespread utilities, -such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove, -@command{prove} utility}, at least for the simpler usages. - -TAP started its life as part of the test harness for Perl, but today -it has been (mostly) standardized, and has various independent -implementations in different languages; among them, C, C++, Perl, -Python, PHP, and Java. For a semi-official specification of the -TAP protocol, please refer to the documentation of -@uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod, - @samp{Test::Harness::TAP}}. - -The most relevant real-world usages of TAP are obviously in the testsuites -of @command{perl} and of many perl modules. Still, also other important -third-party packages, such as @uref{http://git-scm.com/, @command{git}}, -use TAP in their testsuite. - -@node Use TAP with the Automake test harness -@subsection Use TAP with the Automake test harness - -Currently, the TAP driver that comes with Automake requires some by-hand -steps on the developer's part (this situation should hopefully be improved -in future Automake versions). You'll have to grab the @file{tap-driver.sh} -script from the Automake distribution by hand, copy it in your source tree, -and use the Automake support for third-party test drivers to instruct the -harness to use the @file{tap-driver.sh} script and the awk program found -by @code{AM_INIT_AUTOMAKE} to run your TAP-producing tests. See the example -below for clarification. - -Apart from the options common to all the Automake test drivers -(@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh} -supports the following options, whose names are chosen for enhanced -compatibility with the @command{prove} utility. - -@table @option -@c Keep in sync with 'tap-exit.sh' and 'tap-signal.tap'. -@item --ignore-exit -Causes the test driver to ignore the exit status of the test scripts; -by default, the driver will report an error if the script exits with a -non-zero status. This option has effect also on non-zero exit statuses -due to termination by a signal. -@item --comments -Instruct the test driver to display TAP diagnostic (i.e., lines beginning -with the @samp{#} character) in the testsuite progress output too; by -default, TAP diagnostic is only copied to the @file{.log} file. -@item --no-comments -Revert the effects of @option{--comments}. -@item --merge -Instruct the test driver to merge the test scripts' standard error into -their standard output. This is necessary if you want to ensure that -diagnostics from the test scripts are displayed in the correct order -relative to test results; this can be of great help in debugging -(especially if your test scripts are shell scripts run with shell -tracing active). As a downside, this option might cause the test -harness to get confused if anything that appears on standard error -looks like a test result. -@item --no-merge -Revert the effects of @option{--merge}. -@item --diagnostic-string=@var{STRING} -Change the string that introduces TAP diagnostic from the default value -of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your -TAP-based test scripts produce verbose output on which they have limited -control (because, say, the output comes from other tools invoked in the -scripts), and it might contain text that gets spuriously interpreted as -TAP diagnostic: such an issue can be solved by redefining the string that -activates TAP diagnostic to a value you know won't appear by chance in -the tests' output. Note however that this feature is non-standard, as -the ``official'' TAP protocol does not allow for such a customization; so -don't use it if you can avoid it. -@end table - -@noindent -Here is an example of how the TAP driver can be set up and used. - -@c Keep in sync with tap-doc2.sh -@example -% @kbd{cat configure.ac} -AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org]) -AC_CONFIG_AUX_DIR([build-aux]) -AM_INIT_AUTOMAKE([foreign -Wall -Werror]) -AC_CONFIG_FILES([Makefile]) -AC_REQUIRE_AUX_FILE([tap-driver.sh]) -AC_OUTPUT - -% @kbd{cat Makefile.am} -TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \ - $(top_srcdir)/build-aux/tap-driver.sh -TESTS = foo.test bar.test baz.test -EXTRA_DIST = $(TESTS) - -% @kbd{cat foo.test} -#!/bin/sh -echo 1..4 # Number of tests to be executed. -echo 'ok 1 - Swallows fly' -echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress' -echo 'ok 3 - Pigs fly # SKIP not enough acid' -echo '# I just love word plays ...' -echo 'ok 4 - Flies fly too :-)' - -% @kbd{cat bar.test} -#!/bin/sh -echo 1..3 -echo 'not ok 1 - Bummer, this test has failed.' -echo 'ok 2 - This passed though.' -echo 'Bail out! Ennui kicking in, sorry...' -echo 'ok 3 - This will not be seen.' - -% @kbd{cat baz.test} -#!/bin/sh -echo 1..1 -echo ok 1 -# Exit with error, even if all the tests have been successful. -exit 7 - -% @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.sh .} -% @kbd{autoreconf -vi && ./configure && make check} -... -PASS: foo.test 1 - Swallows fly -XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress -SKIP: foo.test 3 - Pigs fly # SKIP not enough acid -PASS: foo.test 4 - Flies fly too :-) -FAIL: bar.test 1 - Bummer, this test has failed. -PASS: bar.test 2 - This passed though. -ERROR: bar.test - Bail out! Ennui kicking in, sorry... -PASS: baz.test 1 -ERROR: baz.test - exited with status 7 -... -Please report to bug-automake@@gnu.org -... -% @kbd{echo exit status: $?} -exit status: 1 - -@c Keep the "skewed" indentation below, it produces pretty PDF output. -% @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \ - TESTS='foo.test baz.test' make -e check} -... -PASS: foo.test 1 - Swallows fly -XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress -SKIP: foo.test 3 - Pigs fly # SKIP not enough acid -# foo.test: I just love word plays... -PASS: foo.test 4 - Flies fly too :-) -PASS: baz.test 1 -... -% @kbd{echo exit status: $?} -exit status: 0 -@end example - -@node Incompatibilities with other TAP parsers and drivers -@subsection Incompatibilities with other TAP parsers and drivers - -For implementation or historical reasons, the TAP driver and harness as -implemented by Automake have some minors incompatibilities with the -mainstream versions, which you should be aware of. - -@itemize @bullet -@item -A @code{Bail out!} directive doesn't stop the whole testsuite, but only -the test script it occurs in. This doesn't follow TAP specifications, -but on the other hand it maximizes compatibility (and code sharing) with -the ``hard error'' concept of the default testsuite driver. -@item -The @code{version} and @code{pragma} directives are not supported. -@item -The @option{--diagnostic-string} option of our driver allows to modify -the string that introduces TAP diagnostic from the default value -of ``@code{#}''. The standard TAP protocol has currently no way to -allow this, so if you use it your diagnostic will be lost to more -compliant tools like @command{prove} and @code{Test::Harness} -@item -And there are probably some other small and yet undiscovered -incompatibilities, especially in corner cases or with rare usages. -@end itemize - -@node Links and external resources on TAP -@subsection Links and external resources on TAP - -@noindent -Here are some links to more extensive official or third-party -documentation and resources about the TAP protocol and related -tools and libraries. -@itemize @bullet -@item -@uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod, - @samp{Test::Harness::TAP}}, -the (mostly) official documentation about the TAP format and protocol. -@item -@uref{http://search.cpan.org/~andya/Test-Harness/bin/prove, - @command{prove}}, -the most famous command-line TAP test driver, included in the distribution -of @command{perl} and -@uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm, - @samp{Test::Harness}}. -@item -The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}. -@item -A ``gentle introduction'' to testing for perl coders: -@uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod, - @samp{Test::Tutorial}}. -@item -@uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm, - @samp{Test::Simple}} -and -@uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm, - @samp{Test::More}}, -the standard perl testing libraries, which are based on TAP. -@item -@uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness}, -a C-based project implementing both a TAP producer and a TAP consumer. -@item -@uref{http://www.tap4j.org/,tap4j}, -a Java-based project implementing both a TAP producer and a TAP consumer. -@end itemize - -@node DejaGnu Tests -@section DejaGnu Tests - -If @uref{https://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in -@code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is -assumed. The variable @code{DEJATOOL} is a list of names that are -passed, one at a time, as the @option{--tool} argument to -@command{runtest} invocations; it defaults to the name of the package. - -The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and -@option{--srcdir} flags that are passed to dejagnu by default; this can be -overridden if necessary. -@vindex RUNTESTDEFAULTFLAGS - -The variables @code{EXPECT} and @code{RUNTEST} can -also be overridden to provide project-specific values. For instance, -you will need to do this if you are testing a compiler toolchain, -because the default values do not take into account host and target -names. -@opindex dejagnu -@vindex DEJATOOL -@vindex EXPECT -@vindex RUNTEST - -The contents of the variable @code{RUNTESTFLAGS} are passed to the -@code{runtest} invocation. This is considered a ``user variable'' -(@pxref{User Variables}). If you need to set @command{runtest} flags in -@file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead. -@vindex RUNTESTFLAGS -@vindex AM_RUNTESTFLAGS - -@cindex @file{site.exp} -Automake will generate rules to create a local @file{site.exp} file, -defining various variables detected by @command{configure}. This file -is automatically read by DejaGnu. It is OK for the user of a package -to edit this file in order to tune the test suite. However this is -not the place where the test suite author should define new variables: -this should be done elsewhere in the real test suite code. -Especially, @file{site.exp} should not be distributed. - -Still, if the package author has legitimate reasons to extend -@file{site.exp} at @command{make} time, he can do so by defining -the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed -there will be considered @file{site.exp} prerequisites, and their -content will be appended to it (in the same order in which they -appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are -@emph{not} distributed by default. - -For more information regarding DejaGnu test suites, see @ref{Top, , , -dejagnu, The DejaGnu Manual}. - -@node Install Tests -@section Install Tests - -The @code{installcheck} target is available to the user as a way to -run any tests after the package has been installed. You can add tests -to this by writing an @code{installcheck-local} rule. - - -@node Rebuilding -@chapter Rebuilding Makefiles -@cindex rebuild rules - -Automake generates rules to automatically rebuild @file{Makefile}s, -@file{configure}, and other derived files like @file{Makefile.in}. - -@acindex AM_MAINTAINER_MODE -If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then -these automatic rebuilding rules are only enabled in maintainer mode. - -@vindex CONFIG_STATUS_DEPENDENCIES -@vindex CONFIGURE_DEPENDENCIES -@cindex @file{version.sh}, example -@cindex @file{version.m4}, example - -Sometimes it is convenient to supplement the rebuild rules for -@file{configure} or @file{config.status} with additional dependencies. -The variables @code{CONFIGURE_DEPENDENCIES} and -@code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra -dependencies. These variables should be defined in all -@file{Makefile}s of the tree (because these two rebuild rules are -output in all them), so it is safer and easier to @code{AC_SUBST} them -from @file{configure.ac}. For instance, the following statement will -cause @file{configure} to be rerun each time @file{version.sh} is -changed. - -@c Keep in sync with remake-config-status-dependencies.sh -@example -AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh']) -@end example - -@noindent -Note the @samp{$(top_srcdir)/} in the file name. Since this variable -is to be used in all @file{Makefile}s, its value must be sensible at -any level in the build hierarchy. - -Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for -@code{CONFIG_STATUS_DEPENDENCIES}. - -@c Keep in sync with remake-configure-dependencies.sh -@code{CONFIGURE_DEPENDENCIES} adds dependencies to the -@file{configure} rule, whose effect is to run @command{autoconf}. This -variable should be seldom used, because @command{automake} already tracks -@code{m4_include}d files. However it can be useful when playing -tricky games with @code{m4_esyscmd} or similar non-recommendable -macros with side effects. Be also aware that interactions of this -variable with the @ref{Autom4te Cache, , autom4te cache, autoconf, -The Autoconf Manual} are quite problematic and can cause subtle -breakage, so you might want to disable the cache if you want to use -@code{CONFIGURE_DEPENDENCIES}. - -@code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the -@file{config.status} rule, whose effect is to run @file{configure}. -This variable should therefore carry any non-standard source that may -be read as a side effect of running @command{configure}, like @file{version.sh} -in the example above. - -Speaking of @file{version.sh} scripts, we recommend against them -today. They are mainly used when the version of a package is updated -automatically by a script (e.g., in daily builds). Here is what some -old-style @file{configure.ac}s may look like: - -@example -AC_INIT -. $srcdir/version.sh -AM_INIT_AUTOMAKE([name], $VERSION_NUMBER) -@dots{} -@end example - -@noindent -Here, @file{version.sh} is a shell fragment that sets -@code{VERSION_NUMBER}. The problem with this example is that -@command{automake} cannot track dependencies (listing @file{version.sh} -in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up -to the user), and that it uses the obsolete form of @code{AC_INIT} and -@code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not -straightforward, because shell variables are not allowed in -@code{AC_INIT}'s arguments. We recommend that @file{version.sh} be -replaced by an M4 file that is included by @file{configure.ac}: - -@example -m4_include([version.m4]) -AC_INIT([name], VERSION_NUMBER) -AM_INIT_AUTOMAKE -@dots{} -@end example - -@noindent -Here @file{version.m4} could contain something like -@samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this -second form is that @command{automake} will take care of the -dependencies when defining the rebuild rule, and will also distribute -the file automatically. An inconvenience is that @command{autoconf} -will now be rerun each time the version number is bumped, when only -@file{configure} had to be rerun in the previous setup. - - -@node Options -@chapter Changing Automake's Behavior - -@menu -* Options generalities:: Semantics of Automake option -* List of Automake options:: A comprehensive list of Automake options -@end menu - -@node Options generalities -@section Options generalities - -Various features of Automake can be controlled by options. Except where -noted otherwise, options can be specified in one of several ways. Most -options can be applied on a per-@file{Makefile} basis when listed in a -special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some -of these options only make sense when specified in the toplevel -@file{Makefile.am} file. Options are applied globally to all processed -@file{Makefile} files when listed in the first argument of -@code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which -require changes to the @command{configure} script can only be specified -there. These are annotated below. - -As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take -precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in -turn take precedence over those specified on the command line. - -Also, some care must be taken about the interactions among strictness -level and warning categories. As a general rule, strictness-implied -warnings are overridden by those specified by explicit options. For -example, even if @samp{portability} warnings are disabled by default -in @option{foreign} strictness, an usage like this will end up enabling -them: - -@example -AUTOMAKE_OPTIONS = -Wportability foreign -@end example - -However, a strictness level specified in a higher-priority context -will override all the explicit warnings specified in a lower-priority -context. For example, if @file{configure.ac} contains: - -@example -AM_INIT_AUTOMAKE([-Wportability]) -@end example - -@noindent -and @file{Makefile.am} contains: - -@example -AUTOMAKE_OPTIONS = foreign -@end example - -@noindent -then @samp{portability} warnings will be @emph{disabled} in -@file{Makefile.am}. - -@node List of Automake options -@section List of Automake options - -@vindex AUTOMAKE_OPTIONS - -@table @asis -@item @option{gnits} -@itemx @option{gnu} -@itemx @option{foreign} -@cindex Option, @option{gnits} -@cindex Option, @option{gnu} -@cindex Option, @option{foreign} -@opindex gnits -@opindex gnu -@opindex foreign - -Set the strictness as appropriate. The @option{gnits} option also -implies options @option{readme-alpha} and @option{check-news}. - -@item @option{check-news} -@cindex Option, @option{check-news} -@opindex check-news -Cause @samp{make dist} to fail unless the current version number appears -in the first few lines of the @file{NEWS} file. - -@item @option{dejagnu} -@cindex Option, @option{dejagnu} -@opindex dejagnu -Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}. - -@item @option{dist-bzip2} -@cindex Option, @option{dist-bzip2} -@opindex dist-bzip2 -Hook @code{dist-bzip2} to @code{dist}. -@trindex dist-bzip2 - -@item @option{dist-lzip} -@cindex Option, @option{dist-lzip} -@opindex dist-lzip -Hook @code{dist-lzip} to @code{dist}. -@trindex dist-lzip - -@item @option{dist-xz} -@cindex Option, @option{dist-xz} -@opindex dist-xz -Hook @code{dist-xz} to @code{dist}. -@trindex dist-xz - -@item @option{dist-zip} -@cindex Option, @option{dist-zip} -@opindex dist-zip -Hook @code{dist-zip} to @code{dist}. -@trindex dist-zip - -@item @option{filename-length-max=99} -@cindex Option, @option{filename-length-max=99} -@opindex filename-length-max=99 -Abort if file names longer than 99 characters are found during -@samp{make dist}. Such long file names are generally considered not to -be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar} -options below. This option should be used in the top-level -@file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in -@file{configure.ac}, it will be ignored otherwise. It will also be -ignored in sub-packages of nested packages (@pxref{Subpackages}). - -@item @option{info-in-builddir} -@cindex Option, @option{info-in-builddir} -@opindex info-in-builddir -Instruct Automake to place the generated @file{.info} files in the -@code{builddir} rather than in the @code{srcdir}. Note that this -might make VPATH builds with some non-GNU make implementations more -brittle. - -@item @option{no-define} -@cindex Option, @option{no-define} -@opindex no-define -This option is meaningful only when passed as an argument to -@code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and -@code{VERSION} variables from being @code{AC_DEFINE}d. But notice -that they will remain defined as shell variables in the generated -@code{configure}, and as make variables in the generated -@code{Makefile}; this is deliberate, and required for backward -compatibility. - -@item @option{no-dependencies} -@cindex Option, @option{no-dependencies} -@opindex no-dependencies -This is similar to using @option{--ignore-deps} on the command line, -but is useful for those situations where you don't have the necessary -bits to make automatic dependency tracking work -(@pxref{Dependencies}). In this case the effect is to effectively -disable automatic dependency tracking. - -@item @option{no-dist} -@cindex Option, @option{no-dist} -@opindex no-dist -Don't emit any code related to @code{dist} target. This is useful -when a package has its own method for making distributions. - -@item @option{no-dist-gzip} -@cindex Option, @option{no-dist-gzip} -@opindex no-dist-gzip -Do not hook @code{dist-gzip} to @code{dist}. -@trindex no-dist-gzip - -@item @option{no-exeext} -@cindex Option, @option{no-exeext} -@opindex no-exeext -If your @file{Makefile.am} defines a rule for target @code{foo}, it -will override a rule for a target named @samp{foo$(EXEEXT)}. This is -necessary when @code{EXEEXT} is found to be empty. However, by -default @command{automake} will generate an error for this use. The -@option{no-exeext} option will disable this error. This is intended for -use only where it is known in advance that the package will not be -ported to Windows, or any other operating system using extensions on -executables. - -@item @option{no-installinfo} -@cindex Option, @option{no-installinfo} -@opindex no-installinfo -The generated @file{Makefile.in} will not cause info pages to be built -or installed by default. However, @code{info} and @code{install-info} -targets will still be available. This option is disallowed at -@option{gnu} strictness and above. -@trindex info -@trindex install-info - -@item @option{no-installman} -@cindex Option, @option{no-installman} -@opindex no-installman -The generated @file{Makefile.in} will not cause man pages to be -installed by default. However, an @code{install-man} target will still -be available for optional installation. This option is disallowed at -@option{gnu} strictness and above. -@trindex install-man - -@item @option{nostdinc} -@cindex Option, @option{nostdinc} -@opindex nostdinc -This option can be used to disable the standard @option{-I} options that -are ordinarily automatically provided by Automake. - -@item @option{no-texinfo.tex} -@cindex Option, @option{no-texinfo.tex} -@opindex no-texinfo.tex -Don't require @file{texinfo.tex}, even if there are texinfo files in -this directory. - -@item @option{serial-tests} -@cindex Option, @option{serial-tests} -@opindex serial-tests -Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial -Test Harness}, for more information). - -@item @option{parallel-tests} -@cindex Option, @option{parallel-tests} -@opindex parallel-tests -Enable test suite harness for @code{TESTS} that can run tests in parallel -(@pxref{Parallel Test Harness}, for more information). This option is -only kept for backward-compatibility, since the parallel test harness is -the default now. - -@item @option{readme-alpha} -@cindex Option, @option{readme-alpha} -@opindex readme-alpha -If this release is an alpha release, and the file @file{README-alpha} -exists, then it will be added to the distribution. If this option is -given, version numbers are expected to follow one of two forms. The -first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each -element is a number; the final period and number should be left off for -non-alpha releases. The second form is -@samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a -letter; it should be omitted for non-alpha releases. - -@item @option{std-options} -@cindex Options, @option{std-options} -@cindex @samp{make installcheck}, testing @option{--help} and @option{--version} -@cindex @option{--help} check -@cindex @option{--version} check -@opindex std-options - -Make the @code{installcheck} rule check that installed scripts and -programs support the @option{--help} and @option{--version} options. -This also provides a basic check that the program's -run-time dependencies are satisfied after installation. - -@vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT -In a few situations, programs (or scripts) have to be exempted from this -test. For instance, @command{false} (from GNU coreutils) is never -successful, even for @option{--help} or @option{--version}. You can list -such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}. -Programs (not scripts) listed in this variable should be suffixed by -@samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we -build @file{false} as a program but @file{true.sh} as a script, and that -neither of them support @option{--help} or @option{--version}: - -@example -AUTOMAKE_OPTIONS = std-options -bin_PROGRAMS = false ... -bin_SCRIPTS = true.sh ... -AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh -@end example - -@item @option{subdir-objects} -@cindex Options, @option{subdir-objects} -@opindex subdir-objects -This option does nothing; it exists solely for compatibility with -older Automake versions. - -@anchor{tar-formats} -@item @option{tar-v7} -@itemx @option{tar-ustar} -@itemx @option{tar-pax} -@cindex Option, @option{tar-v7} -@cindex Option, @option{tar-ustar} -@cindex Option, @option{tar-pax} -@cindex @command{tar} formats -@cindex v7 @command{tar} format -@cindex ustar format -@cindex pax format -@opindex tar-v7 -@opindex tar-ustar -@opindex tar-pax - -These three mutually exclusive options select the tar format to use -when generating tarballs with @samp{make dist}. (The tar file created -is then compressed according to the set of @option{no-dist-gzip}, -@option{dist-bzip2}, @option{dist-lzip} and @option{dist-xz} in use). - -These options must be passed as arguments to @code{AM_INIT_AUTOMAKE} -(@pxref{Macros}) because they can require additional configure checks. -Automake will complain if it sees such options in an -@code{AUTOMAKE_OPTIONS} variable. - -@option{tar-v7} selects the old V7 tar format. This is the historical -default. This antiquated format is understood by all tar -implementations and supports file names with up to 99 characters. When -given longer file names some tar implementations will diagnose the -problem while other will generate broken tarballs or use non-portable -extensions. Furthermore, the V7 format cannot store empty -directories. When using this format, consider using the -@option{filename-length-max=99} option to catch file names too long. - -@option{tar-ustar} selects the ustar format defined by POSIX -1003.1-1988. This format is believed to be old enough to be portable. -It fully supports empty directories. It can store file names with up -to 256 characters, provided that the file name can be split at -directory separator in two parts, first of them being at most 155 -bytes long. So, in most cases the maximum file name length will be -shorter than 256 characters. However you may run against broken tar -implementations that incorrectly handle file names longer than 99 -characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we -can document this accurately). - -@option{tar-pax} selects the new pax interchange format defined by POSIX -1003.1-2001. It does not limit the length of file names. However, -this format is very young and should probably be restricted to -packages that target only very modern platforms. There are moves to -change the pax format in an upward-compatible way, so this option may -refer to a more recent version in the future. - -@xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for -further discussion about tar formats. - -@command{configure} knows several ways to construct these formats. It -will not abort if it cannot find a tool up to the task (so that the -package can still be built), but @samp{make dist} will fail. - -@item @var{version} -@cindex Option, @var{version} -A version number (e.g., @samp{0.30}) can be specified. If Automake is not -newer than the version specified, creation of the @file{Makefile.in} -will be suppressed. - -@item @option{-W@var{category}} or @option{--warnings=@var{category}} -@cindex Option, warnings -@cindex Option, @option{-W@var{category}} -@cindex Option, @option{--warnings=@var{category}} -These options behave exactly like their command-line counterpart -(@pxref{automake Invocation}). This allows you to enable or disable some -warning categories on a per-file basis. You can also setup some warnings -for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])} -in your @file{configure.ac}. - -@end table - -Unrecognized options are diagnosed by @command{automake}. - -If you want an option to apply to all the files in the tree, you can use -the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}. -@xref{Macros}. - - -@node Miscellaneous -@chapter Miscellaneous Rules - -There are a few rules and variables that didn't fit anywhere else. - -@menu -* Tags:: Interfacing to cscope, etags and mkid -* Suffixes:: Handling new file extensions -@end menu - - -@node Tags -@section Interfacing to @command{etags} - -@cindex @file{TAGS} support - -Automake will generate rules to generate @file{TAGS} files for use with -GNU Emacs under some circumstances. - -@trindex tags -If any C, C++ or Fortran 77 source code or headers are present, then -@code{tags} and @code{TAGS} rules will be generated for the directory. -All files listed using the @code{_SOURCES}, @code{_HEADERS}, and -@code{_LISP} primaries will be used to generate tags. Note that -generated source files that are not distributed must be declared in -variables like @code{nodist_noinst_HEADERS} or -@code{nodist_@var{prog}_SOURCES} or they will be ignored. - -A @code{tags} rule will be output at the topmost directory of a -multi-directory package. When run from this topmost directory, -@samp{make tags} will generate a @file{TAGS} file that includes by -reference all @file{TAGS} files from subdirectories. - -The @code{tags} rule will also be generated if the variable -@code{ETAGS_ARGS} is defined. This variable is intended for use in -directories that contain taggable source that @command{etags} does -not understand. The user can use the @code{ETAGSFLAGS} to pass -additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also -available for use in @file{Makefile.am}. -@vindex ETAGS_ARGS -@vindex ETAGSFLAGS -@vindex AM_ETAGSFLAGS - -Here is how Automake generates tags for its source, and for nodes in its -Texinfo file: - -@example -ETAGS_ARGS = automake.in --lang=none \ - --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi -@end example - -If you add file names to @code{ETAGS_ARGS}, you will probably also -want to define @code{TAGS_DEPENDENCIES}. The contents of this variable -are added directly to the dependencies for the @code{tags} rule. -@vindex TAGS_DEPENDENCIES - -Automake also generates a @code{ctags} rule that can be used to -build @command{vi}-style @file{tags} files. The variable @code{CTAGS} -is the name of the program to invoke (by default @command{ctags}); -@code{CTAGSFLAGS} can be used by the user to pass additional flags, -and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}. - -@trindex id -Automake will also generate an @code{ID} rule that will run -@command{mkid} on the source. This is only supported on a -directory-by-directory basis. - -Similarly, the @code{cscope} rule will create a list of all the source -files in the tree and run @command{cscope} to build an inverted index -database. The variable @code{CSCOPE} is the name of the program to invoke -(by default @command{cscope}); @code{CSCOPEFLAGS} and -@code{CSCOPE_ARGS} can be used by the user to pass additional flags and -file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the -@file{Makefile.am}. Note that, currently, the Automake-provided -@code{cscope} support, when used in a VPATH build, might not work well -with non-GNU make implementations (especially with make implementations -performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf, -The Autoconf Manual}). - -Finally, Automake also emits rules to support the -@uref{https://www.gnu.org/software/global/, GNU Global Tags program}. -The @code{GTAGS} rule runs Global Tags and puts the -result in the top build directory. The variable @code{GTAGS_ARGS} -holds arguments that are passed to @command{gtags}. -@vindex GTAGS_ARGS - - -@node Suffixes -@section Handling new file extensions - -@cindex Adding new @code{SUFFIXES} -@cindex @code{SUFFIXES}, adding -@vindex SUFFIXES - -It is sometimes useful to introduce a new implicit rule to handle a file -type that Automake does not know about. - -For instance, suppose you had a compiler that could compile @file{.foo} -files to @file{.o} files. You would simply define a suffix rule for -your language: - -@example -.foo.o: - foocc -c -o $@@ $< -@end example - -Then you could directly use a @file{.foo} file in a @code{_SOURCES} -variable and expect the correct results: - -@example -bin_PROGRAMS = doit -doit_SOURCES = doit.foo -@end example - -This was the simpler and more common case. In other cases, you will -have to help Automake to figure out which extensions you are defining your -suffix rule for. This usually happens when your extension does not -start with a dot. Then, all you have to do is to put a list of new -suffixes in the @code{SUFFIXES} variable @strong{before} you define your -implicit rule. - -For instance, the following definition prevents Automake from misinterpreting -the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into -@file{.cpp} files. - -@c Keep in sync with suffix7.sh -@example -SUFFIXES = .idl C.cpp -.idlC.cpp: - # whatever -@end example - -As you may have noted, the @code{SUFFIXES} variable behaves like the -@code{.SUFFIXES} special target of @command{make}. You should not touch -@code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let -Automake generate the suffix list for @code{.SUFFIXES}. Any given -@code{SUFFIXES} go at the start of the generated suffixes list, followed -by Automake generated suffixes not already in the list. - -@node Include -@chapter Include - -@cmindex include -@cindex Including @file{Makefile} fragment -@cindex @file{Makefile} fragment, including - -Automake supports an @code{include} directive that can be used to -include other @file{Makefile} fragments when @command{automake} is run. -Note that these fragments are read and interpreted by @command{automake}, -not by @command{make}. As with conditionals, @command{make} has no idea that -@code{include} is in use. - -There are two forms of @code{include}: - -@table @code -@item include $(srcdir)/file -Include a fragment that is found relative to the current source -directory. - -@item include $(top_srcdir)/file -Include a fragment that is found relative to the top source directory. -@end table - -Note that if a fragment is included inside a conditional, then the -condition applies to the entire contents of that fragment. - -Makefile fragments included this way are always distributed because -they are needed to rebuild @file{Makefile.in}. - -Inside a fragment, the construct @code{%reldir%} is replaced with the -directory of the fragment relative to the base @file{Makefile.am}. -Similarly, @code{%canon_reldir%} is replaced with the canonicalized -(@pxref{Canonicalization}) form of @code{%reldir%}. As a convenience, -@code{%D%} is a synonym for @code{%reldir%}, and @code{%C%} -is a synonym for @code{%canon_reldir%}. - -A special feature is that if the fragment is in the same directory as -the base @file{Makefile.am} (i.e., @code{%reldir%} is @code{.}), then -@code{%reldir%} and @code{%canon_reldir%} will expand to the empty -string as well as eat, if present, a following slash or underscore -respectively. - -Thus, a makefile fragment might look like this: - -@example -bin_PROGRAMS += %reldir%/mumble -%canon_reldir%_mumble_SOURCES = %reldir%/one.c -@end example - -@node Conditionals -@chapter Conditionals - -@cindex Conditionals - -Automake supports a simple type of conditionals. - -These conditionals are not the same as conditionals in -GNU Make. Automake conditionals are checked at configure time by the -@file{configure} script, and affect the translation from -@file{Makefile.in} to @file{Makefile}. They are based on options passed -to @file{configure} and on results that @file{configure} has discovered -about the host system. GNU Make conditionals are checked at @command{make} -time, and are based on variables passed to the make program or defined -in the @file{Makefile}. - -Automake conditionals will work with any make program. - -@menu -* Usage of Conditionals:: Declaring conditional content -* Limits of Conditionals:: Enclosing complete statements -@end menu - -@node Usage of Conditionals -@section Usage of Conditionals - -@acindex AM_CONDITIONAL -Before using a conditional, you must define it by using -@code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}). - -@defmac AM_CONDITIONAL (@var{conditional}, @var{condition}) -The conditional name, @var{conditional}, should be a simple string -starting with a letter and containing only letters, digits, and -underscores. It must be different from @samp{TRUE} and @samp{FALSE} -that are reserved by Automake. - -The shell @var{condition} (suitable for use in a shell @code{if} -statement) is evaluated when @command{configure} is run. Note that you -must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every -time @command{configure} is run. If @code{AM_CONDITIONAL} is run -conditionally (e.g., in a shell @code{if} statement), then the result -will confuse @command{automake}. -@end defmac - -@cindex @option{--enable-debug}, example -@cindex Example conditional @option{--enable-debug} -@cindex Conditional example, @option{--enable-debug} - -Conditionals typically depend upon options that the user provides to -the @command{configure} script. Here is an example of how to write a -conditional that is true if the user uses the @option{--enable-debug} -option. - -@example -AC_ARG_ENABLE([debug], -[ --enable-debug Turn on debugging], -[case "$@{enableval@}" in - yes) debug=true ;; - no) debug=false ;; - *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;; -esac],[debug=false]) -AM_CONDITIONAL([DEBUG], [test x$debug = xtrue]) -@end example - -Here is an example of how to use that conditional in @file{Makefile.am}: - -@cmindex if -@cmindex endif -@cmindex else - -@example -if DEBUG -DBG = debug -else -DBG = -endif -noinst_PROGRAMS = $(DBG) -@end example - -This trivial example could also be handled using @code{EXTRA_PROGRAMS} -(@pxref{Conditional Programs}). - -You may only test a single variable in an @code{if} statement, possibly -negated using @samp{!}. The @code{else} statement may be omitted. -Conditionals may be nested to any depth. You may specify an argument to -@code{else} in which case it must be the negation of the condition used -for the current @code{if}. Similarly you may specify the condition -that is closed on the @code{endif} line: - -@example -if DEBUG -DBG = debug -else !DEBUG -DBG = -endif !DEBUG -@end example - -@noindent -Unbalanced conditions are errors. The @code{if}, @code{else}, and -@code{endif} statements should not be indented, i.e., start on column -one. - -The @code{else} branch of the above two examples could be omitted, -since assigning the empty string to an otherwise undefined variable -makes no difference. - -@acindex AM_COND_IF -In order to allow access to the condition registered by -@code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow -conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used: - -@defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false}) -If @var{conditional} is fulfilled, execute @var{if-true}, otherwise -execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES}, -it will cause @command{automake} to output the rules for the respective -files only for the given condition. -@end defmac - -@code{AM_COND_IF} macros may be nested when m4 quotation is used -properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}). - -@cindex Example conditional @code{AC_CONFIG_FILES} -@cindex @code{AC_CONFIG_FILES}, conditional - -Here is an example of how to define a conditional config file: - -@example -AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue]) -AM_COND_IF([SHELL_WRAPPER], - [AC_CONFIG_FILES([wrapper:wrapper.in])]) -@end example - -@node Limits of Conditionals -@section Limits of Conditionals - -Conditionals should enclose complete statements like variables or -rules definitions. Automake cannot deal with conditionals used inside -a variable definition, for instance, and is not even able to diagnose -this situation. The following example would not work: - -@example -# This syntax is not understood by Automake -AM_CPPFLAGS = \ - -DFEATURE_A \ -if WANT_DEBUG - -DDEBUG \ -endif - -DFEATURE_B -@end example - -However the intended definition of @code{AM_CPPFLAGS} can be achieved -with - -@example -if WANT_DEBUG - DEBUGFLAGS = -DDEBUG -endif -AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B -@end example - -@noindent -or - -@example -AM_CPPFLAGS = -DFEATURE_A -if WANT_DEBUG -AM_CPPFLAGS += -DDEBUG -endif -AM_CPPFLAGS += -DFEATURE_B -@end example - -More details and examples of conditionals are described alongside -various Automake features in this manual (@pxref{Conditional -Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional -Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional -Libtool Sources}). - -@node Silencing Make -@chapter Silencing @command{make} - -@cindex Silent @command{make} -@cindex Silencing @command{make} -@cindex Silent rules -@cindex Silent @command{make} rules - -@menu -* 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 -@end menu - -@node Make verbosity -@section Make is verbose by default - -Normally, when executing the set of rules associated with a target, -@command{make} prints each rule before it is executed. This behaviour, -while having been in place for a long time, and being even mandated by -the POSIX standard, starkly violates the ``silence is golden'' UNIX -principle@footnote{See also -@uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}: - -@quotation -When a program has nothing interesting or surprising to say, it should -say nothing. Well-behaved Unix programs do their jobs unobtrusively, -with a minimum of fuss and bother. Silence is golden. -@end quotation - -In fact, while such verbosity of @command{make} can theoretically be -useful to track bugs and understand reasons of failures right away, it -can also hide warning and error messages from @command{make}-invoked -tools, drowning them in a flood of uninteresting and seldom useful -messages, and thus allowing them to go easily undetected. - -This problem can be very annoying, especially for developers, who usually -know quite well what's going on behind the scenes, and for whom the -verbose output from @command{make} ends up being mostly noise that hampers -the easy detection of potentially important warning messages. - -@node Tricks For Silencing Make -@section Standard and generic ways to silence make - -Here we describe some common idioms/tricks to obtain a quieter make -output, with their relative advantages and drawbacks. In the next -section (@ref{Automake Silent Rules}) we'll see how Automake can help -in this respect, providing more elaborate and flexible idioms. - -@itemize @bullet - -@item @command{make -s} - -This simply causes @command{make} not to print @emph{any} rule before -executing it. - -The @option{-s} flag is mandated by POSIX, universally supported, and -its purpose and function are easy to understand. - -But it also has its serious limitations too. First of all, it embodies -an ``all or nothing'' strategy, i.e., either everything is silenced, or -nothing is; this lack of granularity can sometimes be a fatal flaw. -Moreover, when the @option{-s} flag is used, the @command{make} output -might turn out to be too much terse; in case of errors, the user won't -be able to easily see what rule or command have caused them, or even, -in case of tools with poor error reporting, what the errors were! - -@item @command{make >/dev/null || make} - -Apparently, this perfectly obeys the ``silence is golden'' rule: warnings -from stderr are passed through, output reporting is done only in case of -error, and in that case it should provide a verbose-enough report to allow -an easy determination of the error location and causes. - -However, calling @command{make} two times in a row might hide errors -(especially intermittent ones), or subtly change the expected semantic -of the @command{make} calls --- things these which can clearly make -debugging and error assessment very difficult. - -@item @command{make --no-print-directory} - -This is GNU @command{make} specific. When called with the -@option{--no-print-directory} option, GNU @command{make} will disable -printing of the working directory by invoked sub-@command{make}s (the -well-known ``@i{Entering/Leaving directory ...}'' messages). This helps -to decrease the verbosity of the output, but experience has shown that -it can also often render debugging considerably harder in projects using -deeply-nested @command{make} recursion. - -As an aside, notice that the @option{--no-print-directory} option is -automatically activated if the @option{-s} flag is used. - -@c TODO: Other tricks? -@c TODO: Maybe speak about the @code{.SILENT} target? -@c TODO: - Pros: More granularity on what to silence. -@c TODO: - Cons: No easy way to temporarily override. - -@end itemize - -@node Automake Silent Rules -@section How Automake can help in silencing make - -The tricks and idioms for silencing @command{make} described in the -previous section can be useful from time to time, but we've seen that -they all have their serious drawbacks and limitations. That's why -automake provides support for a more advanced and flexible way of -obtaining quieter output from @command{make} (for most rules at least). - -To give the gist of what Automake can do in this respect, here is a simple -comparison between a typical @command{make} output (where silent rules -are disabled) and one with silent rules enabled: - -@example -% @kbd{cat Makefile.am} -bin_PROGRAMS = foo -foo_SOURCES = main.c func.c -% @kbd{cat main.c} -int main (void) @{ return func (); @} /* func used undeclared */ -% @kbd{cat func.c} -int func (void) @{ int i; return i; @} /* i used uninitialized */ - -@i{The make output is by default very verbose. This causes warnings -from the compiler to be somewhat hidden, and not immediate to spot.} -% @kbd{make CFLAGS=-Wall} -gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ... --DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ... --DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o --MD -MP -MF .deps/main.Tpo -c -o main.o main.c -main.c: In function ‘main’: -main.c:3:3: warning: implicit declaration of function ‘func’ -mv -f .deps/main.Tpo .deps/main.Po -gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ... --DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ... --DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o --MD -MP -MF .deps/func.Tpo -c -o func.o func.c -func.c: In function ‘func’: -func.c:4:3: warning: ‘i’ used uninitialized in this function -mv -f .deps/func.Tpo .deps/func.Po -gcc -Wall -o foo main.o func.o - -@i{Clean up, so that we we can rebuild everything from scratch.} -% @kbd{make clean} -test -z "foo" || rm -f foo -rm -f *.o - -@i{Silent rules enabled: the output is minimal but informative. In -particular, the warnings from the compiler stick out very clearly.} -% @kbd{make V=0 CFLAGS=-Wall} - CC main.o -main.c: In function ‘main’: -main.c:3:3: warning: implicit declaration of function ‘func’ - CC func.o -func.c: In function ‘func’: -func.c:4:3: warning: ‘i’ used uninitialized in this function - CCLD foo -@end example - -@cindex silent rules and libtool -Also, in projects using @command{libtool}, the use of silent rules can -automatically enable the @command{libtool}'s @option{--silent} option: - -@example -% @kbd{cat Makefile.am} -lib_LTLIBRARIES = libx.la - -% @kbd{make # Both make and libtool are verbose by default.} -... -libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\" - -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC - -DPIC -o .libs/libx.o -mv -f .deps/libx.Tpo .deps/libx.Plo -/bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath - /usr/local/lib libx.lo -libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0 - -o .libs/libx.so.0.0.0 -libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so -... - -% @kbd{make V=0} - CC libx.lo - CCLD libx.la -@end example - -For Automake-generated @file{Makefile}s, the user may influence the -verbosity at @command{configure} run time as well as at @command{make} -run time: - -@itemize @bullet -@item -@opindex --enable-silent-rules -@opindex --disable-silent-rules -Passing @option{--enable-silent-rules} to @command{configure} will cause -build rules to be less verbose; the option @option{--disable-silent-rules} -will cause normal verbose output. -@item -@vindex @code{V} -At @command{make} run time, the default chosen at @command{configure} -time may be overridden: @code{make V=1} will produce verbose output, -@code{make V=0} less verbose output. -@end itemize - -@cindex default verbosity for silent rules -Note that silent rules are @emph{disabled} by default; the user must -enable them explicitly at either @command{configure} run time or at -@command{make} run time. We think that this is a good policy, since -it provides the casual user with enough information to prepare a good -bug report in case anything breaks. - -Still, notwithstanding the rationales above, a developer who really -wants to make silent rules enabled by default in his own package can -do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}. - -@c Keep in sync with silent-configsite.sh -Users who prefer to have silent rules enabled by default can edit their -@file{config.site} file to make the variable @code{enable_silent_rules} -default to @samp{yes}. This should still allow disabling silent rules -at @command{configure} time and at @command{make} time. - -@c FIXME: there's really a need to specify this explicitly? -For portability to different @command{make} implementations, package authors -are advised to not set the variable @code{V} inside the @file{Makefile.am} -file, to allow the user to override the value for subdirectories as well. - -To work at its best, the current implementation of this feature normally -uses nested variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile} -feature that is not required by POSIX 2008 but is widely supported in -practice. On the rare @command{make} implementations that do not support -nested variable expansion, whether rules are silent is always determined at -configure time, and cannot be overridden at make time. Future versions of -POSIX are likely to require nested variable expansion, so this minor -limitation should go away with time. - -@vindex @code{AM_V_GEN} -@vindex @code{AM_V_at} -@vindex @code{AM_DEFAULT_VERBOSITY} -@vindex @code{AM_V} -@vindex @code{AM_DEFAULT_V} -To extend the silent mode to your own rules, you have few choices: - -@itemize @bullet - -@item -You can use the predefined variable @code{AM_V_GEN} as a prefix to -commands that should output a status line in silent mode, and -@code{AM_V_at} as a prefix to commands that should not output anything -in silent mode. When output is to be verbose, both of these variables -will expand to the empty string. - -@item -You can silence a recipe unconditionally with @code{@@}, and then use -the predefined variable @code{AM_V_P} to know whether make is being run -in silent or verbose mode, adjust the verbose information your recipe -displays accordingly: - -@example -generate-headers: - @set -e; \ - ... [commands defining a shell variable '$headers'] ...; \ - if $(AM_V_P); then set -x; else echo " GEN [headers]"; fi; \ - rm -f $$headers && generate-header --flags $$headers -@end example - -@item -You can add your own variables, so strings of your own choice are shown. -The following snippet shows how you would define your own equivalent of -@code{AM_V_GEN}: - -@example -pkg_verbose = $(pkg_verbose_@@AM_V@@) -pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@) -pkg_verbose_0 = @@echo PKG-GEN $@@; - -foo: foo.in - $(pkg_verbose)cp $(srcdir)/foo.in $@@ -@end example - -@end itemize - -As a final note, observe that, even when silent rules are enabled, -the @option{--no-print-directory} option is still required with GNU -@command{make} if the ``@i{Entering/Leaving directory ...}'' messages -are to be disabled. - -@node Gnits -@chapter The effect of @option{--gnu} and @option{--gnits} - -@cindex @option{--gnu}, required files -@cindex @option{--gnu}, complete description - -The @option{--gnu} option (or @option{gnu} in the -@code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check -the following: - -@itemize @bullet -@item -The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS}, -and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER} -or @file{COPYING}, are required at the topmost directory of the package. - -If the @option{--add-missing} option is given, @command{automake} will -add a generic version of the @file{INSTALL} file as well as the -@file{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, @uref{https://www.gnu.org/@/copyleft/@/gpl.html}). -However, an existing @file{COPYING} file will never be overwritten by -@command{automake}. - -@item -The options @option{no-installman} and @option{no-installinfo} are -prohibited. -@end itemize - -Note that this option will be extended in the future to do even more -checking; it is advisable to be familiar with the precise requirements -of the GNU standards. Also, @option{--gnu} can require certain -non-standard GNU programs to exist for use by various maintainer-only -rules; for instance, in the future @command{pathchk} might be required for -@samp{make dist}. - -@cindex @option{--gnits}, complete description - -The @option{--gnits} option does everything that @option{--gnu} does, and -checks the following as well: - -@itemize @bullet -@item -@samp{make installcheck} will check to make sure that the @option{--help} -and @option{--version} really print a usage message and a version string, -respectively. This is the @option{std-options} option (@pxref{Options}). - -@item -@samp{make dist} will check to make sure the @file{NEWS} file has been -updated to the current version. - -@item -@code{VERSION} is checked to make sure its format complies with Gnits -standards. -@c FIXME xref when standards are finished - -@item -@cindex @file{README-alpha} -If @code{VERSION} indicates that this is an alpha release, and the file -@file{README-alpha} appears in the topmost directory of a package, then -it is included in the distribution. This is done in @option{--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 @file{README-alpha} should be -included. - -@item -The file @file{THANKS} is required. -@end itemize - - -@node Not Enough -@chapter When Automake Isn't Enough - -In some situations, where Automake is not up to one task, one has to -resort to handwritten rules or even handwritten @file{Makefile}s. - -@menu -* Extending:: Adding new rules or overriding existing ones. -* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s. -@end menu - -@node Extending -@section Extending Automake Rules - -With some minor exceptions (for example @code{_PROGRAMS} variables, -@code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append -@samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to -@file{Makefile.in} verbatim. - -@cindex copying semantics - -These copying semantics mean that many problems can be worked around -by simply adding some @command{make} variables and rules to -@file{Makefile.am}. Automake will ignore these additions. - -@cindex conflicting definitions -@cindex rules, conflicting -@cindex variables, conflicting -@cindex definitions, conflicts - -Since a @file{Makefile.in} is built from data gathered from three -different places (@file{Makefile.am}, @file{configure.ac}, and -@command{automake} itself), it is possible to have conflicting -definitions of rules or variables. When building @file{Makefile.in} -the following priorities are respected by @command{automake} to ensure -the user always has the last word: - -@itemize -@item -User defined variables in @file{Makefile.am} have priority over -variables @code{AC_SUBST}ed from @file{configure.ac}, and -@code{AC_SUBST}ed variables have priority over -@command{automake}-defined variables. -@item -As far as rules are concerned, a user-defined rule overrides any -@command{automake}-defined rule for the same target. -@end itemize - -@cindex overriding rules -@cindex overriding semantics -@cindex rules, overriding - -These overriding semantics make it possible to fine tune some default -settings of Automake, or replace some of its rules. Overriding -Automake rules is often inadvisable, particularly in the topmost -directory of a package with subdirectories. The @option{-Woverride} -option (@pxref{automake Invocation}) comes in handy to catch overridden -definitions. - -Note that Automake does not make any distinction between rules with -commands and rules that only specify dependencies. So it is not -possible to append new dependencies to an @command{automake}-defined -target without redefining the entire rule. - -@cindex @option{-local} targets -@cindex local targets - -However, various useful targets have a @samp{-local} version you can -specify in your @file{Makefile.am}. Automake will supplement the -standard target with these user-supplied targets. - -@trindex all -@trindex all-local -@trindex info -@trindex info-local -@trindex dvi -@trindex dvi-local -@trindex ps -@trindex ps-local -@trindex pdf -@trindex pdf-local -@trindex html -@trindex html-local -@trindex check -@trindex check-local -@trindex install -@trindex install-data -@trindex install-data-local -@trindex install-dvi -@trindex install-dvi-local -@trindex install-exec -@trindex install-exec-local -@trindex install-html -@trindex install-html-local -@trindex install-info -@trindex install-info-local -@trindex install-pdf -@trindex install-pdf-local -@trindex install-ps -@trindex install-ps-local -@trindex uninstall -@trindex uninstall-local -@trindex mostlyclean -@trindex mostlyclean-local -@trindex clean -@trindex clean-local -@trindex distclean -@trindex distclean-local -@trindex installdirs -@trindex installdirs-local -@trindex installcheck -@trindex installcheck-local - -The targets that support a local version are @code{all}, @code{info}, -@code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check}, -@code{install-data}, @code{install-dvi}, @code{install-exec}, -@code{install-html}, @code{install-info}, @code{install-pdf}, -@code{install-ps}, @code{uninstall}, @code{installdirs}, -@code{installcheck} and the various @code{clean} targets -(@code{mostlyclean}, @code{clean}, @code{distclean}, and -@code{maintainer-clean}). - -Note that there are no @code{uninstall-exec-local} or -@code{uninstall-data-local} targets; just use @code{uninstall-local}. -It doesn't make sense to uninstall just data or just executables. - -For instance, here is one way to erase a subdirectory during -@samp{make clean} (@pxref{Clean}). - -@example -clean-local: - -rm -rf testSubDir -@end example - -You may be tempted to use @code{install-data-local} to install a file -to some hard-coded location, but you should avoid this -(@pxref{Hard-Coded Install Paths}). - -With the @code{-local} targets, there is no particular guarantee of -execution order; typically, they are run early, but with parallel -make, there is no way to be sure of that. - -@cindex @option{-hook} targets -@cindex hook targets -@trindex install-data-hook -@trindex install-exec-hook -@trindex uninstall-hook -@trindex dist-hook - -In contrast, some rules also have a way to run another rule, called a -@dfn{hook}; hooks are always executed after the main rule's work is done. -The hook is named after the principal target, with @samp{-hook} appended. -The targets allowing hooks are @code{install-data}, -@code{install-exec}, @code{uninstall}, @code{dist}, and -@code{distcheck}. - -For instance, here is how to create a hard link to an installed program: - -@example -install-exec-hook: - ln $(DESTDIR)$(bindir)/program$(EXEEXT) \ - $(DESTDIR)$(bindir)/proglink$(EXEEXT) -@end example - -Although cheaper and more portable than symbolic links, hard links -will not work everywhere (for instance, OS/2 does not have -@command{ln}). Ideally you should fall back to @samp{cp -p} when -@command{ln} does not work. An easy way, if symbolic links are -acceptable to you, is to add @code{AC_PROG_LN_S} to -@file{configure.ac} (@pxref{Particular Programs, , Particular Program -Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in -@file{Makefile.am}. - -@cindex versioned binaries, installing -@cindex installing versioned binaries -@cindex @code{LN_S} example -For instance, here is how you could install a versioned copy of a -program using @samp{$(LN_S)}: - -@c Keep in sync with insthook.sh -@example -install-exec-hook: - cd $(DESTDIR)$(bindir) && \ - mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \ - $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT) -@end example - -Note that we rename the program so that a new version will erase the -symbolic link, not the real binary. Also we @command{cd} into the -destination directory in order to create relative links. - -When writing @code{install-exec-hook} or @code{install-data-hook}, -please bear in mind that the exec/data distinction is based on the -installation directory, not on the primary used (@pxref{The Two Parts of -Install}). -@c Keep in sync with primary-prefix-couples-documented-valid.sh -So a @code{foo_SCRIPTS} will be installed by -@code{install-data}, and a @code{barexec_SCRIPTS} will be installed by -@code{install-exec}. You should define your hooks consequently. - -@c FIXME should include discussion of variables you can use in these -@c rules - -@node Third-Party Makefiles -@section Third-Party @file{Makefile}s - -@cindex Third-party packages, interfacing with -@cindex Interfacing with third-party packages - -In most projects all @file{Makefile}s are generated by Automake. In -some cases, however, projects need to embed subdirectories with -handwritten @file{Makefile}s. For instance, one subdirectory could be -a third-party project with its own build system, not using Automake. - -It is possible to list arbitrary directories in @code{SUBDIRS} or -@code{DIST_SUBDIRS} provided each of these directories has a -@file{Makefile} that recognizes all the following recursive targets. - -@cindex recursive targets and third-party @file{Makefile}s -When a user runs one of these targets, that target is run recursively -in all subdirectories. This is why it is important that even -third-party @file{Makefile}s support them. - -@table @code -@item all -Compile the entire package. This is the default target in -Automake-generated @file{Makefile}s, but it does not need to be the -default in third-party @file{Makefile}s. - -@item distdir -@trindex distdir -@vindex distdir -@vindex top_distdir -Copy files to distribute into @samp{$(distdir)}, before a tarball is -constructed. Of course this target is not required if the -@option{no-dist} option (@pxref{Options}) is used. - -The variables @samp{$(top_distdir)} and @samp{$(distdir)} -(@pxref{The dist Hook}) will be passed from the outer package to the subpackage -when the @code{distdir} target is invoked. These two variables have -been adjusted for the directory that is being recursed into, so they -are ready to use. - -@item install -@itemx install-data -@itemx install-exec -@itemx uninstall -Install or uninstall files (@pxref{Install}). - -@item install-dvi -@itemx install-html -@itemx install-info -@itemx install-ps -@itemx install-pdf -Install only some specific documentation format (@pxref{Texinfo}). - -@item installdirs -Create install directories, but do not install any files. - -@item check -@itemx installcheck -Check the package (@pxref{Tests}). - -@item mostlyclean -@itemx clean -@itemx distclean -@itemx maintainer-clean -Cleaning rules (@pxref{Clean}). - -@item dvi -@itemx pdf -@itemx ps -@itemx info -@itemx html -Build the documentation in various formats (@pxref{Texinfo}). - -@item tags -@itemx ctags -Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}). -@end table - -If you have ever used Gettext in a project, this is a good example of -how third-party @file{Makefile}s can be used with Automake. The -@file{Makefile}s @command{gettextize} puts in the @file{po/} and -@file{intl/} directories are handwritten @file{Makefile}s that -implement all of these targets. That way they can be added to -@code{SUBDIRS} in Automake packages. - -Directories that are only listed in @code{DIST_SUBDIRS} but not in -@code{SUBDIRS} need only the @code{distclean}, -@code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional -Subdirectories}). - -Usually, many of these rules are irrelevant to the third-party -subproject, but they are required for the whole package to work. It's -OK to have a rule that does nothing, so if you are integrating a -third-party project with no documentation or tag support, you could -simply augment its @file{Makefile} as follows: - -@example -EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags -.PHONY: $(EMPTY_AUTOMAKE_TARGETS) -$(EMPTY_AUTOMAKE_TARGETS): -@end example - -Another aspect of integrating third-party build systems is whether -they support VPATH builds (@pxref{VPATH Builds}). Obviously if the -subpackage does not support VPATH builds the whole package will not -support VPATH builds. This in turns means that @samp{make distcheck} -will not work, because it relies on VPATH builds. Some people can -live without this (actually, many Automake users have never heard of -@samp{make distcheck}). Other people may prefer to revamp the -existing @file{Makefile}s to support VPATH@. Doing so does not -necessarily require Automake, only Autoconf is needed (@pxref{Build -Directories, , Build Directories, autoconf, The Autoconf Manual}). -The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@}, -and @samp{@@top_builddir@@} are defined by @file{configure} when it -processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset -Output Variables, autoconf, The Autoconf Manual}), they are not -computed by the Makefile like the aforementioned @samp{$(distdir)} and -@samp{$(top_distdir)} variables. - -It is sometimes inconvenient to modify a third-party @file{Makefile} -to introduce the above required targets. For instance, one may want to -keep the third-party sources untouched to ease upgrades to new -versions. - -@cindex @file{GNUmakefile} including @file{Makefile} -Here are two other ideas. If GNU make is assumed, one possibility is -to add to that subdirectory a @file{GNUmakefile} that defines the -required targets and includes the third-party @file{Makefile}. For -this to work in VPATH builds, @file{GNUmakefile} must lie in the build -directory; the easiest way to do this is to write a -@file{GNUmakefile.in} instead, and have it processed with -@code{AC_CONFIG_FILES} from the outer package. For example if we -assume @file{Makefile} defines all targets except the documentation -targets, and that the @code{check} target is actually called -@code{test}, we could write @file{GNUmakefile} (or -@file{GNUmakefile.in}) like this: - -@example -# First, include the real Makefile -include Makefile -# Then, define the other targets needed by Automake Makefiles. -.PHONY: dvi pdf ps info html check -dvi pdf ps info html: -check: test -@end example - -@cindex Proxy @file{Makefile} for third-party packages -A similar idea that does not use @code{include} is to write a proxy -@file{Makefile} that dispatches rules to the real @file{Makefile}, -either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if -it's OK to rename the original @file{Makefile}) or with @samp{cd -subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the -subdirectory project one directory deeper). The good news is that -this proxy @file{Makefile} can be generated with Automake. All we -need are @option{-local} targets (@pxref{Extending}) that perform the -dispatch. Of course the other Automake features are available, so you -could decide to let Automake perform distribution or installation. -Here is a possible @file{Makefile.am}: - -@example -all-local: - cd subdir && $(MAKE) $(AM_MAKEFLAGS) all -check-local: - cd subdir && $(MAKE) $(AM_MAKEFLAGS) test -clean-local: - cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean - -# Assuming the package knows how to install itself -install-data-local: - cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data -install-exec-local: - cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec -uninstall-local: - cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall - -# Distribute files from here. -EXTRA_DIST = subdir/Makefile subdir/program.c ... -@end example - -Pushing this idea to the extreme, it is also possible to ignore the -subproject build system and build everything from this proxy -@file{Makefile.am}. This might sound very sensible if you need VPATH -builds but the subproject does not support them. - -@node Distributing -@chapter Distributing @file{Makefile.in}s - -Automake places no restrictions on the distribution of the resulting -@file{Makefile.in}s. We still encourage software authors to -distribute their work under terms like those of the GPL, but doing so -is not required to use Automake. - -Some of the files that can be automatically installed via the -@option{--add-missing} switch do fall under the GPL@. However, these also -have a special exception allowing you to distribute them with your -package, regardless of the licensing you choose. - - -@node API Versioning -@chapter Automake API Versioning - -New Automake releases usually include bug fixes and new features. -Unfortunately they may also introduce new bugs and incompatibilities. -This makes four reasons why a package may require a particular Automake -version. - -Things get worse when maintaining a large tree of packages, each one -requiring a different version of Automake. In the past, this meant that -any developer (and sometimes users) had to install several versions of -Automake in different places, and switch @samp{$PATH} appropriately for -each package. - -Starting with version 1.6, Automake installs versioned binaries. This -means you can install several versions of Automake in the same -@samp{$prefix}, and can select an arbitrary Automake version by running -@command{automake-1.6} or @command{automake-1.7} without juggling with -@samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6 -will use @command{automake-1.6} explicitly in their rebuild rules. - -The number @samp{1.6} in @command{automake-1.6} is Automake's API version, -not Automake's version. If a bug fix release is made, for instance -Automake 1.6.1, the API version will remain 1.6. This means that a -package that works with Automake 1.6 should also work with 1.6.1; after -all, this is what people expect from bug fix releases. - -If your package relies on a feature or a bug fix introduced in -a release, you can pass this version as an option to Automake to ensure -older releases will not be used. For instance, use this in your -@file{configure.ac}: - -@example - AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better. -@end example - -@noindent -or, in a particular @file{Makefile.am}: - -@example - AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better. -@end example - -@noindent -Automake will print an error message if its version is -older than the requested version. - - -@heading What is in the API - -Automake's programming interface is not easy to define. Basically it -should include at least all @strong{documented} variables and targets -that a @file{Makefile.am} author can use, any behavior associated with -them (e.g., the places where @samp{-hook}'s are run), the command line -interface of @command{automake} and @command{aclocal}, @dots{} - -@heading What is not in the API - -Every undocumented variable, target, or command line option, is not part -of the API@. You should avoid using them, as they could change from one -version to the other (even in bug fix releases, if this helps to fix a -bug). - -If it turns out you need to use such an undocumented feature, contact -@email{automake@@gnu.org} and try to get it documented and exercised by -the test-suite. - -@node Upgrading -@chapter Upgrading a Package to a Newer Automake Version - -Automake maintains three kind of files in a package. - -@itemize -@item @file{aclocal.m4} -@item @file{Makefile.in}s -@item auxiliary tools like @file{install-sh} or @file{py-compile} -@end itemize - -@file{aclocal.m4} is generated by @command{aclocal} and contains some -Automake-supplied M4 macros. Auxiliary tools are installed by -@samp{automake --add-missing} when needed. @file{Makefile.in}s are -built from @file{Makefile.am} by @command{automake}, and rely on the -definitions of the M4 macros put in @file{aclocal.m4} as well as the -behavior of the auxiliary tools installed. - -Because all of these files are closely related, it is important to -regenerate all of them when upgrading to a newer Automake release. -The usual way to do that is - -@example -aclocal # with any option needed (such a -I m4) -autoconf -automake --add-missing --force-missing -@end example - -@noindent -or more conveniently: - -@example -autoreconf -vfi -@end example - -The use of @option{--force-missing} ensures that auxiliary tools will be -overridden by new versions (@pxref{automake Invocation}). - -It is important to regenerate all of these files each time Automake is -upgraded, even between bug fixes releases. For instance, it is not -unusual for a bug fix to involve changes to both the rules generated -in @file{Makefile.in} and the supporting M4 macros copied to -@file{aclocal.m4}. - -Presently @command{automake} is able to diagnose situations where -@file{aclocal.m4} has been generated with another version of -@command{aclocal}. However it never checks whether auxiliary scripts -are up-to-date. In other words, @command{automake} will tell you when -@command{aclocal} needs to be rerun, but it will never diagnose a -missing @option{--force-missing}. - -Before upgrading to a new major release, it is a good idea to read the -file @file{NEWS}. This file lists all changes between releases: new -features, obsolete constructs, known incompatibilities, and -workarounds. - -@node FAQ -@chapter Frequently Asked Questions about Automake - -This chapter covers some questions that often come up on the mailing -lists. - -@menu -* 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 -@end menu - -@node CVS -@section CVS and generated files - -@subheading Background: distributed generated Files -@cindex generated files, distributed -@cindex rebuild rules - -Packages made with Autoconf and Automake ship with some generated -files like @file{configure} or @file{Makefile.in}. These files were -generated on the developer's machine and are distributed so that -end-users do not have to install the maintainer tools required to -rebuild them. Other generated files like Lex scanners, Yacc parsers, -or Info documentation, are usually distributed on similar grounds. - -Automake output rules in @file{Makefile}s to rebuild these files. For -instance, @command{make} will run @command{autoconf} to rebuild -@file{configure} whenever @file{configure.ac} is changed. This makes -development safer by ensuring a @file{configure} is never out-of-date -with respect to @file{configure.ac}. - -As generated files shipped in packages are up-to-date, and because -@command{tar} preserves times-tamps, these rebuild rules are not -triggered when a user unpacks and builds a package. - -@subheading Background: CVS and Timestamps -@cindex timestamps and CVS -@cindex CVS and timestamps - -Unless you use CVS keywords (in which case files must be updated at -commit time), CVS preserves timestamp during @samp{cvs commit} and -@samp{cvs import -d} operations. - -When you check out a file using @samp{cvs checkout} its timestamp is -set to that of the revision that is being checked out. - -However, during @command{cvs update}, files will have the date of the -update, not the original timestamp of this revision. This is meant to -make sure that @command{make} notices sources files have been updated. - -This timestamp shift is troublesome when both sources and generated -files are kept under CVS@. Because CVS processes files in lexical -order, @file{configure.ac} will appear newer than @file{configure} -after a @command{cvs update} that updates both files, even if -@file{configure} was newer than @file{configure.ac} when it was -checked in. Calling @command{make} will then trigger a spurious rebuild -of @file{configure}. - -@subheading Living with CVS in Autoconfiscated Projects -@cindex CVS and generated files -@cindex generated files and CVS - -There are basically two clans amongst maintainers: those who keep all -distributed files under CVS, including generated files, and those who -keep generated files @emph{out} of CVS. - -@subsubheading All Files in CVS - -@itemize @bullet -@item -The CVS repository contains all distributed files so you know exactly -what is distributed, and you can checkout any prior version entirely. - -@item -Maintainers can see how generated files evolve (for instance, you can -see what happens to your @file{Makefile.in}s when you upgrade Automake -and make sure they look OK). - -@item -Users do not need the autotools to build a checkout of the project, it -works just like a released tarball. - -@item -If users use @command{cvs update} to update their copy, instead of -@command{cvs checkout} to fetch a fresh one, timestamps will be -inaccurate. Some rebuild rules will be triggered and attempt to -run developer tools such as @command{autoconf} or @command{automake}. - -Calls to such tools are all wrapped into a call to the @command{missing} -script discussed later (@pxref{maintainer-mode}), so that the user will -see more descriptive warnings about missing or out-of-date tools, and -possible suggestions about how to obtain them, rather than just some -``command not found'' error, or (worse) some obscure message from some -older version of the required tool they happen to have installed. - -Maintainers interested in keeping their package buildable from a CVS -checkout even for those users that lack maintainer-specific tools might -want to provide an helper script (or to enhance their existing bootstrap -script) to fix the timestamps after a -@command{cvs update} or a @command{git checkout}, to prevent spurious -rebuilds. In case of a project committing the Autotools-generated -files, as well as the generated @file{.info} files, such script might -look something like this: - -@smallexample -#!/bin/sh -# fix-timestamp.sh: prevents useless rebuilds after "cvs update" -sleep 1 -# aclocal-generated aclocal.m4 depends on locally-installed -# '.m4' macro files, as well as on 'configure.ac' -touch aclocal.m4 -sleep 1 -# autoconf-generated configure depends on aclocal.m4 and on -# configure.ac -touch configure -# so does autoheader-generated config.h.in -touch config.h.in -# and all the automake-generated Makefile.in files -touch `find . -name Makefile.in -print` -# finally, the makeinfo-generated '.info' files depend on the -# corresponding '.texi' files -touch doc/*.info -@end smallexample - -@item -In distributed development, developers are likely to have different -version of the maintainer tools installed. In this case rebuilds -triggered by timestamp lossage will lead to spurious changes -to generated files. There are several solutions to this: - -@itemize -@item -All developers should use the same versions, so that the rebuilt files -are identical to files in CVS@. (This starts to be difficult when each -project you work on uses different versions.) -@item -Or people use a script to fix the timestamp after a checkout (the GCC -folks have such a script). -@item -Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will -disable all of these rebuild rules by default. This is further discussed -in @ref{maintainer-mode}. -@end itemize - -@item -Although we focused on spurious rebuilds, the converse can also -happen. CVS's timestamp handling can also let you think an -out-of-date file is up-to-date. - -For instance, suppose a developer has modified @file{Makefile.am} and -has rebuilt @file{Makefile.in}, and then decides to do a last-minute -change to @file{Makefile.am} right before checking in both files -(without rebuilding @file{Makefile.in} to account for the change). - -This last change to @file{Makefile.am} makes the copy of -@file{Makefile.in} out-of-date. Since CVS processes files -alphabetically, when another developer @samp{cvs update}s his or her -tree, @file{Makefile.in} will happen to be newer than -@file{Makefile.am}. This other developer will not see that -@file{Makefile.in} is out-of-date. - -@end itemize - -@subsubheading Generated Files out of CVS - -One way to get CVS and @command{make} working peacefully is to never -store generated files in CVS, i.e., do not CVS-control files that -are @file{Makefile} targets (also called @emph{derived} files). - -This way developers are not annoyed by changes to generated files. It -does not matter if they all have different versions (assuming they are -compatible, of course). And finally, timestamps are not lost, changes -to sources files can't be missed as in the -@file{Makefile.am}/@file{Makefile.in} example discussed earlier. - -The drawback is that the CVS repository is not an exact copy of what -is distributed and that users now need to install various development -tools (maybe even specific versions) before they can build a checkout. -But, after all, CVS's job is versioning, not distribution. - -Allowing developers to use different versions of their tools can also -hide bugs during distributed development. Indeed, developers will be -using (hence testing) their own generated files, instead of the -generated files that will be released actually. The developer who -prepares the tarball might be using a version of the tool that -produces bogus output (for instance a non-portable C file), something -other developers could have noticed if they weren't using their own -versions of this tool. - -@subheading Third-party Files -@cindex CVS and third-party files -@cindex third-party files and CVS - -Another class of files not discussed here (because they do not cause -timestamp issues) are files that are shipped with a package, but -maintained elsewhere. For instance, tools like @command{gettextize} -and @command{autopoint} (from Gettext) or @command{libtoolize} (from -Libtool), will install or update files in your package. - -These files, whether they are kept under CVS or not, raise similar -concerns about version mismatch between developers' tools. The -Gettext manual has a section about this, see @ref{CVS Issues, CVS -Issues, Integrating with CVS, gettext, GNU gettext tools}. - -@node maintainer-mode -@section @command{missing} and @code{AM_MAINTAINER_MODE} - -@subheading @command{missing} -@cindex @command{missing}, purpose - -The @command{missing} script is a wrapper around several maintainer -tools, designed to warn users if a maintainer tool is required but -missing. Typical maintainer tools are @command{autoconf}, -@command{automake}, @command{bison}, etc. Because file generated by -these tools are shipped with the other sources of a package, these -tools shouldn't be required during a user build and they are not -checked for in @file{configure}. - -However, if for some reason a rebuild rule is triggered and involves a -missing tool, @command{missing} will notice it and warn the user, even -suggesting how to obtain such a tool (at least in case it is a well-known -one, like @command{makeinfo} or @command{bison}). This is more helpful -and user-friendly than just having the rebuild rules spewing out a terse -error message like @samp{sh: @var{tool}: command not found}. Similarly, -@command{missing} will warn the user if it detects that a maintainer -tool it attempted to use seems too old (be warned that diagnosing this -correctly is typically more difficult that detecting missing tools, and -requires cooperation from the tool itself, so it won't always work). - -If the required tool is installed, @command{missing} will run it and -won't attempt to continue after failures. This is correct during -development: developers love fixing failures. However, users with -missing or too old maintainer tools may get an error when the rebuild -rule is spuriously triggered, halting the build. This failure to let -the build continue is one of the arguments of the -@code{AM_MAINTAINER_MODE} advocates. - -@subheading @code{AM_MAINTAINER_MODE} -@cindex @code{AM_MAINTAINER_MODE}, purpose -@acindex AM_MAINTAINER_MODE - -@code{AM_MAINTAINER_MODE} allows you to choose whether the so called -"rebuild rules" should be enabled or disabled. With -@code{AM_MAINTAINER_MODE([enable])}, they are enabled by default, -otherwise they are disabled by default. In the latter case, if -you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run -@samp{./configure && make}, then @command{make} will *never* attempt to -rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc. -I.e., this disables build rules for files that are usually distributed -and that users should normally not have to update. - -The user can override the default setting by passing either -@samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode} -to @command{configure}. - -People use @code{AM_MAINTAINER_MODE} either because they do not want their -users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or -because they simply can't stand the rebuild rules and prefer running -maintainer tools explicitly. - -@code{AM_MAINTAINER_MODE} also allows you to disable some custom build -rules conditionally. Some developers use this feature to disable -rules that need exotic tools that users may not have available. - -Several years ago Fran@,{c}ois Pinard pointed out several arguments -against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to -insecurity. By removing dependencies you get non-dependable builds: -changes to sources files can have no effect on generated files and this -can be very confusing when unnoticed. He adds that security shouldn't -be reserved to maintainers (what @option{--enable-maintainer-mode} -suggests), on the contrary. If one user has to modify a -@file{Makefile.am}, then either @file{Makefile.in} should be updated -or a warning should be output (this is what Automake uses -@command{missing} for) but the last thing you want is that nothing -happens and the user doesn't notice it (this is what happens when -rebuild rules are disabled by @code{AM_MAINTAINER_MODE}). - -Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was -swayed by Fran@,{c}ois's arguments, and got rid of -@code{AM_MAINTAINER_MODE} in all of his packages. - -Still many people continue to use @code{AM_MAINTAINER_MODE}, because -it helps them working on projects where all files are kept under version -control, and because @command{missing} isn't enough if you have the -wrong version of the tools. - - -@node Wildcards -@section Why doesn't Automake support wildcards? -@cindex wildcards - -Developers are lazy. They would often like to use wildcards in -@file{Makefile.am}s, so that they would not need to remember to -update @file{Makefile.am}s every time they add, delete, or rename -a file. - -There are several objections to this: -@itemize -@item -When using CVS (or similar) developers need to remember they have to -run @samp{cvs add} or @samp{cvs rm} anyway. Updating -@file{Makefile.am} accordingly quickly becomes a reflex. - -Conversely, if your application doesn't compile -because you forgot to add a file in @file{Makefile.am}, it will help -you remember to @samp{cvs add} it. - -@item -Using wildcards makes it easy to distribute files by mistake. For -instance, some code a developer is experimenting with (a test case, -say) that should not be part of the distribution. - -@item -Using wildcards it's easy to omit some files by mistake. For -instance, one developer creates a new file, uses it in many places, -but forgets to commit it. Another developer then checks out the -incomplete project and is able to run @samp{make dist} successfully, -even though a file is missing. By listing files, @samp{make dist} -@emph{will} complain. - -@item -Wildcards are not portable to some non-GNU @command{make} implementations, -e.g., NetBSD @command{make} will not expand globs such as @samp{*} in -prerequisites of a target. - -@item -Finally, it's really hard to @emph{forget} to add a file to -@file{Makefile.am}: files that are not listed in @file{Makefile.am} are -not compiled or installed, so you can't even test them. -@end itemize - -Still, these are philosophical objections, and as such you may disagree, -or find enough value in wildcards to dismiss all of them. Before you -start writing a patch against Automake to teach it about wildcards, -let's see the main technical issue: portability. - -Although @samp{$(wildcard ...)} works with GNU @command{make}, it is -not portable to other @command{make} implementations. - -The only way Automake could support @command{$(wildcard ...)} is by -expanding @command{$(wildcard ...)} when @command{automake} is run. -The resulting @file{Makefile.in}s would be portable since they would -list all files and not use @samp{$(wildcard ...)}. However that -means developers would need to remember to run @command{automake} each -time they add, delete, or rename files. - -Compared to editing @file{Makefile.am}, this is a very small gain. Sure, -it's easier and faster to type @samp{automake; make} than to type -@samp{emacs Makefile.am; make}. But nobody bothered enough to write a -patch to add support for this syntax. Some people use scripts to -generate file lists in @file{Makefile.am} or in separate -@file{Makefile} fragments. - -Even if you don't care about portability, and are tempted to use -@samp{$(wildcard ...)} anyway because you target only GNU Make, you -should know there are many places where Automake needs to know exactly -which files should be processed. As Automake doesn't know how to -expand @samp{$(wildcard ...)}, you cannot use it in these places. -@samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed -variables as far Automake is concerned. - -You can get warnings about @samp{$(wildcard ...}) constructs using the -@option{-Wportability} flag. - -@node Limitations on File Names -@section Limitations on File Names -@cindex file names, limitations on - -Automake attempts to support all kinds of file names, even those that -contain unusual characters or are unusually long. However, some -limitations are imposed by the underlying operating system and tools. - -Most operating systems prohibit the use of the null byte in file -names, and reserve @samp{/} as a directory separator. Also, they -require that file names are properly encoded for the user's locale. -Automake is subject to these limits. - -Portable packages should limit themselves to POSIX file -names. These can contain ASCII letters and digits, -@samp{_}, @samp{.}, and @samp{-}. File names consist of components -separated by @samp{/}. File name components cannot begin with -@samp{-}. - -Portable POSIX file names cannot contain components that exceed a -14-byte limit, but nowadays it's normally safe to assume the -more-generous XOPEN limit of 255 bytes. POSIX -limits file names to 255 bytes (XOPEN allows 1023 bytes), -but you may want to limit a source tarball to file names of 99 bytes -to avoid interoperability problems with old versions of @command{tar}. - -If you depart from these rules (e.g., by using non-ASCII -characters in file names, or by using lengthy file names), your -installers may have problems for reasons unrelated to Automake. -However, if this does not concern you, you should know about the -limitations imposed by Automake itself. These limitations are -undesirable, but some of them seem to be inherent to underlying tools -like Autoconf, Make, M4, and the shell. They fall into three -categories: install directories, build directories, and file names. - -The following characters: - -@example -@r{newline} " # $ ' ` -@end example - -should not appear in the names of install directories. For example, -the operand of @command{configure}'s @option{--prefix} option should -not contain these characters. - -Build directories suffer the same limitations as install directories, -and in addition should not contain the following characters: - -@example -& @@ \ -@end example - -For example, the full name of the directory containing the source -files should not contain these characters. - -Source and installation file names like @file{main.c} are limited even -further: they should conform to the POSIX/XOPEN -rules described above. In addition, if you plan to port to -non-POSIX environments, you should avoid file names that -differ only in case (e.g., @file{makefile} and @file{Makefile}). -Nowadays it is no longer worth worrying about the 8.3 limits of -DOS file systems. - -@c FIXME This should probably be moved in the "Checking the Distribution" -@c FIXME section... -@node Errors with distclean -@section Errors with distclean -@cindex @code{distclean}, diagnostic -@cindex @samp{make distclean}, diagnostic -@cindex dependencies and distributed files -@trindex distclean - -This is a diagnostic you might encounter while running @samp{make -distcheck}. - -As explained in @ref{Checking the Distribution}, @samp{make distcheck} -attempts to build and check your package for errors like this one. - -@samp{make distcheck} will perform a @code{VPATH} build of your -package (@pxref{VPATH Builds}), and then call @samp{make distclean}. -Files left in the build directory after @samp{make distclean} has run -are listed after this error. - -This diagnostic really covers two kinds of errors: - -@itemize @bullet -@item -files that are forgotten by distclean; -@item -distributed files that are erroneously rebuilt. -@end itemize - -The former left-over files are not distributed, so the fix is to mark -them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve -more explanations. - -The latter bug is not always easy to understand and fix, so let's -proceed with an example. Suppose our package contains a program for -which we want to build a man page using @command{help2man}. GNU -@command{help2man} produces simple manual pages from the @option{--help} -and @option{--version} output of other commands (@pxref{Top, , Overview, -help2man, The Help2man Manual}). Because we don't want to force our -users to install @command{help2man}, we decide to distribute the -generated man page using the following setup. - -@example -# This Makefile.am is bogus. -bin_PROGRAMS = foo -foo_SOURCES = foo.c -dist_man_MANS = foo.1 - -foo.1: foo$(EXEEXT) - help2man --output=foo.1 ./foo$(EXEEXT) -@end example - -This will effectively distribute the man page. However, -@samp{make distcheck} will fail with: - -@example -ERROR: files left in build directory after distclean: -./foo.1 -@end example - -Why was @file{foo.1} rebuilt? Because although distributed, -@file{foo.1} depends on a non-distributed built file: -@file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it -will always appear to be newer than the distributed @file{foo.1}. - -@samp{make distcheck} caught an inconsistency in our package. Our -intent was to distribute @file{foo.1} so users do not need to install -@command{help2man}, however since this rule causes this file to be -always rebuilt, users @emph{do} need @command{help2man}. Either we -should ensure that @file{foo.1} is not rebuilt by users, or there is -no point in distributing @file{foo.1}. - -More generally, the rule is that distributed files should never depend -on non-distributed built files. If you distribute something -generated, distribute its sources. - -One way to fix the above example, while still distributing -@file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance, -assuming @command{foo --version} and @command{foo --help} do not -change unless @file{foo.c} or @file{configure.ac} change, we could -write the following @file{Makefile.am}: - -@example -bin_PROGRAMS = foo -foo_SOURCES = foo.c -dist_man_MANS = foo.1 - -foo.1: foo.c $(top_srcdir)/configure.ac - $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT) - help2man --output=foo.1 ./foo$(EXEEXT) -@end example - -This way, @file{foo.1} will not get rebuilt every time -@file{foo$(EXEEXT)} changes. The @command{make} call makes sure -@file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another -way to ensure this would be to use separate directories for binaries -and man pages, and set @code{SUBDIRS} so that binaries are built -before man pages. - -We could also decide not to distribute @file{foo.1}. In -this case it's fine to have @file{foo.1} dependent upon -@file{foo$(EXEEXT)}, since both will have to be rebuilt. -However it would be impossible to build the package in a -cross-compilation, because building @file{foo.1} involves -an @emph{execution} of @file{foo$(EXEEXT)}. - -Another context where such errors are common is when distributed files -are built by tools that are built by the package. The pattern is -similar: - -@example -distributed-file: built-tools distributed-sources - build-command -@end example - -@noindent -should be changed to - -@example -distributed-file: distributed-sources - $(MAKE) $(AM_MAKEFLAGS) built-tools - build-command -@end example - -@noindent -or you could choose not to distribute @file{distributed-file}, if -cross-compilation does not matter. - -The points made through these examples are worth a summary: - -@cartouche -@itemize -@item -Distributed files should never depend upon non-distributed built -files. -@item -Distributed files should be distributed with all their dependencies. -@item -If a file is @emph{intended} to be rebuilt by users, then there is no point -in distributing it. -@end itemize -@end cartouche - -@vrindex distcleancheck_listfiles -For desperate cases, it's always possible to disable this check by -setting @code{distcleancheck_listfiles} as documented in @ref{Checking -the Distribution}. -Make sure you do understand the reason why @samp{make distcheck} -complains before you do this. @code{distcleancheck_listfiles} is a -way to @emph{hide} errors, not to fix them. You can always do better. - -@node Flag Variables Ordering -@section Flag Variables Ordering -@cindex Ordering flag variables -@cindex Flag variables, ordering - -@display -What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and -@code{mumble_CFLAGS}? -@end display - -@display -Why does @command{automake} output @code{CPPFLAGS} after -@code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse? -@end display - -@display -My @file{configure} adds some warning flags into @code{CXXFLAGS}. In -one @file{Makefile.am} I would like to append a new flag, however if I -put the flag into @code{AM_CXXFLAGS} it is prepended to the other -flags, not appended. -@end display - -@subheading Compile Flag Variables -@cindex Flag Variables, Ordering -@cindex Compile Flag Variables -@cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS} -@cindex @code{AM_CFLAGS} and @code{CFLAGS} -@cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS} -@cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS} -@cindex @code{AM_FCFLAGS} and @code{FCFLAGS} -@cindex @code{AM_FFLAGS} and @code{FFLAGS} -@cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS} -@cindex @code{AM_LDFLAGS} and @code{LDFLAGS} -@cindex @code{AM_LFLAGS} and @code{LFLAGS} -@cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS} -@cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS} -@cindex @code{AM_OBJCXXFLAGS} and @code{OBJXXCFLAGS} -@cindex @code{AM_RFLAGS} and @code{RFLAGS} -@cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS} -@cindex @code{AM_YFLAGS} and @code{YFLAGS} -@cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS} -@cindex @code{CFLAGS} and @code{AM_CFLAGS} -@cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS} -@cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS} -@cindex @code{FCFLAGS} and @code{AM_FCFLAGS} -@cindex @code{FFLAGS} and @code{AM_FFLAGS} -@cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS} -@cindex @code{LDFLAGS} and @code{AM_LDFLAGS} -@cindex @code{LFLAGS} and @code{AM_LFLAGS} -@cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS} -@cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS} -@cindex @code{OBJCXXFLAGS} and @code{AM_OBJCXXFLAGS} -@cindex @code{RFLAGS} and @code{AM_RFLAGS} -@cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS} -@cindex @code{YFLAGS} and @code{AM_YFLAGS} - -This section attempts to answer all the above questions. We will -mostly discuss @code{CPPFLAGS} in our examples, but actually the -answer holds for all the compile flags used in Automake: -@code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS}, -@code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS}, -@code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS}, -@code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}. - -@code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are -three variables that can be used to pass flags to the C preprocessor -(actually these variables are also used for other languages like C++ -or preprocessed Fortran). @code{CPPFLAGS} is the user variable -(@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable, -and @code{mumble_CPPFLAGS} is the variable specific to the -@code{mumble} target (we call this a per-target variable, -@pxref{Program and Library Variables}). - -Automake always uses two of these variables when compiling C sources -files. When compiling an object file for the @code{mumble} target, -the first variable will be @code{mumble_CPPFLAGS} if it is defined, or -@code{AM_CPPFLAGS} otherwise. The second variable is always -@code{CPPFLAGS}. - -In the following example, - -@example -bin_PROGRAMS = foo bar -foo_SOURCES = xyz.c -bar_SOURCES = main.c -foo_CPPFLAGS = -DFOO -AM_CPPFLAGS = -DBAZ -@end example - -@noindent -@file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)}, -(because @file{xyz.o} is part of the @code{foo} target), while -@file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)} -(because there is no per-target variable for target @code{bar}). - -The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS} -being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS} -is a user variable, i.e., a variable that users are entitled to modify -in order to compile the package. This variable, like many others, -is documented at the end of the output of @samp{configure --help}. - -For instance, someone who needs to add @file{/home/my/usr/include} to -the C compiler's search path would configure a package with - -@example -./configure CPPFLAGS='-I /home/my/usr/include' -@end example - -@noindent -and this flag would be propagated to the compile rules of all -@file{Makefile}s. - -It is also not uncommon to override a user variable at -@command{make}-time. Many installers do this with @code{prefix}, but -this can be useful with compiler flags too. For instance, if, while -debugging a C++ project, you need to disable optimization in one -specific object file, you can run something like - -@example -rm file.o -make CXXFLAGS=-O0 file.o -make -@end example - -The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or -@samp{$(mumble_CPPFLAGS)} in the compile command is that users -should always have the last say. It probably makes more sense if you -think about it while looking at the @samp{CXXFLAGS=-O0} above, which -should supersede any other switch from @code{AM_CXXFLAGS} or -@code{mumble_CXXFLAGS} (and this of course replaces the previous value -of @code{CXXFLAGS}). - -You should never redefine a user variable such as @code{CPPFLAGS} in -@file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such -mistakes. Even something like - -@example -CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@ -@end example - -@noindent -is erroneous. Although this preserves @file{configure}'s value of -@code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a -user attempts to override @code{CPPFLAGS} from the @command{make} -command line. - -@example -AM_CPPFLAGS = -DDATADIR=\"$(datadir)\" -@end example - -@noindent -is all that is needed here if no per-target flags are used. - -You should not add options to these user variables within -@file{configure} either, for the same reason. Occasionally you need -to modify these variables to perform a test, but you should reset -their values afterwards. In contrast, it is OK to modify the -@samp{AM_} variables within @file{configure} if you @code{AC_SUBST} -them, but it is rather rare that you need to do this, unless you -really want to change the default definitions of the @samp{AM_} -variables in all @file{Makefile}s. - -What we recommend is that you define extra flags in separate -variables. For instance, you may write an Autoconf macro that computes -a set of warning options for the C compiler, and @code{AC_SUBST} them -in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that -determines which compiler and which linker flags should be used to -link with library @file{libfoo}, and @code{AC_SUBST} these in -@code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a -@file{Makefile.am} could use these variables as follows: - -@example -AM_CFLAGS = $(WARNINGCFLAGS) -bin_PROGRAMS = prog1 prog2 -prog1_SOURCES = @dots{} -prog2_SOURCES = @dots{} -prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS) -prog2_LDFLAGS = $(LIBFOOLDFLAGS) -@end example - -In this example both programs will be compiled with the flags -substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will -additionally be compiled with the flags required to link with -@file{libfoo}. - -Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS} -variable is a common idiom to ensure that @code{AM_CFLAGS} applies to -every target in a @file{Makefile.in}. - -Using variables like this gives you full control over the ordering of -the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that -you want to negate for a particular target, you can use something like -@samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all of these flags had -been forcefully appended to @code{CFLAGS}, there would be no way to -disable one flag. Yet another reason to leave user variables to -users. - -Finally, we have avoided naming the variable of the example -@code{LIBFOO_LDFLAGS} (with an underscore) because that would cause -Automake to think that this is actually a per-target variable (like -@code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target. - -@subheading Other Variables - -There are other variables in Automake that follow similar principles -to allow user options. For instance, Texinfo rules (@pxref{Texinfo}) -use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly, -DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and -@code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules -(@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS}, -@code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules -(@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None -of these rules support per-target flags (yet). - -To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories}) -obeys this naming scheme. The slight difference is that -@code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by -@command{make} itself. - -@code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and -has neither @code{AM_} nor per-target cousin. - -Finally you should not think that the existence of a per-target -variable implies the existence of an @code{AM_} variable or of a user -variable. For instance, the @code{mumble_LDADD} per-target variable -overrides the makefile-wide @code{LDADD} variable (which is not a user -variable), and @code{mumble_LIBADD} exists only as a per-target -variable. @xref{Program and Library Variables}. - - -@node Renamed Objects -@section Why are object files sometimes renamed? - -This happens when per-target compilation flags are used. Object -files need to be renamed just in case they would clash with object -files compiled from the same sources, but with different flags. -Consider the following example. - -@example -bin_PROGRAMS = true false -true_SOURCES = generic.c -true_CPPFLAGS = -DEXIT_CODE=0 -false_SOURCES = generic.c -false_CPPFLAGS = -DEXIT_CODE=1 -@end example - -@noindent -Obviously the two programs are built from the same source, but it -would be bad if they shared the same object, because @file{generic.o} -cannot be built with both @samp{-DEXIT_CODE=0} @emph{and} -@samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to -build two different objects: @file{true-generic.o} and -@file{false-generic.o}. - -@command{automake} doesn't actually look whether source files are -shared to decide if it must rename objects. It will just rename all -objects of a target as soon as it sees per-target compilation flags -used. - -It's OK to share object files when per-target compilation flags are not -used. For instance, @file{true} and @file{false} will both use -@file{version.o} in the following example. - -@example -AM_CPPFLAGS = -DVERSION=1.0 -bin_PROGRAMS = true false -true_SOURCES = true.c version.c -false_SOURCES = false.c version.c -@end example - -Note that the renaming of objects is also affected by the -@code{_SHORTNAME} variable (@pxref{Program and Library Variables}). - - -@node Per-Object Flags -@section Per-Object Flags Emulation -@cindex Per-object flags, emulated - -@display -One of my source files needs to be compiled with different flags. How -do I do? -@end display - -Automake supports per-program and per-library compilation flags (see -@ref{Program and Library Variables} and @ref{Flag Variables -Ordering}). With this you can define compilation flags that apply to -all files compiled for a target. For instance, in - -@example -bin_PROGRAMS = foo -foo_SOURCES = foo.c foo.h bar.c bar.h main.c -foo_CFLAGS = -some -flags -@end example - -@noindent -@file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be -compiled with @samp{-some -flags}. (If you wonder about the names of -these object files, see @ref{Renamed Objects}.) Note that -@code{foo_CFLAGS} gives the flags to use when compiling all the C -sources of the @emph{program} @code{foo}, it has nothing to do with -@file{foo.c} or @file{foo-foo.o} specifically. - -What if @file{foo.c} needs to be compiled into @file{foo.o} using some -specific flags, that none of the other files requires? Obviously -per-program flags are not directly applicable here. Something like -per-object flags are expected, i.e., flags that would be used only -when creating @file{foo-foo.o}. Automake does not support that, -however this is easy to simulate using a library that contains only -that object, and compiling this library with per-library flags. - -@example -bin_PROGRAMS = foo -foo_SOURCES = bar.c bar.h main.c -foo_CFLAGS = -some -flags -foo_LDADD = libfoo.a -noinst_LIBRARIES = libfoo.a -libfoo_a_SOURCES = foo.c foo.h -libfoo_a_CFLAGS = -some -other -flags -@end example - -Here @file{foo-bar.o} and @file{foo-main.o} will all be -compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will -be compiled using @samp{-some -other -flags}. Eventually, all -three objects will be linked to form @file{foo}. - -This trick can also be achieved using Libtool convenience libraries, -for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool -Convenience Libraries}). - -Another tempting idea to implement per-object flags is to override the -compile rules @command{automake} would output for these files. -Automake will not define a rule for a target you have defined, so you -could think about defining the @samp{foo-foo.o: foo.c} rule yourself. -We recommend against this, because this is error prone. For instance, -if you add such a rule to the first example, it will break the day you -decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be -compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed -Objects}). Also in order to support dependency tracking, the two -@file{.o}/@file{.obj} extensions, and all the other flags variables -involved in a compilation, you will end up modifying a copy of the -rule previously output by @command{automake} for this file. If a new -release of Automake generates a different rule, your copy will need to -be updated by hand. - -@node Multiple Outputs -@section Handling Tools that Produce Many Outputs -@cindex multiple outputs, rules with -@cindex many outputs, rules with -@cindex rules with multiple outputs - -This section describes a @command{make} idiom that can be used when a -tool produces multiple output files. It is not specific to Automake -and can be used in ordinary @file{Makefile}s. - -Suppose we have a program called @command{foo} that will read one file -called @file{data.foo} and produce two files named @file{data.c} and -@file{data.h}. We want to write a @file{Makefile} rule that captures -this one-to-two dependency. - -The naive rule is incorrect: - -@example -# This is incorrect. -data.c data.h: data.foo - foo data.foo -@end example - -@noindent -What the above rule really says is that @file{data.c} and -@file{data.h} each depend on @file{data.foo}, and can each be built by -running @samp{foo data.foo}. In other words it is equivalent to: - -@example -# We do not want this. -data.c: data.foo - foo data.foo -data.h: data.foo - foo data.foo -@end example - -@noindent -which means that @command{foo} can be run twice. Usually it will not -be run twice, because @command{make} implementations are smart enough -to check for the existence of the second file after the first one has -been built; they will therefore detect that it already exists. -However there are a few situations where it can run twice anyway: - -@itemize -@item -The most worrying case is when running a parallel @command{make}. If -@file{data.c} and @file{data.h} are built in parallel, two @samp{foo -data.foo} commands will run concurrently. This is harmful. -@item -Another case is when the dependency (here @file{data.foo}) is -(or depends upon) a phony target. -@end itemize - -A solution that works with parallel @command{make} but not with -phony dependencies is the following: - -@example -data.c data.h: data.foo - foo data.foo -data.h: data.c -@end example - -@noindent -The above rules are equivalent to - -@example -data.c: data.foo - foo data.foo -data.h: data.foo data.c - foo data.foo -@end example - -@noindent -therefore a parallel @command{make} will have to serialize the builds -of @file{data.c} and @file{data.h}, and will detect that the second is -no longer needed once the first is over. - -Using this pattern is probably enough for most cases. However it does -not scale easily to more output files (in this scheme all output files -must be totally ordered by the dependency relation), so we will -explore a more complicated solution. - -Another idea is to write the following: - -@example -# There is still a problem with this one. -data.c: data.foo - foo data.foo -data.h: data.c -@end example - -@noindent -The idea is that @samp{foo data.foo} is run only when @file{data.c} -needs to be updated, but we further state that @file{data.h} depends -upon @file{data.c}. That way, if @file{data.h} is required and -@file{data.foo} is out of date, the dependency on @file{data.c} will -trigger the build. - -This is almost perfect, but suppose we have built @file{data.h} and -@file{data.c}, and then we erase @file{data.h}. Then, running -@samp{make data.h} will not rebuild @file{data.h}. The above rules -just state that @file{data.c} must be up-to-date with respect to -@file{data.foo}, and this is already the case. - -What we need is a rule that forces a rebuild when @file{data.h} is -missing. Here it is: - -@example -data.c: data.foo - foo data.foo -data.h: data.c -## Recover from the removal of $@@ - @@if test -f $@@; then :; else \ - rm -f data.c; \ - $(MAKE) $(AM_MAKEFLAGS) data.c; \ - fi -@end example - -The above scheme can be extended to handle more outputs and more -inputs. One of the outputs is selected to serve as a witness to the -successful completion of the command, it depends upon all inputs, and -all other outputs depend upon it. For instance, if @command{foo} -should additionally read @file{data.bar} and also produce -@file{data.w} and @file{data.x}, we would write: - -@example -data.c: data.foo data.bar - foo data.foo data.bar -data.h data.w data.x: data.c -## Recover from the removal of $@@ - @@if test -f $@@; then :; else \ - rm -f data.c; \ - $(MAKE) $(AM_MAKEFLAGS) data.c; \ - fi -@end example - -However there are now three minor problems in this setup. One is related -to the timestamp ordering of @file{data.h}, @file{data.w}, -@file{data.x}, and @file{data.c}. Another one is a race condition -if a parallel @command{make} attempts to run multiple instances of the -recover block at once. Finally, the recursive rule breaks @samp{make -n} -when run with GNU @command{make} (as well as some other @command{make} -implementations), as it may remove @file{data.h} even when it should not -(@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make, -The GNU Make Manual}). - -Let us deal with the first problem. @command{foo} outputs four files, -but we do not know in which order these files are created. Suppose -that @file{data.h} is created before @file{data.c}. Then we have a -weird situation. The next time @command{make} is run, @file{data.h} -will appear older than @file{data.c}, the second rule will be -triggered, a shell will be started to execute the @samp{if@dots{}fi} -command, but actually it will just execute the @code{then} branch, -that is: nothing. In other words, because the witness we selected is -not the first file created by @command{foo}, @command{make} will start -a shell to do nothing each time it is run. - -A simple riposte is to fix the timestamps when this happens. - -@example -data.c: data.foo data.bar - foo data.foo data.bar -data.h data.w data.x: data.c - @@if test -f $@@; then \ - touch $@@; \ - else \ -## Recover from the removal of $@@ - rm -f data.c; \ - $(MAKE) $(AM_MAKEFLAGS) data.c; \ - fi -@end example - -Another solution is to use a different and dedicated file as witness, -rather than using any of @command{foo}'s outputs. - -@example -data.stamp: data.foo data.bar - @@rm -f data.tmp - @@touch data.tmp - foo data.foo data.bar - @@mv -f data.tmp $@@ -data.c data.h data.w data.x: data.stamp -## Recover from the removal of $@@ - @@if test -f $@@; then :; else \ - rm -f data.stamp; \ - $(MAKE) $(AM_MAKEFLAGS) data.stamp; \ - fi -@end example - -@file{data.tmp} is created before @command{foo} is run, so it has a -timestamp older than output files output by @command{foo}. It is then -renamed to @file{data.stamp} after @command{foo} has run, because we -do not want to update @file{data.stamp} if @command{foo} fails. - -This solution still suffers from the second problem: the race -condition in the recover rule. If, after a successful build, a user -erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then -@command{make} may start both recover rules in parallel. If the two -instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS) -data.stamp} concurrently the build is likely to fail (for instance, the -two rules will create @file{data.tmp}, but only one can rename it). - -Admittedly, such a weird situation does not arise during ordinary -builds. It occurs only when the build tree is mutilated. Here -@file{data.c} and @file{data.h} have been explicitly removed without -also removing @file{data.stamp} and the other output files. -@code{make clean; make} will always recover from these situations even -with parallel makes, so you may decide that the recover rule is solely -to help non-parallel make users and leave things as-is. Fixing this -requires some locking mechanism to ensure only one instance of the -recover rule rebuilds @file{data.stamp}. One could imagine something -along the following lines. - -@example -data.c data.h data.w data.x: data.stamp -## Recover from the removal of $@@ - @@if test -f $@@; then :; else \ - trap 'rm -rf data.lock data.stamp' 1 2 13 15; \ -## mkdir is a portable test-and-set - if mkdir data.lock 2>/dev/null; then \ -## This code is being executed by the first process. - rm -f data.stamp; \ - $(MAKE) $(AM_MAKEFLAGS) data.stamp; \ - result=$$?; rm -rf data.lock; exit $$result; \ - else \ -## This code is being executed by the follower processes. -## Wait until the first process is done. - while test -d data.lock; do sleep 1; done; \ -## Succeed if and only if the first process succeeded. - test -f data.stamp; \ - fi; \ - fi -@end example - -Using a dedicated witness, like @file{data.stamp}, is very handy when -the list of output files is not known beforehand. As an illustration, -consider the following rules to compile many @file{*.el} files into -@file{*.elc} files in a single command. It does not matter how -@code{ELFILES} is defined (as long as it is not empty: empty targets -are not accepted by POSIX). - -@example -ELFILES = one.el two.el three.el @dots{} -ELCFILES = $(ELFILES:=c) - -elc-stamp: $(ELFILES) - @@rm -f elc-temp - @@touch elc-temp - $(elisp_comp) $(ELFILES) - @@mv -f elc-temp $@@ - -$(ELCFILES): elc-stamp - @@if test -f $@@; then :; else \ -## Recover from the removal of $@@ - trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \ - if mkdir elc-lock 2>/dev/null; then \ -## This code is being executed by the first process. - rm -f elc-stamp; \ - $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \ - rmdir elc-lock; \ - else \ -## This code is being executed by the follower processes. -## Wait until the first process is done. - while test -d elc-lock; do sleep 1; done; \ -## Succeed if and only if the first process succeeded. - test -f elc-stamp; exit $$?; \ -@c $$ - fi; \ - fi -@end example - -These solutions all still suffer from the third problem, namely that -they break the promise that @samp{make -n} should not cause any actual -changes to the tree. For those solutions that do not create lock files, -it is possible to split the recover rules into two separate recipe -commands, one of which does all work but the recursion, and the -other invokes the recursive @samp{$(MAKE)}. The solutions involving -locking could act upon the contents of the @samp{MAKEFLAGS} variable, -but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,, -autoconf, The Autoconf Manual}). Here is an example: - -@example -ELFILES = one.el two.el three.el @dots{} -ELCFILES = $(ELFILES:=c) - -elc-stamp: $(ELFILES) - @@rm -f elc-temp - @@touch elc-temp - $(elisp_comp) $(ELFILES) - @@mv -f elc-temp $@@ - -$(ELCFILES): elc-stamp -## Recover from the removal of $@@ - @@dry=; for f in x $$MAKEFLAGS; do \ - case $$f in \ - *=*|--*);; \ - *n*) dry=:;; \ - esac; \ - done; \ - if test -f $@@; then :; else \ - $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \ - if $$dry mkdir elc-lock 2>/dev/null; then \ -## This code is being executed by the first process. - $$dry rm -f elc-stamp; \ - $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \ - $$dry rmdir elc-lock; \ - else \ -## This code is being executed by the follower processes. -## Wait until the first process is done. - while test -d elc-lock && test -z "$$dry"; do \ -@c $$ - sleep 1; \ - done; \ -## Succeed if and only if the first process succeeded. - $$dry test -f elc-stamp; exit $$?; \ - fi; \ - fi -@end example - -For completeness it should be noted that GNU @command{make} is able to -express rules with multiple output files using pattern rules -(@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make -Manual}). We do not discuss pattern rules here because they are not -portable, but they can be convenient in packages that assume GNU -@command{make}. - - -@node Hard-Coded Install Paths -@section Installing to Hard-Coded Locations - -@display -My package needs to install some configuration file. I tried to use -the following rule, but @samp{make distcheck} fails. Why? - -@example -# Do not do this. -install-data-local: - $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile -@end example -@end display - -@display -My package needs to populate the installation directory of another -package at install-time. I can easily compute that installation -directory in @file{configure}, but if I install files therein, -@samp{make distcheck} fails. How else should I do? -@end display - -These two setups share their symptoms: @samp{make distcheck} fails -because they are installing files to hard-coded paths. In the later -case the path is not really hard-coded in the package, but we can -consider it to be hard-coded in the system (or in whichever tool that -supplies the path). As long as the path does not use any of the -standard directory variables (@samp{$(prefix)}, @samp{$(bindir)}, -@samp{$(datadir)}, etc.), the effect will be the same: -user-installations are impossible. - -As a (non-root) user who wants to install a package, you usually have no -right to install anything in @file{/usr} or @file{/usr/local}. So you -do something like @samp{./configure --prefix ~/usr} to install a -package in your own @file{~/usr} tree. - -If a package attempts to install something to some hard-coded path -(e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting, -then the installation will fail. @samp{make distcheck} performs such -a @option{--prefix} installation, hence it will fail too. - -Now, there are some easy solutions. - -The above @code{install-data-local} example for installing -@file{/etc/afile} would be better replaced by - -@example -sysconf_DATA = afile -@end example - -@noindent -by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because -this is what the GNU Standards require. When such a package is -installed on an FHS compliant system, the installer will have to set -@samp{--sysconfdir=/etc}. As the maintainer of the package you -should not be concerned by such site policies: use the appropriate -standard directory variable to install your files so that the installer -can easily redefine these variables to match their site conventions. - -Installing files that should be used by another package is slightly -more involved. Let's take an example and assume you want to install -a shared library that is a Python extension module. If you ask Python -where to install the library, it will answer something like this: - -@example -% @kbd{python -c 'from distutils import sysconfig; - print sysconfig.get_python_lib(1,0)'} -/usr/lib/python2.5/site-packages -@end example - -If you indeed use this absolute path to install your shared library, -non-root users will not be able to install the package, hence -distcheck fails. - -Let's do better. The @samp{sysconfig.get_python_lib()} function -actually accepts a third argument that will replace Python's -installation prefix. - -@example -% @kbd{python -c 'from distutils import sysconfig; - print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'} -$@{exec_prefix@}/lib/python2.5/site-packages -@end example - -You can also use this new path. If you do -@itemize @bullet -@item -root users can install your package with the same @option{--prefix} -as Python (you get the behavior of the previous attempt) - -@item -non-root users can install your package too, they will have the -extension module in a place that is not searched by Python but they -can work around this using environment variables (and if you installed -scripts that use this shared library, it's easy to tell Python were to -look in the beginning of your script, so the script works in both -cases). -@end itemize - -The @code{AM_PATH_PYTHON} macro uses similar commands to define -@samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}). - -Of course not all tools are as advanced as Python regarding that -substitution of @var{prefix}. So another strategy is to figure the -part of the installation directory that must be preserved. For -instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp}) -computes @samp{$(lispdir)}: - -@example -$EMACS -batch -Q -eval '(while load-path - (princ (concat (car load-path) "\n")) - (setq load-path (cdr load-path)))' >conftest.out -lispdir=`sed -n - -e 's,/$,,' - -e '/.*\/lib\/x*emacs\/site-lisp$/@{ - s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q; - @}' - -e '/.*\/share\/x*emacs\/site-lisp$/@{ - s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q; - @}' - conftest.out` -@end example - -I.e., it just picks the first directory that looks like -@file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in -the search path of emacs, and then substitutes @samp{$@{libdir@}} or -@samp{$@{datadir@}} appropriately. - -The emacs case looks complicated because it processes a list and -expects two possible layouts, otherwise it's easy, and the benefits for -non-root users are really worth the extra @command{sed} invocation. - - -@node Debugging Make Rules -@section Debugging Make Rules -@cindex debugging rules -@cindex rules, debugging - -The rules and dependency trees generated by @command{automake} can get -rather complex, and leave the developer head-scratching when things -don't work as expected. Besides the debug options provided by the -@command{make} command (@pxref{Options Summary,,, make, The GNU Make -Manual}), here's a couple of further hints for debugging makefiles -generated by @command{automake} effectively: - -@itemize -@item -If less verbose output has been enabled in the package with the use -of silent rules (@pxref{Automake Silent Rules}), you can use -@code{make V=1} to see the commands being executed. -@item -@code{make -n} can help show what would be done without actually doing -it. Note however, that this will @emph{still execute} commands prefixed -with @samp{+}, and, when using GNU @command{make}, commands that contain -the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of -Execution,,, make, The GNU Make Manual}). -Typically, this is helpful to show what recursive rules would do, but it -means that, in your own rules, you should not mix such recursion with -actions that change any files.@footnote{Automake's @samp{dist} and -@samp{distcheck} rules had a bug in this regard in that they created -directories even with @option{-n}, but this has been fixed in Automake -1.11.} Furthermore, note that GNU @command{make} will update -prerequisites for the @file{Makefile} file itself even with @option{-n} -(@pxref{Remaking Makefiles,,, make, The GNU Make Manual}). -@item -@code{make SHELL="/bin/bash -vx"} can help debug complex rules. -@xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some -portability quirks associated with this construct. -@item -@code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print} -can be handy to examine the expanded value of variables. You may need -to use a target other than @samp{print} if that is already used or a -file with that name exists. -@item -@url{http://bashdb.sourceforge.net/@/remake/} provides a modified -GNU @command{make} command called @command{remake} that copes with -complex GNU @command{make}-specific Makefiles and allows to trace -execution, examine variables, and call rules interactively, much like -a debugger. -@end itemize - - -@node Reporting Bugs -@section Reporting Bugs - -Most nontrivial software has bugs. Automake is no exception. Although -we cannot promise we can or will fix a bug, and we might not even agree -that it is a bug, we want to hear about problems you encounter. Often we -agree they are bugs and want to fix them. - -To make it possible for us to fix a bug, please report it. In order to -do so effectively, it helps to know when and how to do it. - -Before reporting a bug, it is a good idea to see if it is already known. -You can look at the @uref{https://debbugs.gnu.org/, GNU Bug Tracker} -and the @uref{https://lists.gnu.org/@/archive/@/html/@/bug-automake/, -bug-automake mailing list archives} for previous bug reports. We -previously used a -@uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake, -Gnats database} for bug tracking, so some bugs might have been reported -there already. Please do not use it for new bug reports, however. - -If the bug is not already known, it should be reported. It is very -important to report bugs in a way that is useful and efficient. For -this, please familiarize yourself with -@uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to -Report Bugs Effectively} and -@uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask -Questions the Smart Way}. This helps you and developers to save time -which can then be spent on fixing more bugs and implementing more -features. - -For a bug report, a feature request or other suggestions, please send -email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new -bug in the @uref{https://debbugs.gnu.org/@/automake, bug tracker}. Be -sure to include the versions of Autoconf and Automake that you use. -Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that -reproduces the problem you encounter. If you have encountered test -suite failures, please attach the @file{test-suite.log} file. - -@c ========================================================== Appendices - -@page -@node Copying This Manual -@appendix Copying This Manual - -@menu -* GNU Free Documentation License:: License for copying this manual -@end menu - -@node GNU Free Documentation License -@appendixsec GNU Free Documentation License -@include fdl.texi - -@page -@node Indices -@appendix Indices - -@menu -* Macro Index:: Index of Autoconf macros -* Variable Index:: Index of Makefile variables -* General Index:: General index -@end menu - -@node Macro Index -@appendixsec Macro Index - -@printindex fn - -@node Variable Index -@appendixsec Variable Index - -@printindex vr - -@node General Index -@appendixsec General Index - -@printindex cp - - -@bye - -@c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry -@c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp -@c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex -@c LocalWords: dir Automake's ac Dist Gnits gnits dfn Autoconf's pxref -@c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo -@c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt -@c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex -@c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS -@c LocalWords: libmumble CC YFLAGS itemx de fication config url comp -@c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf -@c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr -@c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc -@c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod -@c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp -@c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex -@c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean -@c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX -@c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION -@c LocalWords: dirlist noindent usr TIOCGWINSZ sc -@c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS -@c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC -@c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi -@c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum -@c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif -@c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd -@c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux -@c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar -@c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy -@c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc -@c LocalWords: OBJCXXFLAGS -@c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb -@c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval -@c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact -@c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys -@c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks -@c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname -@c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran -@c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe -@c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's -@c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm -@c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz -@c LocalWords: depfile tmpdepfile depmode const interoperate -@c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython -@c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois -@c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf -@c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard -@c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean -@c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip exp -@c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck -@c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln -@c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS -@c LocalWords: installcheck gzipped std utils etags mkid cd -@c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl -@c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC -@c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE -@c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API -@c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret -@c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ -@c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar -@c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor -@c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te -@c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux -@c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc -@c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE -@c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar -@c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF -@c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's -@c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich -@c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org -@c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston -@c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake -@c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre -@c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel -@c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec -@c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO -@c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS -@c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS -@c LocalWords: barexec Pinard's automatize initialize lzip xz cscope diff --git a/doc/fdl.texi b/doc/fdl.texi deleted file mode 100644 index 16589f90b..000000000 --- a/doc/fdl.texi +++ /dev/null @@ -1,506 +0,0 @@ -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000-2017 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all of these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - 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, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: - diff --git a/doc/help2man b/doc/help2man deleted file mode 100755 index f7a9c455c..000000000 --- a/doc/help2man +++ /dev/null @@ -1,768 +0,0 @@ -#!/usr/bin/perl -w - -# Generate a short man page from --help and --version output. -# Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, -# 2010, 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc. - -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 3, or (at your option) -# any later version. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with this program; if not, see . - -# Written by Brendan O'Dea -# Available from https://ftp.gnu.org/gnu/help2man/ - -use 5.008; -use strict; -use Getopt::Long; -use Text::ParseWords qw(shellwords); -use Text::Tabs qw(expand); -use POSIX qw(strftime setlocale LC_ALL); - -my $this_program = 'help2man'; -my $this_version = '1.47.4'; - -sub _ { $_[0] } -sub configure_locale -{ - my $locale = shift; - die "$this_program: no locale support (Locale::gettext required)\n" - unless $locale eq 'C'; -} - -sub dec { $_[0] } -sub enc { $_[0] } -sub enc_user { $_[0] } -sub kark { die +(sprintf shift, @_), "\n" } -sub N_ { $_[0] } - -sub program_basename; -sub get_option_value; -sub convert_option; -sub fix_italic_spacing; - -my $version_info = enc_user sprintf _(<<'EOT'), $this_program, $this_version; -GNU %s %s - -Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010, -2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc. -This is free software; see the source for copying conditions. There is NO -warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - -Written by Brendan O'Dea -EOT - -my $help_info = enc_user sprintf _(<<'EOT'), $this_program, $this_program; -`%s' generates a man page out of `--help' and `--version' output. - -Usage: %s [OPTION]... EXECUTABLE - - -n, --name=STRING description for the NAME paragraph - -s, --section=SECTION section number for manual page (1, 6, 8) - -m, --manual=TEXT name of manual (User Commands, ...) - -S, --source=TEXT source of program (FSF, Debian, ...) - -L, --locale=STRING select locale (default "C") - -i, --include=FILE include material from `FILE' - -I, --opt-include=FILE include material from `FILE' if it exists - -o, --output=FILE send output to `FILE' - -p, --info-page=TEXT name of Texinfo manual - -N, --no-info suppress pointer to Texinfo manual - -l, --libtool exclude the `lt-' from the program name - --help print this help, then exit - --version print version number, then exit - -EXECUTABLE should accept `--help' and `--version' options and produce output on -stdout although alternatives may be specified using: - - -h, --help-option=STRING help option string - -v, --version-option=STRING version option string - --version-string=STRING version string - --no-discard-stderr include stderr when parsing option output - -Report bugs to . -EOT - -my $section = 1; -my $manual = ''; -my $source = ''; -my $help_option = '--help'; -my $version_option = '--version'; -my $discard_stderr = 1; -my ($opt_name, @opt_include, $opt_output, $opt_info, $opt_no_info, $opt_libtool, - $version_text); - -my %opt_def = ( - 'n|name=s' => \$opt_name, - 's|section=s' => \$section, - 'm|manual=s' => \$manual, - 'S|source=s' => \$source, - 'L|locale=s' => sub { configure_locale pop }, - 'i|include=s' => sub { push @opt_include, [ pop, 1 ] }, - 'I|opt-include=s' => sub { push @opt_include, [ pop, 0 ] }, - 'o|output=s' => \$opt_output, - 'p|info-page=s' => \$opt_info, - 'N|no-info' => \$opt_no_info, - 'l|libtool' => \$opt_libtool, - 'help' => sub { print $help_info; exit }, - 'version' => sub { print $version_info; exit }, - 'h|help-option=s' => \$help_option, - 'v|version-option=s' => \$version_option, - 'version-string=s' => \$version_text, - 'discard-stderr!' => \$discard_stderr, -); - -# Parse options. -Getopt::Long::config('bundling'); -die $help_info unless GetOptions %opt_def and @ARGV == 1; - -my %include = (); -my %replace = (); -my %append = (); -my %append_match = (); -my @sections = (); # retain order of include file or in-line *section*s - -# Process include file (if given). Format is: -# -# Optional initial text, ignored. May include lines starting with `-' -# which are processed as options. -# -# [section] -# Verbatim text to be included in the named section. By default at -# the start, but in the case of `name' and `synopsis' the content -# will replace the autogenerated contents. -# -# [section] -# Verbatim text to be appended to the end of the named section. -# -# /pattern/ -# Verbatim text for inclusion below a paragraph matching `pattern'. -# - -while (@opt_include) -{ - my ($inc, $required) = @{shift @opt_include}; - - next unless -f $inc or $required; - kark N_("%s: can't open `%s' (%s)"), $this_program, $inc, $! - unless open INC, $inc; - - my $key; - my $hash; - - while () - { - # Convert input to internal Perl format, so that multibyte - # sequences are treated as single characters. - $_ = dec $_; - - # [section] - if (/^\[([^]]+)\]\s*$/) - { - $key = uc $1; - $key =~ s/^\s+//; - $key =~ s/\s+$//; - $hash = \%include; - # Handle explicit [section] - if ($key =~ s/^([<>=])\s*//) - { - if ($1 eq '>') { $hash = \%append; } - elsif ($1 eq '=') { $hash = \%replace; } - } - # NAME/SYNOPSIS replace by default - elsif ($key eq _('NAME') or $key eq _('SYNOPSIS')) - { - $hash = \%replace; - } - else - { - $hash = \%include; - } - - push @sections, $key; - next; - } - - # /pattern/ - if (m!^/(.*)/([ims]*)\s*$!) - { - my $pat = $2 ? "(?$2)$1" : $1; - - # Check pattern. - eval { $key = qr($pat) }; - if ($@) - { - $@ =~ s/ at .*? line \d.*//; - die "$inc:$.:$@"; - } - - $hash = \%append_match; - next; - } - - # Check for options before the first section--anything else is - # silently ignored, allowing the first for comments and - # revision info. - unless ($key) - { - # handle options - if (/^-/) - { - local @ARGV = shellwords $_; - GetOptions %opt_def; - } - - next; - } - - $hash->{$key} .= $_; - } - - close INC; - - kark N_("%s: no valid information found in `%s'"), $this_program, $inc - unless $key; -} - -# Compress trailing blank lines. -for my $hash (\(%include, %replace, %append, %append_match)) -{ - for (keys %$hash) { $hash->{$_} =~ s/\n+$/\n/ } -} - -# Grab help and version info from executable. -my $help_text = get_option_value $ARGV[0], $help_option; -$version_text ||= get_option_value $ARGV[0], $version_option; - -# By default the generated manual pages will include the current date. This may -# however be overriden by setting the environment variable $SOURCE_DATE_EPOCH -# to an integer value of the seconds since the UNIX epoch. This is primarily -# intended to support reproducible builds (wiki.debian.org/ReproducibleBuilds) -# and will additionally ensure that the output date string is UTC. -my $epoch_secs = time; -if (exists $ENV{SOURCE_DATE_EPOCH} and $ENV{SOURCE_DATE_EPOCH} =~ /^(\d+)$/) -{ - $epoch_secs = $1; - $ENV{TZ} = 'UTC'; -} - -# Translators: the following message is a strftime(3) format string, which in -# the English version expands to the month as a word and the full year. It -# is used on the footer of the generated manual pages. If in doubt, you may -# just use %x as the value (which should be the full locale-specific date). -my $date = enc strftime _("%B %Y"), localtime $epoch_secs; -my $program = program_basename $ARGV[0]; -my $package = $program; -my $version; - -if ($opt_output) -{ - unlink $opt_output or kark N_("%s: can't unlink %s (%s)"), - $this_program, $opt_output, $! if -e $opt_output; - - open STDOUT, ">$opt_output" - or kark N_("%s: can't create %s (%s)"), $this_program, $opt_output, $!; -} - -# The first line of the --version information is assumed to be in one -# of the following formats: -# -# -# -# {GNU,Free} -# ({GNU,Free} ) -# - {GNU,Free} -# -# and separated from any copyright/author details by a blank line. - -($_, $version_text) = ((split /\n+/, $version_text, 2), ''); - -if (/^(\S+) +\(((?:GNU|Free) +[^)]+)\) +(.*)/ or - /^(\S+) +- *((?:GNU|Free) +\S+) +(.*)/) -{ - $program = program_basename $1; - $package = $2; - $version = $3; -} -elsif (/^((?:GNU|Free) +)?(\S+) +(.*)/) -{ - $program = program_basename $2; - $package = $1 ? "$1$program" : $program; - $version = $3; -} -else -{ - $version = $_; -} - -# No info for `info' itself. -$opt_no_info = 1 if $program eq 'info'; - -if ($opt_name) -{ - # --name overrides --include contents. - $replace{_('NAME')} = "$program \\- $opt_name\n"; -} - -# Translators: "NAME", "SYNOPSIS" and other one or two word strings in all -# upper case are manual page section headings. The man(1) manual page in your -# language, if available should provide the conventional translations. -for ($replace{_('NAME')} || ($include{_('NAME')} ||= '')) -{ - if ($_) # Use first name given as $program - { - $program = $1 if /^([^\s,]+)(?:,?\s*[^\s,\\-]+)*\s+\\?-/; - } - else # Set a default (useless) NAME paragraph. - { - $_ = sprintf _("%s \\- manual page for %s %s") . "\n", $program, - $program, $version; - } -} - -# Man pages traditionally have the page title in caps. -my $PROGRAM = uc $program; - -# Set default page head/footers -$source ||= "$program $version"; -unless ($manual) -{ - for ($section) - { - if (/^(1[Mm]|8)/) { $manual = enc _('System Administration Utilities') } - elsif (/^6/) { $manual = enc _('Games') } - else { $manual = enc _('User Commands') } - } -} - -# Extract usage clause(s) [if any] for SYNOPSIS. -# Translators: "Usage" and "or" here are patterns (regular expressions) which -# are used to match the usage synopsis in program output. An example from cp -# (GNU coreutils) which contains both strings: -# Usage: cp [OPTION]... [-T] SOURCE DEST -# or: cp [OPTION]... SOURCE... DIRECTORY -# or: cp [OPTION]... -t DIRECTORY SOURCE... -my $PAT_USAGE = _('Usage'); -my $PAT_USAGE_CONT = _('or'); -if ($help_text =~ s/^($PAT_USAGE):( +(\S+))(.*)((?:\n(?: {6}\1| *($PAT_USAGE_CONT): +\S).*)*)//om) -{ - my @syn = $3 . $4; - - if ($_ = $5) - { - s/^\n//; - for (split /\n/) { s/^ *(($PAT_USAGE_CONT): +)?//o; push @syn, $_ } - } - - my $synopsis = ''; - for (@syn) - { - $synopsis .= ".br\n" if $synopsis; - s!^\S*/!!; - s/^lt-// if $opt_libtool; - s/^(\S+) *//; - $synopsis .= ".B $1\n"; - s/\s+$//; - s/(([][]|\.\.+)+)/\\fR$1\\fI/g; - s/^/\\fI/ unless s/^\\fR//; - $_ .= '\fR'; - s/(\\fI)( *)/$2$1/g; - s/\\fI\\fR//g; - s/^\\fR//; - s/\\fI$//; - s/^\./\\&./; - - $_ = fix_italic_spacing $_; - $synopsis .= "$_\n"; - } - - $include{_('SYNOPSIS')} .= $synopsis; -} - -# Process text, initial section is DESCRIPTION. -my $sect = _('DESCRIPTION'); -$_ = "$help_text\n\n$version_text"; - -# Normalise paragraph breaks. -s/^\n+//; -s/\n*$/\n/; -s/\n\n+/\n\n/g; - -# Join hyphenated lines. -s/([A-Za-z])-\n *([A-Za-z])/$1$2/g; - -# Temporarily exchange leading dots, apostrophes and backslashes for -# tokens. -s/^\./\x80/mg; -s/^'/\x81/mg; -s/\\/\x82/g; - -# Translators: patterns are used to match common program output. In the source -# these strings are all of the form of "my $PAT_something = _('...');" and are -# regular expressions. If there is more than one commonly used string, you -# may separate alternatives with "|". Spaces in these expressions are written -# as " +" to indicate that more than one space may be matched. The string -# "(?:[\\w-]+ +)?" in the bug reporting pattern is used to indicate an -# optional word, so that either "Report bugs" or "Report _program_ bugs" will -# be matched. -my $PAT_BUGS = _('Report +(?:[\w-]+ +)?bugs|Email +bug +reports +to'); -my $PAT_AUTHOR = _('Written +by'); -my $PAT_OPTIONS = _('Options'); -my $PAT_ENVIRONMENT = _('Environment'); -my $PAT_FILES = _('Files'); -my $PAT_EXAMPLES = _('Examples'); -my $PAT_FREE_SOFTWARE = _('This +is +free +software'); - -# Start a new paragraph (if required) for these. -s/([^\n])\n($PAT_BUGS|$PAT_AUTHOR) /$1\n\n$2 /og; - -# Convert iso-8859-1 copyright symbol or (c) to nroff -# character. -s/^Copyright +(?:\xa9|\([Cc]\))/Copyright \\(co/mg; - -while (length) -{ - # Convert some standard paragraph names. - if (s/^($PAT_OPTIONS): *\n+//o) - { - $sect = _('OPTIONS'); - next; - } - if (s/^($PAT_ENVIRONMENT): *\n+//o) - { - $sect = _('ENVIRONMENT'); - next; - } - if (s/^($PAT_FILES): *\n+//o) - { - $sect = _('FILES'); - next; - } - elsif (s/^($PAT_EXAMPLES): *\n+//o) - { - $sect = _('EXAMPLES'); - next; - } - - # Custom section indicated by a line containing "*Section Name*". - if (s/^\*(\w(.*\w)?)\* *\n+//) - { - $sect = uc $1; - $sect =~ tr/*/ /; # also accept *Section*Name* - push @sections, $sect; - next; - } - - # Copyright section. - if (/^Copyright /) - { - $sect = _('COPYRIGHT'); - } - - # Bug reporting section. - elsif (/^($PAT_BUGS) /o) - { - $sect = _('REPORTING BUGS'); - } - - # Author section. - elsif (/^($PAT_AUTHOR)/o) - { - $sect = _('AUTHOR'); - } - - # Examples, indicated by an indented leading $, % or > are - # rendered in a constant width font. - if (/^( +)([\$\%>] )\S/) - { - my $indent = $1; - my $prefix = $2; - my $break = '.IP'; - while (s/^$indent\Q$prefix\E(\S.*)\n*//) - { - $include{$sect} .= "$break\n\\f(CW$prefix$1\\fR\n"; - $break = '.br'; - } - - next; - } - - my $matched = ''; - - # Sub-sections have a trailing colon and the second line indented. - if (s/^(\S.*:) *\n / /) - { - $matched .= $& if %append_match; - $include{$sect} .= qq(.SS "$1"\n); - } - - my $indent = 0; - my $content = ''; - - # Option with description. - if (s/^( {1,10}([+-]\S.*?))(?:( +(?!-))|\n( {20,}))(\S.*)\n//) - { - $matched .= $& if %append_match; - $indent = length ($4 || "$1$3"); - $content = ".TP\n\x84$2\n\x84$5\n"; - unless ($4) - { - # Indent may be different on second line. - $indent = length $& if /^ {20,}/; - } - } - - # Option without description. - elsif (s/^ {1,10}([+-]\S.*)\n//) - { - $matched .= $& if %append_match; - $content = ".HP\n\x84$1\n"; - $indent = 80; # not continued - } - - # Indented paragraph with tag. - elsif (s/^( +(\S.*?))(?:( +)|\n( {20,}))(\S.*)\n//) - { - $matched .= $& if %append_match; - $indent = length ($4 || "$1$3"); - $content = ".TP\n\x84$2\n\x84$5\n"; - } - - # Indented paragraph. - elsif (s/^( +)(\S.*)\n//) - { - $matched .= $& if %append_match; - $indent = length $1; - $content = ".IP\n\x84$2\n"; - } - - # Left justified paragraph. - else - { - s/(.*)\n//; - $matched .= $& if %append_match; - $content = ".PP\n" if $include{$sect}; - $content .= "$1\n"; - } - - # Append continuations. - while ($indent ? s/^ {$indent}(\S.*)\n// : s/^(\S.*)\n//) - { - $matched .= $& if %append_match; - $content .= "\x84$1\n"; - } - - # Move to next paragraph. - s/^\n+//; - - for ($content) - { - # Leading dot and apostrophe protection. - s/\x84\./\x80/g; - s/\x84'/\x81/g; - s/\x84//g; - - # Examples should be verbatim. - unless ($sect eq _('EXAMPLES')) - { - # Convert options. - s/(^|[ (])(-[][\w=-]+)/$1 . convert_option $2/mge; - - # Italicise filenames: /a/b, $VAR/c/d, ~/e/f - s! - (^|[ (]) # space/punctuation before - ( - (?:\$\w+|~)? # leading variable, or tilde - (?:/\w(?:[\w.-]*\w)?)+ # path components - ) - ($|[ ,;.)]) # space/punctuation after - !$1\\fI$2\\fP$3!xmg; - - $_ = fix_italic_spacing $_; - } - - # Escape remaining hyphens. - s/-/\x83/g; - - if ($sect eq _('COPYRIGHT')) - { - # Insert line breaks before additional copyright messages - # and the disclaimer. - s/\n(Copyright |$PAT_FREE_SOFTWARE)/\n.br\n$1/og; - } - elsif ($sect eq _('REPORTING BUGS')) - { - # Handle multi-line bug reporting sections of the form: - # - # Report bugs to - # GNU home page: - # ... - s/\n([[:upper:]])/\n.br\n$1/g; - } - } - - # Check if matched paragraph contains /pat/. - if (%append_match) - { - for my $pat (keys %append_match) - { - if ($matched =~ $pat) - { - $content .= ".PP\n" unless $append_match{$pat} =~ /^\./; - $content .= $append_match{$pat}; - } - } - } - - $include{$sect} .= $content; -} - -# Refer to the real documentation. -unless ($opt_no_info) -{ - my $info_page = $opt_info || $program; - - $sect = _('SEE ALSO'); - $include{$sect} .= ".PP\n" if $include{$sect}; - $include{$sect} .= sprintf _(<<'EOT'), $program, $program, $info_page; -The full documentation for -.B %s -is maintained as a Texinfo manual. If the -.B info -and -.B %s -programs are properly installed at your site, the command -.IP -.B info %s -.PP -should give you access to the complete manual. -EOT -} - -# Append additional text. -while (my ($sect, $text) = each %append) -{ - $include{$sect} .= $append{$sect}; -} - -# Replace sections. -while (my ($sect, $text) = each %replace) -{ - $include{$sect} = $replace{$sect}; -} - -# Output header. -print < 1 } @pre, @post; - -# Output content. -my %done; -for my $sect (@pre, (grep !$filter{$_}, @sections), @post) -{ - next if $done{$sect}++; # ignore duplicates - next unless $include{$sect}; - if ($include{$sect}) - { - my $quote = $sect =~ /\W/ ? '"' : ''; - print enc ".SH $quote$sect$quote\n"; - - for ($include{$sect}) - { - # Replace leading dot, apostrophe, backslash and hyphen - # tokens. - s/\x80/\\&./g; - s/\x81/\\&'/g; - s/\x82/\\e/g; - s/\x83/\\-/g; - - # Convert some latin1 chars to troff equivalents - s/\xa0/\\ /g; # non-breaking space - - print enc $_; - } - } -} - -close STDOUT or kark N_("%s: error writing to %s (%s)"), $this_program, - $opt_output || 'stdout', $!; - -exit; - -# Get program basename, and strip libtool "lt-" prefix if required. -sub program_basename -{ - local $_ = shift; - s!.*/!!; - s/^lt-// if $opt_libtool; - $_; -} - -# Call program with given option and return results. -sub get_option_value -{ - my ($prog, $opt) = @_; - my $stderr = $discard_stderr ? '/dev/null' : '&1'; - my $value = join '', - map { s/ +$//; expand $_ } - map { dec $_ } - `$prog $opt 2>$stderr`; - - unless ($value) - { - my $err = N_("%s: can't get `%s' info from %s%s"); - my $extra = $discard_stderr - ? "\n" . N_("Try `--no-discard-stderr' if option outputs to stderr") - : ''; - - kark $err, $this_program, $opt, $prog, $extra; - } - - $value; -} - -# Convert option dashes to \- to stop nroff from hyphenating 'em, and -# embolden. Option arguments get italicised. -sub convert_option -{ - local $_ = '\fB' . shift; - - s/-/\x83/g; - unless (s/\[=(.*)\]$/\\fR[=\\fI$1\\fR]/) - { - s/=(.)/\\fR=\\fI$1/; - s/ (.)/ \\fI$1/; - $_ .= '\fR'; - } - - $_; -} - -# Insert spacing escape characters \, and \/ before and after italic text. See -# https://www.gnu.org/software/groff/manual/html_node/Ligatures-and-Kerning.html -sub fix_italic_spacing -{ - local $_ = shift; - s!\\fI(.*?)\\f([BRP])!\\fI\\,$1\\/\\f$2!g; - return $_; -} diff --git a/doc/local.mk b/doc/local.mk deleted file mode 100644 index b6742e6aa..000000000 --- a/doc/local.mk +++ /dev/null @@ -1,115 +0,0 @@ -## Included by top-level Makefile for Automake. - -## Copyright (C) 1995-2017 Free Software Foundation, Inc. -## -## This program is free software; you can redistribute it and/or modify -## it under the terms of the GNU General Public License as published by -## the Free Software Foundation; either version 2, or (at your option) -## any later version. -## -## This program is distributed in the hope that it will be useful, -## but WITHOUT ANY WARRANTY; without even the implied warranty of -## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -## GNU General Public License for more details. -## -## You should have received a copy of the GNU General Public License -## along with this program. If not, see . - -## ---------------- ## -## Documentation. ## -## ---------------- ## - -info_TEXINFOS = %D%/automake.texi %D%/automake-history.texi -doc_automake_TEXINFOS = %D%/fdl.texi -doc_automake_history_TEXINFOS = %D%/fdl.texi - -man1_MANS = \ - %D%/aclocal.1 \ - %D%/automake.1 \ - %D%/aclocal-$(APIVERSION).1 \ - %D%/automake-$(APIVERSION).1 - -$(man1_MANS): $(top_srcdir)/configure.ac - -CLEANFILES += $(man1_MANS) -# XXX: This script should be updated with 'fetch' target. -EXTRA_DIST += %D%/help2man - -update_mans = \ - $(AM_V_GEN): \ - && $(MKDIR_P) %D% \ - && ./pre-inst-env $(PERL) $(srcdir)/%D%/help2man --output=$@ - -%D%/aclocal.1 %D%/automake.1: - $(AM_V_GEN): \ - && $(MKDIR_P) %D% \ - && f=`echo $@ | sed 's|.*/||; s|\.1$$||; $(transform)'` \ - && echo ".so man1/$$f-$(APIVERSION).1" > $@ - -%D%/aclocal-$(APIVERSION).1: $(aclocal_script) lib/Automake/Config.pm - $(update_mans) aclocal-$(APIVERSION) -%D%/automake-$(APIVERSION).1: $(automake_script) lib/Automake/Config.pm - $(update_mans) automake-$(APIVERSION) - -## ---------------------------- ## -## Example package "amhello". ## -## ---------------------------- ## - -amhello_sources = \ - %D%/amhello/configure.ac \ - %D%/amhello/Makefile.am \ - %D%/amhello/README \ - %D%/amhello/src/main.c \ - %D%/amhello/src/Makefile.am - -amhello_configury = \ - aclocal.m4 \ - autom4te.cache \ - Makefile.in \ - config.h.in \ - configure \ - depcomp \ - install-sh \ - missing \ - src/Makefile.in - -dist_noinst_DATA += $(amhello_sources) -dist_doc_DATA = $(srcdir)/%D%/amhello-1.0.tar.gz - -setup_autotools_paths = { \ - ACLOCAL=aclocal-$(APIVERSION) && export ACLOCAL \ - && AUTOMAKE=automake-$(APIVERSION) && export AUTOMAKE \ - && AUTOCONF='$(am_AUTOCONF)' && export AUTOCONF \ - && AUTOM4TE='$(am_AUTOM4TE)' && export AUTOM4TE \ - && AUTORECONF='$(am_AUTORECONF)' && export AUTORECONF \ - && AUTOHEADER='$(am_AUTOHEADER)' && export AUTOHEADER \ - && AUTOUPDATE='$(am_AUTOUPDATE)' && export AUTOUPDATE \ - && true; \ -} - -# We depend on configure.ac so that we regenerate the tarball -# whenever the Automake version changes. -$(srcdir)/%D%/amhello-1.0.tar.gz: $(amhello_sources) $(srcdir)/configure.ac - $(AM_V_GEN)tmp=amhello-output.tmp \ - && $(am__cd) $(srcdir)/%D%/amhello \ - && : Make our aclocal and automake avaiable before system ones. \ - && $(setup_autotools_paths) \ - && ( \ - { $(AM_V_P) || exec 5>&2 >$$tmp 2>&1; } \ - && $(abs_builddir)/pre-inst-env $(am_AUTORECONF) -vfi \ - && ./configure \ - && $(MAKE) $(AM_MAKEFLAGS) distcheck \ - && $(MAKE) $(AM_MAKEFLAGS) distclean \ - || { \ - if $(AM_V_P); then :; else \ - echo "$@: recipe failed." >&5; \ - echo "See file '`pwd`/$$tmp' for details" >&5; \ - fi; \ - exit 1; \ - } \ - ) \ - && rm -rf $(amhello_configury) $$tmp \ - && mv -f amhello-1.0.tar.gz .. - - -# vim: ft=automake noet diff --git a/gen-testsuite-part b/gen-testsuite-part deleted file mode 100755 index 3c5fc3852..000000000 --- a/gen-testsuite-part +++ /dev/null @@ -1,420 +0,0 @@ -#! /usr/bin/env perl -# Automatically compute some dependencies for the hand-written tests -# of the Automake testsuite. Also, automatically generate some more -# tests from them (for particular cases/setups only). - -# Copyright (C) 2011-2017 Free Software Foundation, Inc. - -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -#-------------------------------------------------------------------------- - -use warnings FATAL => "all"; -use strict; -use File::Basename (); -use constant TRUE => 1; -use constant FALSE => 0; - -my $me = File::Basename::basename $0; - -# For use in VPATH builds. -my $srcdir = "."; - -# The testsuite subdirectory, relative to the top-lever source directory. -my $testdir = "t"; - -# Where testsuite-related helper scripts, data files and shell libraries -# are placed. Relative to the top-lever source directory. -my $testauxdir = "$testdir/ax"; - -#-------------------------------------------------------------------------- - -sub unindent ($) -{ - my $text = shift; - $text =~ /^(\s*)/; - my $indentation = $1; - $text =~ s/^$indentation//gm; - return $text; -} - -sub atomic_write ($$;$) -{ - my ($outfile, $func) = (shift, shift); - my $perms = @_ > 0 ? shift : 0777; - my $tmpfile = "$outfile-t"; - foreach my $f ($outfile, $tmpfile) - { - unlink $f or die "$me: cannot unlink '$f': $!\n" - if -e $f; - } - open (my $fh, ">$tmpfile") - or die "$me: can't write to '$tmpfile': $!\n"; - $func->($fh); - close $fh - or die "$me: closing '$tmpfile': $!\n"; - chmod ($perms & ~umask, $tmpfile) - or die "$me: cannot change perms for '$tmpfile': $!\n"; - rename ($tmpfile, $outfile) - or die "$me: renaming '$tmpfile' -> '$outfile: $!\n'"; -} - -sub line_match ($$) -{ - my ($re, $file) = (shift, shift); - # Try both builddir and srcdir, with builddir first, to play nice - # with VPATH builds. - open (FH, "<$file") or open (FH, "<$srcdir/$file") - or die "$me: cannot open file '$file': $!\n"; - my $ret = 0; - while (defined (my $line = )) - { - if ($line =~ $re) - { - $ret = 1; - last; - } - } - close FH or die "$me: cannot close file '$file': $!\n"; - return $ret; -} - -sub write_wrapper_script ($$$) -{ - my ($file_handle, $wrapped_test, $shell_setup_code, $creator_name) = @_; - print $file_handle unindent <&2 - exit 99 -EOF -} - -sub get_list_of_tests () -{ - my $make = defined $ENV{MAKE} ? $ENV{MAKE} : "make"; - # Unset MAKEFLAGS, for when we are called from make itself. - my $cmd = "MAKEFLAGS= && unset MAKEFLAGS && cd '$srcdir' && " - . "$make -s -f $testdir/list-of-tests.mk print-list-of-tests"; - my @tests_list = split /\s+/, `$cmd`; - die "$me: cannot get list of tests\n" unless $? == 0 && @tests_list; - my $ok = 1; - foreach my $test (@tests_list) - { - # Respect VPATH builds. - next if -f $test || -f "$srcdir/$test"; - warn "$me: test '$test' not found\n"; - $ok = 0; - } - die "$me: some test scripts not found\n" if !$ok; - return @tests_list; -} - -sub parse_options (@) -{ - use Getopt::Long qw/GetOptions/; - local @ARGV = @_; - GetOptions ('srcdir=s' => \$srcdir) or die "$me: usage error\n"; - die "$me: too many arguments\n" if @ARGV > 0; - die "$me: srcdir '$srcdir': not a directory\n" unless -d $srcdir; -} - -#-------------------------------------------------------------------------- - -my %deps_extractor = - ( - libtool_macros => - { - line_matcher => qr/^\s*required=.*\blibtool/, - nodist_prereqs => "$testdir/libtool-macros.log", - }, - gettext_macros => - { - line_matcher => qr/^\s*required=.*\bgettext/, - nodist_prereqs => "$testdir/gettext-macros.log", - }, - pkgconfig_macros => - { - line_matcher => qr/^\s*required=.*\bpkg-config/, - nodist_prereqs => "$testdir/pkg-config-macros.log", - }, - use_trivial_test_driver => - { - line_matcher => qr/\btrivial-test-driver\b/, - dist_prereqs => "$testauxdir/trivial-test-driver", - }, - check_testsuite_summary => - { - line_matcher => qr/\btestsuite-summary-checks\.sh\b/, - dist_prereqs => "$testauxdir/testsuite-summary-checks.sh", - }, - extract_testsuite_summary => - { - line_matcher => qr/\bextract-testsuite-summary\.pl\b/, - dist_prereqs => "$testauxdir/extract-testsuite-summary.pl", - }, - check_tap_testsuite_summary => - { - line_matcher => qr/\btap-summary-aux\.sh\b/, - dist_prereqs => "$testauxdir/tap-summary-aux.sh", - }, - on_tap_with_common_setup => - { - line_matcher => qr/\btap-setup\.sh\b/, - dist_prereqs => "$testauxdir/tap-setup.sh", - nodist_prereqs => "$testdir/tap-common-setup.log", - }, - depcomp => - { - line_matcher => qr/\bdepcomp\.sh\b/, - dist_prereqs => "$testauxdir/depcomp.sh", - }, - ); - -#-------------------------------------------------------------------------- - -my %test_generators = - ( - # - # Any test script in the Automake testsuite that checks features of - # the Automake-provided parallel testsuite harness might want to - # define a sibling test that does similar checks, but for the old - # serial testsuite harness instead. - # - # Individual tests can request the creation of such a sibling by - # making the string "try-with-serial-tests" appear any line of the - # test itself. - # - serial_testsuite_harness => - { - line_matcher => qr/\btry-with-serial-tests\b/, - shell_setup_code => 'am_serial_tests=yes', - }, - # - # For each test script in the Automake testsuite that tests features - # of one or more automake-provided shell script from the 'lib/' - # subdirectory by running those scripts directly (i.e., not thought - # make calls and automake-generated makefiles), define a sibling test - # that does likewise, but running the said script with the configure - # time $SHELL instead of the default system shell /bin/sh. - # - # A test is considered a candidate for sibling-generation if it calls - # the 'get_shell_script' function anywhere. - # - # Individual tests can prevent the creation of such a sibling by - # explicitly setting the '$am_test_prefer_config_shell' variable - # to either "yes" or "no". - # The rationale for this is that if the variable is set to "yes", - # the test already uses $SHELL, so that a sibling would be just a - # duplicate; while if the variable is set to "no", the test doesn't - # support, or is not meant to use, $SHELL to run the script under - # testing, and forcing it to do so in the sibling would likely - # cause a spurious failure. - # - prefer_config_shell => - { - line_matcher => - qr/(^|\s)get_shell_script\s/, - line_rejecter => - qr/\bam_test_prefer_config_shell=/, - shell_setup_code => - 'am_test_prefer_config_shell=yes', - }, - ); - -#-------------------------------------------------------------------------- - -parse_options @ARGV; - -my @all_tests = get_list_of_tests; -my @generated_tests = (); # Will be updated later. - -print "## -*- Makefile -*-\n"; -print "## Generated by $me. DO NOT EDIT BY HAND!\n\n"; - -print <{line_matcher}, $test; - next - if $x->{line_rejecter} and line_match $x->{line_rejecter}, $test; - @setups = map { ($_, "$_\n$x->{shell_setup_code}") } @setups; - } - @setups = grep { $_ ne '' } @setups; - $wrapper_setups{$test} = \@setups if @setups; - } -# And now create all the wrapper tests. -for my $wrapped_test (sort keys %wrapper_setups) - { - my $setup_list = $wrapper_setups{$wrapped_test}; - (my $base = $wrapped_test) =~ s/\.([^.]*)$//; - my $suf = $1 or die "$me: test '$wrapped_test' lacks a suffix\n"; - my $count = 0; - foreach my $setup (@$setup_list) - { - $count++; - my $wbase = "$base-w" . ($count > 1 ? $count : ''); - my $wrapper_test = "$wbase.$suf"; - # Register wrapper test as "autogenerated". - push @generated_tests, $wrapper_test; - # Create wrapper test. - atomic_write $wrapper_test, - sub { write_wrapper_script $_[0], $wrapped_test, - $setup }, - 0444; - # The generated test works by sourcing the original test, so that - # it has to be re-run every time that changes ... - print "$wbase.log: $wrapped_test\n"; - # ... but also every time the prerequisites of the wrapped test - # changes. The simpler (although suboptimal) way to do so is to - # ensure that the wrapped tests runs before the wrapper one (in - # case it needs to be re-run *at all*). - # FIXME: we could maybe refactor the script to find a more - # granular way to express such implicit dependencies. - print "$wbase.log: $base.log\n"; - } - } - -print < ["cc"], - disabled => ["cc"], - makedepend => ["cc", "makedepend", "-c-o"], - dashmstdout => ["gcc"], - cpp => ["gcc"], -# This was for older (pre-3.x) GCC versions (newer versions -# have depmode "gcc3"). But other compilers use this depmode -# as well (for example, the IMB xlc/xlC compilers, and the HP -# C compiler, see 'lib/depcomp' for more info), so it's not -# obsolete, and it's worth giving it some coverage. - gcc => ["gcc"], -# This is for older (pre-7) msvc versions. Newer versions -# have depmodes "msvc7" and "msvc7msys". - msvisualcpp => ["cl", "cygpath"], - msvcmsys => ["cl", "mingw"], - ); - -foreach my $lt (TRUE, FALSE) - { - foreach my $m (sort keys %depmodes) - { - my $planned = ($lt && $m eq "auto") ? 84 : 28; - my @required = - ( - @{$depmodes{$m}}, - $lt ? ("libtoolize",) : (), - ); - my @vars_init = - ( - "am_create_testdir=empty", - "depmode=$m", - "depcomp_with_libtool=" . ($lt ? "yes" : "no"), - ); - my $test = "$testdir/depcomp" . ($lt ? "-lt-" : "-") . "$m.tap"; - # Register wrapper test as "autogenerated" ... - push @generated_tests, $test; - # ... and create it. - atomic_write ($test, sub - { - my $file_handle = shift; - print $file_handle unindent <{dist_prereqs} || ""; - my $nodist_prereqs = $x->{nodist_prereqs} || ""; - my @tests = grep { line_match $x->{line_matcher}, $_ } @all_tests; - map { s/\.[^.]*$//; s/$/\.log/; } (my @logs = @tests); - print "## Added by deps-extracting key '$k'.\n"; - ## The list of all tests which have a dependency detected by the - ## current key. - print join(" \\\n ", "${k}_TESTS =", @tests) . "\n"; - print "EXTRA_DIST += $dist_prereqs\n"; - map { print "$_: $dist_prereqs $nodist_prereqs\n" } @logs; - print "\n"; - } - -__END__ diff --git a/lib/Automake/ChannelDefs.pm b/lib/Automake/ChannelDefs.pm deleted file mode 100644 index a127b2f49..000000000 --- a/lib/Automake/ChannelDefs.pm +++ /dev/null @@ -1,444 +0,0 @@ -# Copyright (C) 2002-2017 Free Software Foundation, Inc. - -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -package Automake::ChannelDefs; - -use Automake::Config; -BEGIN -{ - if ($perl_threads) - { - require threads; - import threads; - } -} -use Automake::Channels; - -=head1 NAME - -Automake::ChannelDefs - channel definitions for Automake and helper functions - -=head1 SYNOPSIS - - use Automake::ChannelDefs; - - Automake::ChannelDefs::usage (); - prog_error ($MESSAGE, [%OPTIONS]); - error ($WHERE, $MESSAGE, [%OPTIONS]); - error ($MESSAGE); - fatal ($WHERE, $MESSAGE, [%OPTIONS]); - fatal ($MESSAGE); - verb ($MESSAGE, [%OPTIONS]); - switch_warning ($CATEGORY); - parse_WARNINGS (); - parse_warnings ($OPTION, $ARGUMENT); - Automake::ChannelDefs::set_strictness ($STRICTNESS_NAME); - -=head1 DESCRIPTION - -This packages defines channels that can be used in Automake to -output diagnostics and other messages (via C). It also defines -some helper function to enable or disable these channels, and some -shorthand function to output on specific channels. - -=cut - -use 5.006; -use strict; -use Exporter; - -use vars qw (@ISA @EXPORT); - -@ISA = qw (Exporter); -@EXPORT = qw (&prog_error &error &fatal &verb - &switch_warning &parse_WARNINGS &parse_warnings); - -=head2 CHANNELS - -The following channels can be used as the first argument of -C. For some of them we list a shorthand -function that makes the code more readable. - -=over 4 - -=item C - -Fatal errors. Use C<&fatal> to send messages over this channel. - -=item C - -Common errors. Use C<&error> to send messages over this channel. - -=item C - -Errors related to GNU Standards. - -=item C - -Errors related to GNU Standards that should be warnings in 'foreign' mode. - -=item C - -Errors related to GNITS Standards (silent by default). - -=item C - -Internal errors. Use C<&prog_error> to send messages over this channel. - -=item C - -Warnings related to GNU Coding Standards. - -=item C - -Warnings about obsolete features (silent by default). - -=item C - -Warnings about user redefinitions of Automake rules or -variables (silent by default). - -=item C - -Warnings about non-portable constructs. - -=item C - -Extra warnings about non-portable constructs covering obscure tools. - -=item C - -Warnings about weird syntax, unused variables, typos... - -=item C - -Warnings about unsupported (or mis-supported) features. - -=item C - -Messages output in C<--verbose> mode. Use C<&verb> to send such messages. - -=item C - -Informative messages. - -=back - -=cut - -# Initialize our list of error/warning channels. -# Do not forget to update &usage and the manual -# if you add or change a warning channel. - -register_channel 'fatal', type => 'fatal', uniq_part => UP_NONE, ordered => 0; -register_channel 'error', type => 'error'; -register_channel 'error-gnu', type => 'error'; -register_channel 'error-gnu/warn', type => 'error'; -register_channel 'error-gnits', type => 'error', silent => 1; -register_channel 'automake', type => 'fatal', backtrace => 1, - header => ("####################\n" . - "## Internal Error ##\n" . - "####################\n"), - footer => "\nPlease contact <$PACKAGE_BUGREPORT>.", - uniq_part => UP_NONE, ordered => 0; - -register_channel 'extra-portability', type => 'warning', silent => 1; -register_channel 'gnu', type => 'warning'; -register_channel 'obsolete', type => 'warning'; -register_channel 'override', type => 'warning', silent => 1; -register_channel 'portability', type => 'warning', silent => 1; -register_channel 'portability-recursive', type => 'warning', silent => 1; -register_channel 'syntax', type => 'warning'; -register_channel 'unsupported', type => 'warning'; - -register_channel 'verb', type => 'debug', silent => 1, uniq_part => UP_NONE, - ordered => 0; -register_channel 'note', type => 'debug', silent => 0; - -setup_channel_type 'warning', header => 'warning: '; -setup_channel_type 'error', header => 'error: '; -setup_channel_type 'fatal', header => 'error: '; - -=head2 FUNCTIONS - -=over 4 - -=item C - -Display warning categories. - -=cut - -sub usage () -{ - print < - -Signal a programming error (on channel C), -display C<$MESSAGE>, and exit 1. - -=cut - -sub prog_error ($;%) -{ - my ($msg, %opts) = @_; - msg 'automake', '', $msg, %opts; -} - -=item C - -=item C - -Uncategorized errors. - -=cut - -sub error ($;$%) -{ - my ($where, $msg, %opts) = @_; - msg ('error', $where, $msg, %opts); -} - -=item C - -=item C - -Fatal errors. - -=cut - -sub fatal ($;$%) -{ - my ($where, $msg, %opts) = @_; - msg ('fatal', $where, $msg, %opts); -} - -=item C - -C<--verbose> messages. - -=cut - -sub verb ($;%) -{ - my ($msg, %opts) = @_; - $msg = "thread " . threads->tid . ": " . $msg - if $perl_threads; - msg 'verb', '', $msg, %opts; -} - -=item C - -If C<$CATEGORY> is C, turn on channel C. -If it's C, turn C off. -Else handle C and C for completeness. - -=cut - -sub switch_warning ($) -{ - my ($cat) = @_; - my $has_no = 0; - - if ($cat =~ /^no-(.*)$/) - { - $cat = $1; - $has_no = 1; - } - - if ($cat eq 'all') - { - setup_channel_type 'warning', silent => $has_no; - } - elsif ($cat eq 'none') - { - setup_channel_type 'warning', silent => ! $has_no; - } - elsif ($cat eq 'error') - { - $warnings_are_errors = ! $has_no; - # Set exit code if Perl warns about something - # (like uninitialized variables). - $SIG{"__WARN__"} = - $has_no ? 'DEFAULT' : sub { print STDERR @_; $exit_code = 1; }; - } - elsif (channel_type ($cat) eq 'warning') - { - setup_channel $cat, silent => $has_no; - # - # Handling of portability warnings is trickier. For relevant tests, - # see 'dollarvar2', 'extra-portability' and 'extra-portability3'. - # - # -Wportability-recursive and -Wno-portability-recursive should not - # have any effect on other 'portability' or 'extra-portability' - # warnings, so there's no need to handle them separately or ad-hoc. - # - if ($cat eq 'extra-portability' && ! $has_no) # -Wextra-portability - { - # -Wextra-portability must enable 'portability' and - # 'portability-recursive' warnings. - setup_channel 'portability', silent => 0; - setup_channel 'portability-recursive', silent => 0; - } - if ($cat eq 'portability') # -Wportability or -Wno-portability - { - if ($has_no) # -Wno-portability - { - # -Wno-portability must disable 'extra-portability' and - # 'portability-recursive' warnings. - setup_channel 'portability-recursive', silent => 1; - setup_channel 'extra-portability', silent => 1; - } - else # -Wportability - { - # -Wportability must enable 'portability-recursive' - # warnings. But it should have no influence over the - # 'extra-portability' warnings. - setup_channel 'portability-recursive', silent => 0; - } - } - } - else - { - return 1; - } - return 0; -} - -=item C - -Parse the WARNINGS environment variable. - -=cut - -sub parse_WARNINGS () -{ - if (exists $ENV{'WARNINGS'}) - { - # Ignore unknown categories. This is required because WARNINGS - # should be honored by many tools. - switch_warning $_ foreach (split (',', $ENV{'WARNINGS'})); - } -} - -=item C - -Parse the argument of C<--warning=CATEGORY> or C<-WCATEGORY>. - -C<$OPTIONS> is C<"--warning"> or C<"-W">, C<$ARGUMENT> is C. - -This is meant to be used as an argument to C. - -=cut - -sub parse_warnings ($$) -{ - my ($opt, $categories) = @_; - - foreach my $cat (split (',', $categories)) - { - msg 'unsupported', "unknown warning category '$cat'" - if switch_warning $cat; - } -} - -=item C - -Configure channels for strictness C<$STRICTNESS_NAME>. - -=cut - -sub set_strictness ($) -{ - my ($name) = @_; - - if ($name eq 'gnu') - { - setup_channel 'error-gnu', silent => 0; - setup_channel 'error-gnu/warn', silent => 0, type => 'error'; - setup_channel 'error-gnits', silent => 1; - setup_channel 'portability', silent => 0; - setup_channel 'extra-portability', silent => 1; - setup_channel 'gnu', silent => 0; - } - elsif ($name eq 'gnits') - { - setup_channel 'error-gnu', silent => 0; - setup_channel 'error-gnu/warn', silent => 0, type => 'error'; - setup_channel 'error-gnits', silent => 0; - setup_channel 'portability', silent => 0; - setup_channel 'extra-portability', silent => 1; - setup_channel 'gnu', silent => 0; - } - elsif ($name eq 'foreign') - { - setup_channel 'error-gnu', silent => 1; - setup_channel 'error-gnu/warn', silent => 0, type => 'warning'; - setup_channel 'error-gnits', silent => 1; - setup_channel 'portability', silent => 1; - setup_channel 'extra-portability', silent => 1; - setup_channel 'gnu', silent => 1; - } - else - { - prog_error "level '$name' not recognized"; - } -} - -=back - -=head1 SEE ALSO - -L - -=head1 HISTORY - -Written by Alexandre Duret-Lutz EFE. - -=cut - -1; - -### Setup "GNU" style for perl-mode and cperl-mode. -## Local Variables: -## perl-indent-level: 2 -## perl-continued-statement-offset: 2 -## perl-continued-brace-offset: 0 -## perl-brace-offset: 0 -## perl-brace-imaginary-offset: 0 -## perl-label-offset: -2 -## cperl-indent-level: 2 -## cperl-brace-offset: 0 -## cperl-continued-brace-offset: 0 -## cperl-label-offset: -2 -## cperl-extra-newline-before-brace: t -## cperl-merge-trailing-else: nil -## cperl-continued-statement-offset: 2 -## End: diff --git a/lib/Automake/Channels.pm b/lib/Automake/Channels.pm deleted file mode 100644 index 3fc4f6407..000000000 --- a/lib/Automake/Channels.pm +++ /dev/null @@ -1,836 +0,0 @@ -# Copyright (C) 2002-2017 Free Software Foundation, Inc. - -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . - -############################################################### -# The main copy of this file is in Automake's git repository. # -# Updates should be sent to automake-patches@gnu.org. # -############################################################### - -package Automake::Channels; - -=head1 NAME - -Automake::Channels - support functions for error and warning management - -=head1 SYNOPSIS - - use Automake::Channels; - - # Register a channel to output warnings about unused variables. - register_channel 'unused', type => 'warning'; - - # Register a channel for system errors. - register_channel 'system', type => 'error', exit_code => 4; - - # Output a message on channel 'unused'. - msg 'unused', "$file:$line", "unused variable '$var'"; - - # Make the 'unused' channel silent. - setup_channel 'unused', silent => 1; - - # Turn on all channels of type 'warning'. - setup_channel_type 'warning', silent => 0; - - # Redirect all channels to push messages on a Thread::Queue using - # the specified serialization key. - setup_channel_queue $queue, $key; - - # Output a message pending in a Thread::Queue. - pop_channel_queue $queue; - - # Treat all warnings as errors. - $warnings_are_errors = 1; - - # Exit with the greatest exit code encountered so far. - exit $exit_code; - -=head1 DESCRIPTION - -This perl module provides support functions for handling diagnostic -channels in programs. Channels can be registered to convey fatal, -error, warning, or debug messages. Each channel has various options -(e.g. is the channel silent, should duplicate messages be removed, -etc.) that can also be overridden on a per-message basis. - -=cut - -use 5.006; -use strict; -use Exporter; -use Carp; -use File::Basename; - -use vars qw (@ISA @EXPORT %channels $me); - -@ISA = qw (Exporter); -@EXPORT = qw ($exit_code $warnings_are_errors - &reset_local_duplicates &reset_global_duplicates - ®ister_channel &msg &exists_channel &channel_type - &setup_channel &setup_channel_type - &dup_channel_setup &drop_channel_setup - &buffer_messages &flush_messages - &setup_channel_queue &pop_channel_queue - US_GLOBAL US_LOCAL - UP_NONE UP_TEXT UP_LOC_TEXT); - -$me = basename $0; - -=head2 Global Variables - -=over 4 - -=item C<$exit_code> - -The greatest exit code seen so far. C<$exit_code> is updated from -the C options of C and C channels. - -=cut - -use vars qw ($exit_code); -$exit_code = 0; - -=item C<$warnings_are_errors> - -Set this variable to 1 if warning messages should be treated as -errors (i.e. if they should update C<$exit_code>). - -=cut - -use vars qw ($warnings_are_errors); -$warnings_are_errors = 0; - -=back - -=head2 Constants - -=over 4 - -=item C, C, C - -Possible values for the C options. This selects the part -of the message that should be considered when filtering out duplicates. -If C is used, the location and the explanation message -are used for filtering. If C is used, only the explanation -message is used (so the same message will be filtered out if it appears -at different locations). C means that duplicate messages -should be output. - -=cut - -use constant UP_NONE => 0; -use constant UP_TEXT => 1; -use constant UP_LOC_TEXT => 2; - -=item C, C - -Possible values for the C options. -Use C for error messages that should be printed only -once during the execution of the program, C for message that -should be printed only once per file. (Actually, C does not -do this now when files are changed, it relies on you calling -C when this happens.) - -=cut - -# possible values for uniq_scope -use constant US_LOCAL => 0; -use constant US_GLOBAL => 1; - -=back - -=head2 Options - -Channels accept the options described below. These options can be -passed as a hash to the C, C, and C -functions. The possible keys, with their default value are: - -=over - -=item C 'warning'> - -The type of the channel. One of C<'debug'>, C<'warning'>, C<'error'>, or -C<'fatal'>. Fatal messages abort the program when they are output. -Error messages update the exit status. Debug and warning messages are -harmless, except that warnings are treated as errors if -C<$warnings_are_errors> is set. - -=item C 1> - -The value to update C<$exit_code> with when a fatal or error message -is emitted. C<$exit_code> is also updated for warnings output -when C<$warnings_are_errors> is set. - -=item C \*STDERR> - -The file where the error should be output. - -=item C 0> - -Whether the channel should be silent. Use this do disable a -category of warning, for instance. - -=item C 1> - -Whether, with multi-threaded execution, the message should be queued -for ordered output. - -=item C UP_LOC_TEXT> - -The part of the message subject to duplicate filtering. See the -documentation for the C, C, and C -constants above. - -C can also be set to an arbitrary string that will be used -instead of the message when considering duplicates. - -=item C US_LOCAL> - -The scope of duplicate filtering. See the documentation for the -C, and C constants above. - -=item C
''> - -A string to prepend to each message emitted through this channel. -With partial messages, only the first part will have C
-prepended. - -=item C