From 0328754e11fa93d4f8f0c7aaf0e0125f2fe7b0d1 Mon Sep 17 00:00:00 2001 From: Gerwin Klein Date: Mon, 27 Mar 2023 13:09:02 +1100 Subject: [PATCH] manual: prevent unnecessary rebuilds - use a marker file to get a time stamp for when doxygen output was last generated. Use that as a file target instead of a phony target to avoid rebuilds when there is nothing to do. - use static pattern rules so that `make` creates files instead of giving up when the prerequisite of a pattern rule does not exist yet. - remove file list duplication (needed because the static pattern rules also need to mention these files) Signed-off-by: Gerwin Klein --- manual/Makefile | 91 +++++++++++++++++++++++-------------------------- 1 file changed, 43 insertions(+), 48 deletions(-) diff --git a/manual/Makefile b/manual/Makefile index 77f946356..cb05db7c1 100644 --- a/manual/Makefile +++ b/manual/Makefile @@ -8,7 +8,7 @@ # # To create a LaTeX diff against the CVS HEAD revision, use the target # "diff" (or "viewdiff"). -# To use a revision other than HEAD, speciff DIFF=x on the +# To use a revision other than HEAD, speciff DIFF=x on the # make command line to choose the revision x. # @@ -30,7 +30,7 @@ GnuPlot = gnuplot Eps2Pdf = epstopdf --outfile PdfView = xpdf #PdfView = open -a preview -#PdfView = acroread +#PdfView = acroread Lpr = lpr mv = mv awk = awk @@ -72,15 +72,13 @@ Tex = $(addsuffix .tex, $(Targets)) Diff_Pdf = $(addsuffix .pdf, $(Optional)) DoxygenOutput = doxygen-output +DoxygenMarker = $(DoxygenOutput)/.doxygen-done DoxygenXml = $(DoxygenOutput)/xml Stage = stage Libsel4Dir = ../libsel4 GeneratedLatexDir = generated -GeneratedLatex = $(wildcard $(GeneratedLatexDir)/*.tex) - GeneratedMarkdownDir = generated_markdown -GeneratedMarkdown = $(wildcard $(GeneratedMarkdownDir)/*.md) GenerationTool = tools/parse_doxygen_xml.py @@ -94,7 +92,7 @@ all: pdf diff: diff_pdf FORCE: ps: $(Ps) -pdf: generated-latex $(Figures) Makefile $(Pdf) +pdf: $(Figures) Makefile $(Pdf) diff_pdf: $(Figures) Makefile $(Diff_Pdf) markdown: generated-markdown @@ -105,43 +103,55 @@ else Q:=@ endif -.PHONY: doxygen generated-headers generated-latex generated-markdown +.PHONY: doxygen generated-latex generated-markdown + +SYSCALLS = GeneralSystemCalls \ + MCSSystemCalls \ + DebuggingSystemCalls \ + BenchmarkingSystemCalls \ + X86SystemCalls + +OBJECTS = ObjectApi \ + ObjectApiX86 \ + ObjectApiArm \ + ObjectApiAarch32 \ + ObjectApiAarch64 \ + ObjectApiIa32 \ + ObjectApiX64 \ + ObjectApiRISCV + +GENERATED_LATEX_SYSCALLS = $(addsuffix .tex, $(addprefix ${GeneratedLatexDir}/, ${SYSCALLS})) +GENERATED_LATEX_OBJECTS = $(addsuffix .tex, $(addprefix ${GeneratedLatexDir}/, ${OBJECTS})) +GENERATED_LATEX = ${GENERATED_LATEX_SYSCALLS} ${GENERATED_LATEX_OBJECTS} + +DOXYGEN_XML_OUT = $(addsuffix .xml, $(addprefix ${DoxygenXml}/group__, ${SYSCALLS} ${OBJECTS})) + +doxygen: ${DoxygenMarker} + +# Xml files generated by doxygen +${DOXYGEN_XML_OUT}: ${DoxygenMarker} # We call doxygen twice below while excluding either syscalls_master.h or syscalls_mcs.h. # Without excluding one of the two files, the doc strings get merged in inconsistent ways # and lead to bad output in the manual. If there is a better way to support duplicates # then it could be used instead. -doxygen: generated-headers +${DoxygenMarker}: ${Stage}/object_invocations.h + @echo "====> Running doxygen" ( cat Doxyfile ; echo "EXCLUDE = ./../libsel4/include/sel4/syscalls_master.h" ) | $(doxygen) - ( cat Doxyfile ; echo "EXCLUDE = ./../libsel4/include/sel4/syscalls_mcs.h" ) | $(doxygen) - - -# Xml files generated by doxygen -${DoxygenXml}/%.xml: doxygen - @echo "====> Generating $@" + touch ${DoxygenMarker} # Latex files translated from doxygen-generated xml -${GeneratedLatexDir}/%SystemCalls.tex: ${DoxygenXml}/group__%SystemCalls.xml +${GENERATED_LATEX_SYSCALLS}: ${GeneratedLatexDir}/%.tex: ${DoxygenXml}/group__%.xml @echo "====> Generating $@" ${Q}${PYTHON} ${GenerationTool} --level 3 --input $< --output $@ -${GeneratedLatexDir}/%.tex: ${DoxygenXml}/group__%.xml +${GENERATED_LATEX_OBJECTS}: ${GeneratedLatexDir}/%.tex: ${DoxygenXml}/group__%.xml @echo "====> Generating $@" ${Q}${PYTHON} ${GenerationTool} --level 2 --input $< --output $@ # Collect generated latex files into single rule -generated-latex: ${GeneratedLatexDir}/GeneralSystemCalls.tex \ - ${GeneratedLatexDir}/MCSSystemCalls.tex \ - ${GeneratedLatexDir}/DebuggingSystemCalls.tex \ - ${GeneratedLatexDir}/BenchmarkingSystemCalls.tex \ - ${GeneratedLatexDir}/X86SystemCalls.tex \ - ${GeneratedLatexDir}/ObjectApi.tex \ - ${GeneratedLatexDir}/ObjectApiX86.tex \ - ${GeneratedLatexDir}/ObjectApiArm.tex \ - ${GeneratedLatexDir}/ObjectApiAarch32.tex \ - ${GeneratedLatexDir}/ObjectApiAarch64.tex \ - ${GeneratedLatexDir}/ObjectApiIa32.tex \ - ${GeneratedLatexDir}/ObjectApiX64.tex \ - ${GeneratedLatexDir}/ObjectApiRISCV.tex +generated-latex: ${GENERATED_LATEX} # Markdown files translated from doxygen-generated xml ${GeneratedMarkdownDir}/%.md: ${DoxygenXml}/group__%.xml Makefile @@ -149,19 +159,7 @@ ${GeneratedMarkdownDir}/%.md: ${DoxygenXml}/group__%.xml Makefile ${Q}${PYTHON} ${GenerationTool} --format markdown --level 2 --input $< --output $@ # Collect generated markdown files into single rule -generated-markdown: ${GeneratedMarkdownDir}/GeneralSystemCalls.md \ - ${GeneratedMarkdownDir}/MCSSystemCalls.md \ - ${GeneratedMarkdownDir}/DebuggingSystemCalls.md \ - ${GeneratedMarkdownDir}/BenchmarkingSystemCalls.md \ - ${GeneratedMarkdownDir}/X86SystemCalls.md \ - ${GeneratedMarkdownDir}/ObjectApi.md \ - ${GeneratedMarkdownDir}/ObjectApiX86.md \ - ${GeneratedMarkdownDir}/ObjectApiArm.md \ - ${GeneratedMarkdownDir}/ObjectApiAarch32.md \ - ${GeneratedMarkdownDir}/ObjectApiAarch64.md \ - ${GeneratedMarkdownDir}/ObjectApiIa32.md \ - ${GeneratedMarkdownDir}/ObjectApiX64.md \ - ${GeneratedMarkdownDir}/ObjectApiRISCV.md +generated-markdown: $(addsuffix .md, $(addprefix ${GeneratedMarkdownDir}/, ${SYSCALLS} ${OBJECTS})) # Generate object invocation prototypes ${Stage}/object_invocations.h: ${Libsel4Dir}/include/interfaces/sel4.xml \ @@ -175,15 +173,12 @@ ${Stage}/object_invocations.h: ${Libsel4Dir}/include/interfaces/sel4.xml \ @echo "====> Generating documented object invocation header" ${Q}${PYTHON} ${GenerateObjectInvocationTool} --dtd ${InterfaceDtd} --output $@ $^ -# Collect generated headers into single rule -generated-headers: ${Stage}/object_invocations.h - # Fetch information from the environment that needs to go into the document. env.tex: FORCE @echo 'ENV ->' $@ ${Q}${PYTHON} tools/gen_env.py $@ -manual.pdf: VERSION env.tex manual.tex parts/*.tex parts/api/*.tex +manual.pdf: VERSION Makefile env.tex manual.tex parts/*.tex parts/api/*.tex ${GENERATED_LATEX} %.pdf: %.perf tools/bargraph.pl @echo $< '->' $@ @@ -270,7 +265,7 @@ Undefined = '((Reference|Citation).*undefined)|(Label.*multiply defined)' Error = '^! ' # combine citation commands from all targets into tmp.aux, generate references.bib from this -references.bib: $(addsuffix .tex, $(Targets)) env.tex +references.bib: $(addsuffix .tex, $(Targets)) @echo "====> Parsing targets for references"; ${Q}for i in $(Targets); do \ $(LaTeX) $$i.tex >>.log; \ @@ -289,7 +284,7 @@ references.bib: $(addsuffix .tex, $(Targets)) env.tex echo "====> Building references.bib"; \ $(BibTexEnv) ./tools/bibexport.sh -t -o references.bib tmp.aux > /dev/null 2> /dev/null; \ cp tmp.aux references.aux; \ - fi; + fi; ${Q}rm all_refs.aux tmp.aux references.diff %.pdf: %.tex references.bib $(Figures) Makefile @@ -306,8 +301,8 @@ references.bib: $(addsuffix .tex, $(Targets)) env.tex ${Q}grep "dimension:" $*.log || echo "None." ############################################################################## -# Generate a list of FIXMEs -fixmes: +# Generate a list of FIXMEs +fixmes: ${Q}for i in $(Tex); do \ echo "FIXMEs in $$i:"; \ nl -b a $$i | grep "FIXME{" | nl -b a; \