Build Infrastructure

Most RISC-V AsciiDoc documents use a Makefile to simplify the build process. For many documents, building the PDF and HTML flavors of the documents is as simple as going into the root directory of the document repository and typing make.

If Docker is already installed, the Makefile will invoke docker for the build process. Otherwise, it will build natively.

Source directory

In the Antora-based template, AsciiDoc source files live in modules/ROOT/pages/ rather than a flat src/ directory. The Makefile sets SRC_DIR := modules/ROOT/pages accordingly. The entry point for the PDF and HTML build is modules/ROOT/pages/spec-sample.adoc.

For a full description of the Antora directory structure and how to register your specification with the RISC-V documentation site, see [antora-structure].

As an author of a document, there are some conventions to be aware of:

  • The version, date, and state (draft, frozen, ratified) of the document should be specified in the .adoc file for that document via use of the :revnumber: and :revremark: keywords. An example usage is the following:

...
:revnumber: v0.5.1
:revremark: Draft
...

The version, date, and state (draft/frozen/ratified) of the specification should be specified only in the appropriate .adoc file in that repository. Some of the document repositories currently use an override in the Makefile, which can lead to the Makefile and the source document claiming different revision numbers, dates, and states.

  • When preparing to release a specification, it is incumbent to ensure the release is fully reproducible and self-documenting. To maintain this, please follow these steps for a release:

    1. Update the revision number :revnumber: in the source document to reflect the release number. This may contain any text (except carriage returns), like the following examples. There are no currently agreed-upon conventions for this, but please ensure your tag is meaningful for others.

      • v0.2

      • v0.2 (with draft of potential Zxyz additions)

      • 2025-01-26

      • v1.0.0-draft

      • v1.0.0-rc2

      • v1.0.0

      • v1.0.0-ratified

    2. Update the revision remark :revremark: in the source document to reflect the specification state. Some examples include:

      • This document is in development. Assume everything can change.

      • draft

      • This document is in draft state. Change should be expected.

      • This document is in stable state. Assume everything could change.

      • Frozen

      • Release candidate

      • Ratified

    3. If desired, update the date field :revdate: in the source document. If left unspecified, no date will be printed on the revision subtitle. The recommended date format is YYYY-MM-DD.

    4. Perform a make clean all to ensure everything builds cleanly.

    5. Use git tag <tag-name> to tag the repository so this build can be perfectly reproduced. Some example tag names:

      • riscv-Zxyz-v1.0.0-rc2

      • riscv-Zxyz-v20240411-draft

      • v0.4

      • v0.6-public-review

    6. Push your changes to upstream.

    7. Perform a make clean all to perform the official build off of the tag.

    8. Inspect the final PDF(s) to ensure the git SHA tag does not contain dirty as part of the name; if so, there are some uncommitted changes in your working repository. If not, then commit your changes and re-tag the release and try again.

    9. Publish the document appropriately.

  • To help ensure clean "coding" in the documentation, it can be useful to turn Asciidoctor’s error checking to the more strict --failure-level=WARNING such that any warnings during the document build process are considered fatal errors. This can be adjusted by altering the asciidoc invocation in the Makefile.

This document repository currently adheres to all of these conventions, and may be a useful starting point for other specifications.

ISA vs. non-ISA specifications

How a specification is authored and where it lives depends on whether it is an ISA or non-ISA specification.

ISA specifications

Extensions to the RISC-V Unprivileged or Privileged ISA are authored as chapters within a branch or fork of the riscv-isa-manual repository. The specification state and revision information are set within the relevant chapter file(s) in that branch, consistent with the conventions of the ISA manual.

Non-ISA specifications

All other RISC-V specifications are authored in their own autonomous GitHub repository, using the docs-spec-template as the starting point. The repository layout, build infrastructure, and GitHub Actions workflows are all provided by the template.

Specification lifecycle

RISC-V specifications progress through four defined states. The current state is set via the :revremark: attribute in the document header and is displayed on the cover page of every build. The canonical definitions of each state are maintained at riscv.org/spec-state.

Draft

The specification is under active development. Everything is subject to change. Use :revremark: This document is in the Development state or simply :revremark: Draft.

Stable

The specification is feature-complete but may still change in response to public review feedback. Use :revremark: Stable.

Frozen

The specification has completed public review. Only critical bug fixes are permitted. Implementations based on this version may proceed at the implementer’s risk. Use :revremark: Frozen.

Ratified

The specification has been formally ratified by RISC-V International. No further changes will be made to this version. Use :revremark: Ratified.

State advancement is manual

State advancement is not automated. No process or workflow automatically promotes a specification from one state to the next. Authors must update :revremark: in the source document by hand, following approval through the appropriate RISC-V governance process.

Non-ISA specifications: releasing a new state

For non-ISA specifications, each state transition should be accompanied by a corresponding GitHub release so the published PDF is permanently associated with that state. The build-pdf.yml GitHub Actions workflow supports this via a manual workflow_dispatch trigger.

To publish a release at a new state:

  1. Update :revremark: in modules/ROOT/pages/spec-sample.adoc to the new state.

  2. Update :revnumber: to the appropriate version string.

  3. Commit and push the changes.

  4. In GitHub, navigate to Actions → Create Specification Document → Run workflow.

  5. Select the matching revision_mark (Draft, Stable, Frozen, or Ratified).

  6. Set prerelease and draft flags as appropriate.

  7. Run the workflow — it will build the PDF, create a git tag, and publish a GitHub release.

The revision_mark selected in the workflow dispatch sets the REVMARK environment variable passed to make, which overrides :revremark: in the built PDF. Ensure the value you select matches what is set in the source document so the two are consistent.

ISA specifications: state within the ISA manual

For ISA specifications, the specification state is not tracked via a standalone GitHub release workflow. Instead, the state is reflected within the chapter(s) of the relevant ISA manual — either the Unprivileged or Privileged specification — in the branch of riscv-isa-manual where the author is working. The state and revision information should follow the conventions established within that repository and be consistent with the overall state of the ISA manual branch.