summaryrefslogtreecommitdiffstats
path: root/build
diff options
context:
space:
mode:
authorNeels Hofmeyr <neels@hofmeyr.de>2017-10-19 05:11:57 +0200
committerNeels Hofmeyr <nhofmeyr@sysmocom.de>2017-10-25 16:51:55 +0000
commitc481a988e33e4046c53f1f38d52522db67401820 (patch)
tree46a96b07214e9168a051c4e026881168564389af /build
parent1b1b176e68730f5e42bf71e444c0ba1f3d9acea4 (diff)
refactor Makefile build rules, don't use the FORCE
The initial goal was to make sure we don't have overall FORCE rules causing unnecessary rebuilds -- annoying while writing documentation. As I looked through possible dependencies, I finally understood what's going on here. Remove code dup and nicely sort which belongs where in build/Makefile.*.inc. In each, describe in a top comment how to use it, and also unify how they are used: - Rename Makefile.inc to Makefile.docbook.inc and refactor - Add Makefile.vty-reference.inc - Add Makefile.common.inc Make sure that we accurately pick up all dependencies. Drop use of the macro called 'command', that silenced the actual command lines invoked and replaced them with short strings: it obscures what is actually going on and makes the Makefiles hard to read and understand. Each manual's makefile is greatly reduced to few definitions and a Makefile include, e.g. one for asciidoc, one for VTY reference. Move common/bsc_vty_additions.xml to OsmoBSC/vty/libbsc_vty_additions.xml, link from OsmoNITB. It applies only to OsmoBSC and OsmoNITB. Add a script that combines a VTY reference file with *all* additions files found in a manual's vty/ dir. Call this from Makefile.vty-reference.inc. Change-Id: I9758e04162a480e28c7dc83475b514cf7fd25ec0
Diffstat (limited to 'build')
-rw-r--r--build/Makefile.asciidoc.inc35
-rw-r--r--build/Makefile.common.inc14
-rw-r--r--build/Makefile.docbook.inc35
-rw-r--r--build/Makefile.inc47
-rw-r--r--build/Makefile.vty-reference.inc42
-rwxr-xr-xbuild/vty_reference_combine.sh25
6 files changed, 145 insertions, 53 deletions
diff --git a/build/Makefile.asciidoc.inc b/build/Makefile.asciidoc.inc
index e088624..a28a5bb 100644
--- a/build/Makefile.asciidoc.inc
+++ b/build/Makefile.asciidoc.inc
@@ -1,19 +1,38 @@
+# USAGE:
+#
+# - define 'TOPDIR' to point at the git root,
+# - define in 'ASCIIDOC' all root .adoc files,
+# - optionally define in 'ASCIIDOC_DEPS' all dependencies common to all .adocs,
+# - include this file,
+# - optionally define further dependencies for individual .pdf targets.
+#
+# e.g.
+#
+# TOPDIR = ..
+# ASCIIDOC = osmo_yada.adoc osmo_moo.adoc
+# ASCIIDOC_DEPS = for_all/*.adoc
+# include $(TOPDIR)/build/Makefile.asciidoc.inc
+# osmo_yada.pdf: yada/*.adoc yada/*.msc
+
BUILDDIR = $(TOPDIR)/build
GIT_VERSION := $(shell git describe --abbrev=4 --dirty --always --tags)
GIT_DATE := $(shell $(TOPDIR)/build/unix-time-to-fmt.py `git log -n 1 "--pretty=%at" ../.`)
# prepend the document name with the version numbe suffix
-#DOCS_VER = $(foreach P, $(ASCIIDOCS), $(P)-v$(shell xmllint --recover --xpath "//revnumber[position()=last()]/text()" $(P)-docinfo.xml 2>/dev/null))
+#DOCS_VER = $(foreach P, $(ASCIIDOC_NAME), $(P)-v$(shell xmllint --recover --xpath "//revnumber[position()=last()]/text()" $(P)-docinfo.xml 2>/dev/null))
#PDFS = $(DOCS_VER:%=%.pdf)
# generate list of PDFs that we're supposed to render
-ASCIIDOCPDFS = $(ASCIIDOCS:%=%.pdf)
-ASCIIDOC_CHECKS = $(ASCIIDOCS:%=%.check)
+ASCIIDOC_NAME = $(patsubst %.adoc,%,$(ASCIIDOC))
+ASCIIDOC_PDF = $(ASCIIDOC_NAME:%=%.pdf)
+ASCIIDOC_CHECKS = $(ASCIIDOC_NAME:%=%.check)
ASCIIDOCSTYLE ?= $(BUILDDIR)/custom-dblatex.sty
-cleanfiles += $(ASCIIDOCPDFS)
+CLEAN_FILES += $(ASCIIDOC_NAME:%=%__*.png) $(ASCIIDOC_NAME:%=%__*.svg) $(ASCIIDOC_CHECKS)
+CLEAN_FILES += $(ASCIIDOC_PDF)
+UPLOAD_FILES += $(ASCIIDOC_PDF)
ASCIIDOC_OPTS := -f $(BUILDDIR)/mscgen-filter.conf -f $(BUILDDIR)/diag-filter.conf -f $(BUILDDIR)/docinfo-releaseinfo.conf -f $(BUILDDIR)/python2-filter.conf
DBLATEX_OPTS := -s $(ASCIIDOCSTYLE) -P draft.mode=yes -P draft.watermark=0
@@ -27,9 +46,13 @@ endif
A2X_OPTS := -L --asciidoc-opts="$(ASCIIDOC_OPTS)" --dblatex-opts="$(DBLATEX_OPTS)" -a docinfo -a revnumber="$(REVNUMBER)" -a revdate="$(GIT_DATE)"
-all: $(ASCIIDOCPDFS)
+all: $(ASCIIDOC_PDF)
-$(ASCIIDOCPDFS): %.pdf: %.adoc %-docinfo.xml $(ASCIIDOCSTYLE) $(TOPDIR)/common/chapters/*.adoc
+$(ASCIIDOC_PDF): %.pdf: %.adoc %-docinfo.xml \
+ $(ASCIIDOC_DEPS) \
+ $(ASCIIDOCSTYLE) \
+ $(TOPDIR)/common/*/*.adoc \
+ $(TOPDIR)/common/images/*
@test -n "$(BUILD_RELEASE)" && echo -e "\n\n\
NOTE: TO REMOVE DRAFT MODE, YOU NEED TO EDIT build/custom-dblatex.sty\n\
and remove three lines starting with '% \"DRAFT\" on first page'\n" \
diff --git a/build/Makefile.common.inc b/build/Makefile.common.inc
new file mode 100644
index 0000000..e624b5f
--- /dev/null
+++ b/build/Makefile.common.inc
@@ -0,0 +1,14 @@
+# Usage:
+#
+# Other makefiles like Makefile.asciidoc.inc and Makefile.vty-reference.inc add
+# entries to UPLOAD_FILES and CLEAN_FILES.
+#
+# Include this file at the end to have 'upload' and 'clean' targets.
+
+UPLOAD_PATH ?= generic@sysmocom-downloads:documents
+
+upload: $(UPLOAD_FILES)
+ rsync -avz $(UPLOAD_FILES) $(UPLOAD_PATH)/
+
+clean:
+ -rm -rf $(CLEAN_FILES)
diff --git a/build/Makefile.docbook.inc b/build/Makefile.docbook.inc
new file mode 100644
index 0000000..70dfafa
--- /dev/null
+++ b/build/Makefile.docbook.inc
@@ -0,0 +1,35 @@
+# USAGE:
+#
+# - define 'TOPDIR' to point at the git root,
+# - define in 'DOCBOOKS' all root .xml files,
+# - optionally define in 'DOCBOOKS_DEPS' all dependencies common to all .xmls,
+# - include this file,
+# - optionally define further dependencies for individual .pdf targets.
+#
+# e.g.
+#
+# TOPDIR = ..
+# DOCBOOKS = osmo_yada.xml osmo_moo.xml
+# ASCIIDOC_DEPS = for_all/*.xml
+# include $(TOPDIR)/build/Makefile.docbook.inc
+# osmo_yada.pdf: yada/*.xml
+#
+# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
+# Makefile from BitBake/OpenEmbedded manuals, edited.
+
+DOCBOOKS_PDF = $(patsubst %.xml,%.pdf,$(DOCBOOKS))
+lint = $(patsubst %.xml,%.lint,$(DOCBOOKS))
+
+CLEAN_FILES += $(DOCBOOKS_PDF) $(lint)
+UPLOAD_FILES += $(DOCBOOKS_PDF)
+
+all: $(DOCBOOKS_PDF)
+
+# Lint the file
+%.xml-lint: %.xml
+ xmllint --xinclude --postvalid --noout $<
+
+# Create a PDF file and lint it before
+%.pdf: %.xml %.xml-lint $(DOCBOOKS_DEPS)
+ dblatex $(dblatex_quiet) -P draft.mode=no $<
+
diff --git a/build/Makefile.inc b/build/Makefile.inc
deleted file mode 100644
index 3905cb0..0000000
--- a/build/Makefile.inc
+++ /dev/null
@@ -1,47 +0,0 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
-
-LIBOSMO_DIR ?= ~/source/gsm/libosmocore
-MERGE_DOC := $(LIBOSMO_DIR)/doc/vty/merge_doc.xsl
-UPLOAD_PATH ?= generic@sysmocom-downloads:documents
-
-pdfs = $(patsubst %.xml,%.pdf,$(manuals))
-lint = $(patsubst %.xml,%.xml-lint,$(manuals))
-
-#cleanfiles = $(foreach i,$(types),$(topdir)/$(i))
-cleanfiles += $(pdfs) $(lint)
-
-ifdef DEBUG
-dblatex_quiet =
-define command
- $(1)
-endef
-else
-dblatex_quiet = -q
-define command
- @echo $(2) $(3)
- @$(1)
-endef
-endif
-
-all: $(types)
-
-
-$(types): FORCE
-
-
-pdf: $(pdfs) $(manuals)
-
-
-# Lint the file
-%.xml-lint: %.xml FORCE
- $(call command,xmllint --xinclude --postvalid --noout $<,XMLLINT,$<)
-
-# Create a PDF file and lint it before
-%.pdf: %.xml %.xml-lint $(EXTRA_DEPS) FORCE
- $(call command,dblatex $(dblatex_quiet) -P draft.mode=no $<,DBLATEX,$<)
-
-upload: $(pdfs) $(ASCIIDOCPDFS)
- rsync -avz $(pdfs) $(ASCIIDOCPDFS) $(UPLOAD_PATH)/
-
-FORCE:
diff --git a/build/Makefile.vty-reference.inc b/build/Makefile.vty-reference.inc
new file mode 100644
index 0000000..baf9cf5
--- /dev/null
+++ b/build/Makefile.vty-reference.inc
@@ -0,0 +1,42 @@
+# Usage:
+# Have files:
+# - osmoyada-vty-reference.xml
+# A docbook root XML including a &chapter-vty; reference.
+# - vty/*additions*.xml
+# Manual additions to specific VTY nodes, any number of files.
+# - vty/*_reference.xml
+# Export from VTY 'show online-help', exactly one file.
+#
+# In your Makefile,
+# - define 'TOPDIR' to point at the git root,
+# - define the (single) name of the vty-reference source in VTY_REFERENCE,
+# - include this file.
+#
+# e.g.
+#
+# TOPDIR = ..
+# VTY_REFERENCE = osmofoo-vty-reference
+# include $(TOPDIR)/build/Makefile.vty-reference.inc
+#
+# This uses the Makefile.docbook.inc, you should not mix uses of
+# Makefile.vty-reference.inc and Makefile.docbook.inc.
+
+DOCBOOKS = $(VTY_REFERENCE)
+DOCBOOKS_DEPS = generated/docbook_vty.xml
+include $(TOPDIR)/build/Makefile.docbook.inc
+
+LIBOSMO_DIR ?= ~/source/gsm/libosmocore
+MERGE_DOC = $(LIBOSMO_DIR)/doc/vty/merge_doc.xsl
+
+CLEAN_FILES += generated
+
+generated/docbook_vty.xml: \
+ vty/*xml \
+ $(TOPDIR)/common/vty_additions.xml \
+ $(TOPDIR)/common/chapters/vty.xml \
+ $(TOPDIR)/vty_reference.xsl
+ $(TOPDIR)/build/vty_reference_combine.sh "$(MERGE_DOC)" \
+ $(TOPDIR)/common/vty_additions.xml \
+ vty/*additions*.xml
+ xsltproc $(TOPDIR)/vty_reference.xsl generated/combined.xml \
+ > generated/docbook_vty.xml
diff --git a/build/vty_reference_combine.sh b/build/vty_reference_combine.sh
new file mode 100755
index 0000000..be234a7
--- /dev/null
+++ b/build/vty_reference_combine.sh
@@ -0,0 +1,25 @@
+#!/bin/sh
+set -e
+
+# the first argument should point at libosmocore/doc/vty/merge_doc.xsl
+MERGE_DOC="$1"
+shift
+
+combined="generated/combined.xml"
+combine_src="generated/combine_src.xml"
+
+reference="vty/*reference.xml"
+test "$(ls -1 $reference | wc -l)" = "1"
+
+set -x
+mkdir -p generated
+cp $reference "$combined"
+
+while [ -n "$1" ]; do
+ addition="$(realpath "$1")"
+ shift
+ mv "$combined" "$combine_src"
+ xsltproc -o "$combined" \
+ --stringparam with "$addition" \
+ "$MERGE_DOC" "$combine_src"
+done