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`. 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 The ISLE compiler is built as a build-dependency, and the build script then
source files that went into building a given ISLE-generated Rust file. If the uses it to compile ISLE source to generated Rust code. In other words, the ISLE
hashes of these files on disk don't match the hashes in the manifest, then the compiler behaves as an additional compile step, and ISLE source is rebuilt just
ISLE-generated Rust file is stale and needs to be rebuilt. In this case, the like any Rust source would be. Nothing special needs to be done when editing
`build.rs` will report a build error. This way, downstream crates that use ISLE.
Cranelift don't need to build ISLE, and get fewer transitive dependencies and
faster build times.
To intentionally rebuild ISLE-generated Rust files, use the `rebuild-isle` Cargo Sometimes, it's desirable to see what code is actually generated. By default,
feature with `cranelift-codegen`: 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 ```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 This will place the ISLE source in `cranelift/codegen/isle_generated_code/`,
create the new versions of the ISLE-generated Rust files and update the manifest where you can inspect it, debug by setting breakpoints in it, etc. Note that if
files. 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 Additionally, the `cranelift-codegen-meta` crate will automatically generate
ISLE `extern` declarations and helpers for working with CLIF. The code that does 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 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? ## 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 * `cranelift/codegen/src/prelude.isle`: Common definitions and declarations for
ISLE. This gets included in every ISLE compilation. ISLE. This gets included in every ISLE compilation.
* `cranelift/codegen/src/clif.isle`: Auto-generated declarations and helpers for * `target/.../out/clif.isle`: Auto-generated declarations and helpers for
working with CLIF inside ISLE. Generated by `cranelift/codegen/build.rs` when working with CLIF inside ISLE. Generated by `cranelift/codegen/build.rs`.
the `rebuild-isle` feature is enabled. This gets included in every ISLE This gets included in every ISLE compilation.
compilation.
* `cranelift/codegen/src/machinst/isle.rs`: Common Rust code for gluing * `cranelift/codegen/src/machinst/isle.rs`: Common Rust code for gluing
ISLE-generated code into a target architecture's backend. Contains 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 for this ISA. Contains implementations of ISA-specific `extern` helpers
declared in ISLE. 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 ## Gluing ISLE's generated code into Cranelift
Each ISA-specific, ISLE-generated file is generic over a `Context` trait that Each ISA-specific, ISLE-generated file is generic over a `Context` trait that