From: Stefano Lattarini Date: Fri, 27 Jul 2012 09:13:26 +0000 (+0200) Subject: [ng] header vars: prefer '#' comments over '##' ones; improve few comments X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=634f9a53d3a7981191ae7e1b241332cba6b43632;p=thirdparty%2Fautomake.git [ng] header vars: prefer '#' comments over '##' ones; improve few comments * lib/am/header-vars.am: Here, throughout the file. This will make it easier for someone reading the generated Makefile.in to understand what it's going on. And improve/fix few existing comments while at it. Signed-off-by: Stefano Lattarini --- diff --git a/lib/am/header-vars.am b/lib/am/header-vars.am index ca9450d6a..472d0b2b5 100644 --- a/lib/am/header-vars.am +++ b/lib/am/header-vars.am @@ -14,21 +14,21 @@ ## You should have received a copy of the GNU General Public License ## along with this program. If not, see . -## Makefiles generated by Automake-NG require GNU make >= 3.81. -## The .FEATURES special variable has been introduced in that make -## version, so use it as a witness to determine whether the current -## make is good enough. +# Makefiles generated by Automake-NG require GNU make >= 3.81. +# The .FEATURES special variable has been introduced in that make +# version, so use it as a witness to determine whether the current +# make is good enough. ifndef .FEATURES $(error Automake-NG based builds require GNU make 3.81 or later) endif VPATH = $(srcdir) -## Enhance performance by removing GNU make builtin rules that would be -## rather irrelevant (e.g., rules to automatically check out files from -## from RCS or SCCS repositories), or overridden by Automake (e.g., rules -## to compile C or C++ files). For larger packages (like GNU coreutils), -## this can greatly speed up null or almost-null builds, up to even 50%! +# Enhance performance by removing GNU make builtin rules that would be +# rather irrelevant (e.g., rules to automatically check out files from +# from RCS or SCCS repositories), or overridden by Automake (e.g., rules +# to compile C or C++ files). For larger packages (like GNU coreutils), +# this can greatly speed up null or almost-null builds, up to even 50%! MAKEFLAGS += --no-builtin-rules # For when we need a do-nothing target. Add an actual rule to it to avoid @@ -37,9 +37,9 @@ MAKEFLAGS += --no-builtin-rules .am/nil: @: -## Declare an error, without immediately terminating the execution (proper -## code will take care later of that). This will allow us to diagnose more -## issues at once, rather than stopping at the first one. +# Declare an error, without immediately terminating the execution (proper +# code will take care later of that). This will allow us to diagnose more +# issues at once, rather than stopping at the first one. am.error.seen := define am.error $(warning $1)$(eval am.error.seen := yes) @@ -70,8 +70,8 @@ define am.chars.newline $(am.chars.empty) endef -## Neutralize unwarranted environment settings that might interfere with -## our Makefiles. +# Neutralize unwarranted environment settings that might interfere with +# our Makefiles. ifdef SUBDIRS ifneq "$(origin SUBDIRS)" "file" ifneq "$(origin SUBDIRS)" "command line" @@ -110,12 +110,12 @@ am__ensure_dir_exists = \ # exists, by creating it if necessary. am__ensure_target_dir_exists = $(call am__ensure_dir_exists,$(@D)) -## The 'all' target must be the default one, independently from the -## position it is declared in the output Makefile. +# The 'all' target must be the default one, independently from the +# position it is declared in the output Makefile. .DEFAULT_GOAL := all -## Emulate VPATH rewrites. This uses only GNU make primitives, which -## allows us to avoid extra forks. +# Emulate VPATH rewrites. This uses only GNU make primitives, which +# allows us to avoid extra forks. am.vpath.rewrite = \ $(firstword $(wildcard $(strip $(1))) $(srcdir)/$(strip $(1))) @@ -123,15 +123,15 @@ am.vpath.rewrite = \ # with mainline Automake. DESTDIR ?= -## Tell whether make is running in "dry mode". It is either 'true' or -## 'false', so that it can be easily used in shell code as well as in -## GNU make conditionals. -## If we run "make TESTS='snooze nap'", GNU make will export MAKEFLAGS to -## "TESTS=foo\ nap", so that the builtins operating on word-split lists -## would see a "make flag" equal to "nap" when analyzing $(MAKEFLAGS), and -## would wrongly misinterpret that as and indication that make is running -## in dry mode. This has already happened in practice. So we need the -## hack with $(subst \ , ...). +# Tell whether make is running in "dry mode". It is either 'true' or +# 'false', so that it can be easily used in shell code as well as in +# GNU make conditionals. +# If we run "make TESTS='snooze nap'", GNU make will export MAKEFLAGS to +# "TESTS=foo\ nap", so that the builtins operating on word-split lists +# would see a "make flag" equal to "nap" when analyzing $(MAKEFLAGS), and +# would wrongly misinterpret that as and indication that make is running +# in dry mode. This has already happened in practice. So we need the +# hack with $(subst \ , ...). am.make.dry-run := \ $(strip $(if $(strip \ $(foreach v, $(subst \ ,,$(strip $(MAKEFLAGS))), \ @@ -142,8 +142,8 @@ am.make.dry-run := \ am.util.strip-first-word = $(wordlist 2,$(words $(1)),$(1)) am.util.strip-last-word = $(wordlist 2,$(words $(1)),dummy $(1)) -## Remove repeated elements from the given list (without reordering), -## and return the reduced list. +# Remove repeated elements from the given list (without reordering), +# and return the reduced list. am.util.uniq = $(strip \ ## If the list is empty, we have nothing to do. Otherwise, go on. $(if $(strip $(1)), \ @@ -212,34 +212,34 @@ am.util.canon = $(strip \ $(subst !,_,$1))))))))))))))))))))))))))))))) -## Simple memoization for recursive make variables. It is useful for -## situations where immediate variables can't be used (due, say, to -## ordering issues with the assignments of the referenced variables), -## but where the value of the lazy variable is costly to calculate -## (e.g., a $(shell ...) call with a non-trivial command line), so that -## we can't afford to re-calculate it over and over every time the -## variable gets expanded. Example of usage: -## -## var1 = $(am.memoize,var1,$(shell EXPENSIVE-COMMAND-LINE)) -## var2 = $(am.memoize,var2,$(sort VERY-LONG-LIST)) -## -## This API and implementation seems to work around a bug in GNU make -## (present up to and including version 3.82) which caused our first -## implementation attempts to fail: -## -## -## -## -## So please don't change this without a very good reason. -## +# Simple memoization for recursive make variables. It is useful for +# situations where immediate variables can't be used (due, say, to +# ordering issues with the assignments of the referenced variables), +# but where the value of the lazy variable is costly to calculate +# (e.g., a $(shell ...) call with a non-trivial command line), so that +# we can't afford to re-calculate it over and over every time the +# variable gets expanded. Example of usage: +# +# var1 = $(am.memoize,var1,$(shell EXPENSIVE-COMMAND-LINE)) +# var2 = $(am.memoize,var2,$(sort VERY-LONG-LIST)) +# +# This API and implementation seems to work around a bug in GNU make +# (present up to and including version 3.82) which caused our first +# implementation attempts to fail: +# +# +# +# +# So please don't change this without a very good reason. +# am.memoize = $(or $(am.memoize.value/$1),$(strip \ $(eval am.memoize.value/$1 := $$2))$(am.memoize.value/$1)) -## $(call am.util.strip-suffixes, SUFFIXES, LIST) -## ---------------------------------------------- -## Strip any of the SUFFIXES from each of the entries of LIST. Even if an -## entry of LIST terminates with several suffixes, only one is stripped: -## the first one that matches. +# $(call am.util.strip-suffixes, SUFFIXES, LIST) +# ---------------------------------------------- +# Strip any of the SUFFIXES from each of the entries of LIST. Even if an +# entry of LIST terminates with several suffixes, only one is stripped: +# the first one that matches. am.hack.private-suffix = .,;&!@ am.util.strip-suffixes = $(strip \ $(if \ @@ -250,18 +250,20 @@ am.util.strip-suffixes = $(strip \ $(patsubst %$(firstword $1),%$(am.hack.private-suffix),$2))), \ $2)) -# Helper variables and function to help in recipes that could exceed -# the command line length limit. +# Now, some helper functions and variables to help in recipes that could +# exceed the command line length limit. -## FIXME: Forty aguments; this is basically arbitrary. In the long term, -## FIXME: defining this after a configure-time test on the command-line -## FIXME: length limits, or at least on a system-by-system basis, might -## FIXME: be better. But don't make it too big, or our implementation -## FIXME: will likely suffer in performance and memory consumption. # And in the Information Age, we somehow managed to revert to abacus-like # counting. Yay for us :-) am.max-cmdline-args := xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +# FIXME! The above accounts for max forty aguments; this is basically +# arbitrary. In the long term, defining that after a configure-time test +# on the command-line length limits, or at least on a system-by-system +# basis, might be better. But don't make the new limit too big (even if +# the system would allow it), or our implementation will likely suffer in +# performance and in memory consumption. + # $(call am.xargs-map,FUNCTION,LIST) # ---------------------------------- # Map the function $1 on the arguments $2, ensuring that each @@ -292,7 +294,10 @@ am.rm-rf = $(if $(strip $1),rm -rf $(strip $1)$(am.chars.newline)) am.clean-cmd.f = $(call am.xargs-map,am.rm-f,$1) am.clean-cmd.d = $(call am.xargs-map,am.rm-rf,$1) -## Some derived variables that have been found to be useful. +# Some derived variables that have been found to be useful. +# These have since long been documented in the Automake manual and used +# by many real-world packages, so they are now an established feature +# and should not be changed. pkgdatadir = $(datadir)/$(PACKAGE) pkgincludedir = $(includedir)/$(PACKAGE) pkglibdir = $(libdir)/$(PACKAGE) @@ -304,8 +309,8 @@ install_sh_SCRIPT = $(install_sh) -c INSTALL_HEADER = $(INSTALL_DATA) transform = $(program_transform_name) -## These are defined because otherwise make on NetBSD V1.1 will print -## (eg): $(NORMAL_INSTALL) expands to empty string. +# These are defined like this to avoid introducing gratuitous +# incompatibilities with mainline Automake. NORMAL_INSTALL = : PRE_INSTALL = : POST_INSTALL = :