Skip to main content

Compile

Beginner
Developing canisters

After you have created a canister, you need to compile its code into a WebAssembly module and then install it into the canister before it can be deployed.

Canister compilation is done automatically in the background of the dfx deploy command. However, there may be certain workflows where manually compiling code into Wasm is necessary.

How code is compiled to Wasm​

WebAssembly (Wasm) is a platform-independent binary format that can be executed in the Wasm virtual machine. Many modern compilers support Wasm as the compilation target along with traditional targets such as x86 and arm32.

ICP uses vanilla Wasm to compile canister code, then provides a set of system API functions to the Wasm program. Many compilers denote this target as wasm32-unknown-unknown since they do not know the target host environment and do not make any assumptions about the available APIs.

An ICP canister development kit (CDK) of a supported programming language comes with build scripts that link to the system API and compile code to Wasm programs that are compatible with ICP.

Rust and Motoko compile to the wasm32-unknown-unknown target directly under the hood.

Azle and Kybra first compile to the wasm32-wasi target and then convert the Wasm binary to wasm32-unknown-unknown using the wasi2ic tool.

For the convenience of developers, dfx wraps the CDK-specific build scripts and provides the dfx build command to compile the code to a Wasm binary.

Compiling code​

dfx build looks in a project's dfx.json to determine the source code file(s) that should be compiled for a specific canister or all canisters configured within the project.

Compilation happens on the local machine of the developer. dfx build isn't the only workflow that can be used for compiling code. For example, Rust canisters can be compiled using cargo.

Verify the location of your canister's source code files and their file names. If necessary, edit your project's dfx.json file to reflect the current intended configuration.

To compile canisters from within the project's directory, use:

dfx build <canister-name> --network=<NETWORK>

When this command is executed, the following steps happen:

  • The source code for a canister is compiled into a Wasm module.

  • If a canister is written in Motoko, type declarations are automatically generated using Candid.

  • If a canister is written in Rust, the build process checks for Rust vulnerabilities.