From 95d18493a5d3399993053b94cb1fc4542699f884 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Fri, 28 Oct 2016 12:45:33 -0400 Subject: (systemd) Autothing documentation --- build-aux/Makefile.once.head/00-gitfiles.mk | 41 ++++++++++++++++++++++ build-aux/Makefile.once.head/00-quote.mk | 23 ++++++++++-- build-aux/Makefile.once.head/00-var.mk | 14 ++++++++ build-aux/Makefile.once.head/10-dist.mk | 34 ++++++++++++++++++ build-aux/Makefile.once.head/10-files.mk | 39 ++++++++++++++++++++ build-aux/Makefile.once.head/10-gnuconf.mk | 17 +++++++-- build-aux/Makefile.once.head/10-nested.mk | 26 ++++++++++++++ build-aux/Makefile.once.head/10-write-atomic.mk | 18 ++++++++++ build-aux/Makefile.once.head/10-write-ifchanged.mk | 18 ++++++++++ build-aux/Makefile.once.head/zz-mod.mk | 22 ++++++++++++ 10 files changed, 247 insertions(+), 5 deletions(-) (limited to 'build-aux/Makefile.once.head') diff --git a/build-aux/Makefile.once.head/00-gitfiles.mk b/build-aux/Makefile.once.head/00-gitfiles.mk index b17b63a..faae91d 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 9fce401..4c954b1 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 . 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 d1e537e..636bbb0 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 . 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 e139096..8c68d04 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 . 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 5441735..9d27ae9 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 c07cfb5..6d641bb 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 . -# 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 af9fdf7..72e15ab 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 . 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 f099ae2..ce6acd8 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 b0a5ac4..5abb3ce 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 732f1e1..1b12a2f 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". -- cgit v1.2.2