Docs / On-chain builds / Linking and installing

Linking and installingalpha

What linking does to an on-chain build's output, and how to install the result.

The compiler produces an unlinked module: your compiled code without the Motoko runtime. Linking adds the runtime and makes it a canister module you can install. moxzi build --remote does both and writes a linked, deployable .wasm, as a local build does.

Where linking happens#

	Linked by
`moxzi build`	The linker on your machine
`moxzi build --remote`	The compiler canister. It records the linked module's hash, so a registry can check it later. Against an older canister without on-chain linking, `moxzi` links locally and prints `linking locally`
`moxzi build --remote --no-link`	Nobody. You get the unlinked module

Linking is deterministic: the same unlinked module always produces the same linked module, wherever it's linked.

Linking by hand#

If you have an unlinked module, for example from --no-link or from the canister's getArtifact method, link it with moxzi link:

moxzi build hello.mo --no-link -o unlinked.wasm
moxzi link unlinked.wasm -o hello.wasm

hello.mo -> unlinked.wasm + unlinked.did (57749 bytes, 1 file(s), 50 steps, 0.23s)
compiled by ~/.local/lib/moxzi/compiler.wasm (sha256 9294817c6e9069cbd0e712d0e9dde0ec1b6893d0e7b42d798fa3dd4c8cd772cb), moxzi 0.1.0-alpha.10
unlinked.wasm -> hello.wasm (57749 -> 246457 bytes, 0.36s)

An unlinked module fails wasm-validate and can't be installed. That's expected; link it first.

Installing#

A linked module is an ordinary canister module. Install it with dfx, icp, or the management canister:

dfx canister install my_canister --wasm hello.wasm

Use --gzip when you build to also get hello.wasm.gz, which you need to send a large module as a call argument (for example, to an orchestrator canister).

The .did file#

A remote build writes the .did file it gets from the canister. The interface is also embedded in the module's public candid:service metadata, so tools that read metadata (dfx canister metadata ID candid:service) see it after installation.

Limitations#

Limitation	What to do
A `--compact-rts` link is for `moxzid` and `moxzi-web`, not the IC	Build without `--compact-rts` for canisters