From b14b1cb795ee50750237e53b4f44bcb8cf5fe422 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Thu, 5 Feb 2026 19:02:12 +0100 Subject: [PATCH] docs: update installation to use official Homebrew formulas and ensure consistent ordering --- .claude/CLAUDE.md | 9 +++++++++ README.md | 2 +- docs/guides/installation.md | 39 +++++++++++++------------------------ docs/quickstart.md | 2 +- docs/tutorial.md | 2 +- 5 files changed, 26 insertions(+), 28 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 69d8c23e..8c60248a 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -222,6 +222,15 @@ Documentation follows the Diátaxis framework: - `docs/reference/` — Information-oriented technical specifications - `docs/migration/` — Migration guides (e.g., from dfx) +### Installation Instructions + +- **npm is the recommended installation method** for quickstarts, tutorials, and READMEs +- Only `docs/guides/installation.md` should list all installation options +- Follow DRY: other docs should link to the installation guide rather than duplicating instructions +- Consistent ordering: npm (in Quick Install), then Homebrew, then Shell Script (in Alternative Methods) +- When referencing alternatives in other docs, maintain this order: "Homebrew, shell script, ..." (e.g., "See the Installation Guide for Homebrew, shell script, or other options") +- Both `icp-cli` and `ic-wasm` are available as official Homebrew formulas: `brew install icp-cli` and `brew install ic-wasm` + ### Paths All paths are UTF-8. `PathBuf` and `Path` are the types from `camino`. diff --git a/README.md b/README.md index 8f9d187c..0831f402 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm 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. +> **Alternative methods:** See the [Installation Guide](docs/guides/installation.md) for Homebrew, shell script, 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 e0048194..af817968 100644 --- a/docs/guides/installation.md +++ b/docs/guides/installation.md @@ -20,7 +20,7 @@ Set up everything you need to build and deploy canisters on the Internet Compute > sudo dnf install -y dbus-libs openssl ca-certificates > ``` -## Quick Install (Recommended) +## Quick Install via npm (Recommended) **Required:** [Node.js](https://nodejs.org/) (LTS) — needed for npm and for building frontend canisters. @@ -60,33 +60,23 @@ If you prefer not to use npm, or need platform-specific options, see the section ### icp-cli -**Shell Script (macOS / Linux / WSL):** +**Homebrew (macOS/Linux):** ```bash -curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.sh | sh -``` - -Restart your shell or follow the instructions shown by the installer. - -**Shell Script (Windows, for Rust-only mainnet projects):** - -```ps1 -powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.ps1 | iex" +brew install icp-cli ``` -Restart your terminal after installation. - -**Homebrew (macOS/Linux only):** +**Shell Script (macOS/Linux/WSL):** ```bash -brew install dfinity/tap/icp-cli +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.sh | sh ``` -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. +**Shell Script (Windows):** -> **Note:** [Node.js](https://nodejs.org/) (LTS recommended) is still required for the Motoko toolchain and frontend canisters when using alternative installation methods. +```ps1 +powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.ps1 | iex" +``` ### ic-wasm @@ -103,12 +93,10 @@ To update later: `brew upgrade dfinity/tap/icp-cli` **Installation:** -> **Note:** If you installed icp-cli via Homebrew, ic-wasm is already included. Skip this section. - -**npm (recommended):** +**Homebrew (macOS/Linux):** ```bash -npm install -g @icp-sdk/ic-wasm +brew install ic-wasm ``` **Shell Script (macOS/Linux):** @@ -130,10 +118,11 @@ Learn more: [ic-wasm repository](https://github.com/dfinity/ic-wasm) **Motoko:** ```bash -npm install -g ic-mops -mops toolchain init +curl -fsSL cli.mops.one/install.sh | sh && mops toolchain init ``` +> **Note:** Requires [Node.js](https://nodejs.org/) and a package manager (npm, pnpm, or bun). The shell script installs the latest Mops version stored onchain on ICP. + **Rust:** Install from [rustup.rs](https://rustup.rs/): diff --git a/docs/quickstart.md b/docs/quickstart.md index 33d8c587..3dd4735e 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -16,7 +16,7 @@ npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm npm install -g ic-mops && mops toolchain init ``` -> **Alternative methods:** See the [Installation Guide](guides/installation.md) for shell script, Homebrew, or other options. +> **Alternative methods:** See the [Installation Guide](guides/installation.md) for Homebrew, shell script, or other options. ## Steps diff --git a/docs/tutorial.md b/docs/tutorial.md index 76371700..e575b0bf 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -33,7 +33,7 @@ This installs: - **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. +> **Alternative methods:** See the [Installation Guide](guides/installation.md) for Homebrew, shell script, Rust setup, or other options. Verify the tools are installed: