Build Instructions

Using The Automatic Build Script

This guide assumes that you are already familiar with the command line and Bash syntax.

To build the project, open a new terminal in the folder containing "Cargo.TOML" and run this bash script; make sure to have RustUp installed.

./build.sh

That script will create a super-optimized WebAssembly binary, a tiny JS file along with a HTML file located in the ./pkg folder.
You can use a server with application/wasm mime type to run them.

Alternatively, you could follow the below guide for an in-depth explanation of each step.

---

Manual Building

Be aware that while the generality of these steps is identical between different different platforms; depending on your OS, a few modifications might be required.

The following sections will guide you through the building process.
(Copy and paste each code snippet into your terminal)

---

1. Downloading And Installing RustUp

RustUp is the official installer for Rust.

Toolchain requirements are minimal, you won't need anything beyond cargo and some of its additional components.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

---

2. Installing The Nightly Toolchain With WebAssembly Components

Rust installs the Stable toolchain by default. To enable Atomics and other features in later steps, we'll have to install the Nightly toolchain.

rustup toolchain install nightly

Since we are compiling to WebAssembly, we'll also need to install the appropriate target triple. In our case its WebAssembly (wasm32) that compiles anywhere (unknown) and runs anywhere (unknown) as well.

rustup +nightly target add wasm32-unknown-unknown

Next, we need to install rust's new linker that use's LLVM's LLD, this linker should make the compilation process less time consuming. it not only reduces the size of our produced binary, but also makes it faster. We will also need to install the standard library's source code as we need to re-compile it with additional features later.

rustup +nightly component add llvm-tools-preview rust-src

As of now, WebAssembly can not use DOM methods (such as console.log) directly, this will however be solved once WebIDL bindings proposals are merged. for now we will need a very small JavaScript file that only imports the method's we need and simply make a instance of the .wasm module, this is currently the most efficient and minimalistic solution.
wasm-bindgen-cli is the tool that will generate these bindings for us, it will also optimize our binary further and snip unneeded sections. be aware that neither RASM nor Oxidized-Skies depend on wasm-bindgen as a library.

cargo install wasm-bindgen-cli

---

3. Passing Necessary Flags To The Compiler

This environment variable will tell the compiler to enable Atomic instructions, shared memory support and other sorts of optimizations previously mentioned.

It also changes the default linker to the one we installed earlier.

export RUSTFLAGS="
    -C target-cpu=bleeding-edge
    -C target-feature=+atomics,+bulk-memory,+simd128
    -C linker=rust-lld
"

---

4. Cloning The Repository And Compiling

Now that the compiler is ready, we can begin the compilation process.
Cargo is both a package manager and build system for rust.

Clone the repository and navigate to the extracted folder containing "Cargo.TOML".

cargo +nightly build --target wasm32-unknown-unknown --release -Z build-std=core,std,panic_abort

The above command builds an optimized WebAssembly binary called "oxidized_skies.wasm" located in "./target/wasm32-unknown-unknown/release".

---

5. Packing Up.

Now we will generate JS bindings and snip the binary.

wasm-bindgen --target web --no-typescript --no-demangle --remove-producers-section --remove-name-section --out-dir pkg ./target/wasm32-unknown-unknown/release/oxidized_skies.wasm

We also need to move in the hand-written HTML file from ./src to the newly created ./pkg folder.

cp src/index.html pkg