22 releases (14 breaking)
0.16.0 | Sep 5, 2024 |
---|---|
0.15.0 | Jul 31, 2024 |
0.14.0 | Jul 9, 2024 |
0.9.1 | Mar 13, 2024 |
0.0.0 |
|
#1593 in WebAssembly
135KB
3K
SLoC
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
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 keyring to securely store signing keys.
Use the warg
CLI to manage your signing keys.
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.
Dependencies
~32–49MB
~804K SLoC