summaryrefslogtreecommitdiff
path: root/build-aux
diff options
context:
space:
mode:
Diffstat (limited to 'build-aux')
-rw-r--r--build-aux/Makefile.README.mk20
-rw-r--r--build-aux/Makefile.README.old.txt134
-rw-r--r--build-aux/Makefile.README.txt401
-rw-r--r--build-aux/Makefile.each.head/00-texinfo.mk16
-rw-r--r--build-aux/Makefile.each.tail/00-dist.mk2
-rw-r--r--build-aux/Makefile.each.tail/00-var.mk6
-rw-r--r--build-aux/Makefile.each.tail/10-files.mk23
-rw-r--r--build-aux/Makefile.each.tail/10-nested.mk3
-rw-r--r--build-aux/Makefile.each.tail/11-texinfo.mk38
-rw-r--r--build-aux/Makefile.head.mk36
-rw-r--r--build-aux/Makefile.once.head/00-var.mk7
-rw-r--r--build-aux/Makefile.once.head/10-dist.mk10
-rw-r--r--build-aux/Makefile.once.head/10-files.mk37
-rw-r--r--build-aux/Makefile.once.head/10-gitfiles.mk (renamed from build-aux/Makefile.once.head/00-gitfiles.mk)15
-rw-r--r--build-aux/Makefile.once.head/10-gnuconf.mk7
-rw-r--r--build-aux/Makefile.once.head/10-nested.mk3
-rw-r--r--build-aux/Makefile.once.head/10-texinfo.mk47
-rw-r--r--build-aux/Makefile.once.tail/00-dist.mk5
18 files changed, 583 insertions, 227 deletions
diff --git a/build-aux/Makefile.README.mk b/build-aux/Makefile.README.mk
new file mode 100644
index 0000000000..fe9010aafc
--- /dev/null
+++ b/build-aux/Makefile.README.mk
@@ -0,0 +1,20 @@
+# This Makefile is a minimal stub that exists to allow the
+# `at-modules` set of Make targets to print documentation for the
+# present Autothing modules.
+#
+# This file is part of the documentation for Autothing.
+#
+# Copyright (C) 2017 Luke Shumaker
+#
+# This documentation file is placed into the public domain. If that
+# is not possible in your legal system, I grant you permission to use
+# it in absolutely every way that I can legally grant to you.
+
+dist.pkgname = autothing
+dist.version = 1.0
+gnuconf.pkgname = autothing
+
+topoutdir ?= .
+topsrcdir ?= .
+include $(topsrcdir)/build-aux/Makefile.head.mk
+include $(topsrcdir)/build-aux/Makefile.tail.mk
diff --git a/build-aux/Makefile.README.old.txt b/build-aux/Makefile.README.old.txt
index b0a09651bf..b4ea562be4 100644
--- a/build-aux/Makefile.README.old.txt
+++ b/build-aux/Makefile.README.old.txt
@@ -1,20 +1,14 @@
Obsolete
========
-The following was written for previous versions of Autothing. I'm leaving it
-here for now because I'll likely canibalize it for other bits of documentation,
-either for Autothing itself, the `files` module, or the `dist` module.
+The following was written for previous versions of Autothing. I'm
+leaving it here for now because I'll likely canibalize it for other
+bits of documentation, either for Autothing itself, the `files`
+module, or the `dist` module.
High-level overview
-------------------
-Now, what this does for you is:
-
- (search for the paper
-"Recursive Make Considered Harmful") As harmful as recursive make is,
-it's historically been difficult to to write non-recursive Makefiles.
-This makes it easy.
-
It also makes it easy to follow the GNU standards for your makefiles:
it takes care of this entire table of .PHONY targets for you:
@@ -33,126 +27,6 @@ it takes care of this entire table of .PHONY targets for you:
(You are still responsible for implementing the `$(outdir)/check`
target in each of your Makefiles.)
-What you have to do is:
-
-In each source directory, you write a `Makefile`, very similarly to if
-you were writing for plain GNU Make, with
-
- topoutdir ?= ...
- topsrcdir ?= ...
- include $(topsrcdir)/build-aux/Makefile.head.mk
-
- # your makefile
-
- include $(topsrcdir)/build-aux/Makefile.tail.mk
-
-And in the top-level source directory, Write your own helper makefiles
-that get included:
- - `common.once.head.mk`: before parsing any of your Makefiles
- - `common.each.head.mk`: before parsing each of your Makefiles
- - `common.each.tail.mk`: after parsing each of your Makefiles
- - `common.each.tail.mk`: after parsing all of your Makefiles
-
-The `common.*.mk` makefiles are nice for including generic pattern
-rules and variables that aren't specific to a directory.
-
-You're probably thinking that this sounds too good to be true!
-Unfortunately, there are two major deviations from writing a plain
-recursive Makefile:
-
- 1. all targets and prerequisites (including .PHONY targets!) need to
- be prefixed with
- `$(srcdir)`/`$(outdir)`/`$(topsrcdir)`/`$(topoutdir)`.
- * sub-gotcha: this means that if a pattern rule has a
- prerequisite that may be in srcdir or outdir, then it must be
- specified twice, once for each case.
- 2. if a prerequisite is in a directory "owned" by another Makefile,
- you must filter the pathname through `am_path`:
- `$(call am_path,YOUR_PATH)`. Further, that path must NOT contain
- a `..` segment; if you need to refer to a sibling directory, do it
- relative to `$(topoutdir)` or `$(topsrcdir)`.
-
-Telling automake about your program
------------------------------------
-
-You tell automake what to do for you by setting some variables. They
-are all prefixed with `am_`; this prefix may be changed by editing the
-`_am` variable at the top of `automake.head.mk`.
-
-The exception to this is the `am_path` variable, which is a macro that
-is used to make a list of filenames relative to the appropriate
-directory, because unlike normal GNU (Auto)Make, `$(outdir)` isn't
-nescessarily equal to `.`. See above.
-
-There are several commands that generate files; simply record the list
-of files that each command generates as the following variable
-variables:
-
-| Variable | Create Command | Delete Command | Description | Relative to |
-|--------------+----------------+-----------------------------+-----------------------------------+-------------|
-| am_src_files | emacs | rm -rf . | Files that the developer writes | srcdir |
-| am_gen_files | ??? | make maintainer-clean | Files the developer compiles | srcdir |
-| am_cfg_files | ./configure | make distclean | Users' compile-time configuration | outdir |
-| am_out_files | make all | make mostlyclean/make clean | Files the user compiles | outdir |
-| am_sys_files | make install | make uninstall | Files the user installs | DESTDIR |
-
-In addition, there are two more variables that control not how files
-are created, but how they are deleted:
-
-| Variable | Affected command | Description | Relative to |
-|----------------+------------------+------------------------------------------------+-------------|
-| am_clean_files | make clean | A list of things to `rm` in addition to the | outdir |
-| | | files in `$(am_out_files)`. (Example: `*.o`) | |
-|----------------+------------------+------------------------------------------------+-------------|
-| am_slow_files | make mostlyclean | A list of things that (as an exception) should | outdir |
-| | | _not_ be deleted. (otherwise, `mostlyclean` | |
-| | | is the same as `clean`) | |
-
-Finally, there are two variables that express the relationships
-between directories:
-
-| Variable | Description |
-|------------+---------------------------------------------------------|
-| am_subdirs | A list of other directories (containing Makefiles) that |
-| | may be considered "children" of this |
-| | directory/Makefile; building a phony target in this |
-| | directory should also build it in the subdirectory. |
-| | They are not necesarily actually subdirectories of this |
-| | directory in the filesystem. |
-|------------+---------------------------------------------------------|
-| am_depdirs | A list of other directories (containing Makefiles) that |
-| | contain or generate files that are dependencies of |
-| | targets in this directory. They are not necesarily |
-| | actually subdirectories of this directory in the |
-| | filesystem. Except for files that are dependencies of |
-| | files in this directory, things in the dependency |
-| | directory will not be built. |
-
-Tips, notes
------------
-
-I like to have the first (non-comment) line in a Makefile be:
-
- include $(dir $(lastword $(MAKEFILE_LIST)))/../../config.mk
-
-(adjusting the number of `../` sequences as nescessary). Then, my
-(user-editable) `config.mk` is of the form:
-
- ifeq ($(topsrcdir),)
- topoutdir := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
- topsrcdir := $(topoutdir)
-
- # your configuration
-
- endif
-
-If the package has a `./configure` script, then I have it modifiy
-topsrcdir as necessary, as well as modifying whatever other parts of
-the configuration. All of the configuration lives in `config.mk`;
-`./configure` doesn't modify any `Makefile`s, it just generates
-`config.mk`, and copies (or (sym?)link?) every `$(srcdir)/Makefile` to
-`$(outdir)/Makefile`.
-
----
Copyright (C) 2016 Luke Shumaker
diff --git a/build-aux/Makefile.README.txt b/build-aux/Makefile.README.txt
index 3be7a9d878..f67ede2a3d 100644
--- a/build-aux/Makefile.README.txt
+++ b/build-aux/Makefile.README.txt
@@ -5,36 +5,110 @@ Autothing 3: The smart way to write GNU Makefiles
Autothing is a thing that does things automatically.
-Ok, more helpfully: Autothing is a pair of .mk Makefile fragments that
-you can `include` from your Makefiles to make them easier to write;
-specifically, it makes it _easy_ to write non-recursive Makefiles--and
-ones that are similar to plain recursive Makefiles, at that!
+Ok, more helpfully: Autothing is a pair of .mk Makefile fragments
+(`Makefile.head.mk` and `Makefile.tail.mk`) that you can `include`
+from your Makefiles to make them easier to write; specifically, it
+makes it _easy_ to write non-recursive Makefiles--and ones that are
+similar to plain recursive Makefiles, at that!
-Synopsis
---------
+To many people, talking about GNU Make directly is a non-starter
+because it means giving up the many other features that things like
+GNU Automake provide. Other projects like GNU Automake were created
+to plaster over differences between make(1) implementations; however,
+this isn't all that Automake provides, it also makes it easy to do
+complex things that users want, or the GNU Coding Standards require.
+That's silly; the implementation of these features should be
+orthogonal to plastering over the differences between Make
+implementations. So, in addition to the Automake core, Automake is
+distributed with several "modules" that implement similar feature sets
+to what Automake provides.
-Write your makefiles of the form:
+Autothing does depend on GNU Make; other make(1) implementations will
+not work. However, if you are open to adding GNU Make as a
+dependency, then Autothing should obviate the need for GNU Automake,
+while also making your Makefiles better.
+
+Non-recursive?
+--------------
+
+ (For those of you who aren't up on Makefile jargon)
+
+When you have a project that spans multiple directories, you'll
+probably want to split up the Makefile, having the appropriate parts
+in each sub-directory. There are a number of strategies you can use
+to approach this.
+
+One of the more prevelant strategies (so much so that GNU make
+includes special support for it) is to write "recursive Makefiles";
+that is, have Make rules that include commands like
+
+ other-directory/libfoo.so:
+ $(MAKE) -C other-directory libfoo.so
+
+or
+
+ other-directory/libfoo.so
+ cd other-directory && $(MAKE) libfoo.so
+This approach is popular because it is both very easy to implement,
+and is supported by a wide variety of Make implementations. But, it
+also introduces a wide variety of issues; so much so that a rather
+famous paper was written about it: "Recursive Make Considered Harmful"
+(Miller, 1997).
+
+For all of the arguments against it, and all of the alternative
+approaches, recusive Makefiles are hard to beat because they are just
+so easy to write, and the alternatives... aren't. UNTIL NOW!
+
+Instead of having rules that spawn a separate Make process in another
+directory for targets in that directory, Autothing lets you provide a
+list of directories that include targets that targets in this
+directory might depend on, and Autothing will automagically include
+the Makefile in that other directory into *this* instance of the Make
+program.
+
+ Peter Miller (1997) "Recursive Make Considered Harmful"
+ <http://aegis.sourceforge.net/auug97.pdf>
+
+An example Makefile / Introduction
+----------------------------------
+
+Write your Makefiles of the form:
+
+ # Initialize basic information about how your project is structured.
topsrcdir ?= ...
topoutdir ?= ...
- at.Makefile ?= Makefile # Optional
+
+ # Include the Autothing entry point
include $(topsrcdir)/build-aux/Makefile.head.mk
+ # Now write your Makefile very similarly to how you normally
+ # would. Just make sure that outputs are relative to $(outdir)
+ # and inputs relative to $(srcdir).
$(outdir)/%.o: $(srcdir)/%.c:
- $(CC) -c -o $@ $<
-
- $(outdir)/hello: $(outdir)/hello.o
+ $(CC) -c -o $@ $<
+ $(outdir)/hello: $(outdir)/hello.o
+ # If any of the dependencies of files here are outputs of a
+ # Makefile in another directory, list those directories here.
at.subdirs = ...
- at.targets = ...
+ # This part is kind of a pain: define a list of ouput targets that
+ # this Makefile produces.
+ at.targets = $(outdir)/%.o $(outdir)/hello
+
+ # Include the Autothing exit point
include $(topsrcdir)/build-aux/Makefile.tail.mk
This is similar to, but not quite, the comfortable way that you probably
already write your Makefiles.
-Details
--------
+It is recommended that Autothing lives inside of the "build-aux"
+directory in the top level of your project sources; "build-aux" is a
+standard directory for auxiliary build programs and tools.
+
+What does Autothing do for me?
+------------------------------
There are two fundamental things that Autothing provides:
@@ -49,15 +123,178 @@ The second is important because GNU Make is too dumb to know that
Then, there's something that maybe doesn't belong, but I didn't have the heart
to cut it out:
- 3. A module (plugin) system.
+ 3. A module (plugin) system, which allows for modules to provide
+ additional feature sets.
The module system is "important" because there are very often common bits that
you want to be included in every Makefile, and this gives some structure to
that.
-Requirements:
- - A version of GNU Make that supports `undefine`. (TODO: check which version
- of GNU Make introduced this feature)
+Let's step through each of those features.
+
+## Variable namespacing
+
+When you write a Makefile, you quite likely use (global) variables.
+When you have a project that uses multiple Makefiles, each Makefile
+might have the same variable names, but with different values
+(especially if converting from recursive Make).
+
+You could be very disciplined and carefully name your variables so
+that they don't conflict. This is difficult and error prone normally,
+but becomes neigh-on-impossible if you are converting a large-ish
+project from recursive Make.
+
+So, Autothing provides a solution. If you provide Autothing with a
+list of targets defined in your Makefile (via the `at.targets`
+variable), Autothing will make any variables you defined local to that
+Makefile; they will be present when making targets listed in
+`at.targets`, but will be hidden from other Makfiles that get
+included.
+
+Any variables defined before `Makefile.head.mk` is included are
+treated as truly global; all Makefiles included will have access to
+them.
+
+## Tools for dealing with paths
+
+As stated above, GNU Make is too dumb to realize that `foo/bar/../baz`
+== `foo/baz`; so one has to be reasonably careful about path
+normalization. For dealing with path normalization problems that
+arise because of the way Autothing inclusions work, several global
+functions are provided for dealing with paths.
+
+`$(call at.is_subdir,a,b)` returns whether `b` is a sub-directory of
+`a` (including `a` as a sub-directory of itself).
+`at.is_strict_subdir` does the same, but does not treat `a` as a
+sub-directory of itself. (These function names mimic the terms
+"subset" and "strict subset" in mathematics.) These use an empty
+string for "false" and a non-empty string for "true".
+
+`$(call at.path,files...)` is a generic path-normalization routine.
+The outputs of the other `at.*` functions are already normalized, and
+do not need to be passed through this. Files immediately inside of
+`$(srcdir)` or `$(outdir)` (without another directory name after the
+variable) are already normalized, and do not need to be passed through
+this function either. However, it is always safe to pass a path
+through this function, so if in doubt, call `at.path`.
+
+`$(call at.relbase,dir,files...)` and its cousin `at.relto` take a
+directory and a list of files, and transform each of the filenames to
+be relative to the directory, if the file is inside of the directory.
+Where they differ is that if the file is not inside of the directory;
+`at.relbase` transforms it into an absolute path, while `at.relto`
+prepends as many `../` segments as necessary to make it relative to
+the directory. (These function names mimic the `--relative-base` and
+`--relative-to` flags of the `realpath` utility that is part of GNU
+coreutils.)
+
+If `$(srcdir)` and `$(outdir)` are the same, then `$(call
+at.out2src,files...)` is a no-op, but otherwise it takes a (possibly
+relative) path in `$(outdir)`, and transforms it to the equivalent
+filename in `$(srcdir)`.
+
+`$(call at.addprefix,dir,files...)` takes a directory and a list of
+filenames, and looks at each filename; if it is an absolute path, it
+passes it through (well, "only" normalizes it); if the filename is a
+relative path, it is joined with the given base directory.
+
+## Modules to provide feature sets
+
+The module system serves two purposes
+
+ 1. Allow your developers to share logic between Makefiles in multiple
+ directories.
+ 2. Allow your developers to import "standard" modules implementing
+ common feature sets, so they don't have to.
+
+Distributed along with autothing are some "standard" modules that
+provide commonly desired functionality from Makefiles; tricky little
+things that your developers shouldn't have to implement themselves for
+every project; the things that GNU Automake would take care of if you
+used Automake (a piece of software that Autothing hopes to replace).
+
+The module system is conceptually quite simple: have 4 directories for
+`.mk` makefile snippets that get included at certain points:
+
+ Makefile.once.head/*.mk
+
+ Makefile.each.head/*.mk
+ a/Makefile
+ Makefile.each.tail/*.mk
+
+ Makefile.each.head/*.mk
+ b/Makefile
+ Makefile.each.tail/*.mk
+
+ Makefile.each.head/*.mk
+ c/Makefile
+ Makefile.each.tail/*.mk
+
+ Makefile.once.tail/*.mk
+
+Deciding which of the 4 directories to put your snippets in... you'll
+figure it out pretty quickly once you start playing with it.
+
+Beyond these 4 directories, Autothing itself imposes no structure, but
+there are some conventions that are followed by the distributed along
+with Autothing, and I recommend that your developers follow.
+
+Each of the `.mk` files is name `NN-MODULE.mk` where NN is a number
+(to affect the order that the module files are evaluated in, in case
+of dependencies between them), and MODULE is the module name. Each
+module has "public" variables prefixed with `MODULE.`, and "private"
+variables prefixed with `_MODULE.` (again, "MODULE" being the module
+name). For example, the "groups" parameter of the "files" module is
+configured via the `files.groups` variable. Within this convention,
+Autothing presents itself as a pseudo-module named "at"; that is,
+public Autothing variables are prefixed with `at.`.
+
+If you follow these conventions, then the "mod" module distributed
+along with Autothing can display information about the modules that a
+project uses, and documentation on each module. Running the command
+`make at-modules` (implemented by the "mod" module) will produce a
+list of the modules present in a project, and short descriptions of
+them:
+
+ $ make at-modules
+ Autothing modules used in this project:
+ - dist `dist` target for distribution tarballs (more)
+ - files Keeping track of groups of files (more)
+ - gitfiles Automatically populate files.src.src from git (more)
+ - gnuconf GNU standard configuration variables (more)
+ - mod Display information about Autothing modules (more)
+ - nested Easy nested .PHONY targets (more)
+ - quote Macros to quote tricky strings (more)
+ - texinfo The GNU documentation system (more)
+ - var Depend on the values of variables (more)
+ - write-atomic `write-atomic` auxiliary build script (more)
+ - write-ifchanged `write-ifchanged` auxiliary build script (more)
+
+The "(more)" at the end of a line indicates that there is further
+documentation for that module, which can be produced by running the
+command `make at-modules/MODULE_NAME`. See the output of `make
+at-modules/mod` for instructions on how to produce this further
+documentation for modules you develop.
+
+Besides the "mod" module, the set modules distributed along with
+Autothing primarily exists to provide the bits of (sometimes somewhat
+tricky) functionality required of Makefiles by the GNU Coding
+Standards. Run the `at-modules` commands above for documentation on
+each of them.
+
+Formal interface
+----------------
+
+System requirements:
+ - A version of GNU Make that supports `undefine` (ie, version 3.82
+ and above).
+
+ If the user attempts to use your Autothing-using Makefile with an
+ older version of GNU Make, `Makefile.head.mk` will print an error
+ message and refuse to proceed:
+
+ $ make-3.81
+ build-aux/Makefile.head.mk:58: *** Autothing: We need a version of Make that supports 'undefine'. Stop.
Inputs:
- In each `Makefile`:
@@ -71,6 +308,31 @@ Inputs:
- Files:
- `${topsrcdir}/build-aux/Makefile.{each,once}.{head,tail}/*.mk`
+ Unfortunately, a limitation of Autothing is that it does require a
+ designated "top" directory; it can't be used to have a sub-project
+ that can also be totally separate and built alone. In your
+ Makefiles, before you include `Makefile.head.mk`, you must tell
+ Autothing what the top directory is by setting `topoutdir` and
+ `topsrcdir`.
+
+ If you wish for your per-directory Makefiles to have a name other
+ than `Makefile` (such as `GNUmakefile` or `makefile`, which GNU Make
+ also looks for by default; or another name for project-specific
+ reasons), Autothing supports this by setting the `at.Makefile`
+ variable. Unfortunately, Autothing does not support having a list
+ of filenames to try; so one must be consistent about the filename
+ throughout the project.
+
+ In the body of each Makefile, you may set the `at.targets` variable
+ to list which targets should have access to the variables defined in
+ the body of that Makefile.
+
+ In the body of each Makefile, you may set the `at.subdirs` variable
+ to list of directories which have their own Makefile which produces
+ targets that targets in this directory depend on. Directories
+ listed in `at.subdirs` may be relative or absolute; if relative,
+ they are interpreted as relative to `$(outdir)`.
+
Outputs:
- Global:
- Variable (function): `$(call at.is_subdir, parent, child)`
@@ -80,32 +342,105 @@ Outputs:
- Variable (function): `$(call at.path, paths...)`
- Variable (function): `$(call at.out2src, paths...)`
- Variable (function): `$(call at.addprefix, prefix, paths...)`
+ - Variable : `$(at.nl)` # a single newline
- Per-directory:
- Variable: `$(outdir)`
- Variable: `$(srcdir)`
-TODO: actually explain things.
+ For dealing with path normalization problems that arise because of
+ the way Autothing inclusions work, several global functions are
+ provided for dealing with paths; see the above "Tools for dealing
+ with paths" section for documentation on each of these functions.
-Motivation/Exposition
----------------------
+ For convenience, it also provides `$(at.nl)` which is a single
+ newline, as newlines are very difficult to type in Make variable
+ values.
-This section needs rewritten. Or really just written.
+Tips, notes
+-----------
-Other projects like GNU Automake were created to plaster over differences
-between make(1) implementations; however, this isn't all that Automake
-provides, it also makes it easy to do complex things that users want, or the
-GNU Coding Standards require. That's silly.
+If you use Autoconf (or similar), I recommend having a file at
+`$(topsrcdir)/config.mk.in` of the form
-Autothing does depend on GNU Make; other make(1) implementations will
-not work. However, if you are open to adding GNU Make as a
-dependency, then Autothing should obviate the need for GNU Automake,
-while also making your Makefiles better.
+ ifeq ($(origin topsrcdir),undefined)
+ topoutdir := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
+ topsrcdir := $(topoutdir)/@top_srcdir@
- Peter Miller (1997) "Recursive Make Considered Harmful"
- <http://aegis.sourceforge.net/auug97.pdf>
+ # Any other global variables you might want to set
+
+ endif
+
+Then have `./configure` generate `$(topoutdir)/config.mk` from it by
+placing `AC_CONFIG_FILES([config.mk])` in your `configure.ac`. I
+recommend that you have `config.mk` be the _only_ Makefile edited by
+`./configure`; which will require manual support to have `./configure`
+link/copy the Makefiles unedited into `$(topoutdir)`; you can do this
+by placing something like this in your `configure.ac`:
+
+ AC_OUTPUT([], [], [
+ if test "$srcdir" != .; then
+ find "$srcdir" -name Makefile -printf '%P\n' \
+ | while read -r filename; do
+ mkdir -p "\$(dirname "\$filename")"
+ ln -srfT "$srcdir/\$filename" "\$filename"
+ done
+ fi
+ ])
+
+This will allow you to write your Makefiles in the form:
+
+ include $(dir $(lastword $(MAKEFILE_LIST)))/../../config.mk
+ include $(topsrcdir)/build-aux/Makefile.head.mk
+
+ # your Makefile here
+
+ include $(topsrcdir)/build-aux/Makefile.tail.mk
+
+Where you only need to adjust the number of `../` segments in the
+first line based on how deep that directory is.
+
+Further development
+-------------------
+
+Most of the modules distributed along with Autothing have the goal of
+combining to provide the things that the GNU Coding Standards require.
+Between `gnuconf`, `dist`, `files`, and `texinfo`; the GNU Coding
+Standards for Makefiles are nearly entirely satisfied. However, there
+are a few targets that are required, but aren't implemented by a
+module (yet!):
+
+ - `install-strip`
+ - `TAGS`
+ - `check`
+ - `installcheck` (optional, but recommended)
+
+TODO
+----
+
+ - Write documentation on `srcdir`, `outdir`, and out-of-tree builds;
+ I don't think discussions involving the separate `srcdir` and
+ `outdir` make much sense without that context.
+
+Bugs/Limitations
+----------------
+
+ - This documentation file is almost three times as long as the code
+ that it documents.
+
+ - The "parse time" for projects with hundreds of sub-directories
+ (each having a Makefile) can be slow (ex: a project with 166
+ directories has a parse time of around 12 seconds on my box). I
+ blame GNU Make's garbage collector; I don't think it was ever
+ designed to deal with as much "garbage" as Autothing's variable
+ namespacing throws at it.
+
+ - Requires a designated "top" directory; see discussion above.
+
+ - Does not support varying per-directory Makefile names; see
+ discussion above.
----
-Copyright (C) 2016 Luke Shumaker
+Copyright (C) 2016-2017 Luke Shumaker
This documentation file is placed into the public domain. If that is
not possible in your legal system, I grant you permission to use it in
diff --git a/build-aux/Makefile.each.head/00-texinfo.mk b/build-aux/Makefile.each.head/00-texinfo.mk
new file mode 100644
index 0000000000..88aaeb5262
--- /dev/null
+++ b/build-aux/Makefile.each.head/00-texinfo.mk
@@ -0,0 +1,16 @@
+# Copyright (C) 2016-2017 Luke Shumaker
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 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 Affero General Public License for more details.
+#
+# 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/>.
+
+texinfo.docs ?=
diff --git a/build-aux/Makefile.each.tail/00-dist.mk b/build-aux/Makefile.each.tail/00-dist.mk
index bc2a3d5dd1..b023e80235 100644
--- a/build-aux/Makefile.each.tail/00-dist.mk
+++ b/build-aux/Makefile.each.tail/00-dist.mk
@@ -1 +1 @@
-_dist.files := $(strip $(_dist.files) $(call at.addprefix,$(srcdir),$(files.src)))
+_dist.files := $(strip $(_dist.files) $(call at.addprefix,$(srcdir),$(filter-out $(files.src.int),$(files.src))))
diff --git a/build-aux/Makefile.each.tail/00-var.mk b/build-aux/Makefile.each.tail/00-var.mk
index c2fd9d7001..954defb2da 100644
--- a/build-aux/Makefile.each.tail/00-var.mk
+++ b/build-aux/Makefile.each.tail/00-var.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2016 Luke Shumaker
+# Copyright (C) 2016-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -13,10 +13,10 @@
# 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/>.
-mod.var.depends += quote write-ifchanged
+mod.var.depends += files quote write-ifchanged
$(outdir)/.var.%: _var.FORCE
@printf '%s' $(call quote.shell,$($*)) | sed 's/^/#/' | $(WRITE_IFCHANGED) $@
-include $(wildcard $(outdir)/.var.*)
-at.targets += $(addprefix $(outdir)/,.var.%)
+files.out.int += .var.*
diff --git a/build-aux/Makefile.each.tail/10-files.mk b/build-aux/Makefile.each.tail/10-files.mk
index 8ab187b401..787a3bdbd1 100644
--- a/build-aux/Makefile.each.tail/10-files.mk
+++ b/build-aux/Makefile.each.tail/10-files.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2016 Luke Shumaker
+# Copyright (C) 2015-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -34,24 +34,19 @@ $(eval \
$(foreach _files.g,$(files.groups),\
$$(outdir)/$(_files.g): $$(_files.out.$(_files.g))$(at.nl))\
$(foreach _files.g,$(filter-out $(files.default),$(files.groups)),\
- $$(outdir)/install-$(_files.g): $$(_files.sys.$(_files.g)))$(at.nl))
+ $$(outdir)/install-$(_files.g): $$(_files.sys.$(_files.g))$(at.nl)))
# Destructive targets
_files.uninstall = $(_files.sys)
_files.mostlyclean = $(filter-out $(_files.out.slow) $(_files.out.cfg),$(_files.out))
_files.clean = $(filter-out $(_files.out.cfg),$(_files.out))
_files.distclean = $(_files.out)
-$(addprefix $(outdir)/,uninstall mostlyclean clean distclean): %: %-hook
- $(RM) -- $(sort $(filter-out %/,$(_files.$(@F))))
- $(RM) -r -- $(sort $(filter %/,$(_files.$(@F))))
- $(RMDIR_P) -- $(sort $(dir $(_files.$(@F))))
-_files.maintainer-clean = $(filter-out $(_files.src.cfg) $(_files.src.src),$(_files.src))
-_files.$(files.vcsclean) = $(filter-out $(_files.src.src),$(_files.src))
-$(addprefix $(outdir)/,maintainer-clean $(files.vcsclean)): $(outdir)/%: $(outdir)/distclean $(outdir)/%-hook
- @echo 'This command is intended for maintainers to use; it'
- @echo 'deletes files that may need special tools to rebuild.'
- $(RM) -- $(sort $(filter-out %/,$(_files.$(@F))))
- $(RM) -r -- $(sort $(filter %/,$(_files.$(@F))))
- $(RMDIR_P) -- $(sort $(dir $(_files.$(@F))))
+_files.maintainer-clean = $(_files.distclean) $(filter-out $(_files.src.cfg) $(_files.src.src),$(_files.src))
+_files.$(files.vcsclean) = $(_files.distclean) $(filter-out $(_files.src.src),$(_files.src))
+$(addprefix $(outdir)/,uninstall mostlyclean clean distclean maintainer-clean $(files.vcsclean)): %: %-hook
+ $(call _files.XARGS,$(RM) --, $(sort $(wildcard $(filter-out %/,$(_files.$(@F))))) )
+ $(call _files.XARGS,$(RM) -r --, $(sort $(wildcard $(filter %/,$(_files.$(@F))))) )
+ $(call _files.XARGS,$(RMDIR_P) --,$(filter-out ./,$(sort $(wildcard $(dir $(_files.$(@F)))))))
+$(addprefix $(outdir)/,maintainer-clean $(files.vcsclean)): _files.maintainer-clean-warning
$(foreach t,uninstall mostlyclean clean distclean maintainer-clean $(files.vcsclean), $(outdir)/$t-hook)::
.PHONY: $(foreach t,uninstall mostlyclean clean distclean maintainer-clean $(files.vcsclean), $(outdir)/$t-hook)
diff --git a/build-aux/Makefile.each.tail/10-nested.mk b/build-aux/Makefile.each.tail/10-nested.mk
index 5e5a40b921..667ec6f901 100644
--- a/build-aux/Makefile.each.tail/10-nested.mk
+++ b/build-aux/Makefile.each.tail/10-nested.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2016 Luke Shumaker
+# Copyright (C) 2016-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -18,3 +18,4 @@ $(eval $(foreach _tmp.nested,$(nested.targets),\
.PHONY: $(addprefix $(outdir)/,$(nested.targets))
at.subdirs += $(nested.subdirs)
+at.targets += $(addprefix $(outdir)/,$(nested.targets))
diff --git a/build-aux/Makefile.each.tail/11-texinfo.mk b/build-aux/Makefile.each.tail/11-texinfo.mk
new file mode 100644
index 0000000000..1ee5843d69
--- /dev/null
+++ b/build-aux/Makefile.each.tail/11-texinfo.mk
@@ -0,0 +1,38 @@
+# Copyright (C) 2016 Luke Shumaker
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 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 Affero General Public License for more details.
+#
+# 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/>.
+
+$(outdir)/info : $(addsuffix .info,$(texinfo.docs))
+files.src.gen += $(addsuffix .info,$(texinfo.docs))
+files.out.dvi += $(addsuffix .dvi ,$(texinfo.docs))
+files.out.html += $(addsuffix .html,$(texinfo.docs))
+files.out.pdf += $(addsuffix .pdf ,$(texinfo.docs))
+files.out.ps += $(addsuffix .ps ,$(texinfo.docs))
+
+files.sys.all += $(foreach f,$(texinfo.docs), $(infodir)/$f.info )
+files.sys.dvi += $(foreach f,$(texinfo.docs), $(dvidir)/$f.dvi )
+files.sys.html += $(foreach f,$(texinfo.docs), $(htmldir)/$f.html )
+files.sys.pdf += $(foreach f,$(texinfo.docs), $(pdfdir)/$f.pdf )
+files.sys.ps += $(foreach f,$(texinfo.docs), $(psdir)/$f.ps )
+
+$(outdir)/%.info: $(srcdir)/%.texi; $(MAKEINFO) -o $(@D) $<
+$(outdir)/%.info: $(outdir)/%.texi; $(MAKEINFO) -o $(@D) $<
+$(outdir)/%.dvi : $(srcdir)/%.texi; $(TEXI2DVI) -o $(@D) $<
+$(outdir)/%.dvi : $(outdir)/%.texi; $(TEXI2DVI) -o $(@D) $<
+$(outdir)/%.html: $(srcdir)/%.texi; $(TEXI2HTML) -o $(@D) $<
+$(outdir)/%.html: $(outdir)/%.texi; $(TEXI2HTML) -o $(@D) $<
+$(outdir)/%.pdf : $(srcdir)/%.texi; $(TEXI2PDF) -o $(@D) $<
+$(outdir)/%.pdf : $(outdir)/%.texi; $(TEXI2PDF) -o $(@D) $<
+$(outdir)/%.ps : $(srcdir)/%.texi; $(TEXI2PS) -o $(@D) $<
+$(outdir)/%.ps : $(outdir)/%.texi; $(TEXI2PS) -o $(@D) $<
diff --git a/build-aux/Makefile.head.mk b/build-aux/Makefile.head.mk
index c2ce3075b2..6ac3d49f9f 100644
--- a/build-aux/Makefile.head.mk
+++ b/build-aux/Makefile.head.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2016 Luke Shumaker
+# Copyright (C) 2015-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -13,8 +13,9 @@
# 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/>.
+at.Makefile ?= Makefile
_at.MAKEFILE_LIST ?=
-_at.MAKEFILE_LIST := $(strip $(_at.MAKEFILE_LIST) $(abspath $(lastword $(filter-out %.mk,$(MAKEFILE_LIST)))))
+_at.MAKEFILE_LIST := $(strip $(_at.MAKEFILE_LIST) $(lastword $(filter %/$(at.Makefile),$(abspath $(MAKEFILE_LIST)))))
# This bit only gets evaluated once, at the very beginning
ifeq ($(origin _at.NO_ONCE),undefined)
@@ -24,24 +25,26 @@ ifeq ($(origin _at.NO_ONCE),undefined)
# These 4 functions are all $(call _at.func,parent,child)
_at.is_strict_subdir = $(filter $(abspath $1)/%,$(abspath $2))
_at.is_subdir = $(filter $(abspath $1)/%,$(abspath $2)/.)
-_at.relbase = $(strip \
- $(if $(call _at.is_subdir,$1,$2), \
- $(patsubst %/.,$(patsubst $(abspath $1)/%,%,$(abspath $2)/.)), \
+_at.relbase = $(strip \
+ $(if $(call _at.is_subdir,$1,$2), \
+ $(patsubst %/.,%,$(patsubst $(abspath $1)/%,%,$(abspath $2)/.)), \
$(abspath $2)))
_at.relto = $(strip \
$(if $(call _at.is_subdir,$1,$2), \
$(patsubst %/.,%,$(patsubst $(abspath $1)/%,%,$(abspath $2)/.)), \
- ../$(call _at.relto,$(dir $1),$2)))
+ ../$(call _at.relto,$(dir $(abspath $1)),$2)))
# These 3 functions only take one operand; we define public multi-operand
# versions below.
-_at.path = $(strip \
- $(if $(call _at.is_subdir,$(topoutdir),$1), \
- $(patsubst %/.,%,$(topoutdir)/$(call _at.relto,.,$1)), \
- $(if $(call _at.is_subdir,$(topsrcdir),$1), \
- $(patsubst %/.,%,$(topsrcdir)/$(call _at.relto,$(topsrcdir),$1)), \
- $(abspath $1))))
-_at.out2src = $(call _at.path,$(if $(call _at.is_subdir,$(topoutdir),$1),$(topsrcdir)/$(call _at.path,$1),$1))
+_at.path = $(strip $(or \
+ $(if $(call _at.is_subdir, . ,$1), $(call _at.relto, . ,$1) ), \
+ $(if $(call _at.is_subdir,$(topoutdir),$1),$(patsubst %/.,%,$(topoutdir)/$(call _at.relto,$(topoutdir),$1))), \
+ $(if $(call _at.is_subdir,$(topsrcdir),$1),$(patsubst %/.,%,$(topsrcdir)/$(call _at.relto,$(topsrcdir),$1))), \
+ $(abspath $1)))
+_at.out2src = $(call _at.path,$(strip \
+ $(if $(call _at.is_subdir,$(topoutdir),$1), \
+ $(topsrcdir)/$(call _at.relto,$(topoutdir),$1), \
+ $1)))
_at.addprefix = $(call _at.path,$(if $(filter-out /%,$2),$1/$2,$2))
_at.rest = $(wordlist 2,$(words $1),$1)
@@ -86,9 +89,6 @@ define at.nl
endef
-# External configuration ###############################################
-at.Makefile ?= Makefile
-
# Include modules ######################################################
include $(sort $(wildcard $(topsrcdir)/build-aux/Makefile.once.head/*.mk))
_at.tmp_targets =
@@ -105,9 +105,7 @@ ifeq ($(call _at.is_subdir,$(topoutdir),$(outdir)),)
$(error Autothing: not a subdirectory of topoutdir=$(topoutdir): $(outdir))
endif
-# Don't use at.out2src because we *know* that $(outdir) is inside $(topoutdir),
-# and has already had $(_at.path) called on it.
-srcdir := $(call _at.path,$(topsrcdir)/$(outdir))
+srcdir := $(call _at.out2src,$(outdir))
ifeq ($(call _at.is_subdir,$(topsrcdir),$(srcdir)),)
$(error Autothing: not a subdirectory of topsrcdir=$(topsrcdir): $(srcdir))
endif
diff --git a/build-aux/Makefile.once.head/00-var.mk b/build-aux/Makefile.once.head/00-var.mk
index 1f50f21f1a..7c9e6ffe55 100644
--- a/build-aux/Makefile.once.head/00-var.mk
+++ b/build-aux/Makefile.once.head/00-var.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2016 Luke Shumaker
+# Copyright (C) 2016-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -20,14 +20,17 @@ define mod.var.doc
# Outputs:
# Target : `$(outdir)/.var.%`
# Directory variable: `at.targets`
+# Directory variable: `var.`
#
# 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`.
+# `$(outdir)/.var.VARNAME`, or `$(var.)VARNAME` for short.
endef
mod.var.doc := $(value mod.var.doc)
+var. = $(patsubst ./%,%,$(outdir)/.var.)
+
.PHONY: _var.FORCE
diff --git a/build-aux/Makefile.once.head/10-dist.mk b/build-aux/Makefile.once.head/10-dist.mk
index 831ca125f8..3621195c0d 100644
--- a/build-aux/Makefile.once.head/10-dist.mk
+++ b/build-aux/Makefile.once.head/10-dist.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2016 Luke Shumaker
+# Copyright (C) 2015-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -13,7 +13,7 @@
# 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/>.
-mod.dist.description = `dist` target for distribution tarballs
+mod.dist.description = `dist` target to create distribution tarballs
define mod.dist.doc
# User variables:
# - `CP ?= cp`
@@ -50,6 +50,12 @@ define mod.dist.doc
endef
mod.dist.doc := $(value mod.dist.doc)
+PACKAGE_TARNAME ?=
+PACKAGE ?=
+PACKAGE_NAME ?=
+PACKAGE_VERSION ?=
+VERSION ?=
+
# Developer configuration
dist.exts ?= .tar.gz
diff --git a/build-aux/Makefile.once.head/10-files.mk b/build-aux/Makefile.once.head/10-files.mk
index f6fcf30c3a..564f9d634f 100644
--- a/build-aux/Makefile.once.head/10-files.mk
+++ b/build-aux/Makefile.once.head/10-files.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2016 Luke Shumaker
+# Copyright (C) 2015-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -26,15 +26,15 @@ define mod.files.doc
# - 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...))
+# - Directory variable : `files.src.src` # Sources
+# - Directory variable : `files.src.int` # Intermediates; deletable
+# - Directory variable : `files.src.cfg` # Outputs needed to run ./configure
+# - Directory variable : `files.src.gen` # Other outputs
+# - Directory variable : `files.out.slow` # Things to exclude from `make mostlyclean`
+# - Directory variable : `files.out.int` # Intermediates
+# - Directory variable : `files.out.cfg` # Outputs created by ./configure
+# - Directory variable : `files.out.$(group)` for `group` in `$(files.groups)`
+# - Directory variable : `files.sys.$(group)` for `group` in `$(files.groups)`
# Outputs:
# - Global variable : `nested.targets`
# - Global variable : `at.targets`
@@ -43,7 +43,7 @@ define mod.files.doc
# - Directory variable : `files.out`
# - Directory variable : `files.sys`
# - Creative .PHONY targets:
-# - `$(outdir)/$(files.generate))`
+# - `$(outdir)/$(files.generate)`
# - `$(outdir)/$(group)` for `group` in `$(files.groups)`
# - `$(outdir)/install`
# - `$(outdir)/install-$(group)` for `group` in `$(filter-out $(files.default),$(files.groups))`
@@ -59,6 +59,10 @@ define mod.files.doc
# Basic `*` wildcards are supported. Use `*`, not `%`; it will automatically
# substitute `*`->`%` where appropriate.
#
+# Each of the destructive targets depends on `$(target)-hook`, which
+# is defined to be a "double-colon rule" allowing you to add your own
+# code.
+#
# TODO: prose documentation
endef
mod.files.doc := $(value mod.files.doc)
@@ -76,7 +80,7 @@ nested.targets += install installdirs
nested.targets += $(foreach g,$(files.groups),$g)
nested.targets += $(foreach g,$(filter-out $(files.default),$(files.groups)),install-$g install-$gdirs)
# Standard destructive PHONY targets
-nested.targets += uninstall mostlyclean clean distclean maintainer-clean
+nested.targets += uninstall mostlyclean clean distclean maintainer-clean $(files.vcsclean)
# User configuration
@@ -85,3 +89,12 @@ DESTDIR ?=
RM ?= rm -f
RMDIR_P ?= rmdir -p --ignore-fail-on-non-empty
TRUE ?= true
+
+# Utility functions
+
+_files.XARGS = $(if $(strip $2),$1 $(strip $2))
+
+_files.maintainer-clean-warning:
+ @echo 'This command is intended for maintainers to use; it'
+ @echo 'deletes files that may need special tools to rebuild.'
+.PHONY: _files.maintainer-clean-warning
diff --git a/build-aux/Makefile.once.head/00-gitfiles.mk b/build-aux/Makefile.once.head/10-gitfiles.mk
index 1214e508c4..8566a7f5e9 100644
--- a/build-aux/Makefile.once.head/00-gitfiles.mk
+++ b/build-aux/Makefile.once.head/10-gitfiles.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2016 Luke Shumaker
+# Copyright (C) 2016-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -51,10 +51,10 @@ define mod.gitfiles.doc
# 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`.
+# 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
mod.gitfiles.doc := $(value mod.gitfiles.doc)
@@ -65,10 +65,11 @@ _gitfiles.all =
ifneq ($(wildcard $(topsrcdir)/.git),)
$(topsrcdir)/$(gitfiles.file): _gitfiles.FORCE
- @(cd $(@D) && git ls-files -z) | sed -z -e 's/\$$/\$$$$/g' -e 's/\n/$$(at.nl)/g' | xargs -r0 printf '_gitfiles.all+=%s\n' | $(WRITE_IFCHANGED) $@
+ @(cd $(@D) && git ls-files --recurse-submodules -z) | sed -z -e 's/\$$/\$$$$/g' -e 's/\n/$$(at.nl)/g' | xargs -r0 printf '_gitfiles.all+=%s\n' | $(WRITE_IFCHANGED) $@
.PHONY: _gitfiles.FORCE
endif
_gitfiles.dir = $(call at.relto,$(topsrcdir),$(srcdir))
-_gitfiles.dir.all = $(patsubst $(_gitfiles.dir)/%,%,$(filter $(_gitfiles.dir)/%,$(_gitfiles.all)))
+_gitfiles.pat = $(patsubst ./%,%,$(_gitfiles.dir)/%)
+_gitfiles.dir.all = $(patsubst $(_gitfiles.pat),%,$(filter $(_gitfiles.pat),$(_gitfiles.all)))
_gitfiles.dir.src = $(filter-out $(addsuffix /%,$(nested.subdirs)),$(_gitfiles.dir.all))
diff --git a/build-aux/Makefile.once.head/10-gnuconf.mk b/build-aux/Makefile.once.head/10-gnuconf.mk
index a4b76964f4..87baa14a69 100644
--- a/build-aux/Makefile.once.head/10-gnuconf.mk
+++ b/build-aux/Makefile.once.head/10-gnuconf.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2016 Luke Shumaker
+# Copyright (C) 2016-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -30,6 +30,9 @@ define mod.gnuconf.doc
endef
mod.gnuconf.doc := $(value mod.gnuconf.doc)
+PACKAGE_TARNAME ?=
+PACKAGE ?=
+PACKAGE_NAME ?=
gnuconf.pkgname ?= $(firstword $(PACKAGE_TARNAME) $(PACKAGE) $(PACKAGE_NAME))
ifeq ($(gnuconf.pkgname),)
$(error Autothing module: gnuconf: gnuconf.pkgname must be set)
@@ -101,6 +104,8 @@ TEXI2DVIFLAGS ?=
YACC ?= yacc
YFLAGS ?= # YFLAGS instead of YACCFLAGS
+CPPFLAGS ?=
+
LN_S ?= ln -s # TODO[2]
CHGRP ?= chgrp
diff --git a/build-aux/Makefile.once.head/10-nested.mk b/build-aux/Makefile.once.head/10-nested.mk
index 4f181a9290..d903d53cd4 100644
--- a/build-aux/Makefile.once.head/10-nested.mk
+++ b/build-aux/Makefile.once.head/10-nested.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2016 Luke Shumaker
+# Copyright (C) 2016-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -21,6 +21,7 @@ define mod.nested.doc
# Outputs:
# - .PHONY Targets : `$(addprefix $(outdir)/,$(nested.targets))`
# - Variable : `at.subdirs`
+# - Variable : `at.targets`
#
# The Autothing `at.subdirs` slates a subdirectory's Makefile for inclusion,
# but doesn't help with recursive targets like `all`, `install`, or `clean`,
diff --git a/build-aux/Makefile.once.head/10-texinfo.mk b/build-aux/Makefile.once.head/10-texinfo.mk
new file mode 100644
index 0000000000..d24852d8eb
--- /dev/null
+++ b/build-aux/Makefile.once.head/10-texinfo.mk
@@ -0,0 +1,47 @@
+# Copyright (C) 2016-2017 Luke Shumaker
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 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 Affero General Public License for more details.
+#
+# 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/>.
+
+mod.texinfo.description = The GNU documentation system
+mod.texinfo.depends += files nested gnuconf
+define mod.texinfo.doc
+# User variables (in addition to gnuconf):
+# - `TEXI2HTML ?= makeinfo --html`
+# - `TEXI2PDF ?= texi2pdf`
+# - `TEXI2PS ?= texi2dvi --ps`
+# Inputs:
+# - Directory variable : `texinfo.docs ?=`
+# Outputs:
+# - Global variable : `files.groups += html dvi pdf ps`
+# - Global variable : `nested.targets += info`
+# - Directory variable : `files.src.gen`
+# - Directory variable : `files.out.{dvi,html,pdf,ps}`
+# - Directory variable : `files.sys.{dvi,html,pdf,ps,all}`
+# - .PHONY target : `$(outdir)/info`
+# - Target : `$(outdir)/%.info`
+# - Target : `$(outdir)/%.dvi`
+# - target : `$(outdir)/%.html`
+# - target : `$(outdir)/%.pdf`
+# - Target : `$(outdir)/%.ps`
+#
+# TODO: prose documentation
+endef
+mod.texinfo.doc := $(value mod.texinfo.doc)
+
+TEXI2HTML ?= makeinfo --html
+TEXI2PDF ?= texi2pdf
+TEXI2PS ?= texi2dvi --ps
+
+files.groups += html dvi pdf ps
+nested.targets += info
diff --git a/build-aux/Makefile.once.tail/00-dist.mk b/build-aux/Makefile.once.tail/00-dist.mk
index a890d9d6dc..59a7dc3c70 100644
--- a/build-aux/Makefile.once.tail/00-dist.mk
+++ b/build-aux/Makefile.once.tail/00-dist.mk
@@ -1,4 +1,4 @@
-# Copyright (C) 2015-2016 Luke Shumaker
+# Copyright (C) 2015-2017 Luke Shumaker
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
@@ -13,6 +13,9 @@
# 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/>.
+# NB: intentionally resolve symlinks (tack on the -P flag to `cp` to
+# not resolve them). The GNU Coding Standards say to avoid symlinks
+# in tarballs.
_dist.copyfile = $(MKDIR_P) $(dir $2) && $(CP) -T $1 $2
_dist.addfile = $(call _dist.copyfile,$3,$2/$(call at.relto,$1,$3))
$(topoutdir)/$(dist.pkgname)-$(dist.version): $(_dist.files)