T0b1/wasmtime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update Cranelift-ISLE integration docs to reflect no more checked-in code. (#4229)

Browse Source 
* Update Cranelift-ISLE integration docs to reflect no more checked-in code.

In #4143, we removed the checked-in-generated-code aspect of the ISLE
build process, in order to simplify the development cycle and reduce
errors. However, I failed to update the docs at the same time. This PR
fixes that. Supersedes #4228 (thanks @jlb6740 for noticing this issue!).

* fix typo
This commit is contained in:
Chris Fallin
2022-06-06 12:54:23 -07:00
committed by GitHub
parent 7ac1c53062
commit d8ba1ddc86
1 changed files with 26 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
cranelift/docs/isle-integration.md
View File

@@ -16,29 +16,38 @@ Documentation on the ISLE language itself can be found
The build integration is inside of `cranelift/codegen/build.rs`.
For regular builds, we check a manifest that records the file hashes of the ISLE
source files that went into building a given ISLE-generated Rust file. If the
hashes of these files on disk don't match the hashes in the manifest, then the
ISLE-generated Rust file is stale and needs to be rebuilt. In this case, the
`build.rs` will report a build error. This way, downstream crates that use
Cranelift don't need to build ISLE, and get fewer transitive dependencies and
faster build times.
The ISLE compiler is built as a build-dependency, and the build script then
uses it to compile ISLE source to generated Rust code. In other words, the ISLE
compiler behaves as an additional compile step, and ISLE source is rebuilt just
like any Rust source would be. Nothing special needs to be done when editing
ISLE.
To intentionally rebuild ISLE-generated Rust files, use the `rebuild-isle` Cargo
feature with `cranelift-codegen`:
Sometimes, it's desirable to see what code is actually generated. By default,
the generated code is placed in a Cargo-managed path in `target/`. If you want
to see the source instead, invoke Cargo with the optional feature
`isle-in-source-tree` as follows:
```shell
$ cargo check -p cranelift-codegen --features rebuild-isle
$ cargo check -p cranelift-codegen --features isle-in-source-tree
```
When this feature is active, we rerun the ISLE compiler on the ISLE sources to
create the new versions of the ISLE-generated Rust files and update the manifest
files.
This will place the ISLE source in `cranelift/codegen/isle_generated_code/`,
where you can inspect it, debug by setting breakpoints in it, etc. Note that if
you later build without this feature, the build system will require you to
delete the directory. This is to ensure that no out-of-date copies exist, which
could cause significant confusion.
If there are any errors during ISLE compilation (e.g., a type mismatch), you
will see a basic error message with a file, line number, and one-line error. To
see a more detailed output with context, `--features isle-errors` can be used.
This will leverage the `miette` error-reporting library to give pretty-printed
errors with source context.
Additionally, the `cranelift-codegen-meta` crate will automatically generate
ISLE `extern` declarations and helpers for working with CLIF. The code that does
this is defined inside `cranelift/codegen/meta/src/gen_inst.rs` and it creates
the `cranelift/codegen/src/clif.isle` file.
the `clif.isle` file in the `target/` output directory, which is subsequently
read by the ISLE compiler as part of its prologue.
## Where are the relevant files?
@@ -47,10 +56,9 @@ the `cranelift/codegen/src/clif.isle` file.
* `cranelift/codegen/src/prelude.isle`: Common definitions and declarations for
ISLE. This gets included in every ISLE compilation.
* `cranelift/codegen/src/clif.isle`: Auto-generated declarations and helpers for
working with CLIF inside ISLE. Generated by `cranelift/codegen/build.rs` when
the `rebuild-isle` feature is enabled. This gets included in every ISLE
compilation.
* `target/.../out/clif.isle`: Auto-generated declarations and helpers for
working with CLIF inside ISLE. Generated by `cranelift/codegen/build.rs`.
This gets included in every ISLE compilation.
* `cranelift/codegen/src/machinst/isle.rs`: Common Rust code for gluing
ISLE-generated code into a target architecture's backend. Contains
@@ -70,10 +78,6 @@ the `cranelift/codegen/src/clif.isle` file.
for this ISA. Contains implementations of ISA-specific `extern` helpers
declared in ISLE.
* `cranelift/codegen/src/isa/<arch>/lower/isle/generated_code.rs`: The
ISLE-generated Rust code to perform instruction and CLIF-to-`MachInst`
lowering for each target architecture.
## Gluing ISLE's generated code into Cranelift
Each ISA-specific, ISLE-generated file is generic over a `Context` trait that