srtool
The core component of the Substrate runtime toolbox (srtool
) is a Docker container that enables you to build the Substrate WebAssembly runtime in a deterministic way.
By using this tool, you can ensure that the same source code consistently reproduces an identical WebAssembly blob.
You can also use the tool to inspect and audit the runtime for any Substrate-based chain and to integrate building the WebAssembly runtime into your CI/CD pipeline.
Working with the Docker container
Because srtool
is a Docker container, you must have Docker available in your build environment to use it.
However, you don't need to know anything about using Docker to build a chain using srtool
because you can use the srtool-cli
command-line interface to work with Docker images.
The srtiool-cli
package is a command-line utility written in Rust that installs an executable program called srtool
on your computer.
This program simplifies your interactions with the srtool
Docker container.
Over time, the tooling around the srtool
Docker image has expanded to include the following tools and helper programs:
- srtool-cli provides a command-line interface to pull the
srtool
Docker image, get information about the image and tooling used to interact with it, and build the runtime using thesrtool
Docker container. - subwasm provides command-line options for working with the metadata and WebAssembly runtime built using
srtool
. Thesubwasm
program is also used internally to perform tasks in thesrtool
image. - srtool-actions provides Github actions to integrate builds produced using the
srtool
image with your GitHub CI/CD pipelines. - srtool-app provides a simple graphical user interface for building the runtime using the
srtool
Docker image.
Installing srtool-cli
The srtool
command-line interface enables you to build the WebAssembly runtime using the srtool
Docker image.
You can install the srtool
command-line interface by running the following command:
cargo install --git https://github.com/chevdor/srtool-cli
Basic command usage
The basic syntax for running srtool
commands is:
srtool [options] [subcommand]
Options
You can use the following command-line options with the srtool
command.
Option | Description |
---|---|
-h , --help | Displays usage information. |
i , --image <image> | Specifies an alternative image. Be sure to specify an image that is compatible with the default paritytech/srtool image. You should note that specifying a different image might not produce the same deterministic result that the paritytech/srtool image produces. |
-n , --no-cache | Specifies that you don't want to use the tag value from the local cache. |
-V , --version | Displays version information. |
Subcommands
You can use the following subcommands with the srtool
command.
Command | Description |
---|---|
build | Starts a new srtool container to build your runtime. |
help | Displays usage information for srtool or for a specified subcommand. |
info | Displays information about the srtool container and your repository. |
pull | Pulls the srtool image without running anything else. |
version | Displays version information for the srtool container. Use --version if you want version information for the srtool-cli executable. |
Examples
To get version information for the srtool
Docker image, run the following command:
srtool version
The command displays output similar to the following:
{
"name": "srtool",
"version": "0.9.21",
"rustc": "1.62.0",
"subwasm": "0.18.0",
"tera": "0.2.1",
"toml": "0.2.1"
}
To get version information for the srtool-cli
executable, run the following command:
srtool --version
The command displays output similar to the following:
srtool-cli 0.8.0
srtool build
Use the srtool build
command to start a new srtool
container to build the runtime for the package you specify.
By default, the srtool build
command assumes that the Cargo.toml
file for the runtime is located in a runtime
subdirectory with the name of the chain.
For example, the srtool build
command use the following locations by default:
- runtime/kusama
- runtime/polkadot
- runtime/rococo
- runtime/westend
If the Cargo.toml
file for your runtime is in a different location, you can specify the path as a command-line option.
Basic usage
The basic syntax for running the srtool build
command is:
srtool build [options] --package <package> [--runtime-dir <path>] [project-path]
Arguments
By default, the srtool build
runs in the current working directory. If your project isn't located in the current working directory, you can specify the path to the project location.
Argument | Description |
---|---|
project-path | Specifies the path to the blockchain project you are building the runtime for. |
Options
You can use the following command-line options with the srtool build
command.
Option | Description |
---|---|
-a , --app | Enables a mix of standard output and JSON output during the build. This option is recommended for CI. The JSON output is provided as a single line at the end of the build. |
--build-opts <BUILD_OPTS> | Enables you to pass custom options directly to the cargo build process. If you specify this command-line option, be aware that none of the automatic options for building Kusama or Polkadot are passed to the build process. You must explicitly set the build options you need when you use the --build-opts command-line option. In general, this option rarely required. This option is equivalent to setting the BUILD_OPTS environment variable. |
--default-features <default-features> | Enables you to change the list of default features for the runtime without disabling automatic feature detection. This option is equivalent to setting the DEFAULT_FEATURES environment variable. This command-line option has no effect if you set BUILD_OPTS . |
-h , --help | Displays usage information. |
i , --image <image> | Specifies an alternative image. Be sure to specify an image that is compatible with the default paritytech/srtool image. You should note that specifying a different image might not produce the same deterministic result that the paritytech/srtool image produces. |
-j , --json | Enables JSON output. |
--no-cache | Disables all caching. If you specify this option, the srtool image won't access the Cargo home cache for build dependencies. In general, this option is rarely used because there are no known issues with using the cache. |
-p , --package <package> | Specifies the name of the runtime package you want to build. The name you specify should be the same as the name defined in the Cargo.toml file for the runtime,for example, kusama-runtime, polkadot-runtime, and so on. This option is equivalent to setting the PACKAGE environment variable. |
--profile <profile> | Specifies the profile to use for building the runtime, The default profile to build a runtime is always release . You can override the default with this command-line option. This option is equivalent to setting the PROFILE environment variable. |
-r , --runtime-dir <runtime> | Specifies the location of the Cargo.toml file for the runtime. If your runtime is not in the standard location, you can use this command-line option to specify the correct location. This option is equivalent to setting the RUNTIME_DIR environment variable. |
-V , --version | Displays version information. |
Examples
To build the Westend runtime from the cumulus
repository where the path to the Cargo.toml
for the runtime is parachains/runtimes/assets/asset-hub-westend, you would run the following command:
srtool build --app --package westmint-runtime --runtime-dir parachains/runtimes/assets/westmint
The first time you run the srtool build
command it takes some time to complete.
As the runtime compiles, messages about its progress are displayed as standard output.
Because this example uses the --app
command-line option, JSON output is displayed in a single line at the end of the build similar to the following truncated output:
...
Compiling cumulus-primitives-parachain-inherent v0.1.0 (/build/primitives/parachain-inherent)
Compiling cumulus-pallet-parachain-system v0.1.0 (/build/pallets/parachain-system)
Finished release [optimized] target(s) in 112m 11s
✨ Your Substrate WASM Runtime is ready! ✨
{"gen":"srtool v0.9.21","src":"git","version":"1.0.0","commit":"bd41e3f11887ea2f55fc37be71ff652923388e03","tag":"v0.9.220-rc2","branch":"master","rustc":"rustc 1.62.0 (a8314ef7d 2022-06-27)","pkg":"westmint-runtime","tmsp":"2022-08-22T21:12:18Z","size":"707937","prop":"0x6b8e93443b6660a16f67a6cd34d415af463e2285eda3fd02b9fe052c1ad2ceb9"
... }}}}
srtool help
Use the srtool help
command to display usage message for srtool
or for a specified subcommand.
Basic usage
srtool help [subcommand]
Examples
To display usage information for the build subcommand, run the following command:
subkey help build
srtool info
Use the srtool info
command to display information about the srtool
container and your repository.
By default, the srtool info
command assumes that the Cargo.toml
file for the runtime is located in a runtime
subdirectory with the name of the chain.
For example, the srtool info
command use the following locations by default:
- runtime/kusama
- runtime/polkadot
- runtime/rococo
- runtime/westend
If the Cargo.toml
file for your runtime is in a different location, you can specify the path as a command-line option.
Basic usage
The basic syntax for running the srtool info
command is:
srtool info [options] --package <package> [--runtime-dir <path>] [project-path]
Arguments
By default, the srtool info
runs in the current working directory.
If your project isn't located in the current working directory, you can specify the path to the project location.
Argument | Description |
---|---|
project-path | Specifies the path to the blockchain project if the project isn't located in the current working directory. |
Options
You can use the following command-line options with the srtool info
command.
Option | Description |
---|---|
-h , --help | Displays usage information. |
i , --image <image> | Specifies an alternative image. Be sure to specify an image that is compatible with the default paritytech/srtool image. You should note that specifying a different image might not produce the same deterministic result that the paritytech/srtool image produces. |
-p , --package <package> | Specifies the name of the runtime package you want to build. The name you specify should be the same as the name defined in the Cargo.toml file for the runtime,for example, kusama-runtime, polkadot-runtime, and so on. This option is equivalent to setting the PACKAGE environment variable. |
-r , --runtime-dir <runtime> | Specifies the location of the Cargo.toml file for the runtime. If your runtime is not in the standard location, you can use this command-line option to specify the correct location. This option is equivalent to setting the RUNTIME_DIR environment variable. |
-V , --version | Displays version information. |
Examples
To display information about the srtool
container and the local node-template repository, you might run a command similar to the following:
srtool info --package node-template-runtime --runtime-dir runtime
This command displays output similar to the following:
{
"generator": {
"name": "srtool",
"version": "0.9.21"
},
"src": "git",
"version": "4.0.0-dev",
"git": {
"commit": "6a8b2b12371395979099d2c79ccc1860531b0449",
"tag": "",
"branch": "my-release-branch"
},
"rustc": "rustc 1.62.0 (a8314ef7d 2022-06-27)",
"pkg": "polkadot-runtime",
"profile": "release"
}
srtool pull
Use the srtool pull
command to check for and download the latest version of the srtool
Docker image.
Basic usage
The basic syntax for running the srtool pull
command is:
srtool pull [options]
Options
You can use the following command-line options with the srtool pull
command.
Option | Description |
---|---|
-h , --help | Displays usage information. |
i , --image <image> | Specifies an alternative image. Be sure to specify an image that is compatible with the default paritytech/srtool image. You should note that specifying a different image might not produce the same deterministic result that the paritytech/srtool image produces. |
-V , --version | Displays version information. |
Examples
To check for a new version of the srtool
container and Docker image, you might run a command similar to the following:
srtool pull
This command checks the Docker Hub for the latest version of the paritytech/srtool
image and begins downloading and extracting the software.
For example
Found 1.62.0, we will be using paritytech/srtool:1.62.0 for the build
1.62.0: Pulling from paritytech/srtool
405f018f9d1d: Pull complete
c49473e7f7b3: Pull complete
7edf98d07029: Pull complete
85a50724a6fa: Pull complete
87fb1e3dee5b: Downloading 19.4MB/170.4MB
469075c5d317: Download complete
533bfa44b64a: Download complete
...
When all tasks are complete, the command displays output similar to the following:
Digest: sha256:d5353a63d8fccbef5666e28a8fa0b302d71d4f53cabeb760fe213f3d7df4b8b6
Status: Downloaded newer image for paritytech/srtool:1.62.0
docker.io/paritytech/srtool:1.62.0
If you already have the latest version installed locally, the command displays output similar to the following:
Found 1.62.0, we will be using paritytech/srtool:1.62.0 for the build
1.62.0: Pulling from paritytech/srtool
Digest: sha256:d5353a63d8fccbef5666e28a8fa0b302d71d4f53cabeb760fe213f3d7df4b8b6
Status: Image is up to date for paritytech/srtool:1.62.0
docker.io/paritytech/srtool:1.62.0
srtool version
Use the srtool version
command display version information for the srtool
container. Use --version
if you want the version of the srtool-cli
executable.
Basic usage
The basic syntax for running the srtool version
command is:
srtool version [options]
Options
You can use the following command-line options with the srtool version
command.
Option | Description |
---|---|
-h , --help | Displays usage information. |
i , --image <image> | Specifies an alternative image. Be sure to specify an image that is compatible with the default paritytech/srtool image. You should note that specifying a different image might not produce the same deterministic result that the paritytech/srtool image produces. |
-V , --version | Displays version information. |
Examples
To display information about the srtool container, run the following command:
srtool version
The command displays output similar to the following:
{
"name": "srtool",
"version": "0.9.21",
"rustc": "1.62.0",
"subwasm": "0.18.0",
"tera": "0.2.1",
"toml": "0.2.1"
}
To display version information for the srtool
command-line interface instead of the container, you can run the following command:
srtool version --version
The command displays output similar to the following:
srtool-version 0.8.0