Skip to content

Commit

Permalink
Merge branch 'master' into vincent/SDK-1636
Browse files Browse the repository at this point in the history
  • Loading branch information
@vincent-dfinity
vincent-dfinity authored Sep 3, 2024
2 parents 89afa0c + d838a38 commit 63bd235
Show file tree
Hide file tree
Showing 11 changed files with 296 additions and 105 deletions.
11 changes: 11 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,17 @@

# UNRELEASED

### feat: expose canister upgrade options in CLI

`dfx canister install` and `dfx deploy` takes options `--skip-pre-upgrade` and `--wasm-memory-persistence`.

`dfx deploy --mode` now takes the same possible values as `dfx canister install --mode`: "install", "reinstall", "upgrade" and "auto".

In "auto" mode, the upgrade options are hints which only take effects when the actual install mode is "upgrade".

To maintain backward compatibility, a minor difference between the two commands remains.
If the `--mode` is not set, `dfx deploy` defaults to "auto", while `dfx canister install` defaults to "install".

### feat: Also report Motoko stable compatibility warnings

Report upgrade compatibility warnings for Motoko, such as deleted stable variables, in addition to compatibility errors.
Expand Down
24 changes: 13 additions & 11 deletions docs/cli-reference/dfx-canister.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -534,17 +534,19 @@ dfx canister install [option] [--all | canister_name]

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

| Option | Description |
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--argument <argument>` | Specifies an argument to pass to the canister during installation. |
| `--argument-type <argument-type>` | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] |
| `--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 `-`. |
| `--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. |
| `-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). |
| `--no-wallet` | Performs the call with the user Identity as the Sender of messages. Bypasses the Wallet canister. Enabled by default. |
| `--no-asset-upgrade` | Skips upgrading the asset canister, to only install the assets themselves. |
| `--upgrade-unchanged` | Upgrade the canister even if the .wasm did not change. |
| `--wasm <file.wasm>` | Specifies a particular Wasm file to install, bypassing the dfx.json project settings. |
| Option | Description |
|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--argument <argument>` | Specifies an argument to pass to the canister during installation. |
| `--argument-type <argument-type>` | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] |
| `--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 `-`. |
| `--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. |
| `-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). |
| `--no-wallet` | Performs the call with the user Identity as the Sender of messages. Bypasses the Wallet canister. Enabled by default. |
| `--no-asset-upgrade` | Skips upgrading the asset canister, to only install the assets themselves. |
| `--upgrade-unchanged` | Upgrade the canister even if the .wasm did not change. |
| `--wasm <file.wasm>` | Specifies a particular Wasm file to install, bypassing the dfx.json project settings. |
| `--skip-pre-upgrade` | Skip the pre_upgrade hook on upgrade. This requires the upgrade/auto mode. |
| `--wasm-memory-persistence <mode>` | Keep or replace the Wasm main memory on upgrade. Possible values: keep, replace. This requires the upgrade/auto mode. |

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

Expand Down
37 changes: 20 additions & 17 deletions docs/cli-reference/dfx-deploy.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,23 +26,26 @@ dfx deploy [options] [canister_name]

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

| Option | Description |
|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--network <network>` | Overrides the environment to connect to. By default, the local canister execution environment is used. |
| `--playground ` | Alias for `--network playground`. By default, canisters on this network are borrowed from the Motoko Playground. |
| `--ic ` | Alias for `--network ic`. |
| `--argument <argument>` | Specifies an argument to pass to the canister during installation. |
| `--argument-type <argument-type>` | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] |
| `--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 `-`. |
| `--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- |
| `--from-subaccount <subaccount>` | Subaccount of the selected identity to spend cycles from. |
| `--with-cycles <number-of-cycles>` | Enables you to specify the initial number of cycles for a canister in a project. |
| `--specified-id <PRINCIPAL>` | Attempts to create the canister with this Canister ID |
| `--by-proposal` | Upload proposed changed assets, but do not commit them. Follow up by calling either commit_proposed_batch() or delete_batch(). |
| `--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`. |
| `--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. |
| `--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. |
| `--next-to <canister-principal>` | Create canisters on the same subnet as this canister. |
| Option | Description |
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--network <network>` | Overrides the environment to connect to. By default, the local canister execution environment is used. |
| `--playground ` | Alias for `--network playground`. By default, canisters on this network are borrowed from the Motoko Playground. |
| `--ic ` | Alias for `--network ic`. |
| `--argument <argument>` | Specifies an argument to pass to the canister during installation. |
| `--argument-type <argument-type>` | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] |
| `--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 `-`. |
| `--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- |
| `--from-subaccount <subaccount>` | Subaccount of the selected identity to spend cycles from. |
| `-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). |
| `--with-cycles <number-of-cycles>` | Enables you to specify the initial number of cycles for a canister in a project. |
| `--specified-id <PRINCIPAL>` | Attempts to create the canister with this Canister ID |
| `--by-proposal` | Upload proposed changed assets, but do not commit them. Follow up by calling either commit_proposed_batch() or delete_batch(). |
| `--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`. |
| `--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. |
| `--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. |
| `--next-to <canister-principal>` | Create canisters on the same subnet as this canister. |
| `--skip-pre-upgrade` | Skip the pre_upgrade hook on upgrade. This requires the upgrade/auto mode. |
| `--wasm-memory-persistence <mode>` | Keep or replace the Wasm main memory on upgrade. Possible values: keep, replace. This requires the upgrade/auto mode. |

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

Expand Down
Loading

0 comments on commit 63bd235

Please sign in to comment.