merge queue: checking master (1d2d632) and #12248 together

.github/workflows/cmd-help.yml

@@ -0,0 +1,50 @@
+name: Command help docs
+
+# See: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#concurrency.
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches:
+      - master
+    paths: &paths
+      - doc/Makefile
+      - doc/cmd-v1-help/**
+      - doc/cmd-v2-help/**
+      - doc/cmd-v2-hidden-help/**
+      - doc/setup-help/**
+      - cabal-install/src/Distribution/Client/Cmd*.hs
+      - cabal-install/src/Distribution/Client/Main.hs
+      - cabal-install/src/Distribution/Client/Setup.hs
+      - Cabal/src/Distribution/Simple.hs
+      - Cabal/src/Distribution/Simple/Setup/**
+  pull_request:
+    paths: *paths
+  workflow_dispatch: {}
+
+jobs:
+  cmd-help:
+    name: Check command help docs are up to date
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: haskell-actions/setup@v2
+        with:
+          ghc-version: 9.12.2
+          cabal-version: latest
+      - run: cabal v2-update
+      - name: Cache dependencies
+        uses: actions/cache@v6
+        with:
+          path: ~/.local/state/cabal
+          key: ${{ runner.os }}-cmd-help-${{ hashFiles('cabal.project', 'cabal-install/cabal-install.cabal', 'Cabal/Cabal.cabal') }}
+          restore-keys: ${{ runner.os }}-cmd-help-
+      - name: Regenerate command help docs
+        run: make -B -C doc cmd-help
+      - name: Check that diff is clean
+        run: |
+          git status --porcelain=v1 doc
+          git diff --stat doc
+          git diff -p --exit-code doc

doc/Makefile

@@ -1,5 +1,9 @@
 # Build and safety-check requirements.txt
 
+# Remove a target if its recipe fails, so a failed `cabal run` can't leave a
+# truncated *-help/*.txt behind for `git diff` to find.
+.DELETE_ON_ERROR:
+
 # skjold needs a personal github access token.  This needs no permissions,
 # it is only required to query the GitHub GraphQL API v4.
 # See: https://pythonawesome.com/security-audit-python-project-dependencies-against-security-advisory-databases/
@@ -53,4 +57,118 @@ debug:
 	@echo "SKJOLD_GITHUB_API_TOKEN = $${SKJOLD_GITHUB_API_TOKEN}"
 	@echo "Is SKJOLD_GITHUB_API_TOKEN set? $${SKJOLD_GITHUB_API_TOKEN:+yes}"
 
+CABAL_V1_COMMANDS := \
+	bench \
+	build \
+	clean \
+	configure \
+	copy \
+	freeze \
+	gen-bounds \
+	haddock \
+	install \
+	reconfigure \
+	register \
+	repl \
+	run \
+	test
+
+CABAL_COMMANDS := \
+	bench \
+	build \
+	clean \
+	configure \
+	exec \
+	fetch \
+	freeze \
+	gen-bounds \
+	get \
+	haddock \
+	haddock-project \
+	hscolour \
+	info \
+	init \
+	install \
+	list \
+	list-bin \
+	outdated \
+	path \
+	repl \
+	report \
+	run \
+	sdist \
+	target \
+	test \
+	unpack \
+	update \
+	upload \
+	user-config
+
+CABAL_HIDDEN_COMMANDS := \
+	act-as-setup \
+	format \
+	man
+
+# Distribution.Simple.defaultMain's commands, for build-type: Simple.
+SETUP_COMMANDS := \
+	bench \
+	build \
+	clean \
+	configure \
+	copy \
+	haddock \
+	hscolour \
+	install \
+	register \
+	repl \
+	sdist \
+	test \
+	unregister
+
+# NOTE: To silence the following warning, redirect stderr to /dev/null:
+#   Warning: this is a debug build of cabal-install with assertions enabled.
+cmd-v1-help/%.txt:
+	@mkdir -p $(@D)
+	@cabal run -v0 cabal-install:exe:cabal -- v1-$* --help > $@ 2>/dev/null
+
+cmd-v2-help/%.txt:
+	@mkdir -p $(@D)
+	@cabal run -v0 cabal-install:exe:cabal -- $* --help > $@ 2>/dev/null
+
+# The "You can edit the cabal configuration file..." footer embeds an
+# absolute, machine-specific config path, so strip it for reproducibility.
+cmd-v2-help/help.txt:
+	@mkdir -p $(@D)
+	@cabal run -v0 cabal-install:exe:cabal -- --help 2>/dev/null \
+	  | sed '/^You can edit the cabal configuration file to set defaults:$$/,$$d' > $@
+
+cmd-v2-hidden-help/%.txt:
+	@mkdir -p $(@D)
+	@cabal run -v0 cabal-install:exe:cabal -- $* --help > $@ 2>/dev/null
+
+# act-as-setup runs Distribution.Simple.defaultMainArgs directly; the "--"
+# forwards args after it verbatim instead of being parsed by cabal itself.
+setup-help/%.txt:
+	@mkdir -p $(@D)
+	@cabal run -v0 cabal-install:exe:cabal -- act-as-setup -- $* --help > $@ 2>/dev/null
+
+setup-help/help.txt:
+	@mkdir -p $(@D)
+	@cabal run -v0 cabal-install:exe:cabal -- act-as-setup -- --help > $@ 2>/dev/null
+
+.PHONY: cmd-v1-help
+cmd-v1-help: $(addsuffix .txt,$(addprefix cmd-v1-help/,$(CABAL_V1_COMMANDS)))
+
+.PHONY: cmd-v2-help
+cmd-v2-help: cmd-v2-help/help.txt $(addsuffix .txt,$(addprefix cmd-v2-help/,$(CABAL_COMMANDS)))
+
+.PHONY: cmd-v2-hidden-help
+cmd-v2-hidden-help: $(addsuffix .txt,$(addprefix cmd-v2-hidden-help/,$(CABAL_HIDDEN_COMMANDS)))
+
+.PHONY: setup-help
+setup-help: setup-help/help.txt $(addsuffix .txt,$(addprefix setup-help/,$(SETUP_COMMANDS)))
+
+.PHONY: cmd-help
+cmd-help: cmd-v2-help cmd-v1-help cmd-v2-hidden-help setup-help
+
 # EOF

doc/cmd-v1-help/bench.txt

@@ -0,0 +1,56 @@
+Run all/specific benchmarks.
+
+Usage: cabal v1-bench [FLAGS]
+   or: cabal v1-bench BENCHCOMPONENTS [FLAGS]
+
+If necessary (re)configures with `--enable-benchmarks` flag and builds the
+benchmarks.
+
+Remember that the benchmarks' dependencies must be installed if there are
+additional ones; e.g. with `cabal v1-install --only-dependencies
+--enable-benchmarks`.
+
+By defining UserHooks in a custom Setup.hs, the package can define actions to
+be executed before and after running benchmarks.
+
+Flags for v1-bench:
+ -h, --help                   # Show this help text
+ -v[n], --verbose[=n]         # Control verbosity (n is 0--3, default
+                                verbosity level is 1)
+ --builddir=DIR               # The directory where Cabal puts generated build
+                                files (default dist)
+ --cabal-file=PATH            # use this Cabal file
+ --keep-temp-files            # Keep temporary files.
+ -j[NUM], --jobs[=NUM]        # Run NUM jobs simultaneously (or '$ncpus' if no
+                                NUM is given).
+ --semaphore=SEMAPHORE        # Use the specified semaphore identifier so GHC
+                                can compile components in parallel
+ --with-PROG=PATH             # Give the path to PROG
+ --PROG-option=OPT            # Give an extra option to PROG (passed directly
+                                to PROG as a single argument)
+ --PROG-options=OPTS          # Give extra options to PROG (split on spaces,
+                                use "" to prevent splitting)
+ -v[n], --verbose[=n]         # Control verbosity (n is 0--3, default
+                                verbosity level is 1)
+ --builddir=DIR               # The directory where Cabal puts generated build
+                                files (default dist)
+ --cabal-file=PATH            # use this Cabal file
+ --keep-temp-files            # Keep temporary files.
+ --benchmark-options=TEMPLATES
+                              # Give extra options to benchmark executables
+                                (split on spaces, use "" to prevent splitting;
+                                name templates can use $pkgid, $compiler, $os,
+                                $arch, $benchmark)
+ --benchmark-option=TEMPLATE  # Give extra option to benchmark executables
+                                (passed directly as a single argument; name
+                                template can use $pkgid, $compiler, $os,
+                                $arch, $benchmark)
+
+The v1-bench command is a part of the legacy v1 style of cabal usage.
+
+It is a legacy feature and will be removed in a future release of
+cabal-install. Please file a bug if you cannot replicate a working v1- use
+case with the nix-style commands.
+
+For more information, see:
+https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html

doc/cmd-v1-help/build.txt

@@ -0,0 +1,43 @@
+Compile all/specific components.
+
+Usage: cabal v1-build [FLAGS]
+   or: cabal v1-build COMPONENTS [FLAGS]
+
+Components encompass executables, tests, and benchmarks.
+
+Affected by configuration options, see `v1-configure`.
+
+Flags for v1-build:
+ -h, --help                   # Show this help text
+ -v[n], --verbose[=n]         # Control verbosity (n is 0--3, default
+                                verbosity level is 1)
+ --builddir=DIR               # The directory where Cabal puts generated build
+                                files (default dist)
+ --cabal-file=PATH            # use this Cabal file
+ --keep-temp-files            # Keep temporary files.
+ -j[NUM], --jobs[=NUM]        # Run NUM jobs simultaneously (or '$ncpus' if no
+                                NUM is given).
+ --semaphore=SEMAPHORE        # Use the specified semaphore identifier so GHC
+                                can compile components in parallel
+ --with-PROG=PATH             # Give the path to PROG
+ --PROG-option=OPT            # Give an extra option to PROG (passed directly
+                                to PROG as a single argument)
+ --PROG-options=OPTS          # Give extra options to PROG (split on spaces,
+                                use "" to prevent splitting)
+
+Examples:
+  cabal v1-build               All the components in the package
+  cabal v1-build foo           A component (i.e. lib, exe, test suite)
+
+The flags --with-PROG and --PROG-option(s) can be used with the following programs:
+  alex ar c2hs cpphs doctest gcc ghc ghc-pkg ghcjs ghcjs-pkg haddock happy hpc
+  hsc2hs hscolour jhc ld pkg-config runghc strip tar uhc
+
+The v1-build command is a part of the legacy v1 style of cabal usage.
+
+It is a legacy feature and will be removed in a future release of
+cabal-install. Please file a bug if you cannot replicate a working v1- use
+case with the nix-style commands.
+
+For more information, see:
+https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html

doc/cmd-v1-help/clean.txt

@@ -0,0 +1,26 @@
+Clean up after a build.
+
+Usage: cabal v1-clean [FLAGS]
+
+Removes .hi, .o, preprocessed sources, etc.
+
+Flags for v1-clean:
+ -h, --help                   # Show this help text
+ -v[n], --verbose[=n]         # Control verbosity (n is 0--3, default
+                                verbosity level is 1)
+ --builddir=DIR               # The directory where Cabal puts generated build
+                                files (default dist)
+ --cabal-file=PATH            # use this Cabal file
+ --keep-temp-files            # Keep temporary files.
+ -s, --save-configure         # Do not remove the configuration file
+                                (dist/setup-config) during cleaning. Saves
+                                need to reconfigure.
+
+The v1-clean command is a part of the legacy v1 style of cabal usage.
+
+It is a legacy feature and will be removed in a future release of
+cabal-install. Please file a bug if you cannot replicate a working v1- use
+case with the nix-style commands.
+
+For more information, see:
+https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html