# RISC-V Assembly Programmer's Manual: Building the Specification > The RISC-V Assembly Programmer's Manual is an AsciiDoctor specification repository for RISC-V assembly language guidance. It supports PDF and HTML builds through a Makefile, with Docker as the preferred execution environment when available. **riscv-non-isa/riscv-asm-manual** — RISC-V Assembly Programmer's Manual - Repository: https://github.com/riscv-non-isa/riscv-asm-manual - Website: https://riscv.atlassian.net/browse/RVG-11 - Stars: 1,655 · Forks: 256 - Language: Makefile - License: CC-BY-4.0 - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/riscv-non-isa-riscv-asm-manual ## Assembly Guidance Published from an AsciiDoctor Specification Repository This repository addresses document production rather than program execution. Its purpose is to hold and build the RISC-V Assembly Programmer's Manual, a specification intended for people working with RISC-V assembly language and for contributors preparing revisions to that guidance. The repository does not present itself as an assembler, emulator, debugger, or application programming interface. Its deliverables are specification source files and the PDF and HTML documents generated from them. The visible structure supports a documentation workflow. The `src/` directory contains the AsciiDoctor sources, while `build/` is designated for generated artifacts. A separate `docs-resources/` directory supplies specification resources, themes, and fonts through the submodule configuration in `.gitmodules`. The top-level Makefile names `riscv-asm.adoc` as the primary document and searches for it through `src/`. That boundary matters for evaluation. Engineers looking for a command-line assembler should not select this repository merely because its title includes RISC-V and assembly. Its actual unit of work is an editable manual, with source control, contribution rules, governance, maintainers, and a document build. The project is most relevant to specification readers, technical writers, reviewers, and toolchain engineers who need an assembly-language document. ## From src/riscv-asm.adoc to PDF and HTML Artifacts The Makefile converts the source document into two output formats. It derives `riscv-asm.pdf` and `riscv-asm.html` from the `riscv-asm.adoc` target, while a virtual source path locates the corresponding `.adoc` file under `src/`. The `build-docs` target depends on both generated files, and the public `build` target is the command documented for producing the documentation. When Docker is present, each recipe runs `riscvintl/riscv-docs-base-container-image:latest`. The repository mounts the current working directory at `/build`, selects `/build` as the container's working directory, and invokes the AsciiDoctor tools there. This keeps the rendering command and its tool environment inside the named container rather than relying directly on host-installed rendering packages. Without Docker, the same Makefile rules invoke `asciidoctor-pdf` and `asciidoctor` on the host. Both paths apply the same core options. The build traces processing, enables compressed output, records the value of `DATE` as `revdate`, loads `docs-resources/themes/risc-v_spec-pdf.yml`, and points PDF font handling at `docs-resources/fonts`. The destination is `build`, and `--failure-level=ERROR` treats processing errors as build failures. The required plugin is `asciidoctor-lists`. The Makefile exposes `XTRA_ADOC_OPTS`, but the README does not explain its intended operator-facing use. It also defines separate `build-container` and `build-no-container` targets, although the visible portion of the Makefile does not show their complete recipes. The documented `SKIP_DOCKER=true` condition can disable Docker command construction at Makefile configuration time, but the README does not provide a full tutorial for that override. ## Cloning Submodules and Building the Manual Start by cloning the repository with its submodules. The `--recurse-submodules` option initializes external content referenced by the repository during the clone, which matters because the build expects resources under `docs-resources/`. ```bash git clone --recurse-submodules https://github.com/riscv-non-isa/riscv-asm-manual.git ``` After cloning, enter the repository directory and invoke the documented build command: ```bash cd ./riscv-asm-manual && make build ``` The Makefile first checks whether the `docker` command exists. If it does, the README states that rendering occurs inside `riscvintl/riscv-docs-base-container-image:latest`. If it does not, rendering depends on the locally installed tools. The expected products are the PDF and HTML forms of `riscv-asm.adoc`, with generated files directed into `build/`. For a clone that did not initialize every nested dependency, the README also provides this recovery command: ```bash git clone --recurse-submodules https://github.com/riscv-non-isa/riscv-asm-manual.git && cd riscv-asm-manual && git submodule update --init --recursive ``` This is a complete clone and submodule initialization sequence, although it should not be run as a duplicate clone when the repository directory already exists. Generated files can be removed with the documented cleanup target: ```bash make clean ``` The README lists Make, asciiDoctor-pdf, and Docker as prerequisites, but its fallback description means the exact host requirements depend on whether Docker handles rendering. The README does not document operating-system-specific installation steps or troubleshooting for a missing theme, font, or plugin. ## Pre-Commit Validation for Specification Changes The repository defines local checks through `.pre-commit-config.yaml`, and the README states that GitHub CI enforces the configured checks. Contributors can install the hook interface with `pip3` and register the hooks in the cloned repository. Install the tool once on the system: ```bash pip3 install pre-commit ``` Then install the Git hook once inside the local repository: ```bash pre-commit install ``` After adding or changing configured checks, the README documents a full pass over repository files: ```bash pre-commit run --all-files ``` This workflow is separate from generating the manual. `make build` checks rendering dependencies and produces document artifacts, while `pre-commit run --all-files` exercises repository validation rules. The README does not enumerate the individual hooks in `.pre-commit-config.yaml`, so it cannot establish whether a particular edit will trigger formatting, link, or AsciiDoctor validation without inspection of that file. For contributors, the repository also provides `CONTRIBUTING.md`, `GOVERNANCE.md`, and `MAINTAINERS.md`. The README identifies `src/contributors.adoc` as the contributor list and `MAINTAINERS.md` as the maintainer list. Those files define participation and project organization, but the README does not reproduce their policies. Reviewing the named file is therefore necessary before making a contribution or interpreting approval rights. ## Build Boundaries, Failure Modes, and Wrong-Tool Cases The most immediate failure mode is an incomplete checkout. The specification depends on external resources under `docs-resources/`, and the README's explicit use of recursive submodule initialization indicates that a shallow or partial clone may leave the theme, fonts, or other specification inputs unavailable. A build error at that stage would reflect repository setup rather than an assembly-language issue. A second boundary is the split between Docker and host rendering. With Docker available, the Makefile uses `riscvintl/riscv-docs-base-container-image:latest`. Without Docker, the build falls back to tools installed on the host. Because the container tag is `latest`, the README does not pin that image to an immutable version. The documented path therefore favors environment consistency across systems, but the Makefile does not record an immutable container digest or explain potential changes introduced by future versions of that tag. The host path also has an incomplete dependency story. The README lists Make, asciiDoctor-pdf, and Docker, then says Docker is optional in practice. It does not give installation commands for `asciidoctor`, the `asciidoctor-lists` plugin, or the PDF fonts included through the repository. A reader without Docker therefore has to supply or verify those requirements independently. This project is the wrong tool for validating a particular assembly program. The README does not document a simulator invocation, linker workflow, assembler command, debugging interface, or executable test suite. Use the manual as specification guidance, then use an implementation-specific RISC-V toolchain for actual assembly and execution. The README also does not identify an assembler implementation or state whether generated PDFs are formally normative, so that boundary should be checked against the project's governance and publication process. ## Release History, Repository Activity, and License Ambiguity The repository is not archived. Its last push was on 2026-10-15. A release named `v0.0.1` was published on 2025-02-05. These records establish repository activity and an early versioned release, but they do not establish a release cadence, specification compatibility policy, or a tag-to-tag migration guide. Upgrading contributors may need to account for changes in the `latest` build container, AsciiDoctor tools, Git submodule revisions, and document sources. The Makefile exposes no documented pinned container version in its shown configuration. The repository also contains `CHANGELOG.md`, but the README does not summarize that file's contents, so no specific release change should be inferred from the release name alone. The license information requires particular care. The repository description identifies the project as CC-BY-4.0, and the README says the work is licensed under the Creative Commons Attribution 4.0 International License. In contrast, the Makefile header says CC-BY-SA-4.0 and includes the SPDX identifier `CC-BY-SA-4.0`. The repository also contains a `LICENSE` file, but the README does not reproduce its terms. That inconsistency is project-specific and should be resolved by inspecting `LICENSE` and seeking clarification through the documented governance process before redistributing adapted documentation or build scripts. This is a file-level reuse check, not a determination of legal rights. ## When riscv-asm-manual Differs from an Assembly Toolchain An assembly toolchain turns source text into machine-level artifacts and usually exposes commands for assembly, linking, disassembly, and debugging. This repository has a different workflow: it stores prose specifications in AsciiDoctor and renders them as documents. That difference affects installation, expected outputs, and troubleshooting. A toolchain user normally needs instructions for register syntax, directives, assembler versions, and invocation flags. The README for this repository does not provide such a tutorial. Its first concrete operations are Git operations, Docker detection, AsciiDoctor rendering, cleanup, and pre-commit validation. The actual assembly-language content belongs under `src/`, but the README does not identify a particular assembler or show an assembly program in its build instructions. This makes the repository complementary rather than competitive with an assembler, simulator, or linker. Engineers can consult the manual for language guidance, but they still need a RISC-V implementation to process code. Documentation contributors, by contrast, can use `make build` and `pre-commit run --all-files` as the concrete repository actions. Before adoption, determine whether the need is executable code tooling or maintained assembly specification content, because this project directly addresses only the latter. ## Conclusion Adopt this repository if you need to read, revise, or build the RISC-V Assembly Programmer's Manual from AsciiDoctor sources. Do not treat it as an assembler, simulator, or runnable code package. Verify first which license applies to the files you reuse because the README identifies CC-BY-4.0 while the Makefile header identifies CC-BY-SA-4.0, then confirm that your environment can run the selected Docker or host-tool build path. ## FAQ ### How do I build the RISC-V Assembly Programmer's Manual? Clone the repository with submodules, enter the repository directory, and run `make build`. The Makefile uses Docker when it is available and otherwise invokes the installed AsciiDoctor tools directly. ### Which files does the RISC-V Assembly Programmer's Manual build produce? The Makefile derives `riscv-asm.pdf` and `riscv-asm.html` from `riscv-asm.adoc`. Its rendering rules direct output into the `build` directory. ### What license applies to the RISC-V Assembly Programmer's Manual? The README identifies CC-BY-4.0, while the Makefile header identifies CC-BY-SA-4.0. The repository files do not resolve this discrepancy in the README, so `LICENSE` and the maintainers should be checked before reuse. ## Sources - [License: CC-BY-4.0](https://github.com/riscv-non-isa/riscv-asm-manual/blob/115-create-and-publish-a-v001-document-release/LICENSE) - [Project website](https://riscv.atlassian.net/browse/RVG-11) - [README](https://github.com/riscv-non-isa/riscv-asm-manual/blob/115-create-and-publish-a-v001-document-release/README.md) - [Releases](https://github.com/riscv-non-isa/riscv-asm-manual/releases) - [riscv-non-isa/riscv-asm-manual on GitHub](https://github.com/riscv-non-isa/riscv-asm-manual) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/riscv-non-isa-riscv-asm-manual