Skip to content

Commit d838a38

Browse files
lwshanglwshang
authored
feat: expose canister upgrade options in CLI (#3893)
1 parent 6248fe1 commit d838a38

File tree

11 files changed

+296
-105
lines changed

11 files changed

+296
-105
lines changed

‎CHANGELOG.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,17 @@
22

33
# UNRELEASED
44

5+
### feat: expose canister upgrade options in CLI
6+
7+
`dfx canister install` and `dfx deploy` takes options `--skip-pre-upgrade` and `--wasm-memory-persistence`.
8+
9+
`dfx deploy --mode` now takes the same possible values as `dfx canister install --mode`: "install", "reinstall", "upgrade" and "auto".
10+
11+
In "auto" mode, the upgrade options are hints which only take effects when the actual install mode is "upgrade".
12+
13+
To maintain backward compatibility, a minor difference between the two commands remains.
14+
If the `--mode` is not set, `dfx deploy` defaults to "auto", while `dfx canister install` defaults to "install".
15+
516
### feat: Also report Motoko stable compatibility warnings
617

718
Report upgrade compatibility warnings for Motoko, such as deleted stable variables, in addition to compatibility errors.

‎docs/cli-reference/dfx-canister.mdx

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -534,17 +534,19 @@ dfx canister install [option] [--all | canister_name]
534534

535535
You can use the following options with the `dfx canister install` command.
536536

537-
| Option | Description |
538-
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
539-
| `--argument <argument>` | Specifies an argument to pass to the canister during installation. |
540-
| `--argument-type <argument-type>` | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] |
541-
| `--argument-file <argument-file>` | Specifies the file from which to read the argument to pass to the init method. Stdin may be referred to as `-`. |
542-
| `--async-call` | Enables you to continue without waiting for the result of the installation to be returned by polling the Internet Computer or the local canister execution environment. |
543-
| `-m`, `--mode <mode>` | Specifies whether you want to `install`, `reinstall`, or `upgrade` canisters. Defaults to `install`. For more information about installation modes and canister management, see [managing canisters](/docs/current/developer-docs/smart-contracts/maintain/settings). |
544-
| `--no-wallet` | Performs the call with the user Identity as the Sender of messages. Bypasses the Wallet canister. Enabled by default. |
545-
| `--no-asset-upgrade` | Skips upgrading the asset canister, to only install the assets themselves. |
546-
| `--upgrade-unchanged` | Upgrade the canister even if the .wasm did not change. |
547-
| `--wasm <file.wasm>` | Specifies a particular Wasm file to install, bypassing the dfx.json project settings. |
537+
| Option | Description |
538+
|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
539+
| `--argument <argument>` | Specifies an argument to pass to the canister during installation. |
540+
| `--argument-type <argument-type>` | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] |
541+
| `--argument-file <argument-file>` | Specifies the file from which to read the argument to pass to the init method. Stdin may be referred to as `-`. |
542+
| `--async-call` | Enables you to continue without waiting for the result of the installation to be returned by polling the Internet Computer or the local canister execution environment. |
543+
| `-m`, `--mode <mode>` | Specifies whether you want to `install`, `reinstall`, or `upgrade` canisters. Defaults to `install`. For more information about installation modes and canister management, see [managing canisters](/docs/current/developer-docs/smart-contracts/maintain/settings). |
544+
| `--no-wallet` | Performs the call with the user Identity as the Sender of messages. Bypasses the Wallet canister. Enabled by default. |
545+
| `--no-asset-upgrade` | Skips upgrading the asset canister, to only install the assets themselves. |
546+
| `--upgrade-unchanged` | Upgrade the canister even if the .wasm did not change. |
547+
| `--wasm <file.wasm>` | Specifies a particular Wasm file to install, bypassing the dfx.json project settings. |
548+
| `--skip-pre-upgrade` | Skip the pre_upgrade hook on upgrade. This requires the upgrade/auto mode. |
549+
| `--wasm-memory-persistence <mode>` | Keep or replace the Wasm main memory on upgrade. Possible values: keep, replace. This requires the upgrade/auto mode. |
548550

549551
#### Specifies the argument to pass to the init entrypoint
550552

‎docs/cli-reference/dfx-deploy.mdx

Lines changed: 20 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -26,23 +26,26 @@ dfx deploy [options] [canister_name]
2626

2727
You can use the following options with the `dfx deploy` command.
2828

29-
| Option | Description |
30-
|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
31-
| `--network <network>` | Overrides the environment to connect to. By default, the local canister execution environment is used. |
32-
| `--playground ` | Alias for `--network playground`. By default, canisters on this network are borrowed from the Motoko Playground. |
33-
| `--ic ` | Alias for `--network ic`. |
34-
| `--argument <argument>` | Specifies an argument to pass to the canister during installation. |
35-
| `--argument-type <argument-type>` | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] |
36-
| `--argument-file <argument-file>` | Specifies the file from which to read the argument to pass to the init method. Stdin may be referred to as `-`. |
37-
| `--created-at-time <timestamp>` | Transaction timestamp, in nanoseconds, for use in controlling transaction deduplication, default is system time. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- |
38-
| `--from-subaccount <subaccount>` | Subaccount of the selected identity to spend cycles from. |
39-
| `--with-cycles <number-of-cycles>` | Enables you to specify the initial number of cycles for a canister in a project. |
40-
| `--specified-id <PRINCIPAL>` | Attempts to create the canister with this Canister ID |
41-
| `--by-proposal` | Upload proposed changed assets, but do not commit them. Follow up by calling either commit_proposed_batch() or delete_batch(). |
42-
| `--compute-evidence` | Build a frontend canister, determine batch operations required to synchronize asset canister contents, and compute a hash over those operations. Displays this hash ("evidence"), which should match the evidence displayed by `dfx deploy --by-proposal`. |
43-
| `--subnet-type <subnet-type>` | Specify the subnet type to create the canister on. If no subnet type is provided, the canister will be created on a random default application subnet. |
44-
| `--subnet <subnet-principal>` | Specify the subnet to create the canister on. If no subnet is provided, the canister will be created on a random default application subnet. |
45-
| `--next-to <canister-principal>` | Create canisters on the same subnet as this canister. |
29+
| Option | Description |
30+
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
31+
| `--network <network>` | Overrides the environment to connect to. By default, the local canister execution environment is used. |
32+
| `--playground ` | Alias for `--network playground`. By default, canisters on this network are borrowed from the Motoko Playground. |
33+
| `--ic ` | Alias for `--network ic`. |
34+
| `--argument <argument>` | Specifies an argument to pass to the canister during installation. |
35+
| `--argument-type <argument-type>` | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] |
36+
| `--argument-file <argument-file>` | Specifies the file from which to read the argument to pass to the init method. Stdin may be referred to as `-`. |
37+
| `--created-at-time <timestamp>` | Transaction timestamp, in nanoseconds, for use in controlling transaction deduplication, default is system time. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- |
38+
| `--from-subaccount <subaccount>` | Subaccount of the selected identity to spend cycles from. |
39+
| `-m`, `--mode <mode>` | Specifies whether you want to `install`, `reinstall`, or `upgrade` canisters. Defaults to `auto`. For more information about installation modes and canister management, see [managing canisters](/docs/current/developer-docs/smart-contracts/maintain/settings). |
40+
| `--with-cycles <number-of-cycles>` | Enables you to specify the initial number of cycles for a canister in a project. |
41+
| `--specified-id <PRINCIPAL>` | Attempts to create the canister with this Canister ID |
42+
| `--by-proposal` | Upload proposed changed assets, but do not commit them. Follow up by calling either commit_proposed_batch() or delete_batch(). |
43+
| `--compute-evidence` | Build a frontend canister, determine batch operations required to synchronize asset canister contents, and compute a hash over those operations. Displays this hash ("evidence"), which should match the evidence displayed by `dfx deploy --by-proposal`. |
44+
| `--subnet-type <subnet-type>` | Specify the subnet type to create the canister on. If no subnet type is provided, the canister will be created on a random default application subnet. |
45+
| `--subnet <subnet-principal>` | Specify the subnet to create the canister on. If no subnet is provided, the canister will be created on a random default application subnet. |
46+
| `--next-to <canister-principal>` | Create canisters on the same subnet as this canister. |
47+
| `--skip-pre-upgrade` | Skip the pre_upgrade hook on upgrade. This requires the upgrade/auto mode. |
48+
| `--wasm-memory-persistence <mode>` | Keep or replace the Wasm main memory on upgrade. Possible values: keep, replace. This requires the upgrade/auto mode. |
4649

4750
### Specifies the argument to pass to the init entrypoint
4851

0 commit comments

Comments
 (0)