Cargo WAPM

(API Docs)

A cargo sub-command for publishing Rust crates to the WebAssembly Package Manager.

If you want a deeper understanding of how cargo wapm works, check out Announcing Cargo WAPM.

Getting Started

You can install the cargo wapm command from crates.io.

$ cargo install cargo-wapm

You will also need to install the wapm CLI and [authenticate][auth] with WAPM.

$ curl https://get.wasmer.io -sSfL | sh
$ wapm login
Username: my-user
Password: ****

Once you have done that, open the Cargo.toml for your crate and add a metadata section to tell cargo wapm how your crate will be packaged.

# Cargo.toml
[package.metadata.wapm]
namespace = "Michael-F-Bryan"
abi = "none"

The abi argument tells cargo wapm which target to use when compiling to WebAssembly.

You also need to add cdylib to the crate-type list. You should also add the rlib crate type if other crates depend on this crate (integration tests, doc tests, examples, etc.).

# Cargo.toml
[lib]
crate-type = ["cdylib", "rlib"]

Now the Cargo.toml is up to date, we can do a dry run to make sure everything is correct.

$ cd examples/hello-world/
$ cargo wapm --dry-run
2022-05-03T17:33:31.929353Z  INFO publish: cargo_wapm: Publishing dry_run=true pkg="hello-world"
Successfully published package `Michael-F-Bryan/hello-world@0.1.0`
[INFO] Publish succeeded, but package was not published because it was run in dry-run mode
2022-05-03T17:33:32.366576Z  INFO publish: cargo_wapm: Published! pkg="hello-world"

We can see that some files have been written to the target/wapm/ folder.

$ tree ../../target/wapm
../../target/wapm
└── hello-world
    ├── hello_world.wasm
    ├── LICENSE_MIT.md
    ├── README.md
    └── wapm.toml

1 directory, 4 files

$ cat ../../target/wapm/hello-world/wapm.toml
[package]
name = "Michael-F-Bryan/hello-world"
version = "0.1.0"
description = "A dummy package."
license-file = "LICENSE_MIT.md"
readme = "README.md"

[[module]]
name = "hello-world"
source = "hello_world.wasm"
abi = "none"

If you are happy with the generated files, remove the --dry-run command to publish the crate for real.

The cargo wapm command doesn't take care of any version bumping, so the version being published is read directly from Cargo.toml. Check out the cargo release tool if you something that can manage routine release tasks like bumping versions, tagging commits, or updating your changelog.

Workspaces

Normally, the cargo wapm command will only publish the crate in the current directory.

However, by using the --workspace flag you can publish every crate in the current workspace as long as they have a [package.metadata.wapm] section in their Cargo.toml. The --exclude argument lets you skip a particular crate while publishing.

License

This project is licensed under the Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0).

It is recommended to always use cargo-crev to verify the trustworthiness of each of your dependencies, including this one.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

The intent of this crate is to be free of soundness bugs. The developers will do their best to avoid them, and welcome help in analysing and fixing them.