Skip to content

Commit c31474a

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, pinning both of the observables it is made of: make's exit status 2 and its diagnostic. They are independent, and a wrapper that kept the wording while returning something else would satisfy a check on the message alone. 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 e97416a commit c31474a

1 file changed

Lines changed: 243 additions & 0 deletions

File tree

‎hack/package-mk-phony.bats‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
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+
# Exit status and diagnostic are independent observables, so both are
181+
# pinned. 2 is what make returns for a fatal error, and the number is
182+
# what a caller branches on — a wrapper or a future make that kept the
183+
# wording while returning something else would pass the case below.
184+
if [ "$rc" -ne 2 ]; then
185+
echo "expected 'make $t' to exit 2 in a package that defines no $t rule," >&2
186+
echo "but it exited $rc — is $t named in the .PHONY list?" >&2
187+
echo "$out" >&2
188+
rm -rf "$tmp"
189+
exit 1
190+
fi
191+
case "$out" in
192+
*"No rule to make target"*) ;;
193+
*)
194+
echo "expected 'make $t' to report no rule to make target, got:" >&2
195+
echo "$out" >&2
196+
rm -rf "$tmp"
197+
exit 1
198+
;;
199+
esac
200+
done
201+
202+
rm -rf "$tmp"
203+
}
204+
205+
@test "adding update and image to the .PHONY list silences that failure" {
206+
# Negative control. Test 4 passes vacuously if its Makefile never reads
207+
# package.mk at all: a broken `include` path also exits non-zero with "No
208+
# rule to make target", naming the missing file. This mutates a copy and
209+
# greps that the mutation landed, so a wrong path fails here instead.
210+
repo=$(pwd)
211+
tmp=$(mktemp -d)
212+
213+
sed 's/^\(\.PHONY:.*\)$/\1 update image/' "$repo/hack/package.mk" > "$tmp/package.mk"
214+
if ! grep -q '^\.PHONY:.* update image$' "$tmp/package.mk"; then
215+
echo "mutation extending the declaration did not apply to the copy" >&2
216+
rm -rf "$tmp"
217+
exit 1
218+
fi
219+
220+
printf 'include %s/package.mk\n' "$tmp" > "$tmp/Makefile"
221+
222+
for t in update image; do
223+
rc=0
224+
out=$(LC_ALL=C make --directory "$tmp" "$t" 2>&1) || rc=$?
225+
if [ "$rc" -ne 0 ]; then
226+
echo "mutation did not take effect: 'make $t' still failed with exit $rc" >&2
227+
echo "$out" >&2
228+
rm -rf "$tmp"
229+
exit 1
230+
fi
231+
case "$out" in
232+
*"Nothing to be done"*) ;;
233+
*)
234+
echo "expected the mutated copy to report nothing to be done for $t, got:" >&2
235+
echo "$out" >&2
236+
rm -rf "$tmp"
237+
exit 1
238+
;;
239+
esac
240+
done
241+
242+
rm -rf "$tmp"
243+
}

0 commit comments

Comments
 (0)