Skip to content

Commit

Permalink
docs: updated docs for new cli setup
Browse files Browse the repository at this point in the history
  • Loading branch information
arctic-hen7 committed Jul 18, 2022
1 parent 085cd9b commit eba6cab
Show file tree
Hide file tree
Showing 5 changed files with 11 additions and 20 deletions.
4 changes: 3 additions & 1 deletion docs/next/en-US/core-principles.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,4 +65,6 @@ The upshot of all this is that Perseus is actually creating two separate entrypo

Why do you need to know all this? Because it makes it much easier to understand how to expand your app's capabilities, and it demystifies those macros a bit. Also, it shows that you can actually avoid them entirely if you want to! (Sycamore also has a [builder API](https://sycamore-rs.netlify.app/docs/basics/view#builder-syntax) that you can use to avoid their `view! { .. }` macro too, if you really want.)

One more thing to briefly note is about the `target_wasm/` directory, which is created alongside `target/` (but workspaces are *not* respected yet). As you might have inferred, the purpose of this is to provide a separate compilation space for Wasm code, which is used under the hood by the CLI whenever it builds your app to Wasm. The reason for this is so that we can build the engine and the browser sides in parallel. With only one `target/` directory, Cargo would make us wait until one had completed before starting the other, which slows down compilation. In testing, there tends to be a significant reduction in compilation times as a result of this separation of targets.
One more thing to briefly note is about the `dist/target_wasm/` and `dist/target_engine/` directories. As you might have inferred, the purpose of this is to provide a separate compilation space for Wasm code, which is used under the hood by the CLI whenever it builds your app to Wasm. The reason for this is so that we can build the engine and the browser sides in parallel. With only one `target/` directory, Cargo would make us wait until one had completed before starting the other, which slows down compilation. In testing, there tends to be a significant reduction in compilation times as a result of this separation of targets.

Finally, note that the Perseus CLI will automatically install the `wasm-bindgen` and `wasm-opt` CLIs in a system-wide cache (see [here](https://docs.rs/directories/latest/directories/struct.ProjectDirs.html#method.cache_dir) for how that's calculated), or in `dist/tools/` if that fails (there's an option to ensure the local cache is used as well, which you might want to set for more reproducible builds).
11 changes: 0 additions & 11 deletions docs/next/en-US/getting-started/first-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,6 @@ The second is `[target.'cfg(not(target_arch = "wasm32"))'.dependencies]`, which

The third section is exactly the same as the previous, just without that `not(...)`, so this one defines dependencies that we use in the browser only. We've put `wasm-bindgen` here, which we could compile on the server, but it would be a little pointless, since Perseus only uses it behind the scenes in making your app work in the browser. (This is needed for a macro that a Perseus macro defines, which is why you have to import it yourself.)

Now we've got some really weird stuff, that you may not have seen before even if you've been working with Rust for a while. The next two sections, `[lib]` and `[bin]`, declare that `src/lib.rs` is both a binary *and* a library. What does that mean? Well, a library is something that exposes some functions, and that's what Wasm expects. But the engine needs a binary to not just expose code, but to run it as well. Conveniently, you can define these in the same place, and you can then annoy Cargo a little by telling it to treat `lib.rs` as both a binary and a library. This will print a little warning at the top of every `cargo` command you run in this directory, but there's no actual problem here.

*Note: this solution isn't ideal, and the situation of this will be improved by the time v0.4.0 goes stable. The aim is to get Wasm to work with a binary rather than a library, which requires changing several things in the CLI.*

The only other thing of note here is `crate-type` under the `[lib]` section, which makes your library compatible with Wasm. Unfortunately, Perseus has basically no control over the fact that that's required, and we'd like it to not be necessary too!

So, to summarize, there's a bunch of weird stuff in `Cargo.toml` for every Perseus app, but you usually don't have to care about it too much!

</details>

Next, we can get on with the app's actual code! Head over to `src/lib.rs` and put the following inside:
Expand Down Expand Up @@ -64,7 +56,6 @@ With that all out of the way, add the following to `.gitignore`:

```gitignore
dist/
target_wasm
```

That just tells Git not to pay any attention to the build artifacts that Perseus is about to create. Now run this command:
Expand All @@ -82,5 +73,3 @@ Now, try updating that `Hello World!` message to be a little more like the first
Now stop that command with `Ctrl+C` and run `perseus deploy` instead. This will take a very long time, but it will produce a `pkg/` directory that you could put on a real-world server, and it would be completely ready to serve your brand-new app! Because this app is so simple, you could even use `perseus deploy -e` instead to just produce a bunch of flat files that you could host from anywhere without needing a proper server.

All this has just scratched the surface of what's possible with Perseus, and there's so much more to learn! The next big things are about understanding some of the core principles behind Perseus, which should help you to understand why any of what you just did actually worked.

*Note: next time you make a Perseus app, you can speed up the boilerplate with `perseus new`, which sets up everything you need straight away!*
2 changes: 2 additions & 0 deletions docs/next/en-US/getting-started/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,4 +27,6 @@ cd my-app

This will create a new directory called `my-app/` in your current directory, setting it up for a new Perseus project. If you want to move this directory somewhere else, you can do that as usual, everything's self-contained.

Note that any `perseus` command will also install the `wasm32-unknown-unknown` target if you have `rustup` available to do so, since you need it for developing with Perseus. Also note that the Perseus CLI used to have some other dependencies, namely `wasm-pack`, but these are now all inbuilt, and will be automatically installed and managed for you!

You can run `perseus serve -w` now if you want to see the placeholder app, or you can move ahead to the next section to get your feet wet.
6 changes: 2 additions & 4 deletions docs/next/en-US/reference/compilation-times.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,8 @@ From here, we get a little more radical. There's something called [Cranelift](),

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`.
The easiest way to get Perseus to use this, instead of the usual `cargo`, is to set `--cargo-engine-path cargo-clif` on `perseus` (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`. Note that we only apply this to the engine, since there's no Cranelift support for compiling to Wasm yet. That doesn't matter too much though, since Perseus is internally target-gated enough that Wasm compilations tend to be pretty fast!

**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!

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%!
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%! (And this was deliberately on a fairly old laptop with other programs running in the background to mimic a realistic setup.)
8 changes: 4 additions & 4 deletions docs/next/en-US/tutorials/second-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ Note that this tutorial assumes you've already installed Rust and the Perseus CL

## Setup

We can create a new Rust project by going to some directory and running `cargo new --lib my-app`, which will create a folder called `my-app/` and set it up as a library. Then, you can pop in there and replace everything in `Cargo.toml` with the following:
We can create a new Perseus project by going to some directory and running `perseus new my-app`, which will create a folder called `my-app/` and set it up for Perseus. Then, you can pop in there and make sure `Cargo.toml` looks like the following:

```toml
{{#include ../../../examples/core/basic/Cargo.toml.example}}
```

This is almost identical to the [first app](:getting-started/first-app) we built, so we'll skip over further explanation here. Recall though that this structure of declaring engine-side and browser-side dependencies separately is a fairly standard pattern in Perseus, and remember that the section after `[lib]` is telling Cargo to treat `src/lib.rs` as both a library (for the browser) *and* a binary (for the engine).
This is almost identical to the [first app](:getting-started/first-app) we built, so we'll skip over further explanation here. Recall though that this structure of declaring engine-side and browser-side dependencies separately is a fairly standard pattern in Perseus.

Next, create some files and folders so that your project tree looks like this:

Expand All @@ -36,7 +36,7 @@ mod error_pages;
mod templates;
```

And then add the following to `src/templates/mod.rs` to declare the files in there to Cargo:
And then make `src/templates/mod.rs` look like the following to declare the files in there to Cargo:

```rust
{{#include ../../../examples/core/basic/src/templates/mod.rs}}
Expand All @@ -48,7 +48,7 @@ The reason these are `pub mod`s is so that we can access them from `lib.rs` easi

Let's jump right into the code of this app! We'll start with the index template, which will render the landing page of our site. The code for this is accordingly in `src/templates/index.rs`.

In `src/templates/index.rs`, dump the following code:
In `src/templates/index.rs`, dump the following code (replacing the auto-generated code):

```rust
{{#include ../../../examples/core/basic/src/templates/index.rs}}
Expand Down

0 comments on commit eba6cab

Please sign in to comment.