perf: split target directories for engine/server

This reduces compile-times significantly. Using nightly achieves further
cuts.
Also added docs on this.

.gitignore

@@ -3,3 +3,6 @@ Cargo.lock
 pkg/
 .tribble/
 .idea/
+
+target_wasm/
+dist/

docs/next/en-US/SUMMARY.md

@@ -11,6 +11,7 @@
 # Reference
 
 -   [Feature Discovery Terminal](/docs/features)
+-   [Improving Compilation Times](/docs/reference/compilation-times)
 -   [Live Reloading and HSR](/docs/reference/live-reloading-and-hsr)
 -   [Internationalization](/docs/reference/i18n)
 -   [Hydration](/docs/reference/hydration)

docs/next/en-US/core-principles.md

@@ -64,3 +64,5 @@ The key thing here is that you can easily use this more advanced structure to ga
 The upshot of all this is that Perseus is actually creating two separate entrypoints, one for the engine-side, and another for the browser-side. Crucially, both use the same `PerseusApp`, which is a universal way of defining your app's components, like templates. (You don't need to know this, but it actually does slightly different things on the browser and engine-sides itself to optimize your app.)
 
 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.

docs/next/en-US/getting-started/first-app.md

@@ -62,8 +62,9 @@ The last thing to note is the `ErrorPages`, which are an innovation of Perseus t
 
 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:

docs/next/en-US/reference/compilation-times.md

@@ -0,0 +1,9 @@
+# Improving Compilation Times
+
+As you may have noticed while using Perseus, compiling even very small changes to your app takes *a long time*. This is because Perseus has a significant amount of boilerplate to make all its features work essentially seamlessly, and because Rust generally takes quite a while to compile anything.
+
+The first step in addressing this is to figure out whether your app needs exporting or not. If not, then you should use `#[perseus::main_export]` rather than `#[perseus::main(...)]` in your `lib.rs`, and then you don't need to bring in a server integration, which should speed things up slightly. Notably, if you choose not to do this, there's no actual compile-time difference between `perseus export` and `perseus serve` (there used to be, back in the days of `.perseus/`, but those horrors are gone now). As a general rule, apps that *can* go to static files *should* go to static files, because they'll be faster. (It's also more easily possible to push static files to edge networks in deployment, which usually means faster load times for your users, depending on your hosting provider.)
+
+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.

examples/core/basic/.gitignore

@@ -1 +1,2 @@
 dist/
+target_wasm/

packages/perseus-cli/src/build.rs

@@ -111,9 +111,12 @@ pub fn build_internal(
             &wb_spinner,
             &wb_msg,
             if is_release {
-                vec![("RUSTFLAGS", &wasm_opt_flags)]
+                vec![
+                    ("CARGO_TARGET_DIR", "target_wasm"),
+                    ("RUSTFLAGS", &wasm_opt_flags),
+                ]
             } else {
-                vec![]
+                vec![("CARGO_TARGET_DIR", "target_wasm")]
             }
         )?);
 

packages/perseus-cli/src/export.rs

@@ -175,7 +175,7 @@ pub fn export_internal(
             &wb_target,
             &wb_spinner,
             &wb_msg,
-            vec![]
+            vec![("CARGO_TARGET_DIR", "target_wasm")]
         )?);
 
         Ok(0)