mops-cli
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMops CLI
Mops CLI
Opinionated guide for Motoko projects. Covers project config, dependency management, type-checking, building, and linting.
面向 Motoko 项目的强约定指南。涵盖项目配置、依赖管理、类型检查、构建和 lint。
Key Principles
关键原则
- No dfx — mops neither invokes nor supports . There is no
dfx, nomops toolchain init, and nomoc-wrapper/mops watch --generate. Always pin--deployinmoc; every command that compiles requires it. Use the newest[toolchain]version. Pinmoctoo if you have replica tests, benchmarks, orpocket-ic— with no pin those commands error, naming--check-deploy. Whenmops toolchain use pocket-ic 15.0.0points at an already-running PocketIC server, no pin is needed and an existing pin is ignored with a warning — do not add one to silence it; unset the variable instead.MOPS_POCKET_IC_URL - No — it is deprecated. Always use
mo:base(mo:core).import Array "mo:core/Array" - All config in — canisters, moc flags, toolchain versions, build settings.
mops.toml - Canister-centric workflow — define all canisters in ; never pass file paths to
[canisters]. Exception: library packages (nomops check) use file paths directly:[canisters].mops check src/**/*.mo
- 不使用 dfx — mops 既不调用也不支持 。不存在
dfx、没有mops toolchain init,也不存在moc-wrapper/mops watch --generate。始终在--deploy中锁定[toolchain];每个会进行编译的命令都需要它。使用最新的moc版本。如果有 replica 测试、benchmark 或moc,也应锁定--check-deploy;未锁定时,这些命令会报错并提示pocket-ic。当mops toolchain use pocket-ic 15.0.0指向已经运行的 PocketIC 服务器时,无需锁定,已有锁定会被忽略并发出警告——不要为了消除警告而添加锁定;应改为取消设置该环境变量。MOPS_POCKET_IC_URL - 不使用 — 它已弃用。始终使用
mo:base(mo:core)。import Array "mo:core/Array" - 所有配置都放在 中 — canister、moc 标志、工具链版本和构建设置。
mops.toml - 以 canister 为中心的工作流 — 在 中定义所有 canister;绝不要向
[canisters]传递文件路径。例外:库软件包(没有mops check)可直接使用文件路径:[canisters]。mops check src/**/*.mo
Project Setup
项目设置
Minimal mops.toml
mops.toml最小 mops.toml
mops.tomltoml
[toolchain]
moc = "1.15.1"
lintoko = "0.11.0"
pocket-ic = "15.0.0" # required for replica tests / benchmarks / --check-deploy
[dependencies]
core = "2.6.1"
[moc]
args = ["--default-persistent-actors", "-W=M0223,M0236,M0237"]
[canisters.backend]
main = "src/backend/main.mo"
[canisters.backend.migrations]
chain = "src/backend/migrations"toml
[toolchain]
moc = "1.15.1"
lintoko = "0.11.0"
pocket-ic = "15.0.0" # required for replica tests / benchmarks / --check-deploy
[dependencies]
core = "2.6.1"
[moc]
args = ["--default-persistent-actors", "-W=M0223,M0236,M0237"]
[canisters.backend]
main = "src/backend/main.mo"
[canisters.backend.migrations]
chain = "src/backend/migrations"check-limit = 10 # optional — speeds up mops check
when the chain gets long
mops checkcheck-limit = 10 # optional — speeds up mops check
when the chain gets long
mops check[canisters.backend.check-stable]
path = "deployed/backend.most"
[build]
outputDir = "src/backend/dist"
args = ["--release"]
[canisters.backend.check-stable]
path = "deployed/backend.most"
[build]
outputDir = "src/backend/dist"
args = ["--release"]
check-wasm = true # optional: analyze final Wasm complexity
check-wasm = true # optional: analyze final Wasm complexity
check-deploy = true # optional: verify fresh PocketIC installation after build
check-deploy = true # optional: verify fresh PocketIC installation after build
Opt-in Wasm optimization (Binaryen wasm-opt) for build + bench
Opt-in Wasm optimization (Binaryen wasm-opt) for build + bench
[optimize]
[optimize]
level = "O3" # default
level = "O3" # default
keep-names = true # default
keep-names = true # default
wasm-opt pin: [toolchain] wasm-opt = "131" (required when [optimize] is set)
wasm-opt pin: [toolchain] wasm-opt = "131" (required when [optimize] is set)
`check-stable` runs ICP's upgrade-time stable-variable compatibility check locally, so incompatible changes fail in `mops check` instead of being rejected when upgrading a live canister. It compares the current code against a `.most` from the deployed version.
Bootstrap that `.most`: new project → `mops deployed init` (empty-actor baseline); already-deployed canister → build from the deployed commit, then `mops deployed`. After every deploy, run `mops deployed` to promote the just-built `.most` (see [`mops deployed`](#mops-deployed) below).
Optional canister fields: `candid` (path to .did for compatibility checking), `initArg` (Candid-encoded init args).
`check-stable` 会在本地运行 ICP 的升级时 stable-variable 兼容性检查,因此不兼容的更改会在 `mops check` 阶段失败,而不是在升级线上 canister 时才被拒绝。它会将当前代码与已部署版本的 `.most` 进行比较。
初始化该 `.most`:新项目 → `mops deployed init`(空 actor 基线);已部署的 canister → 从已部署的提交构建,然后执行 `mops deployed`。每次部署后,运行 `mops deployed`,将刚构建的 `.most` 提升为基线(参见下方的 [`mops deployed`](#mops-deployed))。
可选的 canister 字段:`candid`(用于兼容性检查的 `.did` 路径)、`initArg`(Candid 编码的初始化参数)。Warning Flags
警告标志
-W=M0223,M0236,M0237-W=-W=M0223,M0236,M0237-W=Moc Args Layering
Moc 标志分层
Flags are applied in this order (later overrides earlier):
- — global, all commands (check, build, test, bench, etc.)
[moc].args - — build only (e.g.
[build].args)--release - — auto-injected
[canisters.<name>.migrations](managed by mops)--enhanced-migration - — per-canister
[canisters.<name>].args - CLI — one-off overrides; supported by
-- <flags>,mops check,mops build,mops check-stable,mops generate,mops migrate, andmops testmops bench
标志按以下顺序应用(后面的覆盖前面的):
- — 全局,适用于所有命令(check、build、test、bench 等)
[moc].args - — 仅用于构建(例如
[build].args)--release - — 自动注入
[canisters.<name>.migrations](由 mops 管理)--enhanced-migration - — 按 canister 设置
[canisters.<name>].args - CLI — 一次性覆盖;
-- <flags>、mops check、mops build、mops check-stable、mops generate、mops migrate和mops test均支持mops bench
Core Commands
核心命令
mops install
mops installmops install
mops installbash
mops install # dev flow: keeps mops.lock in sync, self-heals a broken one
mops install --locked # CI flow: fail if mops.lock is missing or would changeRun after cloning or after manual edits. is always maintained — there is no flag to opt out, and no flag (removed in v3). A missing, unparseable, legacy-format or -inconsistent lock is regenerated by a plain , including locks that still carry absolute local paths from older CLIs, and locks that lost a transitive dependency (a locked package declares a dependency that no longer lists — typically a botched merge).
mops.tomlmops.lock--lockmops.tomlmops installdeps--lockedmops buildmops checkmops check-stablemops check-candidmops testmops benchmops generate candidmops test --lockedmops sources--lockedmops install --lockedThe env var no longer affects lockfile behavior (removed in v3). Commit — for applications and libraries alike.
CImops.lockA lock also goes stale when a local dependency's own changes — including one nested further down the chain. regenerates it; fails until the regenerated lock is committed. Note the first after upgrading regenerates the lock of any project that has a dependency, so commit it before running in CI. Projects without dependencies keep their existing lock.
pathmops.tomlmops install--lockedmops installpath--lockedpath{MOPS_ENV}path$MOPS_ENVlocalMOPS_ENVmops install--lockedMOPS_ENV--lockedMOPS_ENV--lockedIntegrity is verified at download time, so no longer re-hashes : editing a dependency in place will not fail the next install. Use for the on-demand on-disk audit.
mops install.mops/mops verifyDownloaded files are always checked before anything enters the cache — against when it already records the package, otherwise against the registry. A committed lock therefore makes verification free, which is why a clean checkout installs without asking the registry about hashes.
mops.lockTwo consequences worth knowing: a corrupt or hand-edited now fails a download (the error names as a possible culprit — restore it from version control; already-cached packages are unaffected), and a package the registry publishes no hashes for still installs, unverified, with a warning.
mops.lockmops.lockPackages download in parallel through a bounded pool. or the env var (works on every installing command) caps simultaneous registry requests; the default derives from the CPU count and the file-descriptor soft limit (4–16). Transient network errors (, , ) retry automatically with the concurrency halved, up to twice. Set only if installs still fail after the retries (an egress proxy capping connections, for example).
mops install --concurrency <n>MOPS_CONCURRENCYfetch failedECONNRESETEMFILEMOPS_CONCURRENCY=1bash
mops install # dev flow: keeps mops.lock in sync, self-heals a broken one
mops install --locked # CI flow: fail if mops.lock is missing or would change克隆仓库或手动编辑 后运行。 始终会被维护——没有选择退出的标志,也没有 标志(v3 中已移除)。如果锁文件缺失、无法解析、采用旧格式,或与 不一致,普通的 会重新生成它;这包括仍携带旧版 CLI 绝对本地路径的锁文件,以及丢失传递依赖的锁文件(已锁定的软件包声明了 中不再列出的依赖,通常由错误合并导致)。
mops.tomlmops.lock--lockmops.tomlmops installdeps--lockedmops buildmops checkmops check-stablemops check-candidmops testmops benchmops generate candidmops test --lockedmops sources--lockedmops install --lockedCImops.lock当本地 依赖项自身的 发生变化时,锁文件也会失效——包括依赖链更深处嵌套的 依赖。 会重新生成锁文件; 则会失败,直到重新生成的锁文件被提交。升级后第一次执行 时,任何包含 依赖的项目都会重新生成锁文件,因此请在 CI 中运行 前先提交它。没有 依赖的项目会保留现有锁文件。
pathmops.tomlpathmops install--lockedmops installpath--lockedpathpath{MOPS_ENV}$MOPS_ENVlocalMOPS_ENVmops install--lockedMOPS_ENV--lockedMOPS_ENV--locked完整性会在下载时验证,因此 不再重新计算 的哈希;就地编辑依赖项不会导致下次安装失败。如需按需审计磁盘内容,请使用 。
mops install.mops/mops verify下载的文件在进入 cache 前总会接受检查——如果 已记录该软件包,则依据 检查,否则依据 registry 检查。因此,提交锁文件后校验便无需额外成本,这也是干净检出的环境无需向 registry 查询哈希即可完成安装的原因。
mops.lockmops.lock有两个值得了解的后果:损坏或手工编辑过的 现在会导致下载失败(错误信息会将 列为可能原因——应从版本控制中恢复;已缓存的软件包不受影响);registry 未发布任何哈希的软件包仍会安装,但无法验证,并发出警告。
mops.lockmops.lock软件包通过设有上限的并发池并行下载。 或 环境变量(适用于所有安装命令)可限制同时发往 registry 的请求数;默认值根据 CPU 数量和文件描述符软限制计算(4–16)。暂时性网络错误(、、)会自动重试,并将并发数减半,最多重试两次。仅当重试后安装仍失败时才设置 (例如出口代理限制了连接数)。
mops install --concurrency <n>MOPS_CONCURRENCYfetch failedECONNRESETEMFILEMOPS_CONCURRENCY=1mops verify
mops verifymops verify
mops verifybash
mops verify # re-hash .mops/ against mops.lock, and mops.lock against the registryCovers GitHub dependencies as well as registry ones.
Exits 1 with the offending files and a recovery hint. This is the replacement for anyone who relied on failing when had been modified.
mops install.mops/bash
mops verify # re-hash .mops/ against mops.lock, and mops.lock against the registry它同时覆盖 GitHub 依赖项和 registry 依赖项。
命令会以状态码 1 退出,并列出违规文件和恢复提示。它取代了依赖 在 被修改时失败这一旧行为。
mops install.mops/mops add <package>
mops add <package>mops add <package>
mops add <package>bash
mops add core # latest version
mops add core@2.5.0 # specific version
mops add --dev test # dev dependency
mops add org/repo # GitHub shorthand (also accepts a full github.com url)
mops add ./pkg # local package directoryUpdates and .
mops.tomlmops.lockAdding a package that is already declared in the other section moves it rather than declaring it twice. replaces the declared version and reports what it replaced; it leaves pinned aliases like alone, and there is no flag to create one — write it by hand.
<pkg>@<version>"core@1.0.0" = "1.0.0"bash
mops add core # latest version
mops add core@2.5.0 # specific version
mops add --dev test # dev dependency
mops add org/repo # GitHub shorthand (also accepts a full github.com url)
mops add ./pkg # local package directory更新 和 。
mops.tomlmops.lock如果添加的软件包已声明在另一个区块中,它会将其移动过去,而不是重复声明。 会替换已声明的版本并报告替换内容;它不会改动类似 的固定别名,也没有用于创建别名的标志——请手动编写。
<pkg>@<version>"core@1.0.0" = "1.0.0"mops check
mops checkmops check
mops checkPrimary correctness command — runs moc check, then check-stable (if configured), then lint (if lintoko is in toolchain).
On moc 1.15.0+, canisters with get stricter upgrade diagnostics: a field the initial actor requires that no migration produces fails as an error instead of only warning (), and compat errors carry a source location. Older moc pins and canisters without are unaffected either way.
[migrations]M0267M0254[migrations]The baseline is always a file — as or as the argument. A source is rejected. See for where the baseline comes from — that differs between a fresh project and an already-deployed canister.
check-stable.most[canisters.<name>.check-stable].pathmops check-stable <baseline.most>.momops deployedbash
mops check # all canisters
mops check backend # single canister
mops check --fix # autofix + check + stable + lint
mops check --no-lint # skip the lint step for one run
mops check --verbose # show moc invocations
mops check -- -Werror # treat warnings as errorsAlways use canister names, not file paths. Per-canister args from are applied automatically.
mops.toml--fix--fix.mops/fix.lock主要的正确性检查命令——运行 moc check,然后运行 check-stable(如果已配置),最后运行 lint(如果工具链中有 lintoko)。
在 moc 1.15.0 及更高版本上,带有 的 canister 会获得更严格的升级诊断:如果初始 actor 要求某个字段,但没有任何 migration 生成该字段,则会报 错误,而不只是警告();兼容性错误也会包含源代码位置。较旧的 moc 固定版本以及没有 的 canister 均不受影响。
[migrations]M0267M0254[migrations]check-stable.most[canisters.<name>.check-stable].pathmops check-stable <baseline.most>.momops deployedbash
mops check # all canisters
mops check backend # single canister
mops check --fix # autofix + check + stable + lint
mops check --no-lint # skip the lint step for one run
mops check --verbose # show moc invocations
mops check -- -Werror # treat warnings as errors始终使用 canister 名称,不要使用文件路径。 中的每个 canister 参数都会自动应用。
mops.toml--fix--fix.mops/fix.lockmops build
mops buildmops build
mops buildbash
mops build # all canisters
mops build backend # single canister
mops build --verbose # show compiler commands
mops build --check-wasm # analyze final Wasm complexity without PocketIC
mops build --no-check-wasm # skip configured [build].check-wasm once
mops build --check-deploy # verify fresh installation on PocketIC
mops build --no-check-deploy # skip configured [build].check-deploy once
mops build -- --ai-errors # pass extra moc flagsProduces , , and files in (default ).
.wasm.did.most[build].outputDir.mops/.buildWith in , runs after candid metadata (default ). Requires a Binaryen pin: . Build commands never write the pin themselves, and a failure fails the build. Pass (on or ) to skip the pass for a single run without editing .
[optimize]mops.tomlwasm-opt-O3 -gmops toolchain use wasm-opt 131wasm-opt--no-optimizebuildbenchmops.tomlWhen or is enabled, Mops runs fast Walrus analysis on the final Wasm without starting PocketIC. Per-function IC0505 complexity below 750,000 is quiet, 750,000 through 899,999 emits an early warning, and 900,000 or more emits a critical warning. output includes actionable function metrics, the three largest complexity contributors, and Motoko correction guidance. The estimate never fails the build. Use to skip configured analysis once.
--check-wasm[build].check-wasm = trueMOPS-WASM-COMPLEXITY--no-check-wasmbash
mops build # all canisters
mops build backend # single canister
mops build --verbose # show compiler commands
mops build --check-wasm # analyze final Wasm complexity without PocketIC
mops build --no-check-wasm # skip configured [build].check-wasm once
mops build --check-deploy # verify fresh installation on PocketIC
mops build --no-check-deploy # skip configured [build].check-deploy once
mops build -- --ai-errors # pass extra moc flags在 (默认 )中生成 、 和 文件。
[build].outputDir.mops/.build.wasm.did.most在 中设置 后,会在 candid 元数据之后运行 (默认 )。需要 Binaryen 固定版本:。构建命令绝不会自行写入该固定版本, 失败也会导致构建失败。若只想单次跳过此步骤,可在 或 上传入 ,而无需编辑 。
mops.toml[optimize]wasm-opt-O3 -gmops toolchain use wasm-opt 131wasm-optbuildbench--no-optimizemops.toml启用 或设置 时,Mops 会在不启动 PocketIC 的情况下,对最终 Wasm 运行快速 Walrus 分析。单函数 IC0505 复杂度低于 750,000 时不会产生提示;750,000 到 899,999 会发出早期警告;900,000 或更高会发出严重警告。 输出包含可操作的函数指标、复杂度贡献最大的三个因素,以及 Motoko 修正建议。该估算永远不会导致构建失败。使用 可单次跳过已配置的分析。
--check-wasm[build].check-wasm = trueMOPS-WASM-COMPLEXITY--no-check-wasmmops deployed
mops deployedmops deployed
mops deployedPost-deploy hook — keeps the on-disk baseline used by in sync with what's actually deployed.
.mostcheck-stablebash
mops deployed init backend # one-time bootstrap: empty-actor baseline + sets [check-stable].path
mops deployed backend # post-deploy: promotes .mops/.build/backend.most → deployed/backend.most
mops deployed # all canistersDefault destination is ; override with in or . It reads built files from (default ); override with . errors if the source is missing — it never regenerates. Run it from your deploy pipeline immediately after a successful deploy.
deployed/<name>.most[deployed].dirmops.toml--dir.most[build].outputDir.mops/.build--build-dirmops deployed.most部署后钩子——使 使用的磁盘上的 基线与实际部署内容保持同步。
check-stable.mostbash
mops deployed init backend # one-time bootstrap: empty-actor baseline + sets [check-stable].path
mops deployed backend # post-deploy: promotes .mops/.build/backend.most → deployed/backend.most
mops deployed # all canisters默认目标为 ;可通过 中的 或 覆盖。它从 (默认 )读取已构建的 文件;可通过 覆盖。如果源 缺失, 会报错——它绝不会重新生成。应在部署流水线中紧接成功部署后运行。
deployed/<name>.mostmops.toml[deployed].dir--dir[build].outputDir.mops/.build.most--build-dir.mostmops deployedmops generate candid
mops generate candidmops generate candid
mops generate candidbash
mops generate candid # all canisters
mops generate candid backend # single canister
mops generate candid backend -o <path> # single canister, ad-hoc path(Re)generates the curated from current Motoko source. With set, overwrites that file. Without it, writes next to (e.g. → ) and sets in . Run after every interface change; commit + together. Same moc invocation as , so the result always passes 's subtype check.
.did[canisters.<name>].candid<name>.didmainmain = "src/Backend.mo"src/backend.did[canisters.<name>].candidmops.toml.didmops.tomlmops buildmops buildbash
mops generate candid # all canisters
mops generate candid backend # single canister
mops generate candid backend -o <path> # single canister, ad-hoc path根据当前 Motoko 源代码重新生成整理好的 。设置 后,覆盖该文件;未设置时,在 旁写入 (例如 → ),并在 中设置 。每次接口变更后都应运行; 和 需一起提交。其 moc 调用方式与 相同,因此结果始终能通过 的 subtype 检查。
.did[canisters.<name>].candidmain<name>.didmain = "src/Backend.mo"src/backend.didmops.toml[canisters.<name>].candid.didmops.tomlmops buildmops buildmops toolchain
mops toolchainmops toolchain
mops toolchainbash
mops toolchain use moc 1.15.1 # pin specific version
mops toolchain use moc latest # pin latest version (non-interactive)
mops toolchain use lintoko 0.11.0 # pin specific version
mops toolchain use pocket-ic 15.0.0 # pin for replica tests / benchmarks / --check-deploy
mops toolchain use wasm-opt 131 # Binaryen for [optimize] (or `latest`)
mops toolchain update moc # update to latest (requires existing [toolchain] entry)
mops toolchain update # update all tools to latest
mops toolchain info <tool> # show release info (latest, pinned, history)
mops toolchain info <tool> --versions # list recent releases, newest first
mops toolchain info <tool> --versions --all # full release history (cache warming)
mops toolchain info <tool> --versions --prerelease # include prereleases
mops toolchain bin moc # print path to binarypocket-ic9.0.0latest9.0.0mops bench--check-deploymops toolchain bin pocket-icmops toolchain use pocket-ic 15.0.0Agent note: without a version opens an interactive picker — do not use in scripts or agents. Always pass a version or . The picker, , and all default to stable releases; pass to include prereleases. only works when the tool already has a entry. works without (first GitHub page by default; pass for full history).
toolchain use <tool>latestlatest--versions--prereleasetoolchain update[toolchain]toolchain info <tool> --versionsmops.toml--allbash
mops toolchain use moc 1.15.1 # pin specific version
mops toolchain use moc latest # pin latest version (non-interactive)
mops toolchain use lintoko 0.11.0 # pin specific version
mops toolchain use pocket-ic 15.0.0 # pin for replica tests / benchmarks / --check-deploy
mops toolchain use wasm-opt 131 # Binaryen for [optimize] (or `latest`)
mops toolchain update moc # update to latest (requires existing [toolchain] entry)
mops toolchain update # update all tools to latest
mops toolchain info <tool> # show release info (latest, pinned, history)
mops toolchain info <tool> --versions # list recent releases, newest first
mops toolchain info <tool> --versions --all # full release history (cache warming)
mops toolchain info <tool> --versions --prerelease # include prereleases
mops toolchain bin moc # print path to binarypocket-ic9.0.0latest9.0.0mops bench--check-deploymops toolchain bin pocket-icmops toolchain use pocket-ic 15.0.0Agent 提示:不带版本执行 会打开交互式选择器——不要在脚本或 Agent 中使用。始终传入版本或 。选择器、 和 默认都只包含稳定版;传入 可包含预发布版本。 仅在工具已有 条目时有效。 无需 即可使用(默认获取 GitHub 第一页;传入 获取完整历史)。
toolchain use <tool>latestlatest--versions--prereleasetoolchain update[toolchain]toolchain info <tool> --versionsmops.toml--allEnhanced migrations
增强型 migration
When is configured, , , and automatically inject . Do not add to — mops will error.
[canisters.<name>.migrations]mops checkmops buildmops check-stable--enhanced-migration--enhanced-migration[canisters.<name>].argsCreate migration files directly in the directory.
chainAfter (or ) confirms the chain compiles, run to produce the wasm artifact.
mops check --fixmops check <canister>mops buildUse , or set for every build, to install each built Wasm on a fresh PocketIC canister and catch module validation, initialization, and installation failures. Requires (a version from up, or a local binary path) — or set to an already-running PocketIC server (the pin is then ignored). Unpinned with no URL, the build errors naming . Use to skip configured validation once. The command uses each canister's , or when omitted. Set to a positive integer byte limit on a canister to check deployment under that limit. PocketIC errors are reported as provided by the client, and installation failures are collected across canisters. Before installation, Mops runs from a temporary empty-actor to each generated . If moc reports incompatibility, Mops emits with the compiler diagnostic and does not check that canister on fresh PocketIC. Eligible siblings are still checked; validate the skipped upgrade against representative baseline state.
mops build --check-deploy[build].check-deploy = true[toolchain] pocket-ic9.0.0MOPS_POCKET_IC_URLmops toolchain use pocket-ic 15.0.0--no-check-deployinitArg()wasmMemoryLimitmoc --stable-compatible.most.mostMOPS-CHECK-DEPLOY-SKIPPEDcheck-limitmops checkmops lintmops buildcheck-limit[canisters.<name>.check-stable].path--stable-baselineM0268check-limitmops check.migrations-<canister>/chain.gitignoremocchainOverride for a single run with (, , ) — e.g. to autofix older, normally-trimmed migrations. On and , also suppresses the pending-migration warning.
check-limit--no-check-limitmops checkmops check-stablemops lintmops check --fix --no-check-limitmops checkmops check-stable--no-check-limitWhen is set, (and the stable check inside ) reports if more migrations are pending than the limit allows — as an error if compat failed (replacing the misleading message), otherwise a warning.
check-limitmops check-stablemops checkmoc配置 后,、 和 会自动注入 。不要在 中添加 ——mops 会报错。
[canisters.<name>.migrations]mops checkmops buildmops check-stable--enhanced-migration[canisters.<name>].args--enhanced-migration直接在 目录中创建 migration 文件。
chain在 (或 )确认 chain 可编译后,运行 生成 wasm 制品。
mops check --fixmops check <canister>mops build使用 ,或为每次构建设置 ,以便将每个构建出的 Wasm 安装到全新的 PocketIC canister 上,并捕获模块验证、初始化和安装失败。需要 ( 或更高版本,或本地二进制路径)——也可将 设置为指向已运行的 PocketIC 服务器(此时会忽略固定版本)。若未固定版本且没有 URL,构建会报错并提示 。使用 可单次跳过已配置的验证。该命令使用每个 canister 的 ;未指定时使用 。在 canister 上设置 为正整数字节限制,以检查该限制下的部署。PocketIC 错误按客户端提供的内容报告,跨 canister 收集安装失败。安装前,Mops 会针对每个生成的 ,从临时空 actor 运行 。如果 moc 报告不兼容,Mops 会发出 ,并附上编译器诊断信息,且不会在全新 PocketIC 上检查该 canister。其他符合条件的同级 canister 仍会被检查;请针对有代表性的基线状态验证被跳过的升级。
mops build --check-deploy[build].check-deploy = true[toolchain] pocket-ic9.0.0MOPS_POCKET_IC_URLmops toolchain use pocket-ic 15.0.0--no-check-deployinitArg()wasmMemoryLimit.most.mostmoc --stable-compatibleMOPS-CHECK-DEPLOY-SKIPPEDcheck-limitmops checkmops lintmops buildcheck-limit[canisters.<name>.check-stable].path--stable-baselineM0268check-limitmops checkchain.migrations-<canister>/.gitignorechain可通过 为单次运行覆盖 (适用于 、、)——例如执行 ,以自动修复通常会被裁掉的旧 migration。在 和 上, 还会抑制待处理 migration 警告。
--no-check-limitcheck-limitmops checkmops check-stablemops lintmops check --fix --no-check-limitmops checkmops check-stable--no-check-limit设置 后,如果待处理的 migration 数量超过限制允许的范围,(以及 内部的 stable 检查)会进行报告——如果兼容性检查失败则报为错误,以替代容易误导的 moc 消息,否则发出警告。
check-limitmops check-stablemops checkmops remove <package>
mops remove <package>mops remove <package>
mops remove <package>bash
mops remove coreRemoves from whichever section declares the package; limits it to . A package declared in both sections is removed from both.
--dev[dev-dependencies]bash
mops remove core从声明该软件包的区块中移除; 将操作限制在 。如果两个区块都声明了某个软件包,则会从两者中移除。
--dev[dev-dependencies]Dependency Management
依赖管理
bash
mops outdated # list outdated deps (caret-bound); exit 1 if any, 2 if the check failed
mops outdated core # check a single package
mops update # rewrite mops.toml versions within caret bound (no major-version crossing)
mops update core # update specific package within caret bound
mops update --major # allow updates that cross major versions
mops update --patch # restrict to patch bumps only (mutually exclusive with --major)
mops update --verbose # verbose output
mops sync # add missing / remove unused packages
mops sync --dry-run # print what would change, write nothingmops updatemops.tomlcargo upgradecargo updatemops outdated2mops.tomlmops sync[toolchain] mocmoc --print-depstesttestsbenchbenchmark[dev-dependencies]bash
mops outdated # list outdated deps (caret-bound); exit 1 if any, 2 if the check failed
mops outdated core # check a single package
mops update # rewrite mops.toml versions within caret bound (no major-version crossing)
mops update core # update specific package within caret bound
mops update --major # allow updates that cross major versions
mops update --patch # restrict to patch bumps only (mutually exclusive with --major)
mops update --verbose # verbose output
mops sync # add missing / remove unused packages
mops sync --dry-run # print what would change, write nothingmops updatemops.tomlcargo upgradecargo updatemops outdatedmops.tomlmops sync[toolchain] mocmoc --print-depstesttestsbenchbenchmark[dev-dependencies]Other Commands
其他命令
mops self update
mops self updatemops self update
mops self updateUpdates a global install (npm/pnpm ) only, and fails if the on PATH did not end up on the new version. For as a project dependency, run instead.
-gmopsic-mopsnpm i -D ic-mops@<version>仅更新全局安装(npm/pnpm ),如果 PATH 上的 最终未切换到新版本,则会失败。如果将 作为项目依赖项,请改用 。
-gmopsic-mopsnpm i -D ic-mops@<version>mops publish
mops publishmops publish
mops publishbash
mops publish # publish to the registry (runs tests/docs/bench by default)
mops publish --dry-run # same local steps as publish; no registry contact / identity
mops publish --dry-run --no-test --no-docs --no-bench # packaging checks only
mops publish --no-test --no-docs --no-bench--dry-run--no-*bash
mops publish # publish to the registry (runs tests/docs/bench by default)
mops publish --dry-run # same local steps as publish; no registry contact / identity
mops publish --dry-run --no-test --no-docs --no-bench # packaging checks only
mops publish --no-test --no-docs --no-bench--dry-run--no-*mops test
mops testmops test
mops testTests live in :
test/*.test.mobash
mops test # run all tests
mops test my-test # filter by name
mops test --mode wasi # use wasmtime (for to_candid/from_candid)
mops test --reporter files # one line per file (default is verbose)
mops test --watch # re-run on file changes
mops test -- -Werror # pass extra moc flagsReplica tests (actor files or ) run on PocketIC — the version from , or an already-running server when is set (no pin needed; canister log output is not streamed in attached mode). Unpinned with no URL, they error naming . Same for and . There is no flag and no dfx replica.
// @testmode replicapocket-ic[toolchain]MOPS_POCKET_IC_URLmops toolchain use pocket-ic 15.0.0mops benchmops watch --test--replica测试位于 :
test/*.test.mobash
mops test # run all tests
mops test my-test # filter by name
mops test --mode wasi # use wasmtime (for to_candid/from_candid)
mops test --reporter files # one line per file (default is verbose)
mops test --watch # re-run on file changes
mops test -- -Werror # pass extra moc flagsReplica 测试(actor 文件或 )在 PocketIC 上运行——使用 中的 版本,或在设置 时使用已运行的服务器(无需固定版本;在 attached 模式下不会流式传输 canister 日志输出)。未固定版本且没有 URL 时,会报错并提示 。 和 同理。不存在 标志,也不存在 dfx replica。
// @testmode replica[toolchain]pocket-icMOPS_POCKET_IC_URLmops toolchain use pocket-ic 15.0.0mops benchmops watch --test--replicamops bench
mops benchmops bench
mops benchBenchmarks live in :
bench/*.bench.mobash
mops bench # run all benchmarks
mops bench my-bench # filter by name
mops bench --gc incremental # select GC
mops bench --save # save results to .bench/<name>.json
mops bench --compare # compare with saved results
mops bench -- -Werror # pass extra moc flagsBenchmark 位于 :
bench/*.bench.mobash
mops bench # run all benchmarks
mops bench my-bench # filter by name
mops bench --gc incremental # select GC
mops bench --save # save results to .bench/<name>.json
mops bench --compare # compare with saved results
mops bench -- -Werror # pass extra moc flagsmops lint
mops lintmops lint
mops lintRuns lintoko (also runs automatically as part of when lintoko is in toolchain):
mops checkbash
mops lint # lint all .mo files
mops lint --fix # autofix lint issues
mops lint <name> # filter to .mo files matching <name>When is set, skips the trimmed chain migrations to match what sees during . To lint a trimmed migration on demand, pass an explicit filter (e.g. ) or to lint the full chain.
[canisters.<name>.migrations].check-limitmops lintmocmops checkmops lint OldMigrationName--no-check-limit运行 lintoko(当工具链中有 lintoko 时,也会作为 的一部分自动运行):
mops checkbash
mops lint # lint all .mo files
mops lint --fix # autofix lint issues
mops lint <name> # filter to .mo files matching <name>设置 后, 会跳过被裁掉的 chain migration,以匹配 moc 在 期间看到的范围。要按需 lint 被裁掉的 migration,请传入显式过滤器(例如 )或 以 lint 完整 chain。
[canisters.<name>.migrations].check-limitmops lintmops checkmops lint OldMigrationName--no-check-limitmops format
mops formatmops format
mops formatbash
mops format # format all .mo files
mops format --check # check formatting without modifyingbash
mops format # format all .mo files
mops format --check # check formatting without modifyingmops watch
mops watchmops watch
mops watchbash
mops watch # errors + warnings + format (the default set)
mops watch --warning # errors + warnings only
mops watch -t # errors + testsError checking is always on. Passing any flag selects only the named tasks, so add / when you want them alongside . Those four are the whole set — there is no or .
-w-f-t--generate--deploybash
mops watch # errors + warnings + format (the default set)
mops watch --warning # errors + warnings only
mops watch -t # errors + tests错误检查始终开启。传入任何标志都只会选择指定的任务,因此当希望与 同时运行时,请添加 / 。仅有这四种任务——不存在 或 。
-t-w-f--generate--deployCommon Patterns
常见模式
Warning suppression for a canister
抑制 canister 的警告
Use per-canister (not global) for suppressions:
argstoml
[canisters.backend]
main = "src/backend/main.mo"
args = ["-A=M0198"]使用每个 canister 的 (不要使用全局 )进行抑制:
argsargstoml
[canisters.backend]
main = "src/backend/main.mo"
args = ["-A=M0198"]New project
新项目
bash
mops init -y
mops toolchain use moc latest # pin latest moc (non-interactive)
mops toolchain use lintoko latest # pin latest lintoko
mops add coreThen configure , , and in .
[moc].args[canisters][build]mops.tomlTo update tools later: or (all tools).
mops toolchain update mocmops toolchain updatebash
mops init -y
mops toolchain use moc latest # pin latest moc (non-interactive)
mops toolchain use lintoko latest # pin latest lintoko
mops add core然后在 中配置 、 和 。
mops.toml[moc].args[canisters][build]以后更新工具: 或 (更新所有工具)。
mops toolchain update mocmops toolchain update