diff --git a/.github/workflows/build-check.yml b/.github/workflows/build-check.yml index b87bd0c9..ea08d861 100644 --- a/.github/workflows/build-check.yml +++ b/.github/workflows/build-check.yml @@ -72,6 +72,13 @@ jobs: run: cd wolfBoot && export PATH=$PATH:"/home/runner/work/documentation" && make html - name: wolfBoot pdf run: cd wolfBoot && export PATH=$PATH:"/home/runner/work/documentation" && make pdf + - name: Pin wolfTrust source for this build + run: | + ref=$(git ls-remote https://github.com/wolfSSL/wolfTrust.git refs/heads/main | cut -f1) + test -n "$ref" + echo "WOLFTRUST_REF=$ref" >> "$GITHUB_ENV" + - name: wolfTrust html and pdf + run: cd wolfTrust && export PATH=$PATH:"/home/runner/work/documentation" && make - name: wolfSentry html run: cd wolfSentry && export PATH=$PATH:"/home/runner/work/documentation" && make html - name: wolfSentry pdf diff --git a/Dockerfile b/Dockerfile index 018546d7..33c069e6 100644 --- a/Dockerfile +++ b/Dockerfile @@ -27,8 +27,9 @@ FROM builder AS wolfssl-stage1 ARG MANPATH ARG PDFFILE ARG V +ARG WOLFTRUST_REF=main WORKDIR /src/wolfssl/${MANPATH} -RUN make pdf V=${V} +RUN make pdf V=${V} WOLFTRUST_REF=${WOLFTRUST_REF} # Build wolfSSL HTML FROM wolfssl-stage1 AS wolfssl-stage2 @@ -36,7 +37,11 @@ ARG MANPATH ARG PDFFILE ARG V WORKDIR /src/wolfssl/${MANPATH} -RUN make html V=${V} +RUN if [ "${MANPATH}" = wolfTrust ]; then \ + WOLFTRUST_REF="$(git -C wolftrust rev-parse HEAD)" make html V=${V}; \ + else \ + make html V=${V}; \ + fi # Build both wolfSSL HTML and PDF FROM scratch AS manual diff --git a/Makefile b/Makefile index 5d0d3a72..56f1096a 100644 --- a/Makefile +++ b/Makefile @@ -4,9 +4,10 @@ ifeq ($(V),1) endif # Handy debugging trick: `DOCKER_CMD_EXTRA_ARGS="--progress=plain" make` to see all the output -DOCKER_CMD=DOCKER_BUILDKIT=1 docker build $(DOCKER_CMD_EXTRA_ARGS) -t doc_build --build-arg MANPATH=$(MANPATH) --build-arg PDFFILE=$(PDFFILE) --build-arg V=$(V) --target=manual --output=build -f Dockerfile . +WOLFTRUST_REF ?= main +DOCKER_CMD=DOCKER_BUILDKIT=1 docker build $(DOCKER_CMD_EXTRA_ARGS) -t doc_build --build-arg MANPATH=$(MANPATH) --build-arg PDFFILE=$(PDFFILE) --build-arg V=$(V) --build-arg WOLFTRUST_REF=$(WOLFTRUST_REF) --target=manual --output=build -f Dockerfile . -all: wolfssl wolfssh wolfboot wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm wolfhsm wolfengine wolfprovider fips-ready tuning porting faq fips-faq bc-migration +all: wolfssl wolfssh wolfboot wolftrust wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm wolfhsm wolfengine wolfprovider fips-ready tuning porting faq fips-faq bc-migration build: $(Q)mkdir -p build @@ -29,6 +30,12 @@ wolfboot: PDFFILE=wolfBoot-Manual.pdf wolfboot: build $(Q)$(DOCKER_CMD) +.PHONY: wolftrust +wolftrust: MANPATH=wolfTrust +wolftrust: PDFFILE=wolfTrust-Manual.pdf +wolftrust: build + $(Q)$(DOCKER_CMD) + .PHONY: wolfclu wolfclu: MANPATH=wolfCLU wolfclu: PDFFILE=wolfCLU-Manual.pdf diff --git a/README.md b/README.md index 62b0e65d..a38f4f7b 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ To build the documentation you will need Docker running on your system. In this * `make wolfssl` * `make wolfssh` * `make wolfboot` +* `make wolftrust` * `make wolfclu` * `make wolfcrypt-jni` * `make wolfmqtt` @@ -24,6 +25,13 @@ To build the documentation you will need Docker running on your system. In this * `make fips-ready` * `make bc-migration` +The wolfTrust target reads manual pages from `wolfSSL/wolfTrust` `main` by +default and prints the source commit used. Edit those pages in wolfTrust; this +repository holds only its build entry point and the shared rendering tools. +To rebuild from a specific commit, run `make wolftrust WOLFTRUST_REF=`. +For unmerged local changes, run `make WOLFTRUST_SOURCE=/path/to/wolfTrust` from +the `wolfTrust/` directory with the non-Docker build dependencies installed. + ## Contributing There is a [CONTRIBUTING.md](CONTRIBUTING.md) document which outlines how to add manuals to the tree. @@ -95,4 +103,3 @@ Then you can confirm the font cache includes the installed font files by 'fc-lis fc-list | grep NotoSansCJKjp ``` You will get the list of installed font files. - diff --git a/wolfTrust/.gitignore b/wolfTrust/.gitignore new file mode 100644 index 00000000..6dfc5123 --- /dev/null +++ b/wolfTrust/.gitignore @@ -0,0 +1,8 @@ +/build/ +/html/ +/src/ +/wolftrust/ +/mkdocs.yml +/header.txt +/manual.generated.mk +/wolfTrust-Manual.pdf diff --git a/wolfTrust/Makefile b/wolfTrust/Makefile new file mode 100644 index 00000000..7d4963da --- /dev/null +++ b/wolfTrust/Makefile @@ -0,0 +1,48 @@ +# The manual content and build adapter live in wolfSSL/wolfTrust. +WOLFTRUST_SOURCE ?= wolftrust +WOLFTRUST_REF ?= main +export WOLFTRUST_REF + +.DEFAULT_GOAL := all +.PHONY: all pdf html source +all: source + python3 "$(WOLFTRUST_SOURCE)/tools/docs_manual.py" build \ + --documentation-root .. --source-root "$(WOLFTRUST_SOURCE)" --target all + +source: + @set -eu; \ + if [ "$(WOLFTRUST_SOURCE)" = wolftrust ]; then \ + if [ -e wolftrust ]; then \ + if [ ! -e wolftrust/.git ]; then \ + echo 'wolftrust exists but is not a Git checkout' >&2; exit 1; \ + fi; \ + remote=$$(git -C wolftrust config --get remote.origin.url) || { \ + echo 'wolftrust has no origin remote' >&2; exit 1; \ + }; \ + if [ "$$remote" != https://github.com/wolfSSL/wolfTrust.git ]; then \ + echo "wolftrust origin is $$remote; expected https://github.com/wolfSSL/wolfTrust.git" >&2; exit 1; \ + fi; \ + if [ -n "$$(git -C wolftrust status --porcelain)" ]; then \ + echo 'wolftrust checkout has local changes; use WOLFTRUST_SOURCE for local edits' >&2; exit 1; \ + fi; \ + else \ + git init -q wolftrust; \ + git -C wolftrust remote add origin https://github.com/wolfSSL/wolfTrust.git; \ + fi; \ + ref=$$WOLFTRUST_REF; \ + case "$$ref" in ''|-*) echo 'WOLFTRUST_REF must be a commit, tag, or branch' >&2; exit 1;; esac; \ + if printf '%s' "$$ref" | grep -Eq '^[0-9a-f]{40}$$' && \ + git -C wolftrust cat-file -e "$$ref^{commit}" 2>/dev/null; then \ + git -C wolftrust checkout --detach "$$ref"; \ + else \ + git -C wolftrust fetch --depth 1 origin "$$ref"; \ + git -C wolftrust checkout --detach FETCH_HEAD; \ + fi; \ + echo "wolfTrust source: $$(git -C wolftrust rev-parse HEAD)"; \ + else \ + test -f "$(WOLFTRUST_SOURCE)/tools/docs_manual.py"; \ + fi + +pdf html: source + python3 "$(WOLFTRUST_SOURCE)/tools/docs_manual.py" build \ + --documentation-root .. --source-root "$(WOLFTRUST_SOURCE)" --target $@