window.Module = {};
fetchAndInstantiate("./factorial.wasm", {})
.then(mod => {
  Module.fact_str = function(n) {
    let outptr = mod.exports.fact_str(n);
    let result = copyCStr(Module, outptr);
    return result;
  };
})

// This method reaches into the WebAssembly memory map and copies a
// null-terminated string starting at *ptr. This method also consumes
// the old data, so we tell WebAssembly to deallocate this memory.
function copyCStr(module, ptr) {
  const buffer_as_u8 = new Uint8Array(collectCString(module, ptr))
  const utf8Decoder = new TextDecoder("UTF-8");
  const buffer_as_utf8 = utf8Decoder.decode(buffer_as_u8);
  module.dealloc_str(orig_ptr);
  ...

(Adapted from Hello Rust, a guide for writing Rust and WebAssembly bindings by hand.)

This code looked fragile and prone to copy + paste errors. If any of these manual memory allocations or conversions happened at the wrong time, it could even cause Rust code to panic! After I got a demo working, instead of building out a complex API, I decided to abstract as much of this possible and behind a simple message-passing interface to exchange JSON-encoded strings between WebAssembly and JavaScript.

One upside of this design is that it makes it easier to run and test your WebAssembly code outside of a web context: rather than boot up a web browser, you can have it receive messages from a virtual frontend. It also becomes straightforward to delegate WebAssembly code to a Web Worker and communicate with the main thread using the postMessage interface. The tradeoff is that we have to assume all messages sent by JavaScript are well-formed. Whenever a new message variant is added or changed, the frontend must manually be kept in sync.

What wasm-bindgen exports to TypeScript

It’s now 2019, and the amazing work done by the Rust WebAssembly WG on wasm-bindgen makes it easy to expose functions from Rust, import JavaScript methods, and even manipulate rich data types across the runtime boundary.

Using wasm-bindgen, Rust structs, methods, free functions, and even basic enums can be imported to JavaScript. The command line wasm-bindgen tool can also generate TypeScript definitions (when you pass the --typescript argument). This lets you type-check both your Rust code and your frontend components at the same time, catching type errors during compilation rather than at runtime. This is especially valuable given how hard WebAssembly runtime errors are to debug!

The caveat is that wasm-bindgen only supports a subset of Rust types: those with a corresponding semantic representation in TypeScript. It supports exporting struct fields and impl methods as part of a single class definition, for example, and exporting simple C-like enums as TypeScript enums. If we wanted to export a Rust struct with a single field:

#[wasm_bindgen]
pub struct SimpleMessage {
    pub value: f64,
}

For this type, wasm-bindgen would generate the following TypeScript definition:

export class SimpleMessage {
  free(): void;
  value: number;
}

Note that our one-field struct is exported as a class that is allocated on WebAssembly’s heap (hence the free() method). Rather than initialize a variable with an anonymous JavaScript object, we instead have have to instantiate a member of the SimpleMessage class with new and assign its properties directly.

// expected SimpleMessage, found literal
let message: SimpleMessage = { value: 5 }; 

// this works though
let message = new SimpleMessage();
message.value = 5;

You also can’t add any fields to the struct definition in Rust which do not implement Copy, which includes String. The types of objects we can expose to TypeScript are powerful, but limited in complexity.

The reason wasm-bindgen has these restrictions is because its design is to expose an interface between the two systems, whereas we want to share a data structure. A Typescript definition that looks exactly like our Rust type when serialized into JSON would enable compile-time type-checking. With that, we could add new messages to Rust and know we’ve either handled them explicitly on the frontend, or trigger a compilation error pointing out the missing type.

#[derive(TypeScriptDefinition)]

Let’s say we want to generate a TypeScript definition for any type which can derive the Serialize trait. The types that can implement this trait include:

• struct types, which can be a unit type (Struct()), newtype Struct(u64), tuple type Struct(u64, String), or struct type Struct { value: u64, name: String }
• C-style enum types, which contain only unit discriminants with associated values
• enum types whose variants contain other values, aka sum types. This includes unit, newtype, tuple, or struct variants

My first attempt at exporting custom TypeScript definitions was to hack on the wasm-bindgen crate itself and modify how it generates .d.ts files. It was hard to distinguish what types should be exported as JSON instead of fully interactive interfaces. And a Rust type that can implement Serialize isn’t necessarily supported as a type by wasm-bindgen; for example, support for things like enums with complex variants (sum types) had to be written from scratch.

My next idea was to write a stand-alone crate that understood how serde serialized data and have it print out a JSON-compatible TypeScript definition. Instead of using constructs like class to model a Rust type, this crate would export a type alias for an object literal that matched its JSON serialization. Implementing code in an external crate made it easier to support serde-specific attributes like #[serde(rename="...")], which changes the structure of the type (like renaming fields) but only when serialized.

All this needed was a way to add strings directly to wasm-bindgen’s TypeScript pass. Based on Rust’s wasm_custom_section attribute, I submitted a feature to the wasm-bindgen crate to let you inject strings directly into its generated TypeScript definition file. You can now use the typescript_custom_section attribute to inject custom types when running wasm-bindgen:

// This static string will be injected into the TypeScript definition file. 
#[wasm_bindgen(typescript_custom_section)]
const TS_APPEND_CONTENT: &'static str = r#"

export type Coords = { "latitude": number, "longitude": number }; 

"#;

Note that these &’static str values can be dynamically generated by a macro, for example a #[derive()] macro that adds a custom type definition.

Creating such a macro that could parse a Serialize-able type and generate a type definition was surprisingly easy. Assuming someone had already written a serde-aware crate that printed a self-describing schema, I came across the rust-serde-schema crate (MIT + Apache-2 licensed) which recursively walks the structure of a Rust type and builds up a context object. To generate code, it’s even easier to recursively build up a list of tokens instead. These tokens can then be flattened into a string and inserted by our macro with the #[wasm_bindgen(typescript_custom_section)] annotation.

Putting these ideas together: You can try my experimental wasm-typescript-definition crate, which provides a TypeScriptDefintion macro that exports serde-compatible TypeScript definitions when running wasm-bindgen.

A type only needs to be annotated with the #[derive(TypeScriptDefinition)] attribute to work, though it makes sense to implement Serialize and Deserialize as well so it works with serde_json. A nice demonstration of this macro is with sum types. We can now convert Rust types that are otherwise inexpressible in JavaScript into data types that TypeScript understands. If we wanted to define an enum whose variants are different messages our frontend can receive:

#[derive(TypeScriptDefinition, Serialize, Deserialize)]
#[serde(tag = "tag", content = "fields")]
pub enum FrontendMessage {
  Init { id: String, },
  ButtonState { selected: Vec<String>, time: u32, }
  Render { html: String, time: u32, },
}

When we run wasm-bindgen, it generates a type definition that is inlined into the TypeScript definition file:

export type FrontendMessage =
  | { "tag": "Init", "fields": { "id": string, } },
  | { "tag": "ButtonState", "fields": { "selected": Array<string>, "time": number, } },
  | { "tag": "Render", "fields": { "html": string, "time": number, } },
  ;

The pipe operator | in a type definition means that it can be one of a list of different variants, much like enum variants in Rust.

Now when we create a new message in TypeScript like:

let msg: FrontendMessage =
  {"tag": "ButtonState", "fields": {"selected": ["bold", "list"], time: 0 }};

We can rely on compile time type-checking to ensure the message is well-formed. That guarantees it can be serialized into a string with JSON.stringify and parsed without errors using serde_json::from_str in Rust. It is now possible to change and introduce new messages to interface between the two runtimes without the risk of introducting runtime errors.

A primary benefit of wasm-bindgen is to push Rust’s safety guarantees into frontend code. I think there’s a compelling case for a “serde_typescript” crate that can generate TypeScript definitions for serializable data types, and has complete support for all of serde’s custom serialization attributes. For now, you can check out my Github repo for wasm-typescript-definition. Hope you find it useful!

Bonus: Exhaustive switch statements in TypeScript

Strong typing on the frontend gets us many of the same guarantees we have in Rust and makes it possible to keep frontend and WebAssembly code in sync. But we lack one important aspect of Rust’s pattern matching capabilities: its requirement that all match arms must be “exhaustive” (that is, there are no unhandled cases).

If we matched against the FrontendMessage enum type, but we only handled the Init and ButtonState variants, our program would fail at compile time indicating that we are missing a match arm for the third variant Render. In TypeScript, we have to work to get the same guarantee. Assuming we choose serde’s “internally tagged” representation for our enum, we can branch in TypeScript based on which variant it is by doing e.g.:

switch (message.tag) {
  case "Init": ... 
  case "ButtonState": ...
  case "Render": ...
}

At build time, the compiler can guarantee that each of the values we use for “tag” matches the name of an actual variant, which prevents you from misspelling or omitting a message type. But the compiler doesn’t check to see that your case statements are exhaustive—that every case is handled—unless you explicitly guarantee that the “default” code path will never be taken.

For this arcane purpose, TypeScript provides the never keyword, and in its Advanced Types documentation suggests how you can make a switch statement exhaustively check all variants of a “discriminated union” (essentially the same as our “internally tagged” enum representation):

function assertNever(x: never): never {
    throw new Error("Unexpected object: " + x);
}

function sendFrontendMessage(msg: FrontendMessage) {
    switch (msg.type) {
        case "Init": return App.initialize(msg.id);
        case "ButtonState": return App.updateButtons(msg.selected, msg.time);
        case "Render": return App.render(msg.html, msg.time);

        // If we missed an enum variant, TypeScript would now error out here.
        default: return assertNever(msg); 
    }
}

The assertNever function accepts an argument with a never type, meaning it should never be called given a valid FrontendMessage type. As long as this default: return assertNever(msg); case appears in every switch statement operating on a “discriminated union”, TypeScript can provide compile-time type checking that you’ve handled all possible variants. See this TypeScript playground to try out never types for yourself.

Yet you can also write code that runs on platforms you aren’t simultaneously coding on. Every modern computer architecture supports a C compiler you can download and run on your PC, usually a binary + utils for a new gcc or llvm backend. In practice, using these tools means setting several non-obvious environment variables like CC and searching the internet for magic command line arguments (it takes a lot of work to convince a Makefile not to default to running gcc). Installing a compiler for another machine is easy, but getting a usable result takes trial and error.

If you’ve picked up Rust and are learning systems programming, you might ask: Does Rust, a language whose design addresses C’s inadequacies for developing secure software, also address its shortcomings in generating code on other platforms?

Let’s start with the tiered platform support system Rust maintains to track which platforms it supports and how full that support is (from “it actually might not build at all” to “we test it each release”). On its own, this is a useful reference of the target identifiers of popular consumer OSes, embedded platforms, and some experimental ones (like Redox!). The majority of these different platforms don’t actually support running rustc or cargo from the command line though.

Rust makes up for this by advertising a strong cross-compilation story. Quoting from the announcement post for rustup target:

In practice, there are a lot of ducks you have to get in a row to make [cross-compilation] work: the appropriate Rust standard library, a cross-compiling C toolchain including linker, headers and binaries for C libraries, and so on. This typically involves pouring over various blog posts and package installers to get everything “just so”. And the exact set of tools can be different for every pair of host and target platforms.

The Rust community has been hard at work toward the goal of “push-button cross-compilation”. We want to provide a complete setup for a given host/target pair with the run of a single command.

This is an excellent goal given the infrastructure and design challenges ahead. And I wanted to learn more about this part of the article:

Cross-compilation is an imposing term for a common kind of desire:

• …
• You want to write, test and build code on your Mac, but deploy it to your Linux server.
• …

This is exactly the scenario I’m in! But… understandably, the article doesn’t actually include an example of how to do this, because cross-compiling for another OS requires making several assumptions about the target platform that maybe not apply to everyone. Here is a recap of how I made it work for my project.

Deploying via git and building from git

In my case, the need to build binaries for Linux came up while working on my project edit-text, a collaborative test editor for the web written in Rust. I regularly test changes out in a sandbox environment since you can’t rely on testing code locally to catch behavior that might only appear in production. Yet the issue I kept running into was how long it was taking deploy to my $10 DigitalOcean server. I spent a long time rereading the same compiler logs before it actually dawned on me—I was compiling on my web server and not my laptop. And that’s really slow.

If you have a githook that takes new source code pushed via git and loads it into a Docker container, deploying via git just sends up your source directory and points at a rustc compiler. On each new deploy, your server has to rebuild from your Dockerfile from scratch, and unless you configure it to support caching this throws away the benefit of quickly iterating on your code. If you want the benefit of faster builds by having cargo incrementally cache compiled files between builds, you’ll find it’s complex to get right in your Dockerfile configuration but entirely natural to manage this in your local development environment.

The approach I have the most experience with is to take the compilation environment and just run it locally on my machine. With Docker, we have easy way to run Linux environments (even on Mac) and to pin it to the same development environment I have on my server. Since Docker on my machine will be running Linux in a hypervisor, local performance should beat what I can do on my server even with the overhead of not being the host OS.

Did you know Rust has a first-party story for cross-compiling for Linux using Docker? The Rust cross-compilation image rustlang/rust:nightly can help you generate binaries for the Linux target compiled with nightly Rust and can be invoked on demand from the command line using docker run . I developed this set of command line arguments to get cross-compilation with caching working:

docker run --rm \
  -v $DIR_GIT:/usr/local/cargo/git \ # cache git downloads
  -v $DIR_REGISTRY:/usr/local/cargo/registry \ # cache cargo registry
  -v $DIR_RUSTUP:/usr/local/rustup/toolchains \ # cache rustup
  -v $DIR_SELF:/app \
  -w /app/edit-server \
  -t edit-build-server \
  cargo build --release --target=x86_64-unknown-linux-gnu --bin edit-server --features 'standalone'

The binaries this produced, amazingly, worked when I copied them to and ran them on my Linux server. Compiling locally was marginally faster. But there were drawbacks to this approach for cross-compilation:

• I had to manage and run Docker locally, which on macOS requires a Docker daemon be running on macOS.
• I had to cache each cargo and rust directory individually, which, managed separate from rustup on my machine, seemingly never got garbage collected. I accrued huge directories of cached files just for compiling for Linux.
• Intermediate artifacts from successive builds seemed less likely to be cached between builds, meaning building took longer than they should on my machine.

I like that Docker gives a reproducible environment to build in—building Debian binaries on the Debian kernel makes things easy—but Rust’s cross-compilation support might allow me to manage all the compilation artifacts that make modern Rust compile times tolerable.

“rustup target add”

So far I’ve only mentioned the Rust compiler’s support for cross-compiling. There are a actually handful of components you need to make cross-compiling work:

1. Compiler that support your target
2. Library headers to link your program against (if any)
3. Shared library files to link against (if any)
4. A “linker” for the target platform

Let’s start with compiler support. Passing --target when running cargo build|run changes the assembly your CPU outputs and bundled in object files supported by that OS. But we have to install the new toolchain adding that capability to Cargo. This is done with the command rustup target add.Installing support for another “target” is something you do once on your machine, and from then on cargo can support it via the --target argument.

To install a Linux target on my Mac, I ran:

rustup target add x86_64-unknown-linux-musl

This installs the new compilation target based on its target triplet, which means:

• We’re compiling for the x84-64 processor set (AMD64)
• from an unknown (generic) vendor, targeting the Linux OS
• compiled with the musl toolchain.

A note on musl: the alternative to musl is GNU, as in GNU libc—which almost every Linux environment has installed anyway. So why choose musl? musl is designed to be statically linked into a binary rather than dynamically linked; this means I could compile a single binary I could deploy to any server without any requirements as to what libraries were installed on that OS. This might even mean we can skip steps 2) and 3) above. And I could back to GNU if it didn’t work out.

Finally, we need a program that links our compiled objects together. On macOS, you can use brew to download a community-provided binary for Linux + musl cross-compilation. Just run this to install the toolchain including the command “x86_64-linux-musl-gcc”:

brew install FiloSottile/musl-cross/musl-cross

At this point we need to tell Rust about the linker. The official way to do this is to add a new file named .cargo/config in the root of your project and set its content to something similar:

[target.x86_64-unknown-linux-musl]
linker = "x86_64-linux-musl-gcc"

This should instruct Rust, whenever the target is set to --target=x86_64-unknown-linux-musl, to use the executable “x86_64-linux-musl-gcc” to link the compiled objects. But it seems to be the case that if you have any C code compiled by a Rust build script, you also have to set environment variables like TARGET_CC to get it working. So when my code started throwing linking errors, I just ran the following in my shell:

export TARGET_CC=x86_64-linux-musl-gcc

Thankfully, this made the compilation steps with linker errors work consistently.

Libraries and Linking

musl doesn’t support shared libraries, that is, libraries that are independently installed and versioned on your system via a package manager. Shared libraries are ones your program links to these at runtime (once the program starts), rather than literally embedding them in their binary at compile time (static libraries).

Sometimes you can work around the constraint of requiring static libraries without leaving the cargo ecosystem: some radical crates support a “bundled” feature, as in libsqlite3-sys, which compiles a static library during your build step and links it into your project. For example, the SQLite drivers I was relying on had no problem being compiled with musl if I enabled the “bundled” feature; I didn’t have to apt-get install libsqlite3 on the remote platform, nor did I have to find headers that matched it. An app with only this requirement would be a solid usecase for deploying binaries compiled with musl.

If your project depends on openssl, though, you’ll see this type of error midway during cargo build:

error: failed to run custom build command for `openssl-sys v0.9.33`
process didn't exit successfully: `/Users/timryan/edit-text/target/debug/build/openssl-sys-89bb414c25e8c29b/build-script-main` (exit code: 101)
--- stdout
[...]
--- stderr
thread 'main' panicked at '

Could not find directory of OpenSSL installation, and this `-sys` crate cannot
proceed without this knowledge. If OpenSSL is installed and this crate had
trouble finding it,  you can set the `OPENSSL_DIR` environment variable for the
compilation process.

Make sure you also have the development packages of openssl installed.
For example, `libssl-dev` on Ubuntu or `openssl-devel` on Fedora.

No need to check the exit code, this clearly isn’t building correctly. The error says “Could not find directory of OpenSSL installation”. This doesn’t mean I didn’t have OpenSSL installed on my computer (I did); it means it can’t find its headers and source code to compile. Compiling a static binary is with musl is now much more complicated if I need to download and compile an arbitrary OpenSSL dependency.

Why I need OpenSSL as a dependency to begin with: one of the libraries I depend on in edit-text’s software stack,reqwest, relies on native-tls to support encryption for download data over HTTPS. reqwest is a programmatic HTTP client for Rust, and it uses native-tls to link against the OS’s native SSL implementation and expose an agnostic interface to it in order to support HTTPS. I can imagine in the future a reqwest feature that substitutes a rust-tls backend instead of native-tls, allowing me to compile all my crypto could without needing to touch gcc. But for now, since I don’t want the heavy lift of compilng OpenSSL myself, dynamic linking looks like the only way forward.

Debian Packaging

New plan: compile against the GNU toolchain and use dynamic linking. If we don’t want to cross-compile libraries ourselves, then we have to find a source of pre-compiled libraries and headers (which are sometimes distinct things). Since we’re moving away from musl, we’ll even need to bring our own copy of libc!

Luckily, we just have to recreate the same environment as a Linux compiler. This turns out to be straightforward. When I’m compiling code in Linux and need to, say, link against OpenSSL, I can run the following:

sudo apt-get install libssl-dev

Now I can compile any binary which relies on OpenSSL headers, because they were installed to my system. Where are these files? One way to find them is to run dpkg-query -L libssl-dec to list which files were installed by my package manager. In this case, most of our header files are inserted into /usr/include and the Linux libraries in /usr/lib. If we have the .deb file itself, we can actually confirm this by dumping its archive contents:

$ ar p libssl-dev_1.1.0f-3+deb9u2_amd64.deb data.tar.xz | tar tvf -
drwxr-xr-x  0 root   root        0 Mar 29 06:51 ./
drwxr-xr-x  0 root   root        0 Mar 29 06:51 ./usr/
drwxr-xr-x  0 root   root        0 Mar 29 06:51 ./usr/include/
drwxr-xr-x  0 root   root        0 Mar 29 06:51 ./usr/include/openssl/
-rw-r--r--  0 root   root     3349 Mar 29 06:51 ./usr/include/openssl/aes.h
...

Where aes.h is the header we might require linking against.

We can essentially reuse these packages on other platforms. Package managers extract files to specific locations on your machine. If can extract these same archives locally, we tell the compiler to look in these folders for headers instead of OS folders.

Let’s describe which archives we want: First, my choice of a broadly-accessible Linux distribution that has good tooling is Debian, of which Ubuntu is a fork and which has a straightforward packaging system found with apt and its .deb package format. Second, we need to pick a sufficiently old enough version of Debian that would support ABI-compatible libraries. I chose /jessie/, the version of Debian immediately prior its current stable release, /stretch/.

We can’t just fetch a .deb archive via ‘apt-get install’ on a Mac though. Downloading library headers directly means navigating a hyperlink survey of computer architectures and CDNs. I poked around for a while to see if there was an obvious way to compute the URL of any Debian package, but it looks like to retrieve the package URL you basically need to reimplement all of aptitude (the package manager used by Debian). Because there were no brew formulae for libapt, and no standalone Rust bindings either, I assumed any solution would be more complicated than just referencing the direct URL. As such, the build script fetches each package URL in sequence and extracts them into a local folder:

export URL=http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl-dev_1.1.0f-3+deb9u2_amd64.deb
curl -O $URL
ar p $(basename $URL) data.tar.xz | tar xvf -

export URL=http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl1.1_1.1.0f-3+deb9u2_amd64.deb
curl -O $URL
ar p $(basename $URL) data.tar.xz | tar xvf -

export URL=http://ftp.us.debian.org/debian/pool/main/g/glibc/libc6_2.24-11+deb9u3_amd64.deb
curl -O $URL
ar p $(basename $URL) data.tar.xz | tar xvf -

You can see the dependencies my build script relies on. Note that we only install the packages we need to build with: backtrace-rs requires the libc library headers, and openssl-sys on Rust requires not only the headers in libssl-dev but also the shared library in libssl1.1. Other than that, these are all the packages I required when cross-compiling.

Building Linux binaries on macOS

We again need to install a linker, this time one that targets GNU/Linux. Again this is made easy with brew thanks to another community contribution:

brew tap SergioBenitez/osxct

Now the executable “x86_64-unknown-linux-gnu-gcc” is available on our PATH.

We next make a series of environment variable updates:

# Linker for the target platform
# (cc can also be updated using .cargo/config)
export TARGET_CC="x86_64-unknown-linux-gnu-gcc"

# Library headers to link against
export TARGET_CFLAGS="-I $(pwd)/usr/include/x86_64-linux-gnu -isystem $(pwd)/usr/include"
# Libraries (shared objects) to link against
export LD_LIBRARY_PATH="$(pwd)/usr/lib/x86_64-linux-gnu;$(pwd)/lib/x86_64-linux-gnu"

# openssl-sys specific build flags
export OPENSSL_DIR="$(pwd)/usr/"
export OPENSSL_LIB_DIR="$(pwd)/usr/lib/x86_64-linux-gnu/"

This specifies the linker headers and shared library locations, and some OpenSSL-specific flags required by openssl-sys. Take note of -isystem, which changes where gcc looks for system headers. Because we are using only Debian packages, the OpenSSL-specific build flags refer to the same folders as our other system libraries.

Now we can run the Cargo build command to cross-compile for Linux:

cargo build --target=x86_64-unknown-linux-gnu --features 'standalone'

The “standalone” feature is part of the project, and configures everything that can be built without relying on system libraries (like SQLite).

Now in my project’s ./target/debug/x86_64-unknown-linux-gnu/ folder, I can run file on the edit-server binary:

$ file target/x86_64-unknown-linux-gnu/release/edit-server
target/x86_64-unknown-linux-gnu/release/edit-server: ELF 64-bit \
  LSB shared object, x86-64, version 1 (SYSV), dynamically linked, \
  interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 3.2.0, \
  with debug_info, not stripped

It says it’s a shared object (in this case, an executable) and mentions we compiled it for GNU/Linux. Next, I created a example Dockerfile based on Debian that, when the binary is placed in the same directory, just launches it:

FROM nginx

RUN apt-get update; apt-get install sqlite3 -y

ADD . /app
WORKDIR /app
EXPOSE 80

CMD RUST_BACKTRACE=1 ./edit-server

I tried it out withdocker run on my machine, and saw the server successfully boot up:

$ docker run -it $(docker build -q .)
[ ok ] Restarting nginx: nginx.
client proxy: false
Listening on http://0.0.0.0:8000/
Graphql served on http://0.0.0.0:8003
sync_socket_server is listening for ws connections on 0.0.0.0:8001

This is Debian, running locally on my machine, successfully running the binary we compiled on my Mac. Since this is the same Dockerfile we send to the server, this means the server will be able to deploy it too!

There is one more step here: the binary now has to be sent to the server along with each deploy. Checking a large binary into Git just so Dokku could receive it via git push performs very poorly, and really is not what Git is built for. What worked for me: I switched to creating an archive of my Dockerfile’s directory and piping into ssh running dokku tar:in - on the remote server. This Dokku command loads a tarball from stdin (in this case) and deploys it, making it possible to push new code to the server without needing to check in anything to git each time.

Rust advantages in webdev

And the result: it is now much faster to update code running on a server. Compilation speed improved immensely between compiling it remotely, where each compile felt as slow as a full rebuild—and compiling it locally, where cargo’s incremental cache makes builds feel as fast as targeting your default OS. It’s fast enough I can deploy new code to a remote test server when it’s too annoying to set up a local server. Yet Rust’s cross-compilation story can’t eliminate by itself the clumsy ritual of setting arbitrary environment variables in order to get compilation to succeed.

If rustup target is a blueprint for the future, I imagine an ecosystem of cross-compilation tools will inevitably spring up that makes bundling for other OSes straightforward and configurable. Even though Rust isn’t an interpreted language, if deploying code no longer means compiling code on your server, and local recompilation is fast, it makes deployment in Rust feel much more like modern web development. Cross-compilation support is an undersold factor in Rust’s webdev story.

My hobby projects are mostly written in Rust, and there was a brilliant post earlier this year about how to write your own cargo tools using cargo’s command aliases. This works well for individual tools (like your own cargo todo), and has the benefit of needing no additional setup to work out of the box. The downside of this approach, besides discoverability, is that you don’t have a common entry point for your commands. In my case, most of my tooling shares a lot of common abstractions like debug/release mode switches or common environment variables. Rather than manage a constellation of separate binaries, here’s how I structured a unified build tool written for a moderate-sized Rust project.

To build a single entry point for these, I picked up cargo-script and created the executable “x.rs”, invoking Rust’s own build system “x.py”. The goal is to have a build process as straightforward as running “./x.rs build” from the root of the project.

Design

The project this tool is for is edit-text, a collaborative text editor written in Rust which runs in the browser via WebAssembly. (Here is its ./x.rs script.) Because the editor is collaborative, it needs a server to coordinate editing. Because code can be shared between the server and client, common code is broken out into its own crate. The client is able to be compiled for the web or run as a standalone command-line binary, so we need to support multiple compilation targets; the frontend is an npm module bundled with webpack; also, WebAssembly requires an additional wasm-bindgen step when compiling. Long story short, it has accumulated a lot of build tools spread across many sub-projects.

Instead of having a command line interface that focuses on the action being taken, like how cargo build --bin <target> requires “build” be first, we can make it centered on the component itself: ./x.rs server-build, ./x.rs server-watch, and ./x.rs server will build the server, rebuild while polling its source code for changes, and lastly run the binary. This makes server the target of our commands, and makes it especially easy to reverse-i-search (Ctrl+R) in the terminal for previous server commands. When needed, ./x.rs recursively can shell out to itself, as in the case with ./x.rs server-test which builds and spawns ./x.rs server before running a WebDriver process in the foreground.

The build script is designed to have few dependencies as possible. It depends on the stellar quicli and clap utilities for writing clean command line interfaces, and the failure crate for ergonomic error handling. This ensures we compile fast the first time ./x.rs is run and when it’s next modified. (Sidenote: I’ll probably take this a step further and drop quicli, since structopt is less suited than clap’s builder API for adding new one-off subcommands.)

The build script doesn’t have any knowledge of code running contained in its subcrates, so it remains small and quick to bootstrap but also so build errors from subcrates don’t propagate up to the build tool. Complex functionality can be broken out into crates themselves. For example, ./x.rs logs is a command that shells out to the command cargo run --bin edit-server-logs -- {args}. In this way the logic for the log parser can be part of the project that understands and writes those logs, and we can also independently test and use this functionality outside the build tool. Sending edit-server and edit-server-logs binaries to the server is more useful the vendoring the entire build script.

The last dependency is self-written and provides an abstraction for talking to the shell.

Scripting with commandspec

The challenge of moving from a scripting to a programming language is that shell scripting is very expressive. Using the child process API is trying to express the same thing with way more characters. Because the command line is versatile but permissive, the best strategy to adapting it to modern programming is to limit it to clean subset of features, like how XML is a less permissive HTML. But also, we need to increase the expressive power of the shell to make it easy to work with Rust-native data structures; so really we want what JSX to HTML, a clean, restrictive syntax the allows interpolation.

So I wrote commandspec, a macro_rules! macro to inline shell syntax with your code without requiring it to run in an unsafe shell subprocess. This makes porting from the shell familiar, incremental, and robust. Say we start with this build.sh script:

git submodule update --init --recursive

cd frontend
npm install
npm run build

When we need more flexibility language, we can embed this script directly into a Rust program:

sh_execute!(r"
    git submodule update --init --recursive

    cd frontend
    npm install
    npm run build
")?;

This just runs code directly in a shell process, so we can still make it safer by invoking these programs directly. What our build script is doing is running three commands and making one environment change (changing directories). If we consider each {directory, environment, command} group separately, we can rewrite each of these to use the execute! macro, a safe wrapper over familiar shell syntax:

execute!(r"
    git submodule update --init --recursive
")?;

execute!(r"
    cd frontend
    npm install
")?;

execute!(r"
    cd frontend
    npm run build
")?;

Each step breaks the script into its component parts. You can add one cd instruction, multiple export name=value environment variables, and then ultimately your shell command. But the DSL parses this std::process::Command API underneath, which is cross-platform and doesn’t require a shell process at all:

// This executes the native rustc command in cmd.exe or in sh
// it prints the version the shell and returns Ok(())
execute!(r"
    rustc -V
")?;

From here, Rust-native abstractions can be added (like using the std::fs APIs instead of mv or cp commands) or be left alone, in cases where you would just be replacing it with the equivalent std::process::Command constructor.

A benefit of this pattern is that our commands can be copied almost verbatim into a new shell session and tested in isolation. The syntax is also similar enough for non POSIX shells (Powershell and cmd.exe, namely) that you can trivially rewrite it to run in those terminals.

This execute! method wraps the command! macro, which is identical except for returning a std::process::Command object directly. It then calls .execute(), a new trait method on Command that returns Result<(), CommandError>, the error being an object that wraps over non-0 error codes and filesystem or interrupt errors. Thus we can use execute!(...)? to return immediately for any command that is not successful (exit code of 0), or we can decompose the error as an enum, or we can use the .unwrap_err().error_code() to get the error code directly.

It’s straightforward to combine the command! macro with the full std::process::Command API (or even something more complex, like os_pipe).

let cmd = command!(r"
    tar -xvf -
")?
    .stdin(Stdio::piped())
    .spawn()?;

cmd.stdin.write(/* my precious, piped data */);

commandspec works on stable Rust. This is not a hard requirement for me (edit-text absolutely requires nightly for now) but it’s a good requirement for writing maintainable code generally. It accomplishes this by internally leveraging format!’s macro syntax. As such, you can use a familiar {} syntax and get compile-type typechecking to verify your code will work. Unlike format!, commandspec pre-escapes all strings passed as arguments to the format function to be escaped for the shell:

execute!(
    r"
        export RUST_BACKTRACE=1
        cd my-server
        cargo run {release} -- {custom_args}
    ",
    // Pass options that will be omitted if None
    release = if not_debug { Some("--release") } else { None },
    // Pass vectors to expand to multiple arguments
    custom_args = vec!["./file1", "./file2"],
)?;

All arguments are embedded as strings. This breaks formatting features aside from positional ({}) or indexed embedding ({0}, {release}), unfortunately. Since the command line treats strings and other types indiscriminately, individually format!-ing arguments is an easy workaround.

Even with the release of Macros 2.0 I think this a good balance for embedding shell scripts. If these removed quotes from the macro as in execute!(cargo run --release)?, we’d have to distinguish --release from the raw tokens - - release, which is non-trivial.

Takeaways

My approach to build scripts here evolved over about six months for one project, so I assume it’ll change in the future. However, my takeaways are that building should be 1) easy to refactor and 2) easy to interface with. In order to encourage better abstractions than shell scripting, it should be easy if not pleasant to work with executables with a programmatic API. Using make as a script runner and compilation tool is fundamentally a worser interface than splitting your build system into a project-centric interface, and then well-tested, domain-tailored build tools.

This post is also a shoutout to my favorite Rust tool, cargo-script. It’s brilliant for all sorts of one-off scripts, but I found it also holds up well to the task of managing entire workflows. When I started using cargo-script, it had invalidation issues that caused my script to be re-compiled each time it was run. This no longer seems to be the case, and running command line scripts (that are small enough to compile) feels similar to the workflow of running an interpreted language. If you haven’t legitimately considered Rust for scripting, quicli + cargo-script present a very flattering case.