Skip to content

Commit 916731d

Browse files
committed
test(hack): cover the .PHONY declaration in package.mk
`.PHONY=a b c` and `.PHONY: a b c` differ in the `=` against the `:`, and only the second declares anything. The first defines an ordinary variable named `.PHONY` that nothing reads, leaving every listed target file-backed. A file or directory of that name beside a package Makefile then stands in as the product of the rule: for a target with no prerequisites make reports it up to date, skips the recipe and exits 0, and a target whose prerequisite is itself file-less keeps rebuilding until that prerequisite is shadowed too. The neighbouring `.DEFAULT_GOAL=help` is a real variable and is correct with `=`, so the two lines read alike while only one of them works, which is what let the inert form sit there unnoticed. Add hack/package-mk-phony.bats, five tests, picked up automatically by the hack/*.bats glob in `bats-unit-tests`. Three cover the declaration itself. The first reads the target list out of package.mk rather than repeating it, plants a file named after each target beside a stub Makefile, and requires `make --dry-run` to print the recipe instead of "is up to date". A negative control mutates a copy back to the assignment form and requires the probe to report up-to-date, so the first cannot pass by never reaching a file-backed target; it uses help, check and clean, the three that no-op even when probed alone, so it does not depend on the decoy layout. The third requires the declared list and the defined targets to be the same set. Defined but undeclared is the direction the list rots in: check, clean, suspend and resume sat undeclared for as long as the declaration itself was inert. Declared but undefined is the empty-target trap in its general form, so a future name cannot slip in the way update and image once did. Two more pin what the list deliberately leaves out. package.mk defines neither `update` nor `image`; the including package Makefile does, and most packages define neither. Naming them here would create them as empty targets everywhere, turning "No rule to make target" into "Nothing to be done". Since the CI build matrix is parsed from the root Makefile `build:` target and runs `make -C <pkg> image` per unit, a package reaching that list without an `image:` rule would go from a red job to a green one that builds no image. One test requires that loud failure to survive; its control extends the declaration with the two names in a copy and requires the failure to disappear, so the pin tracks the list rather than some property of the harness. `%-update` is not coverable: .PHONY matches target names literally and does not expand patterns. Assisted-By: Claude <[email protected]> Signed-off-by: Aleksei Sviridkin <[email protected]>
1 parent 81238a6 commit 916731d

1 file changed

Lines changed: 239 additions & 0 deletions

File tree

‎hack/package-mk-phony.bats‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
#!/usr/bin/env bats
2+
# -----------------------------------------------------------------------------
3+
# Unit tests for the .PHONY declaration in hack/package.mk, which most package
4+
# Makefiles under packages/ include.
5+
#
6+
# `.PHONY=a b c` assigns a variable; `.PHONY: a b c` declares targets. Only the
7+
# second does anything, and make reports neither. The declaration lists the nine
8+
# targets package.mk defines and stops there.
9+
#
10+
# `update` and `image` are deliberately absent: package.mk does not define them,
11+
# the including package Makefile does, and naming an undefined target in .PHONY
12+
# creates it as an empty target. That turns "No rule to make target" (exit 2)
13+
# into "Nothing to be done" (exit 0) wherever the rule is missing, including the
14+
# CI build matrix, which is parsed from the root Makefile `build:` target and
15+
# runs `make -C <pkg> image` per unit. The last two tests pin the exclusion.
16+
#
17+
# The first test is narrower than its name suggests: it probes the names on the
18+
# `.PHONY:` line, so it cannot see a name dropped from that line. The
19+
# set-equality test is what guards every name's presence.
20+
#
21+
# Constraints on anyone editing this file: every make invocation is pinned to
22+
# LC_ALL=C, because the assertions match English make wording; cozytest.sh
23+
# recognizes only @test blocks and a bare `}` at column 0, and injects `set -e`,
24+
# so exit statuses are captured explicitly rather than tested inline.
25+
#
26+
# Run with: hack/cozytest.sh hack/package-mk-phony.bats
27+
# -----------------------------------------------------------------------------
28+
29+
@test "every target hack/package.mk declares phony still runs when a file of that name exists" {
30+
repo=$(pwd)
31+
targets=$(sed -n 's/^\.PHONY:[[:space:]]*//p' "$repo/hack/package.mk")
32+
33+
# Without this guard the loop below is a vacuous pass against `.PHONY=`,
34+
# which the sed no longer matches.
35+
if [ -z "$targets" ]; then
36+
echo "no '.PHONY:' declaration found in hack/package.mk" >&2
37+
exit 1
38+
fi
39+
40+
tmp=$(mktemp -d)
41+
printf 'include %s/hack/package.mk\n' "$repo" > "$tmp/Makefile"
42+
43+
for t in $targets; do
44+
touch "$tmp/$t"
45+
done
46+
47+
for t in $targets; do
48+
# cozytest.sh runs with `set -e`, so capture the exit status explicitly
49+
# rather than letting a failing make abort before the diagnostics below.
50+
rc=0
51+
out=$(LC_ALL=C make --dry-run --directory "$tmp" "$t" 2>&1) || rc=$?
52+
if [ "$rc" -ne 0 ]; then
53+
echo "make $t exited $rc under --dry-run:" >&2
54+
echo "$out" >&2
55+
rm -rf "$tmp"
56+
exit 1
57+
fi
58+
case "$out" in
59+
*"is up to date"*)
60+
echo "make $t no-oped with a file named $t present:" >&2
61+
echo "$out" >&2
62+
echo "hack/package.mk does not actually declare $t phony" >&2
63+
rm -rf "$tmp"
64+
exit 1
65+
;;
66+
esac
67+
done
68+
69+
rm -rf "$tmp"
70+
}
71+
72+
@test "the probe reports up-to-date when .PHONY is written as an assignment" {
73+
# Negative control: proves the probe can see a file-backed target at all.
74+
# Names are spelled out because deriving them from the mutated copy is what
75+
# stops working. help, check and clean are package.mk's only targets with no
76+
# prerequisites, so this does not depend on decoy timestamps.
77+
repo=$(pwd)
78+
tmp=$(mktemp -d)
79+
80+
sed 's/^\.PHONY:/.PHONY=/' "$repo/hack/package.mk" > "$tmp/package.mk"
81+
if ! grep -q '^\.PHONY=' "$tmp/package.mk"; then
82+
echo "mutation to the assignment form did not apply to the copy" >&2
83+
rm -rf "$tmp"
84+
exit 1
85+
fi
86+
87+
printf 'include %s/package.mk\n' "$tmp" > "$tmp/Makefile"
88+
89+
for t in help check clean; do
90+
touch "$tmp/$t"
91+
done
92+
93+
for t in help check clean; do
94+
rc=0
95+
out=$(LC_ALL=C make --dry-run --directory "$tmp" "$t" 2>&1) || rc=$?
96+
if [ "$rc" -ne 0 ]; then
97+
echo "make $t exited $rc under --dry-run:" >&2
98+
echo "$out" >&2
99+
rm -rf "$tmp"
100+
exit 1
101+
fi
102+
case "$out" in
103+
*"is up to date"*) ;;
104+
*)
105+
echo "probe failed to detect a file-backed $t:" >&2
106+
echo "$out" >&2
107+
rm -rf "$tmp"
108+
exit 1
109+
;;
110+
esac
111+
done
112+
113+
rm -rf "$tmp"
114+
}
115+
116+
@test "the .PHONY list and the targets package.mk defines are the same set" {
117+
# The first test only probes names already on the list, so this is the sole
118+
# guard on a name being dropped from it. The reverse direction catches a
119+
# declared-but-undefined name, which make turns into an empty target.
120+
# `%-update` is out of reach for both: .PHONY matches literally.
121+
repo=$(pwd)
122+
# Flattened because the `case` tests match on " name " and an embedded
123+
# newline makes a name fail that check and get reported wrongly.
124+
declared=$(sed -n 's/^\.PHONY:[[:space:]]*//p' "$repo/hack/package.mk" \
125+
| tr '\n' ' ')
126+
# A target name outside this pattern — leading underscore, dot, slash — is
127+
# legal in make and skipped here in silence, so keep new names inside it.
128+
# The second grep drops assignments, `:+` covering `::=` and `:::=`.
129+
defined=$(grep -E '^[A-Za-z0-9][A-Za-z0-9_-]*:' "$repo/hack/package.mk" \
130+
| grep -vE '^[A-Za-z0-9][A-Za-z0-9_-]*:+=' | sed 's/:.*//' | sort -u \
131+
| tr '\n' ' ')
132+
133+
if [ -z "$declared" ] || [ -z "$defined" ]; then
134+
echo "could not extract targets from hack/package.mk — extraction broke" >&2
135+
exit 1
136+
fi
137+
138+
missing=""
139+
for t in $defined; do
140+
case " $declared " in
141+
*" $t "*) ;;
142+
*) missing="$missing $t" ;;
143+
esac
144+
done
145+
146+
if [ -n "$missing" ]; then
147+
echo "hack/package.mk defines these targets but does not declare them phony:$missing" >&2
148+
echo "a file of that name next to a package Makefile would silence the recipe" >&2
149+
exit 1
150+
fi
151+
152+
undefined=""
153+
for t in $declared; do
154+
case " $defined " in
155+
*" $t "*) ;;
156+
*) undefined="$undefined $t" ;;
157+
esac
158+
done
159+
160+
if [ -n "$undefined" ]; then
161+
echo "hack/package.mk declares these targets phony but defines none of them:$undefined" >&2
162+
echo "naming an undefined target in .PHONY creates it as an empty target, so the" >&2
163+
echo "command reports success instead of failing with 'No rule to make target'" >&2
164+
exit 1
165+
fi
166+
}
167+
168+
@test "update and image stay undeclared so a package without the rule fails loudly" {
169+
# Pins the exclusion: a package with no `update:`/`image:` rule must still
170+
# fail loudly. Declaring them centrally would make every such package report
171+
# success having built nothing, CI included.
172+
repo=$(pwd)
173+
tmp=$(mktemp -d)
174+
175+
printf 'include %s/hack/package.mk\n' "$repo" > "$tmp/Makefile"
176+
177+
for t in update image; do
178+
rc=0
179+
out=$(LC_ALL=C make --directory "$tmp" "$t" 2>&1) || rc=$?
180+
if [ "$rc" -eq 0 ]; then
181+
echo "expected 'make $t' to fail in a package that defines no $t rule," >&2
182+
echo "but it exited 0 — is $t named in the .PHONY list?" >&2
183+
echo "$out" >&2
184+
rm -rf "$tmp"
185+
exit 1
186+
fi
187+
case "$out" in
188+
*"No rule to make target"*) ;;
189+
*)
190+
echo "expected 'make $t' to report no rule to make target, got:" >&2
191+
echo "$out" >&2
192+
rm -rf "$tmp"
193+
exit 1
194+
;;
195+
esac
196+
done
197+
198+
rm -rf "$tmp"
199+
}
200+
201+
@test "adding update and image to the .PHONY list silences that failure" {
202+
# Negative control. Test 4 passes vacuously if its Makefile never reads
203+
# package.mk at all: a broken `include` path also exits non-zero with "No
204+
# rule to make target", naming the missing file. This mutates a copy and
205+
# greps that the mutation landed, so a wrong path fails here instead.
206+
repo=$(pwd)
207+
tmp=$(mktemp -d)
208+
209+
sed 's/^\(\.PHONY:.*\)$/\1 update image/' "$repo/hack/package.mk" > "$tmp/package.mk"
210+
if ! grep -q '^\.PHONY:.* update image$' "$tmp/package.mk"; then
211+
echo "mutation extending the declaration did not apply to the copy" >&2
212+
rm -rf "$tmp"
213+
exit 1
214+
fi
215+
216+
printf 'include %s/package.mk\n' "$tmp" > "$tmp/Makefile"
217+
218+
for t in update image; do
219+
rc=0
220+
out=$(LC_ALL=C make --directory "$tmp" "$t" 2>&1) || rc=$?
221+
if [ "$rc" -ne 0 ]; then
222+
echo "mutation did not take effect: 'make $t' still failed with exit $rc" >&2
223+
echo "$out" >&2
224+
rm -rf "$tmp"
225+
exit 1
226+
fi
227+
case "$out" in
228+
*"Nothing to be done"*) ;;
229+
*)
230+
echo "expected the mutated copy to report nothing to be done for $t, got:" >&2
231+
echo "$out" >&2
232+
rm -rf "$tmp"
233+
exit 1
234+
;;
235+
esac
236+
done
237+
238+
rm -rf "$tmp"
239+
}

0 commit comments

Comments
 (0)