Stream: git-wasmtime

Topic: wasmtime / issue #4135 Cranelift: modernize documentation

Wasmtime GitHub notifications bot (May 11 2022 at 00:08):

cfallin opened issue #4135:

We should update our documentation in cranelift/docs at least in the following ways:

• We should make a pass to ensure that outdated concepts related to the old backend framework, like encodings and recipes, are removed;
• We should fill out documentation about the new backend framework's architecture, beyond the doc-comments in the source (but likely borrowing from them);
• We should provide more "purpose-directed guides":
  • How to add a new backend (#4126);
  • How to add a new instruction to CLIF;
  • How to add a new instruction to a machine backend;
  • How to add a new lowering from CLIF to a machine backend;
  • Strategies to debug codegen issues (minimization, diffing output, using "optimization fuel" (#4134)).

Wasmtime GitHub notifications bot (May 11 2022 at 00:08):

cfallin labeled issue #4135:

We should update our documentation in cranelift/docs at least in the following ways:

• We should make a pass to ensure that outdated concepts related to the old backend framework, like encodings and recipes, are removed;
• We should fill out documentation about the new backend framework's architecture, beyond the doc-comments in the source (but likely borrowing from them);
• We should provide more "purpose-directed guides":
  • How to add a new backend (#4126);
  • How to add a new instruction to CLIF;
  • How to add a new instruction to a machine backend;
  • How to add a new lowering from CLIF to a machine backend;
  • Strategies to debug codegen issues (minimization, diffing output, using "optimization fuel" (#4134)).

Wasmtime GitHub notifications bot (May 11 2022 at 00:08):

cfallin labeled issue #4135:

We should update our documentation in cranelift/docs at least in the following ways:

• We should make a pass to ensure that outdated concepts related to the old backend framework, like encodings and recipes, are removed;
• We should fill out documentation about the new backend framework's architecture, beyond the doc-comments in the source (but likely borrowing from them);
• We should provide more "purpose-directed guides":
  • How to add a new backend (#4126);
  • How to add a new instruction to CLIF;
  • How to add a new instruction to a machine backend;
  • How to add a new lowering from CLIF to a machine backend;
  • Strategies to debug codegen issues (minimization, diffing output, using "optimization fuel" (#4134)).

Wasmtime GitHub notifications bot (May 11 2022 at 00:08):

cfallin labeled issue #4135:

We should update our documentation in cranelift/docs at least in the following ways:

• We should make a pass to ensure that outdated concepts related to the old backend framework, like encodings and recipes, are removed;
• We should fill out documentation about the new backend framework's architecture, beyond the doc-comments in the source (but likely borrowing from them);
• We should provide more "purpose-directed guides":
  • How to add a new backend (#4126);
  • How to add a new instruction to CLIF;
  • How to add a new instruction to a machine backend;
  • How to add a new lowering from CLIF to a machine backend;
  • Strategies to debug codegen issues (minimization, diffing output, using "optimization fuel" (#4134)).

Wasmtime GitHub notifications bot (Jun 30 2026 at 01:32):

AnnieSld commented on issue #4135:

Good afternoon, while reading through the Cranelift documentation, I noticed that several guides no longer matched the current implementation. I updated the documentation to reflect the current codebase.

The changes include:

• backend-architecture.md: updated the description of the CLIF to VCode to binary pipeline and documented the current roles of ISLE, regalloc2, and MachInst.

• add-new-backend.md: updated outdated function signatures, file names, PRegSet usage, and MachInst trait methods.

• add-clif-instruction.md: corrected the instruction format API, builder methods, generated file names, and interpreter support.

• add-machine-instruction.md: fixed register access in emit(), corrected the ISLE file path, and updated the testing commands.

• debugging-codegen.md: replaced the deprecated CRANELIFT_VERBOSE environment variable with RUST_LOG, updated the clif-util commands, and corrected the chaos mode instructions.

• testing.md: replaced the deprecated test legalizer command with test compile, updated the RISC-V flag, and corrected the CRANELIFT_TEST_BLESS environment variable.

• index.md: refreshed the guide descriptions and restored the missing link to isle-integration.md.
  compare-llvm.md: updated the description of the current compilation pipeline.

Would a PR with these changes be welcome?

Wasmtime GitHub notifications bot (Jun 30 2026 at 01:53):

AnnieSld edited a comment on issue #4135:

While reviewing the Cranelift documentation I found several guides that
no longer matched the current codebase. This PR updates them to reflect
the current implementation.

New pages

• backend-architecture.md: Documents the CLIF-to-VCode-to-binary
  pipeline and the current roles of ISLE, regalloc2, and MachInst.

• add-new-backend.md: Step-by-step guide for creating a new ISA
  backend: directory layout, registration, settings, MachInst trait,
  PRegSet usage, ABI, ISLE lowering rules, and tests.

• add-clif-instruction.md: Guide for adding a new CLIF opcode:
  instruction format API, builder methods, generated file names,
  verifier checks, and interpreter support.

• add-machine-instruction.md: Guide for adding a machine
  instruction variant: register access in emit(), ISLE file paths,
  and testing commands.

• debugging-codegen.md: Guide for debugging the code generator
  using RUST_LOG, clif-util, and chaos mode.

Updates to existing pages

• testing.md: Replaced the deprecated test legalizer command
  with test compile, updated the RISC-V feature flag name, and
  corrected the CRANELIFT_TEST_BLESS environment variable.

• index.md: Refreshed guide descriptions and restored the missing
  link to isle-integration.md.

• compare-llvm.md: Updated the description of the current
  compilation pipeline.

Test plan

• [ ] cargo test -p cranelift-filetests passes
• [ ] cargo doc -p cranelift-codegen builds without warnings
  

Wasmtime GitHub notifications bot (Jun 30 2026 at 17:41):

AnnieSld edited a comment on issue #4135:

While reviewing the Cranelift documentation I found several guides that
no longer matched the current codebase.

New pages

• backend-architecture.md: Documents the CLIF-to-VCode-to-binary
  pipeline and the current roles of ISLE, regalloc2, and MachInst.

• add-new-backend.md: Step-by-step guide for creating a new ISA
  backend: directory layout, registration, settings, MachInst trait,
  PRegSet usage, ABI, ISLE lowering rules, and tests.

• add-clif-instruction.md: Guide for adding a new CLIF opcode:
  instruction format API, builder methods, generated file names,
  verifier checks, and interpreter support.

• add-machine-instruction.md: Guide for adding a machine
  instruction variant: register access in emit(), ISLE file paths,
  and testing commands.

• debugging-codegen.md: Guide for debugging the code generator
  using RUST_LOG, clif-util, and chaos mode.

Updates to existing pages

• testing.md: Replaced the deprecated test legalizer command
  with test compile, updated the RISC-V feature flag name, and
  corrected the CRANELIFT_TEST_BLESS environment variable.

• index.md: Refreshed guide descriptions and restored the missing
  link to isle-integration.md.

• compare-llvm.md: Updated the description of the current
  compilation pipeline.

Last updated: Jul 29 2026 at 05:03 UTC