Repository navigation
Expand file tree
/
Copy pathMakefile
More file actions
192 lines (166 loc) · 7.15 KB
/
Copy pathMakefile
File metadata and controls
192 lines (166 loc) · 7.15 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
# Makefile for RISC-V Doc Template
#
# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
# International License. To view a copy of this license, visit
# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to
# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
#
# SPDX-License-Identifier: CC-BY-SA-4.0
#
# Description:
#
# This Makefile is designed to automate the process of building and packaging
# the Doc Template for RISC-V Extensions.
DOCS := \
spec-sample.adoc
# Spec short name used in ARC-compliant PDF filenames.
# Override in derived repos: e.g. SPEC_SHORT := Zifoo
SPEC_SHORT ?= $(basename $(firstword $(DOCS)))
DATE ?= $(shell date +%Y-%m-%d)
DATE_STAMP := $(subst -,,$(DATE))
VERSION ?= $(shell ./scripts/release-info.sh version)
VERSION_NUM := $(patsubst v%,%,$(VERSION))
# .docmode ("spec" default | "doc") -- see scripts/release-info.sh. "doc" is
# for non-ratified documentation repos (e.g. docs-dev-guide): it keeps the PDF
# and HTML targets but strips the ratification/phase surface below.
DOC_MODE ?= $(shell ./scripts/release-info.sh mode)
PHASE ?= $(shell ./scripts/release-info.sh phase "$(VERSION)")
PHASE_DISPLAY ?= $(shell ./scripts/release-info.sh display "$(VERSION)")
PHASE_NOTICE ?= $(shell ./scripts/release-info.sh notice "$(VERSION)")
REVMARK ?= $(shell ./scripts/release-info.sh revremark "$(VERSION)")
MILESTONE_ID ?= $(PHASE)
# In spec mode, pass the phase/milestone attributes through to asciidoctor so
# spec-sample.adoc's Document State preface and the title-page revremark
# render. In doc mode those are empty (see release-info.sh's neutralization),
# so instead pass a single doc-mode marker attribute: spec-sample.adoc and
# index.adoc key their ifdef::doc-mode[]/ifndef::doc-mode[] guards off its
# PRESENCE, not a blank value, which is what lets them drop those sections
# entirely rather than rendering them empty.
ifeq ($(DOC_MODE),doc)
PHASE_OPTS := -a doc-mode='doc'
else
PHASE_OPTS := -a phase='${PHASE}' \
-a phase_display='${PHASE_DISPLAY}' \
-a phase_notice='${PHASE_NOTICE}' \
-a milestone_id='${MILESTONE_ID}' \
-a revremark='${REVMARK}'
endif
DOCKER_IMG := riscvintl/riscv-docs-base-container-image:latest
DOCKER_BIN ?= docker
ifneq ($(SKIP_DOCKER),true)
DOCKER_IS_PODMAN = \
$(shell ! ${DOCKER_BIN} -v 2>&1 | grep podman >/dev/null ; echo $$?)
ifeq "$(DOCKER_IS_PODMAN)" "1"
DOCKER_VOL_SUFFIX = :z
endif
DOCKER_CMD := \
${DOCKER_BIN} run --rm \
-v ${PWD}:/build${DOCKER_VOL_SUFFIX} \
-w /build \
${DOCKER_IMG} \
/bin/sh -c
DOCKER_QUOTE := "
endif
SRC_DIR := src
BUILD_DIR := build
DOCS_PDF := $(DOCS:%.adoc=%.pdf)
DOCS_HTML := $(DOCS:%.adoc=%.html)
XTRA_ADOC_OPTS :=
ASCIIDOCTOR_PDF := asciidoctor-pdf
ASCIIDOCTOR_HTML := asciidoctor
OPTIONS := --trace \
-a compress \
-a mathematical-format=svg \
-a revnumber=${VERSION} \
-a revdate=${DATE} \
$(PHASE_OPTS) \
-a spec_short='${SPEC_SHORT}' \
-a pdf-fontsdir=docs-resources/fonts \
-a pdf-theme=docs-resources/themes/riscv-pdf.yml \
$(XTRA_ADOC_OPTS) \
-D build \
--failure-level=ERROR
REQUIRES := --require=asciidoctor-bibtex \
--require=asciidoctor-diagram \
--require=asciidoctor-lists \
--require=asciidoctor-mathematical \
--require=./scripts/cross-page-xrefs.rb
DOCS_RESOURCES_CONFIG := docs-resources/global-config.adoc
.PHONY: all build clean build-container build-no-container build-docs stamp-antora check-docs-resources
all: build
check-docs-resources:
@if [ ! -f "$(DOCS_RESOURCES_CONFIG)" ]; then \
echo "Notice: docs-resources submodule is missing or uninitialized."; \
if command -v git >/dev/null 2>&1 && [ -d .git ]; then \
echo "Automatically initializing git submodules..."; \
git submodule update --init --recursive || { \
echo "ERROR: Failed to update git submodules automatically."; \
echo "Please run manually: git submodule update --init --recursive"; \
exit 1; \
}; \
else \
echo "ERROR: Missing docs-resources directory and git is unavailable."; \
echo "Please clone submodules or run: git submodule update --init --recursive"; \
exit 1; \
fi; \
fi
# Stamp antora.yml with the current VERSION/DATE so the Antora HTML site version
# stays in EXACT lockstep with the ARC PDF (both derive from release-info.sh /
# the git tag). Run at release time -- e.g. `make stamp-antora VERSION=v0.8`.
# No Docker needed; edits antora.yml in place and must be committed.
stamp-antora:
./scripts/stamp-antora-version.sh "$(VERSION)" "$(DATE)"
build-docs: check-docs-resources $(DOCS_PDF) $(DOCS_HTML)
# ARC-compliant PDF name: <basename>-v<version>-<YYYYMMDD>.pdf, so every build
# (local or CI) emits a uniquely identifiable artifact.
ARC_PDF = $(1)-v$(VERSION_NUM)-$(DATE_STAMP).pdf
# ...but only a build off a clean vX.YY -- a tag, or an explicit VERSION= as CI
# passes -- is actually SUBMITTABLE. An untagged build resolves VERSION to
# <latest>-<sha> (release-info.sh), so its filename carries the sha and is a dev
# artifact. Report that honestly rather than asserting compliance it lacks.
ARC_EXACT := $(if $(findstring -,$(VERSION)),,yes)
vpath %.adoc $(SRC_DIR)
# AsciiDoctor writes the ARC name itself (-o is resolved relative to -D), rather
# than the build renaming build/<basename>.pdf afterwards. Inside the container
# build/ is created by root, so a host-side `mv` into it fails with EPERM on
# rootful Docker -- which is exactly how v0.61 shipped a non-compliant
# build/spec-sample.pdf while the log claimed the ARC name. Naming it at the
# source removes the failure mode instead of reporting it.
%.pdf: %.adoc
$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) -o $(call ARC_PDF,$*) $< $(DOCKER_QUOTE)
@test -f build/$(call ARC_PDF,$*) || { echo "ERROR: build/$(call ARC_PDF,$*) was not produced" >&2; exit 1; }
@if [ "$(DOC_MODE)" = "doc" ]; then \
echo "PDF: build/$(call ARC_PDF,$*)"; \
elif [ -n "$(ARC_EXACT)" ]; then \
echo "ARC submission PDF: build/$(call ARC_PDF,$*)"; \
else \
echo "Development PDF: build/$(call ARC_PDF,$*)"; \
echo " Built from an untagged commit ($(VERSION)) -- NOT an ARC submission artifact."; \
echo " Build from a v* tag, or run 'make VERSION=vX.YY', to produce one."; \
fi
%.html: %.adoc
$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
build:
@echo "Checking if Docker is available..."
@if command -v ${DOCKER_BIN} >/dev/null 2>&1 ; then \
echo "Docker is available, building inside Docker container..."; \
$(MAKE) build-container; \
else \
echo "Docker is not available, building without Docker..."; \
$(MAKE) build-no-container; \
fi
build-container:
@echo "Starting build inside Docker container..."
$(MAKE) build-docs
@echo "Build completed successfully inside Docker container."
build-no-container:
@echo "Starting build..."
$(MAKE) SKIP_DOCKER=true build-docs
@echo "Build completed successfully."
# Update docker image to latest
docker-pull-latest:
${DOCKER_BIN} pull ${DOCKER_IMG}
clean:
@echo "Cleaning up generated files..."
rm -rf $(BUILD_DIR)
@echo "Cleanup completed."