You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 1538e1e
Browse filesBrowse the repository at this point in the historyBrowse files
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## Project Overview
6
+
7
+
`icp-cli-recipes` contains official build recipe templates for Internet Computer (ICP) canisters. Recipes provide standardized, reusable build configurations using Handlebars templates.
8
+
9
+
## Repository Structure
10
+
11
+
```
12
+
recipes/
13
+
├── rust/ # Rust canister recipe
14
+
│ ├── recipe.hbs # Handlebars template
15
+
│ └── README.md # Documentation
16
+
├── motoko/ # Motoko canister recipe
17
+
├── prebuilt/ # Pre-built WASM recipe
18
+
└── asset-canister/ # Asset canister recipe
19
+
```
20
+
21
+
## Recipe Template Structure
22
+
23
+
Each recipe is a Handlebars template (`.hbs`) that generates YAML build/sync configuration:
24
+
25
+
```handlebars
26
+
{{! Documentation comments for parameters }}
27
+
{{! `param: type` Description }}
28
+
29
+
build:
30
+
steps:
31
+
- type: script
32
+
commands:
33
+
- command using {{ param }}
34
+
35
+
{{#if optional_param}}
36
+
- type: script
37
+
commands:
38
+
- conditional command
39
+
{{/if}}
40
+
```
41
+
42
+
## Key Patterns
43
+
44
+
### Required vs Optional Parameters
45
+
46
+
-**Required parameters**: Used directly as `{{ param }}` - will cause strict mode error if missing
47
+
-**Optional parameters**: Wrapped in conditionals `{{#if param}}{{ param }}{{/if}}`
48
+
49
+
### Common Configuration Options
50
+
51
+
Most recipes support these optional parameters:
52
+
-`shrink: boolean` - Optimize WASM with ic-wasm shrink
**IMPORTANT**: When modifying recipes, always verify:
59
+
60
+
1.**Template matches README**: Every parameter in `recipe.hbs` must be documented in the README
61
+
2.**Required vs Optional**: Parameters used directly (not in `{{#if}}`) are required - document accordingly
62
+
3.**Config option descriptions**: Each parameter must accurately describe what it does, verified against the actual behavior in `recipe.hbs`. For example, if `shrink` runs `ic-wasm shrink`, the description should reflect what that command does ("Remove unused functions and debug info to reduce file size")
63
+
4.**YAML syntax in examples**: Use `canisters: - name:` array syntax, not `canister:`
64
+
5.**Recipe type format**: Use `@dfinity/<recipe-name>`, not just `<recipe-name>`
65
+
6.**Prerequisites accuracy**: List actual dependencies (mops vs moc, ic-wasm requirements, etc.)
66
+
7.**Build process accuracy**: Document what the recipe actually does, step by step
67
+
68
+
### Cross-Repository Verification
69
+
70
+
This repository is used by `icp-cli`. When making changes:
71
+
72
+
1. Check `icp-cli/docs/guides/using-recipes.md` for recipe usage examples
73
+
2. Check `icp-cli/examples/` for example projects using recipes
74
+
3. Ensure documentation in both repos stays in sync
75
+
76
+
## Testing Changes
77
+
78
+
Since recipes are Handlebars templates, test by:
79
+
80
+
1. Creating a test project with `icp.yaml` using the recipe
81
+
2. Running `icp project show` to see the expanded configuration
Copy file name to clipboardExpand all lines: README.md
+13-13Lines changed: 13 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,13 +20,13 @@ Official build recipe templates for Internet Computer (ICP) canisters. Recipes p
20
20
Reference a recipe in your `icp.yaml` file:
21
21
22
22
```yaml
23
-
canister:
24
-
name: backend
25
-
recipe:
26
-
type: "@dfinity/rust"
27
-
configuration:
28
-
package: my-canister
29
-
shrink: true
23
+
canisters:
24
+
- name: backend
25
+
recipe:
26
+
type: "@dfinity/rust"
27
+
configuration:
28
+
package: my-canister
29
+
shrink: true
30
30
```
31
31
32
32
### Recipe Naming Convention
@@ -42,12 +42,12 @@ Recipes follow the `@dfinity/<recipe-name>` naming pattern:
42
42
To pin to a specific recipe version, append `@<version>` to the recipe type:
43
43
44
44
```yaml
45
-
canister:
46
-
name: backend
47
-
recipe:
48
-
type: "@dfinity/rust@v3.0.0"
49
-
configuration:
50
-
package: my-canister
45
+
canisters:
46
+
- name: backend
47
+
recipe:
48
+
type: "@dfinity/rust@v3.0.0"
49
+
configuration:
50
+
package: my-canister
51
51
```
52
52
53
53
Without a version specified, the latest stable version is used. View available versions in the [releases page](https://github.com/dfinity/icp-cli-recipes/releases).
| main | string | Yes | Path to the main Motoko source file | |
24
+
| args | string | No | Additional arguments to pass to moc compiler (e.g., `--incremental-gc`) | |
25
+
| candid | string | No | Path to a custom Candid interface file. If not provided, the interface is auto-generated by the Motoko compiler | (auto-generated) |
26
+
| metadata | array | No | Array of key-value pairs for custom metadata | [] |
27
+
| shrink | boolean | No | Remove unused functions and debug info to reduce file size | false |
28
+
| compress | boolean | No | Gzip compress the WASM file | false |
28
29
29
30
## Prerequisites
30
31
31
-
- `moc` (Motoko compiler) must be installed
32
-
- `ic-wasm`tool must be installed for metadata injection and optimization
33
-
- Motoko source files must be available in your project
32
+
- `mops`(Motoko package manager) - this recipe uses `mops toolchain` to manage the Motoko compiler
33
+
- `ic-wasm`(included with icp-cli installation)
34
34
35
-
### Installation
35
+
> **Note:** If you followed the [icp-cli installation guide](https://github.com/dfinity/icp-cli#installation), both `mops` and `ic-wasm` are already installed.
36
36
37
-
To install the Motoko compiler, see: <https://internetcomputer.org/docs/building-apps/getting-started/install>
37
+
### Additional Installation
38
+
39
+
If mops is not installed, see: <https://mops.one/docs/install>
38
40
39
41
## Examples
40
42
41
43
### Basic Example
42
44
43
45
```yaml
44
-
canister:
45
-
name: hello-world
46
-
recipe:
47
-
type: "@dfinity/motoko"
48
-
configuration:
49
-
entry: src/main.mo
46
+
canisters:
47
+
- name: hello-world
48
+
recipe:
49
+
type: "@dfinity/motoko"
50
+
configuration:
51
+
main: src/main.mo
50
52
```
51
53
52
54
### Advanced Example
53
55
54
56
```yaml
55
-
canister:
56
-
name: complex-backend
57
-
recipe:
58
-
type: "@dfinity/motoko"
59
-
configuration:
60
-
entry: src/backend.mo
61
-
shrink: true
62
-
compress: true
63
-
metadata:
64
-
- name: "canister:type"
65
-
value: "backend"
66
-
- name: "language:version"
67
-
value: "0.10.0"
57
+
canisters:
58
+
- name: complex-backend
59
+
recipe:
60
+
type: "@dfinity/motoko"
61
+
configuration:
62
+
main: src/backend.mo
63
+
args: --incremental-gc
64
+
shrink: true
65
+
compress: true
66
+
metadata:
67
+
- name: "canister:type"
68
+
value: "backend"
69
+
- name: "language:version"
70
+
value: "0.10.0"
68
71
```
69
72
70
73
## Build Process
71
74
72
75
When this recipe is executed:
73
76
74
-
1. Checks if the Motoko compiler (`moc`) is installed
75
-
2. Compiles the specified Motoko entry file using `moc`
76
-
3. Moves the resulting WASM file to the output location
77
+
1. Checks if `mops` is installed (used for Motoko toolchain management)
78
+
2. Compiles the specified Motoko entry file using `moc` via `mops toolchain`
79
+
3. Handles Candid interface: auto-generates from Motoko source, or uses the provided `candid` file
77
80
4. Injects compiler version metadata ("moc:version")
78
81
5. Injects template type metadata ("template:type" = "motoko")
79
82
6. Injects any custom metadata specified in the configuration
80
-
7. Optionally optimizes the WASM file if `shrink` is enabled
81
-
8. Optionally compresses the WASM file if `compress` is enabled
83
+
7. Optionally removes unused functions if `shrink` is enabled
84
+
8. Optionally gzip compresses the WASM file if `compress` is enabled
0 commit comments