summaryrefslogtreecommitdiff
path: root/build-aux/Makefile.once.head
diff options
context:
space:
mode:
Diffstat (limited to 'build-aux/Makefile.once.head')
-rw-r--r--build-aux/Makefile.once.head/00-gitfiles.mk41
-rw-r--r--build-aux/Makefile.once.head/00-quote.mk23
-rw-r--r--build-aux/Makefile.once.head/00-var.mk14
-rw-r--r--build-aux/Makefile.once.head/10-dist.mk34
-rw-r--r--build-aux/Makefile.once.head/10-files.mk39
-rw-r--r--build-aux/Makefile.once.head/10-gnuconf.mk17
-rw-r--r--build-aux/Makefile.once.head/10-nested.mk26
-rw-r--r--build-aux/Makefile.once.head/10-write-atomic.mk18
-rw-r--r--build-aux/Makefile.once.head/10-write-ifchanged.mk18
-rw-r--r--build-aux/Makefile.once.head/zz-mod.mk22
10 files changed, 247 insertions, 5 deletions
diff --git a/build-aux/Makefile.once.head/00-gitfiles.mk b/build-aux/Makefile.once.head/00-gitfiles.mk
index b17b63aa09..faae91dcd1 100644
--- a/build-aux/Makefile.once.head/00-gitfiles.mk
+++ b/build-aux/Makefile.once.head/00-gitfiles.mk
@@ -15,6 +15,47 @@
mod.gitfiles.description = Automatically populate files.src.src from git
mod.gitfiles.depends += files nested write-ifchanged quote
+mod.gitfiles.files += $(topsrcdir)/$(gitfiles.file)
+define mod.gitfiles.doc
+# Inputs:
+# - Global variable : `gitfiles.file` (Default: gitfiles.mk)
+# - Directory variable : `nested.subdirs`
+# - External : git
+# Outputs:
+# - File : `$(topsrcdir)/$(gitfiles.file)`
+# - Directory variable : `files.src.src`
+# - Directory variable : `files.src.gen` (only in top dir)
+#
+# The `files` module has a variable (`files.src.src`) that you (the
+# developer) set to list "pure" source files; the type of files that you
+# would check into a version control system. Since you are a
+# responsible developer, you use a version control system. Since the
+# computer is already maintaining a list of these files *in the VCS*,
+# why should you--a filthy human--need to also maintain the list? Enter
+# gitfiles, which will talk to git to maintain `files.src.src`, but
+# won't require that the git repository be distributed to
+# installing-users.
+#
+# If `$(topsrcdir)/.git` exists, then it will generate
+# `$(topsrcdir)/$(gitfiles.file)`. Otherwise, it will assume that
+# `$(topsrcdir)/$(gitfiles.file)` already exists.
+#
+# It will use the information in `$(topsrcdir)/$(gitfiles.file)` to
+# append to `files.src.src` in each directory
+#
+# Finally, since the generated `$(topsrcdir)/$(gitfiles.file)` must be
+# distributed to users, it is added to $(topsrcdirs)'s `files.src.gen`.
+#
+# When setting `files.src.src`, it needs to know which files "belong" to
+# the current directory directly, and which "belong" to a further
+# subdirectory. To do this, it uses an expression involving
+# `$(nested.subdirs)`.
+#
+# While gitfiles sets `files.src.src` very early
+# in `each.head`, because `nested.subdirs` might not be set yet, it may
+# or may not be safe to use the value of `$(files.src.src)` in your
+# Makefile, depending on how you set `nested.subdirs`.
+endef
gitfiles.file ?= gitfiles.mk
diff --git a/build-aux/Makefile.once.head/00-quote.mk b/build-aux/Makefile.once.head/00-quote.mk
index 9fce401b94..4c954b1040 100644
--- a/build-aux/Makefile.once.head/00-quote.mk
+++ b/build-aux/Makefile.once.head/00-quote.mk
@@ -14,6 +14,24 @@
# along with this program. If not, see <http://www.gnu.org/licenses/>.
mod.quote.description = Macros to quote tricky strings
+define mod.quote.doc
+# Inputs:
+# (none)
+# Outputs:
+# - Global variable: `quote.var` : GNU Make variables
+# - Global variable: `quote.pattern` : GNU Make patterns
+# - Global variable: `quote.ere` : POSIX Extended Regular Expressions
+# - Global variable: `quote.bre` : POSIX Basic Regular Expressions
+# - Global variable: `quote.shell` : POSIX sh(1) strings
+# - Global variable: `quote.shell-each`: POSIX sh(1) strings
+#
+# Escaping/quoting things is hard! This module provides a number of
+# functions to escape/quote strings for various contexts.
+#
+# `quote.shell-each` quotes each list-item separately (munging
+# whitespace), while `quote.shell` keeps them as one string (preserving
+# whitespace).
+endef
_quote.backslash = $(if $1,$(call _quote.backslash,$(wordlist 2,$(words $1),$1),$(subst $(firstword $1),\$(firstword $1),$2)),$2)
@@ -24,6 +42,7 @@ quote.bre = $(call _quote.backslash, \ ^ . [ $$ * ,$1)
quote.shell-each = $(foreach _quote.tmp,$1,$(call quote.shell,$(_quote.tmp)))
-# I put this as the last line in the file because it confuses Emacs syntax
-# highlighting and makes the remainder of the file difficult to edit.
+# I put this as the last line in the file because it confuses Emacs
+# syntax highlighting and makes the remainder of the file difficult to
+# edit.
quote.shell = $(subst $(at.nl),'$$'\n'','$(subst ','\'',$1)')
diff --git a/build-aux/Makefile.once.head/00-var.mk b/build-aux/Makefile.once.head/00-var.mk
index d1e537ef34..636bbb0108 100644
--- a/build-aux/Makefile.once.head/00-var.mk
+++ b/build-aux/Makefile.once.head/00-var.mk
@@ -14,5 +14,19 @@
# along with this program. If not, see <http://www.gnu.org/licenses/>.
mod.var.description = Depend on the values of variables
+define mod.var.doc
+# Inputs:
+# (user-defined)
+# Outputs:
+# Target : `$(outdir)/.var.%`
+# Directory variable: `at.targets`
+#
+# It's a well-known secret that many files generated by a Makefile vary with
+# the values of particular variables, but that GNU Make can't track these
+# dependencies. Well, with some cleverness, it actually can!
+#
+# With this module, to depend on the value of a variable, depend on
+# `$(outdir)/.var.VARNAME`.
+endef
.PHONY: _var.FORCE
diff --git a/build-aux/Makefile.once.head/10-dist.mk b/build-aux/Makefile.once.head/10-dist.mk
index e139096576..8c68d041f3 100644
--- a/build-aux/Makefile.once.head/10-dist.mk
+++ b/build-aux/Makefile.once.head/10-dist.mk
@@ -14,6 +14,40 @@
# along with this program. If not, see <http://www.gnu.org/licenses/>.
mod.dist.description = `dist` target for distribution tarballs
+define mod.dist.doc
+# User variables:
+# - `CP ?= cp`
+# - `GZIP ?= gzip`
+# - `MKDIR ?= mkdir`
+# - `MKDIR_P ?= mkdir -p`
+# - `MV ?= mv`
+# - `RM ?= rm -f`
+# - `TAR ?= tar`
+# - `GZIPFLAGS ?= $(GZIP_ENV)`
+# - `GZIP_ENV ?= --best` (only used via `GZIPFLAGS`, not directly)
+# Inputs:
+# - Global variable : `dist.exts` (Default: `.tar.gz`)
+# - Global variable : `dist.pkgname` (Default: first of PACKAGE_TARNAME PACKAGE PACKAGE_NAME)
+# - Global variable : `dist.version` (Default: first of PACKAGE_VERSION VERSION)
+# - Directory variable : `files.src`
+# Outputs:
+# - Directory variable : `files.out.int` (only in top dir)
+# - .PHONY Target : `$(outdir)/dist`
+# - Target : `$(topoutdir)/$(dist.pkgname)-$(dist.version)`
+# - Target : `$(topoutdir)/$(dist.pkgname)-$(dist.version).tar`
+# - Target : `$(topoutdir)/$(dist.pkgname)-$(dist.version).tar.gz`
+#
+# Provide the standard `dist` .PHONY target, based on the `files` module
+# information.
+#
+# You may change the default compression target easily via the
+# `dist.exts` variable, but you must define the rule for it manually.
+#
+# Bugs:
+#
+# The tarball isn't reproducible. It uses file-system ordering of
+# files, and includes timestamps.
+endef
# Developer configuration
diff --git a/build-aux/Makefile.once.head/10-files.mk b/build-aux/Makefile.once.head/10-files.mk
index 54417356ee..9d27ae9931 100644
--- a/build-aux/Makefile.once.head/10-files.mk
+++ b/build-aux/Makefile.once.head/10-files.mk
@@ -15,6 +15,45 @@
mod.files.description = Keeping track of groups of files
mod.files.depends += nested
+define mod.files.doc
+# User variables:
+# - `DESTDIR ?=`
+# - `RM ?= rm -f`
+# - `RMDIR_P ?= rmdir -p --ignore-fail-on-non-empty`
+# - `TRUE ?= true`
+# Inputs:
+# - Global variable : `files.groups ?= all`
+# - Global variable : `files.default ?= all`
+# - Global variable : `files.vcsclean ?= files.vcsclean`
+# - Global variable : `files.generate ?= files.generate`
+# - Directory variable : `files.src.src`
+# - Directory variable : `files.src.int`
+# - Directory variable : `files.src.cfg`
+# - Directory variable : `files.src.gen`
+# - Directory variable : `files.out.slow`
+# - Directory variable : `files.out.int`
+# - Directory variable : `files.out.cfg`
+# - Directory variable : `files.out.$(files.groups)` (well, $(addprefix...))
+# - Directory variable : `files.sys.$(files.groups)` (well, $(addprefix...))
+# Outputs:
+# - Global variable : `nested.targets`
+# - Global variable : `at.targets`
+# - Global variable : `.DEFAULT_GOAL = $(files.default)`
+# - Creative .PHONY targets:
+# - `$(outdir)/$(files.generate))`
+# - `$(addprefix $(outdir)/,$(files.groups))`
+# - `$(outdir)/installdirs`
+# - `$(outdir)/install`
+# - Destructive .PHONY targets:
+# - `$(outdir)/uninstall`
+# - `$(outdir)/mostlyclean`
+# - `$(outdir)/clean`
+# - `$(outdir)/distclean`
+# - `$(outdir)/maintainer-clean`
+# - `$(outdir)/$(files.vcsclean)`
+#
+# TODO: prose documentation
+endef
files.groups ?= all
files.default ?= all
diff --git a/build-aux/Makefile.once.head/10-gnuconf.mk b/build-aux/Makefile.once.head/10-gnuconf.mk
index c07cfb5cf3..6d641bba7c 100644
--- a/build-aux/Makefile.once.head/10-gnuconf.mk
+++ b/build-aux/Makefile.once.head/10-gnuconf.mk
@@ -13,10 +13,21 @@
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
-# This file is based on §7.2 "Makefile Conventions" of the release of
-# the GNU Coding Standards dated July 25, 2016.
-
mod.gnuconf.description = GNU standard configuration variables
+define mod.gnuconf.doc
+# Inputs:
+# - Global variable: `gnuconf.pkgname`
+# (Default: `$(firstword $(PACKAGE_TARNAME) $(PACKAGE) $(PACKAGE_NAME))`)
+# Outputs:
+# (see below)
+#
+# This module defines default values (using `?=`) a huge list of
+# variables specified in the GNU Coding Standards that installing-users
+# expect to be able to set.
+#
+# This is based on §7.2 "Makefile Conventions" of the July 25, 2016
+# release of the GNU Coding Standards.
+endef
gnuconf.pkgname ?= $(firstword $(PACKAGE_TARNAME) $(PACKAGE) $(PACKAGE_NAME))
ifeq ($(gnuconf.pkgname),)
diff --git a/build-aux/Makefile.once.head/10-nested.mk b/build-aux/Makefile.once.head/10-nested.mk
index af9fdf7d8a..72e15ab533 100644
--- a/build-aux/Makefile.once.head/10-nested.mk
+++ b/build-aux/Makefile.once.head/10-nested.mk
@@ -14,5 +14,31 @@
# along with this program. If not, see <http://www.gnu.org/licenses/>.
mod.nested.description = Easy nested .PHONY targets
+define mod.nested.doc
+# Inputs:
+# - Global variable : `nested.targets`
+# - Directory variable : `nested.subdirs`
+# Outputs:
+# - .PHONY Targets : `$(addprefix $(outdir)/,$(nested.targets))`
+# - Variable : `at.subdirs`
+#
+# The Autothing `at.subdirs` slates a subdirectory's Makefile for inclusion,
+# but doesn't help with recursive targets like `all`, `install`, or `clean`,
+# which one would expect to descend into subdirectories. Enter `nested`:
+# Define a global list of targets that are recursive/nested, and then in each
+# directory define a list of subdirectries that one would expect them to
+# recurse into.
+#
+# Directories added to `nested.subdirs` are automatically added to `at.subdirs`
+# during the each.tail phase.
+#
+# It may help to think of at.subdirs and nested.subdirs in terms of their
+# Automake conterparts:
+#
+# | Autothing | GNU Automake |
+# +----------------+--------------+
+# | at.subdirs | DIST_SUBDIRS |
+# | nested.subdirs | SUBDIRS |
+endef
nested.targets ?=
diff --git a/build-aux/Makefile.once.head/10-write-atomic.mk b/build-aux/Makefile.once.head/10-write-atomic.mk
index f099ae285f..ce6acd8b7c 100644
--- a/build-aux/Makefile.once.head/10-write-atomic.mk
+++ b/build-aux/Makefile.once.head/10-write-atomic.mk
@@ -1,4 +1,22 @@
mod.write-atomic.description = `write-atomic` auxiliary build script
mod.write-atomic.files += $(topsrcdir)/build-aux/write-atomic
+define mod.write-atomic.doc
+# User variables:
+# - `WRITE_ATOMIC ?= $(topsrcdir)/build-aux/write-atomic`
+# Inputs:
+# (none)
+# Outputs:
+# (none)
+#
+# The $(WRITE_ATOMIC) program reads a file from stdin, and writes it to
+# the file named in argv[1], but does so atomically.
+#
+# That is, the following lines are almost equivalient:
+#
+# ... > $@
+# ... | $(WRITE_ATOMIC) $@
+#
+# The are only different in that one is atomic, while the other is not.
+endef
WRITE_ATOMIC ?= $(topsrcdir)/build-aux/write-atomic
diff --git a/build-aux/Makefile.once.head/10-write-ifchanged.mk b/build-aux/Makefile.once.head/10-write-ifchanged.mk
index b0a5ac478f..5abb3cee76 100644
--- a/build-aux/Makefile.once.head/10-write-ifchanged.mk
+++ b/build-aux/Makefile.once.head/10-write-ifchanged.mk
@@ -1,4 +1,22 @@
mod.write-ifchanged.description = `write-ifchanged` auxiliary build script
mod.write-ifchanged.files += $(topsrcdir)/build-aux/write-ifchanged
+define mod.write-ifchanged.doc
+# User variables:
+# - `WRITE_IFCHANGED ?= $(topsrcdir)/build-aux/write-ifchanged`
+# Inputs:
+# (none)
+# Outputs:
+# (none)
+#
+# The $(WRITE_IFCHANGED) program reads a file from stdin, and writes it to the
+# file named in argv[1], but does so atomically, but more importantly, does so
+# in a way that does not bump the file's ctime if the new content is the same
+# as the old content.
+#
+# That is, the following lines are almost equivalient:
+#
+# ... > $@
+# ... | $(WRITE_ATOMIC) $@
+endef
WRITE_IFCHANGED ?= $(topsrcdir)/build-aux/write-ifchanged
diff --git a/build-aux/Makefile.once.head/zz-mod.mk b/build-aux/Makefile.once.head/zz-mod.mk
index 732f1e169d..1b12a2fd33 100644
--- a/build-aux/Makefile.once.head/zz-mod.mk
+++ b/build-aux/Makefile.once.head/zz-mod.mk
@@ -15,6 +15,28 @@
mod.mod.description = Display information about Autothing modules
mod.mod.depends += quote
+define mod.mod.doc
+# Inputs:
+# - Files : `$(topsrcdir)/build-aux/Makefile.*/??-*.mk`
+# - Global variable : `mod.*.name`
+# - Global variable : `mod.*.description`
+# - Global variable : `mod.*.depends`
+# - Global variable : `mod.*.files`
+# - Global variable : `mod.*.doc`
+# Outputs:
+# - Directory variable : `at.targets`
+# - .PHONY Target : `$(outdir)/at-variables-local`
+# - .PHONY Target : `$(outdir)/at-variables-global`
+# - .PHONY Target : `$(outdir)/at-variables`
+# - .PHONY Target : `$(outdir)/at-variables/%`
+# - .PHONY Target : `$(outdir)/at-values`
+# - .PHONY Target : `$(outdir)/at-values/%`
+# - .PHONY Target : `$(outdir)/at-modules`
+# - .PHONY Target : `$(outdir)/at-modules/%`
+# - .PHONY Target : `$(outdir)/at-noop`
+#
+# TODO: prose documentation
+endef
# The trickery that is _mod.empty/_mod.space is from §6.2 of the GNU Make
# manual, "The Two Flavors of Variables".