From 046ff2375644d4851a02fa781215b220cc7d1de3 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Thu, 16 Apr 2026 15:31:02 +0200 Subject: [PATCH 1/2] docs: developer tools overview guide --- docs/guides/tools/overview.md | 147 ++++++++++++++++++++++++++++++---- 1 file changed, 132 insertions(+), 15 deletions(-) diff --git a/docs/guides/tools/overview.md b/docs/guides/tools/overview.md index fc6680dc..989dafbe 100644 --- a/docs/guides/tools/overview.md +++ b/docs/guides/tools/overview.md @@ -5,22 +5,139 @@ sidebar: order: 2 --- -TODO: Write content for this page. +Developer tools are used to create, manage, and interact with canisters. ICP provides tooling across several categories: command-line tools, canister development kits (CDKs), browser-based IDEs, Wasm optimization utilities, and Candid tooling. - -Overview of the ICP developer toolchain. Cover icp-cli (project management, deployment, identity), CDKs (Rust CDK via ic-cdk, Motoko compiler), icp.ninja playground for browser-based development, VS Code extensions, ic-wasm for Wasm optimization, and didc for Candid tools. Each tool gets a brief description and link to its documentation. Do not duplicate tool docs -- link out. +## Command-line tools - -- Portal: building-apps/developer-tools/dev-tools-overview.mdx, cdks/index.mdx, icp-ninja.mdx -- icskills: icp-cli -- icp-cli docs: https://cli.internetcomputer.org/ -- Rust CDK: https://docs.rs/ic-cdk/latest/ic_cdk/ +### icp-cli - -Also mention: Quill (cold wallet signing, NNS governance), icp-cli telemetry opt-out, and link to icp-cli's creating-recipes.md and creating-templates.md for advanced users. +`icp-cli` is the primary tool for building and deploying applications on the Internet Computer. It manages the full development lifecycle: creating projects, building canisters, deploying to local or mainnet environments, managing identities, and handling cycles and ICP tokens. - -- getting-started/quickstart -- icp-cli in action -- guides/tools/migrating-from-dfx -- migration guide -- languages/rust/index -- Rust CDK details -- languages/motoko/index -- Motoko tooling +Key features: +- **Recipes** — reusable, versioned build templates for Rust, Motoko, and asset canisters +- **Environments** — named deployment targets that combine a network, canister set, and settings (e.g., local, staging, production) +- **Project scaffolding** — `icp new` bootstraps new projects from official templates + +Install via npm (requires Node.js ≥ 22): + +```bash +npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm +``` + +Or via Homebrew: + +```bash +brew install icp-cli +``` + +Verify: + +```bash +icp --version +``` + +Full documentation: [cli.internetcomputer.org](https://cli.internetcomputer.org/) + +For advanced users, icp-cli supports authoring custom recipes and project templates: +- [Creating recipes](https://cli.internetcomputer.org/guides/creating-recipes) — encode build conventions as reusable Handlebars templates +- [Creating templates](https://cli.internetcomputer.org/guides/creating-templates) — scaffold new projects with `icp new` + +#### Telemetry opt-out + +`icp` collects anonymous usage data (command names, platform, version, success/failure) to help prioritize features. No personally identifiable information, project names, file paths, or canister IDs are collected. + +To opt out: + +```bash +icp settings telemetry false +``` + +Or set `DO_NOT_TRACK=1` in your environment. Telemetry is automatically disabled in CI when the `CI` environment variable is set. + +### ic-wasm + +`ic-wasm` is a utility for optimizing and annotating WebAssembly modules for the Internet Computer. It shrinks Wasm binary size, embeds Candid metadata, and strips unused sections. The official Rust and Motoko recipes use `ic-wasm` automatically — you only need to call it directly when using custom build steps. + +Install: + +```bash +npm install -g @icp-sdk/ic-wasm +# or +brew install ic-wasm +``` + +### Quill + +Quill is a minimalistic, offline-first CLI for signing and sending governance messages — NNS and SNS proposals, neuron management — from air-gapped machines. Unlike `icp-cli`, Quill is designed for cold wallet workflows: you generate signed messages on an offline device, then submit them from a networked machine. + +Quill is suited for: +- Submitting NNS governance proposals +- Managing SNS neurons from a hardware wallet or cold key + +Resources: +- [Quill GitHub repo](https://github.com/dfinity/quill) + +## Canister development kits (CDKs) + +A canister development kit (CDK) provides a programming language with the libraries and toolchain support needed to compile code to WebAssembly and interact with the ICP system API. + +### Motoko + +Motoko is ICP's native programming language, designed around the actor model, orthogonal persistence, and asynchronous message passing. It compiles directly to WebAssembly and includes a standard library (`mo:core`) with modules for common data structures, cryptography, and system interaction. + +For language documentation, see [languages/motoko](../../languages/motoko/index.md). + +### Rust CDK (`ic-cdk`) + +The Rust CDK (`ic-cdk`) is the official DFINITY-maintained library for building canisters in Rust. It exposes the ICP system API as safe Rust abstractions, including: +- `ic_cdk::api` — system calls (time, caller, stable memory, management canister) +- `ic_cdk_timers` — periodic timers and one-shot timers +- `ic_cdk_macros` — `#[update]`, `#[query]`, `#[init]`, and other attribute macros + +API reference: [docs.rs/ic-cdk](https://docs.rs/ic-cdk/latest/ic_cdk/) + +For Rust-specific guides, see [languages/rust](../../languages/rust/index.md). + +### Community CDKs + +Several community-maintained CDKs extend ICP to other languages: + +| Language | CDK | Resources | +|----------|-----|-----------| +| TypeScript / JavaScript | [Azle](https://github.com/demergent-labs/azle) | [Documentation](https://demergent-labs.github.io/azle/azle.html) | +| Python | [Kybra](https://github.com/demergent-labs/kybra) | [Documentation](https://demergent-labs.github.io/kybra) | +| C++ | [icpp-pro](https://github.com/icppWorld/icpp-pro) | [Documentation](https://docs.icpp.world) | +| MoonBit | [moonbit-ic-cdk](https://github.com/eliezhao/moonbit-ic-cdk) | GitHub repo | + +Community CDKs are maintained independently of DFINITY. Check each project's documentation for current support status. + +## Browser-based IDE + +### ICP Ninja + +[ICP Ninja](https://icp.ninja) is a web-based IDE for writing and deploying ICP canisters directly from a browser — no local toolchain required. It provides a gallery of example projects (Motoko and Rust backends, React frontends) that you can browse, edit, and deploy to the mainnet in one click. + +Deployed canisters remain live for 20 minutes. You can redeploy to reset the timer, or download the project files to continue development locally with icp-cli. + +Limitations: +- Projects are limited to 5 MB and 2 canisters +- ICP Ninja is not a replacement for icp-cli for production workflows + +## Candid tools + +### didc + +`didc` is the Candid command-line tool for working with Candid interfaces: encoding and decoding values, checking `.did` files, generating bindings, and testing Candid compatibility. + +Resources: +- [Candid GitHub repo](https://github.com/dfinity/candid) +- Candid specification: [reference/candid-spec.md](../../reference/candid-spec.md) + +## Next steps + +- **Start building:** [Quickstart](../../getting-started/quickstart.md) — deploy your first canister with icp-cli +- **Coming from dfx?** [Migrating from dfx](migrating-from-dfx.md) — command mapping and configuration changes +- **Rust development:** [Rust language guide](../../languages/rust/index.md) +- **Motoko development:** [Motoko language guide](../../languages/motoko/index.md) + + From 2670e1fa5844e7ad3e505f226ef6acd9c4e6d057 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Thu, 16 Apr 2026 17:08:39 +0200 Subject: [PATCH 2/2] fix(tools/overview): address PR #78 feedback - Fix Node.js version requirement: change ">= 22" to "LTS" to match the authoritative npm/icp-cli/package.json (>=18.0.0) and installation guide - Add brew install ic-wasm to Homebrew install path (was missing, causing recipe failures for users who follow the Homebrew path) - Add Editor tooling section with Motoko VS Code extension (vscode-motoko), as noted in portal source material and the content brief - Add didc install pointer (prebuilt binaries from releases page) - Rename "Coming from dfx?" to "Migrating from the legacy CLI?" in Next steps to avoid naming the deprecated tool in prose - Update Upstream comment to include portal level-1 dev-env and candid README --- docs/guides/tools/overview.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/guides/tools/overview.md b/docs/guides/tools/overview.md index 989dafbe..41321145 100644 --- a/docs/guides/tools/overview.md +++ b/docs/guides/tools/overview.md @@ -18,7 +18,7 @@ Key features: - **Environments** — named deployment targets that combine a network, canister set, and settings (e.g., local, staging, production) - **Project scaffolding** — `icp new` bootstraps new projects from official templates -Install via npm (requires Node.js ≥ 22): +Install via npm (requires Node.js LTS): ```bash npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm @@ -28,6 +28,7 @@ Or via Homebrew: ```bash brew install icp-cli +brew install ic-wasm ``` Verify: @@ -123,12 +124,22 @@ Limitations: - Projects are limited to 5 MB and 2 canisters - ICP Ninja is not a replacement for icp-cli for production workflows +## Editor tooling + +### Motoko VS Code extension + +The [Motoko extension for VS Code](https://github.com/dfinity/vscode-motoko) (`dfinity/vscode-motoko`) adds Motoko language support to VS Code: syntax highlighting, type checking, auto-completion, and inline diagnostics. + +Install by searching for "Motoko" in the VS Code extensions panel, or visit the [vscode-motoko repository](https://github.com/dfinity/vscode-motoko) for details. + ## Candid tools ### didc `didc` is the Candid command-line tool for working with Candid interfaces: encoding and decoding values, checking `.did` files, generating bindings, and testing Candid compatibility. +Install: download a prebuilt binary from the [releases page](https://github.com/dfinity/candid/releases). + Resources: - [Candid GitHub repo](https://github.com/dfinity/candid) - Candid specification: [reference/candid-spec.md](../../reference/candid-spec.md) @@ -136,8 +147,8 @@ Resources: ## Next steps - **Start building:** [Quickstart](../../getting-started/quickstart.md) — deploy your first canister with icp-cli -- **Coming from dfx?** [Migrating from dfx](migrating-from-dfx.md) — command mapping and configuration changes +- **Migrating from the legacy CLI?** [Migration guide](migrating-from-dfx.md) — command mapping and configuration changes - **Rust development:** [Rust language guide](../../languages/rust/index.md) - **Motoko development:** [Motoko language guide](../../languages/motoko/index.md) - +