diff options
Diffstat (limited to 'build-aux/Makefile.once.head/00-gitfiles.mk')
| -rw-r--r-- | build-aux/Makefile.once.head/00-gitfiles.mk | 41 |
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 |