Docs for Odra 2.11 build tooling: test arguments, link_contract_crates, faster builds

docusaurus/docs/advanced/06-building-manually.md

@@ -22,6 +22,15 @@ ODRA_MODULE=my_contract cargo build --release --target wasm32-unknown-unknown --
 Odra uses the environment variable `ODRA_MODULE` to determine which contract to build.
 :::
 
+:::note
+`cargo odra` (0.2.1 and newer) sets two more variables: `ODRA_MODULE__<crate>=<Contract>`, named after
+the crate that defines the contract (`ODRA_MODULE__my_project=MyContract`), and
+`ODRA_BUILD_PROTOCOL=2`. With them Odra 2.11.0 rebuilds only that crate when you switch to another
+contract, not every crate that uses the `odra-build` build script (`odra-modules`, for example),
+which makes building many contracts faster. A manual build works with `ODRA_MODULE` alone. When you
+mix manual builds with `cargo odra`, expect one extra rebuild each time you switch between them.
+:::
+
 Assuming that project's crate is named `my_project`, this command will build
 the `my_contract` contract in release mode and generate the wasm file.
 The file will be put into the `target/wasm32-unknown-unknown/release` directory under

docusaurus/docs/basics/01-cargo-odra.md

@@ -103,25 +103,40 @@ Keep in mind that this is a lot slower than `OdraVM` and you cannot use the debu
 This is why `OdraVM` was created and should be your first choice when developing contracts.
 Of course, testing all of your code against a blockchain VM is a must in the end.
 
-If you want to run only some of the tests, you can pass arguments to the `cargo test` command
-(which is run in the background obviously):
+Cargo Odra runs `cargo test` in the background. Whatever follows `--` goes to the test binary, just
+like after `cargo test --`. If you want to run only the tests whose names contain the word `two`,
+you can execute:
 
 ```bash
-cargo odra test -- this-will-be-passed-to-cargo-test
+cargo odra test -- two
 ```
 
-If you want to run tests which names contain the word `two`, you can execute:
+Of course, you can do the same when using the backend:
 
 ```bash
-cargo odra test -- two
+cargo odra test -b casper -- two
 ```
 
-Of course, you can do the same when using the backend:
+To see what the tests print:
 
 ```bash
-cargo odra test -b casper -- two
+cargo odra test -- --nocapture
 ```
 
+Arguments for `cargo test` itself go before a second `--`:
+
+```bash
+cargo odra test -- --release -- --nocapture
+cargo odra test -- --features my-feature --
+```
+
+:::note
+This is how `cargo-odra` 0.2.1 and newer work. In older versions only the name filter
+(`cargo odra test -- two`) worked: other arguments were appended to those of `cargo test`, so
+`cargo odra test -- --nocapture` failed. There, run `cargo test -- --nocapture` directly
+(`ODRA_BACKEND=casper cargo test -- --nocapture` for the Casper backend, after `cargo odra build`).
+:::
+
 ## Building code
 
 You can also build the code itself and generate the output contracts without running the tests.

docusaurus/docs/basics/02-directory-structure.md

@@ -111,6 +111,8 @@ A small build script that Odra uses to set up code generation. You don't need to
 This is the folder where scripts that will be used to generate code or schemas live.
 `build_contract.rs` and `build_schema.rs` are generated by `cargo odra new` and are used by
 `cargo odra build`, `cargo odra test` and `cargo odra schema` - you don't need to modify those.
+Their `odra::link_contract_crates!();` line links the crates of the contracts that `Odra.toml` takes
+from your dependencies, see [Odra.toml](./03-odra-toml.md#linking-the-other-crate).
 `cli.rs` is different: it is a starting point for your own deployment and interaction commands,
 and it is meant to be edited. See [Odra CLI](../tutorials/odra-cli.md).
 

docusaurus/docs/basics/03-odra-toml.md

@@ -63,6 +63,30 @@ and schemas of your own contracts - there is nothing to copy from the other crat
 The contract is then used like any local one: the `Erc20HostRef` comes from `odra_modules::erc20`,
 and `env.deploy` in tests or a livenet script finds the wasm by the struct name as usual.
 
+### Linking the other crate
+
+Rust links a dependency only into a crate that refers to it. A project that lists
+`odra_modules::erc20::Erc20` but never mentions `odra_modules` in its code would get a wasm without
+entry points. The `bin/build_contract.rs` and `bin/build_schema.rs` of a project generated for Odra
+2.11.0 or newer take care of it with one line:
+
+```rust title="bin/build_contract.rs"
+use my_project;
+
+odra::link_contract_crates!();
+```
+
+The macro refers to every dependency that `Odra.toml` lists a contract of, so there is nothing to
+edit when you add such a contract. Two cases need a hand-written `use` next to it instead:
+
+- a project generated for an older Odra: add the `odra::link_contract_crates!();` line to both files,
+  or `use odra_modules;`,
+- an optional dependency, or one from a `[target.*.dependencies]` table: the macro leaves those out,
+  because it cannot tell if they are there in a given build.
+
+If the reference is missing, `cargo odra build` (0.2.1 and newer) stops with an error that names the
+crate, instead of saving a wasm that cannot be installed.
+
 ## What's next
 In the next section, we'll take a closer look at the code that was generated by Odra by default - the famous
 `Flipper` contract.

docusaurus/docs/migrations/to-2.11.0.md

@@ -0,0 +1,90 @@
+---
+sidebar_position: 8
+description: Migration guide to v2.11.0
+---
+
+# Migration guide to v2.11.0 from 2.10
+
+Odra v2.11.0 needs no changes in contract code. Bump the version:
+
+```toml
+odra = "2.11.0"
+```
+
+and install the matching build tool. `cargo-odra` 0.2.1 goes with Odra 2.11:
+
+```bash
+cargo install cargo-odra --locked
+```
+
+Two things are worth a look:
+
+- [`cargo odra test -- <args>`](#test-arguments) passes the arguments to the test binary. A command
+  that passed arguments to `cargo test` itself needs a small change.
+- [`odra::link_contract_crates!()`](#link-contract-crates) is one optional line that replaces the
+  hand-written `use` of a dependency whose contracts you build.
+
+## Arguments of `cargo odra test` {#test-arguments}
+
+With `cargo-odra` 0.2.1 the arguments after `--` go to the test binary, as they do after
+`cargo test --`:
+
+```bash
+cargo odra test -- --nocapture
+```
+
+Before, they were appended to the arguments of `cargo test`, so this command failed with
+`unexpected argument '--nocapture'`. A name filter keeps working as it did: `cargo odra test -- two`.
+
+Arguments for `cargo test` itself now go before a second `--`. If you passed such arguments, add the
+second `--`:
+
+```bash
+# before
+cargo odra test -- --release
+# after
+cargo odra test -- --release --
+# both kinds
+cargo odra test -- --release -- --nocapture
+```
+
+Without it, the test binary rejects the option (`Unrecognized option: 'release'`).
+
+The name filter may now also be given before the `--`: `cargo odra test two -- --nocapture`.
+
+## Contracts from dependency crates {#link-contract-crates}
+
+A project that builds a contract of a dependency (`fqn = "odra_modules::erc20::Erc20"` in `Odra.toml`)
+had to mention the crate in both build binaries, because Rust links a dependency only where it is
+used:
+
+```rust title="bin/build_contract.rs, bin/build_schema.rs"
+use my_project;
+use odra_modules;
+```
+
+That still works. With Odra 2.11.0 you can replace it with one line that follows `Odra.toml`:
+
+```rust title="bin/build_contract.rs, bin/build_schema.rs"
+use my_project;
+
+odra::link_contract_crates!();
+```
+
+New projects have this line already. An optional dependency, or one from a
+`[target.*.dependencies]` table, still needs its own `use`. See
+[Odra.toml](../basics/03-odra-toml.md#linking-the-other-crate).
+
+`cargo odra build` 0.2.1 also checks the wasm it built: if the contract's crate was not linked, it
+stops with an error that names the crate. Before, it could save a wasm without entry points when the
+crate's name appeared only in a comment.
+
+## Faster builds
+
+Nothing to do here. `cargo odra build`, `cargo odra schema` and `cargo odra test -b casper` no longer
+rebuild crates that do not define the contract being built, such as `odra-modules` in a project that
+depends on it. In Odra's own examples this takes a contract from about 7.3 s to 5.1 s. It needs both
+Odra 2.11.0 and `cargo-odra` 0.2.1; either one with an older counterpart builds as before.
+
+If you build contracts without `cargo odra`, see
+[Building contracts manually](../advanced/06-building-manually.md) for the variables involved.

docusaurus/docs/migrations/to-3.0.0.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 description: Migration guide to v3.0.0
 ---
 

docusaurus/static/llms.txt

@@ -91,6 +91,7 @@
 - [Migration guide to v2.0.0 from 1.*](https://odra.dev/docs/migrations/to-2.0.0)
 - [Migration guide to v2.1.0 from 2.0.*](https://odra.dev/docs/migrations/to-2.1.0)
 - [Migration guide to v2.10.0 from 2.9](https://odra.dev/docs/migrations/to-2.10.0)
+- [Migration guide to v2.11.0 from 2.10](https://odra.dev/docs/migrations/to-2.11.0)
 - [Migration guide to v2.6.0 from 2.*](https://odra.dev/docs/migrations/to-2.6.0)
 - [Migration guide to v3.0.0 from 2.*](https://odra.dev/docs/migrations/to-3.0.0)