The wit tool

A tool for creating and publishing WIT packages to a WebAssembly component registry.

WIT packages are used in the WebAssembly Component Model for defining interfaces, types, and worlds used in WebAssembly components.

Requirements

• The wit tool is written in Rust, so you'll want the latest stable Rust installed.

Installation

To install wit subcommand, run the following command:

cargo install wit

Initializing a WIT package

To initialize a new WIT package in the current directory:

wit init

This creates a wit.toml file with the following contents:

version = "0.1.0"

[dependencies]

[registries]

By default, the WIT package will not have any dependencies specified.

The registries section contains a mapping of registry names to URLs. The intention behind explicitly supporting multiple registries is that no one registry will be the central repository for WebAssembly components; in the future, a federation of registries will be used for publishing and discovering WebAssembly components.

A registry named default will be the registry to use when a dependency does not explicitly specify a registry to use.

An example of setting the default registry:

[registries]
default = "https://preview-registry.bytecodealliance.org"

The default registry may also be set by passing the --registry option to the init command:

wit init --registry https://preview-registry.bytecodealliance.org

Adding a dependency

To add a dependency on another WIT package, use the add command:

wit add <PACKAGE>

Where PACKAGE is the package to add the dependency for, e.g. wasi:cli.

The command will contact the registry to determine the latest version of the package, and add it as a dependency in the wit.toml file.

The version requirement to use may be specified with a delimited @:

wit add wasi:cli@2.0.0

Building the WIT package

To build the WIT package to a binary WebAssembly file, use the build command:

wit build

This command will output a .wasm file based on the package name parsed from the .wit files in the directory containing wit.toml.

Use the --output option to specify the output file name:

wit build --output my-package.wasm

Updating dependencies

To update the dependencies of a WIT package, use the update command:

wit update

This command will contact the registry for the latest versions of the dependencies specified in wit.toml and update the versions in the lock file, wit.lock.

Publishing the WIT package to a registry

To publish the WIT package to a registry, use the publish command:

wit publish

For new packages, the --init option must be used to initialize a new package log for the package being published:

wit publish --init

The command will publish the package to the default registry using the default signing key.

To specify a different registry or signing key, use the --registry and --key-name options, respectively:

wit publish --registry https://registry.example.com --key-name my-signing-key

Managing signing keys

WebAssembly component registries accept packages based on the keys used to sign the records being published.

The wit tool uses the OS-provided key ring to manage signing keys.

To create a new signing key for a registry, use the key new command:

wit key new https://registry.example.com

To print a Key ID (a fingerprint of the public key) for a signing key, use the key id command:

wit key id https://registry.example.com

To explicitly set a signing key, use the key set command:

wit key set https://registry.example.com

This command will securely prompt you for the signing key to set in the OS key ring.

To delete an existing signing key (note: use extreme caution when deleting signing keys), use the key delete command:

wit key delete https://registry.example.com

Contributing to wit

wit is a (future) Bytecode Alliance project, and follows the Bytecode Alliance's Code of Conduct and Organizational Code of Conduct.

Getting the Code

You'll clone the code via git:

git clone https://github.com/bytecodealliance/cargo-component

Testing Changes

We'd like tests ideally to be written for all changes. Test can be run via:

cargo test -p wit

You'll be adding tests primarily to the tests/ directory.

Submitting Changes

Changes to wit are managed through pull requests (PRs). Everyone is welcome to submit a pull request! We'll try to get to reviewing it or responding to it in at most a few days.

Code Formatting

Code is required to be formatted with the current Rust stable's cargo fmt command. This is checked on CI.

Continuous Integration

The CI for the wit repository is relatively significant. It tests changes on Windows, macOS, and Linux.

Publishing

Publication of this crate is entirely automated via CI. A publish happens whenever a tag is pushed to the repository, so to publish a new version you'll want to make a PR that bumps the version numbers (see the ci/publish.rs script), merge the PR, then tag the PR and push the tag. That should trigger all that's necessary to publish all the crates and binaries to crates.io.