|
|
# Cargo.toml
|
|
|
|
|
|
`Cargo.toml` is the manifest file for Rust's package manager, [`cargo`]. This file contains
|
|
|
metadata such as name, version, and dependencies for packages, which are call "crates" in Rust.
|
|
|
|
|
|
[`cargo`]: https://doc.rust-lang.org/cargo/
|
|
|
|
|
|
There's a bunch of metadata that the template gives us, but there are three key parts to discuss:
|
|
|
|
|
|
1. [`crate-type`](#a1-crate-type)
|
|
|
2. [`wasm-bindgen` dependency](#a2-wasm-bindgen-dependency)
|
|
|
3. [`[features]` and `wee_alloc`, `console_error_panic_hook` dependencies](#a3-features-and-wee_alloc-console_error_panic_hook-dependencies)
|
|
|
|
|
|
<hr/>
|
|
|
|
|
|
## 1. `crate-type`
|
|
|
|
|
|
```toml
|
|
|
[lib]
|
|
|
crate-type = ["cdylib", "rlib"]
|
|
|
```
|
|
|
|
|
|
A Rust-`wasm` crate is a bit different from a normal crate, and as a result, we need to note
|
|
|
this in our `Cargo.toml`.
|
|
|
|
|
|
This `[lib]` annotation is typically not needed in Cargo projects, and if you're
|
|
|
familiar with other Rust crates you'll remember that the most common crate types
|
|
|
are `rlib` (the default) or `bin` for binaries (which don't need a `crate-type`
|
|
|
annotation).
|
|
|
|
|
|
Here though `crate-type = ["cdylib"]` typically signifies that you'd like the
|
|
|
compiler to create a dynamic system library, but for WebAssembly target it
|
|
|
simply means "create a `*.wasm` file without a `start` function". On other
|
|
|
platforms this output type will create `*.so` file on Linux, `*.dylib` on
|
|
|
macOS, and `*.dll` Windows.
|
|
|
|
|
|
We also specify `crate-type = ["rlib"]` to ensure that our library can be unit
|
|
|
tested with `wasm-pack test` (which we'll see later). Without this we wouldn't
|
|
|
be able to test our library because the `cdylib` crate type is incompatible with
|
|
|
`wasm-pack`'s style of unit tests.
|
|
|
|
|
|
You can read more about linking and crate types, [here](https://doc.rust-lang.org/reference/linkage.html).
|
|
|
|
|
|
## 2. `wasm-bindgen` dependency
|
|
|
|
|
|
[`wasm-bindgen`] is our most important dependency. This package allows us to use the
|
|
|
`#[wasm-bindgen]` attribute to tag code that represents the interface we want between
|
|
|
our JavaScript and Rust-generated `wasm`. We can import JS and export Rust by using this
|
|
|
attribute.
|
|
|
|
|
|
[`wasm-bindgen`]: https://rustwasm.github.io/docs/wasm-bindgen/
|
|
|
|
|
|
```toml
|
|
|
wasm-bindgen = "0.2"
|
|
|
```
|
|
|
|
|
|
We'll see more about how to use this library when we discuss what has been generated in `lib.rs`.
|
|
|
|
|
|
⚠️ If you are coming from JavaScript, you might note that when we add the dependency
|
|
|
there is no `^` or `~` symbol- it looks like we're locking to the `0.2` version.
|
|
|
However, that's not the case! In Rust, the `^` is implied. You can read more about this in the
|
|
|
[cargo documentation on specifying dependencies].
|
|
|
|
|
|
[cargo documentation on specifying dependencies]: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html
|
|
|
|
|
|
## 3. `[features]` and [`wee_alloc`], [`console_error_panic_hook`] dependencies
|
|
|
|
|
|
[`wee_alloc`]: https://crates.io/crates/wee_alloc
|
|
|
[`console_error_panic_hook`]: https://crates.io/crates/console_error_panic_hook
|
|
|
[`cfg-if`]: https://crates.io/crates/cfg-if
|
|
|
|
|
|
As part of our effort to design a template that helps people discover useful crates
|
|
|
for their particular use case, this template includes two dependencies that can be
|
|
|
very useful for folks developing Rust-`wasm` crates:[ `console_error_panic_hook`] and
|
|
|
[`wee_alloc`].
|
|
|
|
|
|
Because these dependencies are useful primarily in a specific portion of the Rust-`wasm`
|
|
|
crate development workflow, we've also set up a bit of glue code that allows us to include
|
|
|
them both as dependencies, but also allows them to be optionally included.
|
|
|
|
|
|
```toml
|
|
|
[features]
|
|
|
default = ["console_error_panic_hook"]
|
|
|
|
|
|
[dependencies]
|
|
|
cfg-if = "0.1.2"
|
|
|
wasm-bindgen = "0.2"
|
|
|
|
|
|
# The `console_error_panic_hook` crate provides better debugging of panics by
|
|
|
# logging them with `console.error`. This is great for development, but requires
|
|
|
# all the `std::fmt` and `std::panicking` infrastructure, so isn't great for
|
|
|
# code size when deploying.
|
|
|
console_error_panic_hook = { version = "0.1.1", optional = true }
|
|
|
|
|
|
# `wee_alloc` is a tiny allocator for wasm that is only ~1K in code size
|
|
|
# compared to the default allocator's ~10K. It is slower than the default
|
|
|
# allocator, however.
|
|
|
#
|
|
|
# Unfortunately, `wee_alloc` requires nightly Rust when targeting wasm for now.
|
|
|
wee_alloc = { version = "0.4.2", optional = true }
|
|
|
```
|
|
|
|
|
|
[`cfg-if`] allows us to check if certain features are enabled on a Rust crate. We'll
|
|
|
use this crate later to optionally enable [`console_error_panic_hook` or
|
|
|
`wee_alloc`.
|
|
|
|
|
|
By default, only `console_error_panic_hook` is enabled. To disable either
|
|
|
feature, we can remove its name from the `default` vector.
|
|
|
|
|
|
To learn more about these features, we discuss them in-depth in the [`src/lib.rs`] and
|
|
|
[`src/utils.rs`] sections.
|
|
|
|
|
|
[`src/lib.rs`]: src-lib-rs.html
|
|
|
[`src/utils.rs`]: src-utils-rs.html
|
|
|
|
|
|
Briefly, they include:
|
|
|
|
|
|
+ **console_error_panic_hook** for logging panic messages to the developer console.
|
|
|
+ **wee_alloc**, an allocator optimized for small code size.
|
|
|
|
