diff --git a/.github/workflows/crontab_new_template_renewal.yml b/.github/workflows/crontab_new_template_renewal.yml index ab441145..42625d5c 100644 --- a/.github/workflows/crontab_new_template_renewal.yml +++ b/.github/workflows/crontab_new_template_renewal.yml @@ -30,7 +30,7 @@ jobs: let record = http get "https://hub.docker.com/v2/namespaces/sourcescan/repositories/cargo-near/tags" | get results | first; let mod_content = ( - open cargo-near/src/commands/new/new-project-template/Cargo.toml.template --raw | lines + open cargo-near/src/commands/new/new-project-template/Cargo.template.toml --raw | lines | each { |line| if ($line | str starts-with "image = ") { $'image = "sourcescan/cargo-near:($record.name)"' @@ -44,7 +44,7 @@ jobs: | to text ); - $mod_content | save -f cargo-near/src/commands/new/new-project-template/Cargo.toml.template + $mod_content | save -f cargo-near/src/commands/new/new-project-template/Cargo.template.toml git diff diff --git a/README.md b/README.md index 3d9126c2..27fe7f52 100644 --- a/README.md +++ b/README.md @@ -99,26 +99,53 @@ cargo near build Builds a NEAR smart contract along with its [ABI](https://github.com/near/abi) (while in the directory containing contract's Cargo.toml). -By default, this runs a reproducible build in a [Docker](https://docs.docker.com/) container, which: +Running the above command opens a menu with following variants: + +### `non-reproducible-wasm` + +This is a regular build, which behaves much like and is a thin wrapper around a regular `cargo build --target wasm32-unknown-unknown --release`. + +Additional flags for build configuration can be looked up by + +```bash +cargo near build non-reproducible-wasm --help +``` +if needed. + +### `reproducible-wasm` + +This variant runs a reproducible build in a [Docker](https://docs.docker.com/) container, which: 1. runs against source code version, committed to git, ignoring any uncommitted changes 2. requires that `Cargo.lock` of project is created (e.g. via `cargo update`) and added to git. - this enables `--locked` build by downstream `cargo` command. -3. will use configuration in [`[package.metadata.near.reproducible_build]`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.toml.template#L14-L25) - section of contract's `Cargo.toml` and [`package.repository`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.toml.template#L9) field +3. will use configuration in [`[package.metadata.near.reproducible_build]`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.template.toml#L14-L25) + section of contract's `Cargo.toml` and [`package.repository`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.template.toml#L9) field - default values for this section can also be found in `Cargo.toml` of template project, generated by `cargo near new` -Important flags: - -1. `--no-docker` - - flag can be used to perform a regular build with rust toolchain installed onto host, running the `cargo-near` cli. - - *NO*-Docker builds run against actual state of code in filesystem and not against a version, committed to source control. +**What's a reproducible build in context of NEAR?** +Why is it needed? Explanation of these points and a step-by-step tutorial is present at [SourceScan/verification-guide](https://github.com/SourceScan/verification-guide). -2. `--no-locked` - - flag is allowed in *NO*-Docker builds, e.g. to generate a `Cargo.lock` *and* simultaneously build the contract. - - flag is allowed in Docker builds, but - - such builds are not reproducible due to potential update of dependencies and compiled `wasm` mismatch as the result. +
+ Additional (optional) details on possible [package.metadata.near.reproducible_build] configuration

+ +1. available images can be found by this link https://hub.docker.com/r/sourcescan/cargo-near/tags + - [`image`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.template.toml#L18) and [`image_digest`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.template.toml#L19) are straightforward to configure: + ![image_and_digest_pinpoint](./docs/image_and_digest_pinpoint.png) +2. flags of build command, run inside of docker container, can be configured, if needed, by changing [`container_build_command`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.template.toml#L29) field + - base `container_build_command` for images starting with **sourcescan/cargo-near:0.13.0-rust-1.83.0** and after it is `["cargo", "near", "build", "non-reproducible-wasm", "--locked"]`, where the `--locked` flag is required + - base `container_build_command` for images prior to **sourcescan/cargo-near:0.13.0-rust-1.83.0** is `["cargo", "near", "build"]` + - additional flags, if needed, can be looked up on + - `cargo near build non-reproducible-wasm --help` for newer/latest images + - `cargo near build --help` for older ones + - running `docker run -it sourcescan/cargo-near:0.11.0-rust-1.82.0` (or another specific image) and checking the `--help` message of exact `cargo-near` in container may be helpful when in doubt +3. `cargo near` allows parameterizing build with values of environment variables, present at the time of the build and not present in a contract's source code, + by specifying their names in [`passed_env`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.template.toml#L24) array + - supported by **sourcescan/cargo-near:0.10.1-rust-1.82.0** image or later images + - SourceScan/Nearblocks does not support verifying such contracts with additional parameters present in their metadata yet + +

--- @@ -146,22 +173,22 @@ cargo near deploy Builds the smart contract (equivalent to `cargo near build`) and guides you to deploy it to the blockchain. -By default, this runs a reproducible build in a Docker container. +Similar to `build`, running the above command opens a menu with following variants: + +### `build-non-reproducible-wasm` + +This forwards to [non-reproducible-wasm](#non-reproducible-wasm) variant of `build` command. + +### `build-reproducible-wasm` + +This forwards to [reproducible-wasm](#reproducible-wasm) variant of `build` command. `deploy` command from Docker build requires that contract's source code: 1. doesn't have any modified tracked files, any staged changes or any untracked content. 2. has been pushed to remote repository, identified by - [`package.repository`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.toml.template#L9). - -Important flags: - -1. `--no-docker` - - flag can be used to perform a regular *NO*-Docker build *and* deploy. - - Similar to `build` command, in this case none of the git-related concerns and restrictions apply. + [`package.repository`](https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.template.toml#L9). -2. `--no-locked` - - flag is declined for deploy, due to its effects on `build` result ## Contribution diff --git a/cargo-near-build/src/types/near/docker_build/metadata.rs b/cargo-near-build/src/types/near/docker_build/metadata.rs index b751dd65..12e64e8b 100644 --- a/cargo-near-build/src/types/near/docker_build/metadata.rs +++ b/cargo-near-build/src/types/near/docker_build/metadata.rs @@ -211,7 +211,7 @@ impl ReproducibleBuild { "to your contract's Cargo.toml:".cyan() ); println!("{}{}", "- default values for the section can be found at ".cyan(), - "https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.toml.template#L14-L29".magenta()); + "https://github.com/near/cargo-near/blob/main/cargo-near/src/commands/new/new-project-template/Cargo.template.toml#L14-L29".magenta()); println!( "{}{}", "- the same can also be found in Cargo.toml of template project, generated by " diff --git a/cargo-near/src/commands/new/mod.rs b/cargo-near/src/commands/new/mod.rs index 541b1385..8ceb3943 100644 --- a/cargo-near/src/commands/new/mod.rs +++ b/cargo-near/src/commands/new/mod.rs @@ -210,7 +210,7 @@ const NEW_PROJECT_FILES: &[NewProjectFile] = &[ }, NewProjectFile { file_path: "Cargo.toml", - content: include_str!("new-project-template/Cargo.toml.template"), + content: include_str!("new-project-template/Cargo.template.toml"), }, NewProjectFile { file_path: "README.md", diff --git a/cargo-near/src/commands/new/new-project-template/Cargo.toml.template b/cargo-near/src/commands/new/new-project-template/Cargo.template.toml similarity index 100% rename from cargo-near/src/commands/new/new-project-template/Cargo.toml.template rename to cargo-near/src/commands/new/new-project-template/Cargo.template.toml diff --git a/docs/image_and_digest_pinpoint.png b/docs/image_and_digest_pinpoint.png new file mode 100644 index 00000000..bd620565 Binary files /dev/null and b/docs/image_and_digest_pinpoint.png differ