Skip to content

Commit

Permalink
docs: updated docs for cranelift and wasm-opt
Browse files Browse the repository at this point in the history
  • Loading branch information
arctic-hen7 committed Jul 9, 2022
1 parent 99f565f commit 7829c74
Show file tree
Hide file tree
Showing 2 changed files with 18 additions and 1 deletion.
12 changes: 11 additions & 1 deletion docs/next/en-US/reference/compilation-times.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,14 @@ The first step in addressing this is to figure out whether your app needs export

The next step is pretty trivial: `rustup override set nightly`. This command will set the default toolchain in your project (you have to run that command in your proejct directory) to `nightly`, which tends to nearly cut compile times in half! In general, the nightly compiler will be much faster than the stable one, because it uses all sorts of unstable features that improve compilation times. If you want maximum assurances though, switch back to the stable compiler before running `perseus deploy` so your production app is secured against any nightly compiler bugs (which do happen) and you get the best of both worlds.

From here, we get a little more radical.
From here, we get a little more radical. There's something called [Cranelift](), a compiler backend that can be used [for Rust]() to speed up development compilation times. Of course, the sacrifice here is runtime speed, but as long as you build with the usual compiler for production, you again get the best of both worlds. To set this up, you'll need to download the latest version of [this project](https://github.com/bjorn3/rustc_codegen_cranelift) from [here](https://github.com/bjorn3/rustc_codegen_cranelift/actions?query=branch%3Amaster+event%3Apush+is%3Asuccess) (click on the most recent action run, and then download the appropriate artifact). Then, unzip that (twice, there's a nested zip folder) and you'll get a `build/` folder, which you can put anywhere on your system. Then, add the contents of that (which should contain `cargo-clif` and `rustc-clif`) to your system's `PATH` (tutorial [for Windows](https://stackoverflow.com/a/44272417), and [for Linux/MacOS](https://linuxize.com/post/how-to-add-directory-to-path-in-linux/)).

This comment has been minimized.

Copy link
@bjorn3

bjorn3 Apr 10, 2023

Since a couple of weeks I'm now releasing the lastest version on the master branch at https://github.com/bjorn3/rustc_codegen_cranelift/releases/tag/dev This saves a click and ensures that only the latest version that passes all tests is picked. In addition it should work even if you aren't logged in on github, unlike the GHA artifacts download links.


With that done, any new shell (you may have to log out and back in again) will have `cargo-clif` supported as a command! You can verify this by confirming that `cargo-clif -h` results in a help page being printed. This binary acts as a drop-in replacement for `cargo`, using the Cranelift backend instead. Note that you should only ever use this for development, it's not suitable for production, where you should use the normal `cargo` instead.

The easiest way to get Perseus to use this, instead of the usual `cargo`, is to set `PERSEUS_CARGO_PATH=cargo-clif` (you might do this for a single command, or you might add it to an initialization script to run on all `perseus` commands). With that done, you can run `perseus export -w`/`perseus serve -w`, and, after a while of waiting, you should find your app built! Note that this will take a while the first time because Cranelift has to rebuild everything built with the usual `cargo`.

**Remember:** do NOT use `cargo-clif` in production!

*Note:* currently, `PERSEUS_CARGO_PATH` does not take effect in Wasm builds, due to an upstream issue in `wasm-pack`. In future, this will be supported, and compile times should be able to be shortened even further!

This comment has been minimized.

Copy link
@bjorn3

bjorn3 Apr 10, 2023

Cranelift currently doesn't have a WASM backend, so unfortunately you will have to keep using the LLVM backend for WASM builds if/until WASM support is implemented in Cranelift.


After applying all the optimizations herein, a testing benchmark of measuring the time taken to run `perseus build` with the bleeding-edge version of the CLI in development mode on the `basic` example, changing a hardcoded state property, went from taking 28 seconds with the stable compiler and no target directory separation to just 7 seconds, when Cranelift and nightly were used along with the target directory separation now inbuilt into Perseus. In other words, you can cut Perseus' compile times by 75%!

This comment has been minimized.

Copy link
@bjorn3

bjorn3 Apr 10, 2023

That is impressive! For pretty much every project I tested the win was more like 30% to max 50%.

This comment has been minimized.

Copy link
@arctic-hen7

arctic-hen7 Apr 27, 2023

Author Member

No doubt hardware-dependent, I think the benefits are slightly less on more modern processors than the one I tested when I wrote that (although that could also be down to improvements in stable Rust), but feel free to cite us as an example of how good your project is if you'd like to, it's been fantastic for Perseus!

7 changes: 7 additions & 0 deletions docs/next/en-US/reference/deploying.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,4 +34,11 @@ To make this work, you should also add the following to your `Cargo.toml` under
wee_alloc = "0.4"
```

Finally, for another small cut to bundle sizes, you can set `wasm-opt`, a tool that `wasm-pack` runs automatically (and the Perseus CLI runs `wasm-pack`) to optimize for size by adding the following to your `Cargo.toml`:

```toml
[package.metadata.wasm-pack.profile.release]
wasm-opt = [ "-Oz" ]
```

You can find more information about optimizing Wasm bundle sizes [here](https://rustwasm.github.io/book/reference/code-size.html#optimizing-builds-for-code-size).

0 comments on commit 7829c74

Please sign in to comment.