Hi Stephen,
On 1/7/22 17:46, Stephen Kitt wrote:
This is a first step to automating example program checks. It extracts
source snippets introduced by "Program source", assuming it's C, and
attempts to compile it.
For now, only man pages with a single "Program source" entry are
processed. The compiled code isn't linked to avoid having to handle
library requirements (e.g. -ldl).
Signed-off-by: Stephen Kitt <steve@xxxxxxx>
I like the concept of this patch.
However, a few things:
- I prefer a script in ./scripts/,
which can be called from the Makefile.
I'd like to keep the Makefile simple
(it's already quite complex to add more stuff to it).
- I'd like to use make(1) properly,
and only test programs incrementally,
so if a page has already been tested and it hasn't been modified,
it should not be retested.
That part should go in the Makefile, not the test itself.
For that, I'd chose some arbitrary dirname
(<./tests/example_programs/> sounds like a good candidate),
and touch dummy files there when a test is performed:
builddir := $(CURDIR)/build
TESTS_example_programs := $(patsubst
$(MANDIR)/%,$(builddir)/%.example-programs.touch,$(MANPAGES))
$(TESTS_example_programs): $(builddir)/%.example-programs.touch: \
$(MANDIR)/% \
Makefile \
$(CURDIR)/scripts/check_example_programs.sh \
| $$@D)/.
$(info TEST example programs: $@)
$(CURDIR)/scripts/check_example_programs $@
touch $@
Something like the above would be nice.
That would also remove the call to mktemp(1).
- This expects pages to have 'Program source' just before the source.
Few pages do have that currently.
Do you have plans to standardize some convention in the man pages?
I'd be happy to see that.
I think a good approach would be to use C comments,
one line before the code, and one line after the code,
so that there's no doubts about the limits of the code
(we should decide the format of the comment).
The comment should be something not too noisy, but very reliable.
I think I'd also first restrict to the EXAMPLES sections,
even before reading that hypothetical comment (or whatever we put),
to avoid mistakes.
- Logs should go to stdout/stderr,
as in any other standard Unix command,
so just let the compiler print wherever it wants to print,
and let the user redirect them to wherever the user wants to too.
I know there was the groff-warnings test. But I don't like it.
It's there because it predates me,
and I yet have to understand how and if it works,
and then I'll rewrite it properly.
Cheers,
Alex
---
Makefile | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/Makefile b/Makefile
index 0da0328d8..3f597d7c3 100644
--- a/Makefile
+++ b/Makefile
@@ -266,6 +266,23 @@ check-groff-warnings:
done; \
rm -f "$$GROFF_LOG"
+# Check that man pages' examples programs (for now, only pages with a
+# single program) actually compile
+.PHONY: check-example-programs
+check-example-programs:
+ GCC_LOG="$$(mktemp --tmpdir manpages-checksXXXX)" || exit $$?; \
+ for manpage in $$(grep -rc 'Program source' man?/* | grep ':1$$' | cut -d: -f1); \
+ do \
+ (man -Tutf8 $$manpage | \
+ col -bx | \
+ sed -n '/Program source/,/^[[:space:]]\{0,3\}[^[:space:]]/p' | \
+ tail -n+2 | \
+ head -n-1 | \
+ gcc -xc -c -o/dev/null -) 2>| "$$GCC_LOG"; \
+ [ -s "$$GCC_LOG" ] && { echo "$$manpage: "; cat "$$GCC_LOG"; echo; }; \
+ done; \
+ rm -f "$$GCC_LOG"
+
# someone might also want to look at /var/catman/cat2 or so ...
# a problem is that the location of cat pages varies a lot
--
Alejandro Colomar
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
