1 file changed, 34 insertions, 31 deletions

diff --git a/Makefile b/Makefileindex 010427b..e4ff38a 100644--- a/Makefile+++ b/Makefile@@ -1,13 +1,17 @@-# cgit top-level Makefile. cgit itself is compiled inside the bundled Git tree-# by source/cgit.mk, which this file invokes; everything else (docs, install,-# packaging, maintenance) is driven from here.+# The entry point for building, documenting and installing cgit. The program+# itself is compiled inside the bundled Git tree by source/cgit.mk, which this+# file invokes with the paths and the defaults it needs. Everything that is not+# compilation, that is the manual page, the install and uninstall rules and the+# housekeeping targets, is driven from here.  .DEFAULT_GOAL := all .SUFFIXES: -# Project layout. Sources live in source/, web assets in assets/, Lua filters-# in custom/extensions/, the bundled Git tree in vendor/git, and every generated-# file lands in build/. CGIT_ROOT reaches from the Git tree back to the root.+# Sources live in source/, web assets in assets/, Lua filters in+# custom/extensions/, the bundled Git tree in vendor/git, and everything+# generated lands in build/. CGIT_ROOT leads from inside the Git tree back to+# the project root, because the cgit build runs with vendor/git as its working+# directory. SRCDIR   = source ASSETDIR = assets EXTDIR   = custom/extensions@@ -15,13 +19,14 @@ GITDIR   = vendor/git BUILDDIR = build CGIT_ROOT = ../.. -# Git release fetched by get-git when the submodule is not checked out. Keep in-# step with the submodule pin in .gitmodules.+# The Git release that get-git fetches when the submodule is not checked out.+# Keep it in step with the submodule pin in .gitmodules. GIT_VERSION = 2.55.0 GIT_URL = https://www.kernel.org/pub/software/scm/git/git-$(GIT_VERSION).tar.xz -# Compiled-in cgit defaults, overridable through cgit.conf. All carry the CGIT_-# prefix except CACHE_ROOT, inherited from upstream under that name.+# Compiled-in cgit defaults, all overridable through cgit.conf. Every one+# carries the CGIT_ prefix except CACHE_ROOT, which is inherited from upstream+# under that name. CGIT_VERSION = v2.2.0 CGIT_SCRIPT_NAME = cgit.cgi CGIT_SCRIPT_PATH = /var/www/htdocs/cgit@@ -29,8 +34,8 @@ CGIT_DATA_PATH = $(CGIT_SCRIPT_PATH) CGIT_CONFIG = /etc/cgitrc CACHE_ROOT = /var/cache/cgit -# Standard GNU-style install directories, lowercase so packaging can override-# them; filterdir is the one cgit-specific addition.+# The standard GNU install directories, kept lowercase so that packaging can+# override them. filterdir is the one cgit-specific addition. prefix = /usr/local libdir = $(prefix)/lib filterdir = $(libdir)/cgit/filters@@ -38,13 +43,14 @@ docdir = $(prefix)/share/doc/cgit htmldir = $(docdir) mandir = $(prefix)/share/man -# Files installed into the data path and the filter dir. One list each drives-# both install and uninstall, so the two can never drift apart.+# The files that go into the data path and the filter directory. One list each+# drives both install and uninstall, so the two can never drift apart. ASSETS       = cgit.css cgit.js cgit.png favicon.ico robots.txt FILTER_FILES = $(notdir $(wildcard $(EXTDIR)/*.lua)) -# The man-page source (*.5.txt) sits at the project root and is rendered into-# build/. Only one man section exists, so DOC_* derive straight from MAN5_TXT.+# The manual page source, *.5.txt, sits at the project root and is rendered+# into build/. Only one man section exists, so both document lists derive+# straight from MAN5_TXT. MAN5_TXT = $(wildcard *.5.txt) DOC_MAN5 = $(patsubst %.txt,$(BUILDDIR)/%,$(MAN5_TXT)) DOC_HTML = $(patsubst %.txt,$(BUILDDIR)/%.html,$(MAN5_TXT))@@ -56,8 +62,8 @@ ASCIIDOC_HTML = xhtml11 ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) -# Reuse Git's platform detection, then let the user override any of the settings-# above through cgit.conf. Both includes must stay after the defaults.+# Reuse Git's platform detection, then let the user override any of the+# settings above through cgit.conf. Both includes must stay after the defaults. -include $(GITDIR)/config.mak.uname -include cgit.conf @@ -65,13 +71,10 @@ export CGIT_VERSION CGIT_SCRIPT_NAME CGIT_SCRIPT_PATH CGIT_DATA_PATH CGIT_CONFIG  all: cgit -# cgit is compiled inside the bundled Git tree so it can reuse Git's build-# machinery (see source/cgit.mk). Objects and the binary go to build/.-#-# NO_RUST keeps Cargo out of the build. Git 2.55 inverted the flag that used-# to be WITH_RUST, so Rust is now compiled in unless it is turned off, and-# leaving this out would quietly make Cargo a build requirement. Git 3.0 drops-# the choice entirely, at which point this stops working and Rust becomes+# NO_RUST keeps Cargo out of the build. Git 2.55 inverted the flag that used to+# be WITH_RUST, so Rust is now compiled in unless it is turned off, and leaving+# this out would quietly make Cargo a build requirement. Git 3.0 drops the+# choice entirely, at which point this stops working and Rust becomes # mandatory. GIT_BUILD_FLAGS = NO_CURL=1 NO_OPENSSL=1 NO_RUST=1 @@ -86,8 +89,8 @@ sparse: test: cgit-with-git 	+@$(MAKE) -C tests all -# The test helpers link against a fully built Git tree, so this asks the-# sub-make for Git's own `all` alongside cgit.+# The test helpers link against a fully built Git tree, so this asks the sub+# make for Git's own all target alongside cgit. cgit-with-git: 	+@$(MAKE) cgit EXTRA_GIT_TARGETS=all @@ -138,9 +141,10 @@ uninstall-html: 	    rm -fv $(DESTDIR)$(htmldir)/$$i; \ 	done -# Compiled output lives under build/; the test suite writes into tests/, so-# cleaning removes both. The tests descent is guarded because tests/Makefile-# includes git's config.mak.uname, which needs the submodule present.+# Compiled output lives under build/ and the test suite writes into tests/, so+# cleaning removes both. The descent into tests is guarded because+# tests/Makefile includes git's config.mak.uname, which needs the submodule+# present. clean: 	$(RM) -r $(BUILDDIR) 	@if test -e $(GITDIR)/config.mak.uname; then $(MAKE) -C tests clean; fi@@ -148,7 +152,6 @@ clean: cleanall: clean 	@if test -e $(GITDIR)/Makefile; then $(MAKE) -C $(GITDIR) clean; fi -# Fetch a Git release tarball for builds without the submodule checked out. get-git: 	mkdir -p $(dir $(GITDIR)) 	curl -L $(GIT_URL) | tar -xJf - && rm -rf $(GITDIR) && mv git-$(GIT_VERSION) $(GITDIR)
diff --git a/Makefile b/Makefile
index 010427b..e4ff38a 100644
--- a/Makefile
+++ b/Makefile
@@ -1,13 +1,17 @@
-# cgit top-level Makefile. cgit itself is compiled inside the bundled Git tree
-# by source/cgit.mk, which this file invokes; everything else (docs, install,
-# packaging, maintenance) is driven from here.
+# The entry point for building, documenting and installing cgit. The program
+# itself is compiled inside the bundled Git tree by source/cgit.mk, which this
+# file invokes with the paths and the defaults it needs. Everything that is not
+# compilation, that is the manual page, the install and uninstall rules and the
+# housekeeping targets, is driven from here.
 
 .DEFAULT_GOAL := all
 .SUFFIXES:
 
-# Project layout. Sources live in source/, web assets in assets/, Lua filters
-# in custom/extensions/, the bundled Git tree in vendor/git, and every generated
-# file lands in build/. CGIT_ROOT reaches from the Git tree back to the root.
+# Sources live in source/, web assets in assets/, Lua filters in
+# custom/extensions/, the bundled Git tree in vendor/git, and everything
+# generated lands in build/. CGIT_ROOT leads from inside the Git tree back to
+# the project root, because the cgit build runs with vendor/git as its working
+# directory.
 SRCDIR   = source
 ASSETDIR = assets
 EXTDIR   = custom/extensions
@@ -15,13 +19,14 @@ GITDIR   = vendor/git
 BUILDDIR = build
 CGIT_ROOT = ../..
 
-# Git release fetched by get-git when the submodule is not checked out. Keep in
-# step with the submodule pin in .gitmodules.
+# The Git release that get-git fetches when the submodule is not checked out.
+# Keep it in step with the submodule pin in .gitmodules.
 GIT_VERSION = 2.55.0
 GIT_URL = https://www.kernel.org/pub/software/scm/git/git-$(GIT_VERSION).tar.xz
 
-# Compiled-in cgit defaults, overridable through cgit.conf. All carry the CGIT_
-# prefix except CACHE_ROOT, inherited from upstream under that name.
+# Compiled-in cgit defaults, all overridable through cgit.conf. Every one
+# carries the CGIT_ prefix except CACHE_ROOT, which is inherited from upstream
+# under that name.
 CGIT_VERSION = v2.2.0
 CGIT_SCRIPT_NAME = cgit.cgi
 CGIT_SCRIPT_PATH = /var/www/htdocs/cgit
@@ -29,8 +34,8 @@ CGIT_DATA_PATH = $(CGIT_SCRIPT_PATH)
 CGIT_CONFIG = /etc/cgitrc
 CACHE_ROOT = /var/cache/cgit
 
-# Standard GNU-style install directories, lowercase so packaging can override
-# them; filterdir is the one cgit-specific addition.
+# The standard GNU install directories, kept lowercase so that packaging can
+# override them. filterdir is the one cgit-specific addition.
 prefix = /usr/local
 libdir = $(prefix)/lib
 filterdir = $(libdir)/cgit/filters
@@ -38,13 +43,14 @@ docdir = $(prefix)/share/doc/cgit
 htmldir = $(docdir)
 mandir = $(prefix)/share/man
 
-# Files installed into the data path and the filter dir. One list each drives
-# both install and uninstall, so the two can never drift apart.
+# The files that go into the data path and the filter directory. One list each
+# drives both install and uninstall, so the two can never drift apart.
 ASSETS       = cgit.css cgit.js cgit.png favicon.ico robots.txt
 FILTER_FILES = $(notdir $(wildcard $(EXTDIR)/*.lua))
 
-# The man-page source (*.5.txt) sits at the project root and is rendered into
-# build/. Only one man section exists, so DOC_* derive straight from MAN5_TXT.
+# The manual page source, *.5.txt, sits at the project root and is rendered
+# into build/. Only one man section exists, so both document lists derive
+# straight from MAN5_TXT.
 MAN5_TXT = $(wildcard *.5.txt)
 DOC_MAN5 = $(patsubst %.txt,$(BUILDDIR)/%,$(MAN5_TXT))
 DOC_HTML = $(patsubst %.txt,$(BUILDDIR)/%.html,$(MAN5_TXT))
@@ -56,8 +62,8 @@ ASCIIDOC_HTML = xhtml11
 ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA)
 TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
 
-# Reuse Git's platform detection, then let the user override any of the settings
-# above through cgit.conf. Both includes must stay after the defaults.
+# Reuse Git's platform detection, then let the user override any of the
+# settings above through cgit.conf. Both includes must stay after the defaults.
 -include $(GITDIR)/config.mak.uname
 -include cgit.conf
 
@@ -65,13 +71,10 @@ export CGIT_VERSION CGIT_SCRIPT_NAME CGIT_SCRIPT_PATH CGIT_DATA_PATH CGIT_CONFIG
 
 all: cgit
 
-# cgit is compiled inside the bundled Git tree so it can reuse Git's build
-# machinery (see source/cgit.mk). Objects and the binary go to build/.
-#
-# NO_RUST keeps Cargo out of the build. Git 2.55 inverted the flag that used
-# to be WITH_RUST, so Rust is now compiled in unless it is turned off, and
-# leaving this out would quietly make Cargo a build requirement. Git 3.0 drops
-# the choice entirely, at which point this stops working and Rust becomes
+# NO_RUST keeps Cargo out of the build. Git 2.55 inverted the flag that used to
+# be WITH_RUST, so Rust is now compiled in unless it is turned off, and leaving
+# this out would quietly make Cargo a build requirement. Git 3.0 drops the
+# choice entirely, at which point this stops working and Rust becomes
 # mandatory.
 GIT_BUILD_FLAGS = NO_CURL=1 NO_OPENSSL=1 NO_RUST=1
 
@@ -86,8 +89,8 @@ sparse:
 test: cgit-with-git
 	+@$(MAKE) -C tests all
 
-# The test helpers link against a fully built Git tree, so this asks the
-# sub-make for Git's own `all` alongside cgit.
+# The test helpers link against a fully built Git tree, so this asks the sub
+# make for Git's own all target alongside cgit.
 cgit-with-git:
 	+@$(MAKE) cgit EXTRA_GIT_TARGETS=all
 
@@ -138,9 +141,10 @@ uninstall-html:
 	    rm -fv $(DESTDIR)$(htmldir)/$$i; \
 	done
 
-# Compiled output lives under build/; the test suite writes into tests/, so
-# cleaning removes both. The tests descent is guarded because tests/Makefile
-# includes git's config.mak.uname, which needs the submodule present.
+# Compiled output lives under build/ and the test suite writes into tests/, so
+# cleaning removes both. The descent into tests is guarded because
+# tests/Makefile includes git's config.mak.uname, which needs the submodule
+# present.
 clean:
 	$(RM) -r $(BUILDDIR)
 	@if test -e $(GITDIR)/config.mak.uname; then $(MAKE) -C tests clean; fi
@@ -148,7 +152,6 @@ clean:
 cleanall: clean
 	@if test -e $(GITDIR)/Makefile; then $(MAKE) -C $(GITDIR) clean; fi
 
-# Fetch a Git release tarball for builds without the submodule checked out.
 get-git:
 	mkdir -p $(dir $(GITDIR))
 	curl -L $(GIT_URL) | tar -xJf - && rm -rf $(GITDIR) && mv git-$(GIT_VERSION) $(GITDIR)