(systemd) Autothing documentation

1 files changed, 41 insertions, 0 deletions

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