From a30afab151c8237021ad599792f54badf66912ca Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Mon, 2 Feb 2026 22:46:11 +0100 Subject: [PATCH] docs: add npm installation as recommended method with self-contained guides --- README.md | 14 +++- docs/guides/installation.md | 128 +++++++++++++++++++++++------------- docs/quickstart.md | 16 ++++- docs/tutorial.md | 25 ++++++- 4 files changed, 131 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 40b301f4..2935b1d0 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,19 @@ A command-line tool for building and deploying applications on the [Internet Com ## Quick Start -**Install:** See the [Installation Guide](docs/guides/installation.md) for your platform (macOS, Linux, Windows) +**Prerequisites:** [Node.js](https://nodejs.org/) (LTS) + +**Install:** + +```bash +# icp-cli and ic-wasm (required) +npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm + +# Motoko toolchain (for Motoko projects) +npm install -g ic-mops && mops toolchain init +``` + +> **Alternative methods:** See the [Installation Guide](docs/guides/installation.md) for shell script, Homebrew, Rust setup, or platform-specific instructions. Then follow the **[Quickstart](docs/quickstart.md)** to deploy your first canister in under 5 minutes. diff --git a/docs/guides/installation.md b/docs/guides/installation.md index 1451c9f0..9692a996 100644 --- a/docs/guides/installation.md +++ b/docs/guides/installation.md @@ -2,83 +2,93 @@ Set up everything you need to build and deploy canisters on the Internet Computer. -This guide covers: -- Prerequisites (Node.js) -- Installing icp-cli (the core tool) -- Installing language toolchains (Rust or Motoko compilers) -- Installing ic-wasm for optimization +**What you'll install:** -## Prerequisites +| Tool | Purpose | +|------|---------| +| **icp-cli** | Core CLI for building and deploying canisters | +| **ic-wasm** | Optimizes WebAssembly for the Internet Computer | +| **Language toolchain** | Motoko compiler (via mops) or Rust compiler | -[Node.js](https://nodejs.org/) (LTS recommended) is required for: -- Installing the Motoko toolchain -- Building frontend canisters +> **Windows users:** Local networks require [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/), and Motoko requires [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). For the full experience, install both and run commands inside WSL. Rust-only projects deploying to mainnet can run natively on Windows. -> **Rust-only projects:** If you're only building Rust backend canisters without a frontend, you can skip Node.js. +> **Linux users:** The pre-compiled binary requires system libraries that may be missing on minimal installs. If installation fails or `icp` won't start, install these dependencies: +> ```bash +> # Ubuntu/Debian +> sudo apt-get install -y libdbus-1-3 libssl3 ca-certificates +> # Fedora/RHEL +> sudo dnf install -y dbus-libs openssl ca-certificates +> ``` -## Install icp-cli +## Quick Install (Recommended) -**macOS / Linux / WSL:** +**Required:** [Node.js](https://nodejs.org/) (LTS) — needed for npm and for building frontend canisters. + +**1. Install the core tools:** ```bash -curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/download/v0.1.0-beta.6/icp-cli-installer.sh | sh +npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm ``` -Restart your shell or follow the instructions shown by the installer. +**2. Install your language toolchain:** -**Windows:** +**Motoko:** -```ps1 -powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/download/v0.1.0-beta.6/icp-cli-installer.ps1 | iex" +```bash +npm install -g ic-mops && mops toolchain init ``` -Restart your terminal after installation. - -> **Windows notes:** -> - **Local networks** require [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) -> - **Motoko canisters** require [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) — the Motoko compiler doesn't run natively on Windows. Install icp-cli inside WSL and follow the macOS/Linux instructions instead. -> - **Rust canisters** work natively on Windows without WSL - -**Alternative: Homebrew (macOS only)** +**Rust** (if not already installed): ```bash -brew install dfinity/tap/icp-cli +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +rustup target add wasm32-unknown-unknown ``` -To update later: `brew upgrade dfinity/tap/icp-cli` - -### Verify Installation +**3. Verify installation:** ```bash icp --version +ic-wasm --version ``` -## Install Language Toolchains +--- -icp-cli uses your language's compiler to build canisters. Install what you need: +## Alternative Installation Methods -**Rust canisters:** +If you prefer not to use npm, or need platform-specific options, see the sections below. -If you don't have Rust installed, install it from [rustup.rs](https://rustup.rs/): +### icp-cli + +**Shell Script (macOS / Linux / WSL):** ```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.sh | sh ``` -Then add the WebAssembly target: +Restart your shell or follow the instructions shown by the installer. + +**Shell Script (Windows, for Rust-only mainnet projects):** -```bash -rustup target add wasm32-unknown-unknown +```ps1 +powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.ps1 | iex" ``` -**Motoko canisters:** +Restart your terminal after installation. + +**Homebrew (macOS only):** ```bash -npm install -g ic-mops -mops toolchain init +brew install dfinity/tap/icp-cli ``` -## Install ic-wasm (Required for templates and recipes) +To update later: `brew upgrade dfinity/tap/icp-cli` + +> **Note:** Homebrew installs ic-wasm as a dependency, so you can skip the ic-wasm installation below. + +> **Note:** [Node.js](https://nodejs.org/) (LTS recommended) is still required for the Motoko toolchain and frontend canisters when using alternative installation methods. + +### ic-wasm `ic-wasm` is a WebAssembly post-processing tool that optimizes canisters for the Internet Computer. It provides: - **Optimization**: ~10% cycle reduction for Motoko, ~4% for Rust @@ -87,26 +97,52 @@ mops toolchain init - **Shrinking**: Remove unused code and debug symbols **When is it needed?** -- **Required** if using official templates (motoko, rust, hello-world) - all backend templates use recipes that depend on ic-wasm -- **Required** if using official recipes (`@dfinity/motoko`, `@dfinity/rust`) - these recipes inject required metadata using ic-wasm +- **Required** if using official templates (motoko, rust, hello-world) — all backend templates use recipes that depend on ic-wasm +- **Required** if using official recipes (`@dfinity/motoko`, `@dfinity/rust`) — these recipes inject required metadata using ic-wasm - **Not required** if building canisters with custom script steps that don't invoke ic-wasm **Installation:** -**Note:** If you installed icp-cli via Homebrew, ic-wasm is already installed as a dependency. Skip this section. +> **Note:** If you installed icp-cli via Homebrew, ic-wasm is already included. Skip this section. + +**npm (recommended):** + +```bash +npm install -g @icp-sdk/ic-wasm +``` + +**Shell Script (macOS/Linux):** -**macOS/Linux:** ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/ic-wasm/releases/latest/download/ic-wasm-installer.sh | sh ``` -**Windows:** +**Shell Script (Windows):** + ```ps1 powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/ic-wasm/releases/latest/download/ic-wasm-installer.ps1 | iex" ``` Learn more: [ic-wasm repository](https://github.com/dfinity/ic-wasm) +### Language Toolchains + +**Motoko:** + +```bash +npm install -g ic-mops +mops toolchain init +``` + +**Rust:** + +Install from [rustup.rs](https://rustup.rs/): + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +rustup target add wasm32-unknown-unknown +``` + ## Troubleshooting diff --git a/docs/quickstart.md b/docs/quickstart.md index 51afa718..33d8c587 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -2,11 +2,21 @@ Deploy a full-stack app to a local network in under 5 minutes. -## Prerequisites +**Prerequisites:** [Node.js](https://nodejs.org/) (LTS) is required for the installation commands below. -Complete the [Installation Guide](guides/installation.md) first. +> **Windows users:** This quickstart requires [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) (for Motoko) and [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) (for local networks). Install both first, then run all commands inside WSL. -> **Tip:** An npm package for even simpler installation is coming soon. +## Install + +```bash +# icp-cli and ic-wasm (required) +npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm + +# Motoko toolchain (for Motoko projects) +npm install -g ic-mops && mops toolchain init +``` + +> **Alternative methods:** See the [Installation Guide](guides/installation.md) for shell script, Homebrew, or other options. ## Steps diff --git a/docs/tutorial.md b/docs/tutorial.md index c50a6ba9..76371700 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -14,12 +14,33 @@ In this tutorial, you'll deploy two canisters: ## Prerequisites -Complete the **[Installation Guide](guides/installation.md)** first. +**Required:** [Node.js](https://nodejs.org/) (LTS) for the installation commands below. -Verify icp-cli is installed: +> **Windows users:** This tutorial requires [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) (for Motoko) and [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) (for local networks). Install both first, then run all commands inside WSL. + +Install the required tools: + +```bash +# icp-cli and ic-wasm (required) +npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm + +# Motoko toolchain (for Motoko projects) +npm install -g ic-mops && mops toolchain init +``` + +This installs: +- **icp-cli** — the core CLI for building and deploying canisters +- **ic-wasm** — optimizes WebAssembly for the Internet Computer +- **mops** — Motoko package manager, which also installs the Motoko compiler + +> **Alternative methods:** See the [Installation Guide](guides/installation.md) for shell script, Homebrew, Rust setup, or other options. + +Verify the tools are installed: ```bash icp --version +ic-wasm --version +mops --version ``` ## Create a Project