Kyle Den Hartog
0ae4cc76a5
* Add --update-crate flag to update a single vendored tool crate Adds a --update-crate=<name>@<version> option to tools/crates/update.py that updates one crate in-place without running cargo vendor. It downloads the tarball directly from crates.io, replaces the vendor directory, patches Cargo.lock, and regenerates .cargo-checksum.json. This avoids collateral version bumps from a full re-vendor and is useful for targeted security advisory fixes. Exposes the flag via `npm run update_brave_tools_crates -- --update-crate=`.
68 lines
4.1 KiB
Markdown
68 lines
4.1 KiB
Markdown
## Rust usage:
|
||
|
||
When integrating Rust code into brave-core, keep the following points in mind:
|
||
|
||
- Chromium’s networking stack must be used
|
||
- The deps being added (and the deps recursively being added) must be approved
|
||
via an issue posted at [brave/reviews](https://github.com/brave/reviews/issues/new/choose)
|
||
- The new code does not duplicate things already done in Chromium
|
||
- https://chromium.googlesource.com/chromium/src/+/main/docs/adding_to_third_party.md#rust
|
||
also applies generally to all Rust code in brave-core
|
||
- Look at existing deps in `third_party/rust` and try to match up versions
|
||
whenever possible. We are trying to avoid having multiple copies of the same third party libs
|
||
|
||
### Updating vendored tool crates
|
||
|
||
The `tools/crates/` directory vendors Rust CLI tools (`cargo-audit`, `wasm-bindgen-cli`, `wasm-opt`, `wasm-pack`). To update a single transitive dependency (e.g. for a security advisory) without re-vendoring everything:
|
||
|
||
```sh
|
||
npm run update_brave_tools_crates -- --update-crate=<name>@<version>
|
||
```
|
||
|
||
This downloads the crate directly from crates.io and patches only the targeted `vendor/` directory and `Cargo.lock` entry. To do a full re-vendor of all tool crates, run without arguments:
|
||
|
||
```sh
|
||
npm run update_brave_tools_crates
|
||
```
|
||
|
||
### Patching crates
|
||
|
||
There can be cases where patching crates is necessary. To create a patch file,
|
||
make changes to a crate and create a patch with:
|
||
|
||
```sh
|
||
git format-patch \
|
||
--start-number=101 \
|
||
--src-prefix=a/brave/ \
|
||
--dst-prefix=b/brave/ \
|
||
--output-directory \
|
||
third_party/rust/chromium_crates_io/patches/some-crate/ \
|
||
HEAD^
|
||
```
|
||
|
||
For general instructions on how this works in upstream Chromium, check [these instructions](https://chromium.googlesource.com/chromium/src/+/HEAD/third_party/rust/chromium_crates_io/patches/README.md#steps-for-creating-new-patches).
|
||
|
||
### Testing an unreleased version of a dependency
|
||
|
||
`gnrt` generally only allows you to use published releases from https://crates.io for dependencies. For dependencies maintained by Brave, it may be desired to test releases on a local build before publishing an "official" release.
|
||
|
||
In this case, you can modify `brave/third_party/rust/chromium_crates_io/Cargo.toml` to add a patch section for your dependency. Then you can use a `path` or `git` directive to point to one of your local checkouts on disk, or a git repository, respectively.
|
||
|
||
Running `gnrt gen` will update your source tree to use the correct dependency versions. Note that the code from the vendored version of your crate will _not_ be updated (even when running `gnrt vendor`), you will still need to manually copy your code changes in.
|
||
|
||
#### Updating a patch version
|
||
[This PR](https://github.com/brave/brave-core/pull/20113/files) updates `adblock 0.8.0` to `adblock 0.8.1` without any `brave-core` code changes.
|
||
|
||
#### Updating a minor version
|
||
[This PR](https://github.com/brave/brave-core/pull/19648/files) updates `adblock 0.7` to `adblock 0.8`. This is generally similar to the patch version diff, but there are additional related changes (i.e. see `components/brave_shields/adblock/rs/BUILD.gn` where a path is changed), along with additional unrelated changes (`brave-core` code changes to account for the newer API).
|
||
|
||
## Review guidelines
|
||
|
||
A checklist for reviewing Rust code changes, including dependent library crates.
|
||
This is just a starting point and not a comprehensive list.
|
||
|
||
* Third-party dependency versions should be aligned with what's already in the upstream chromium or brave trees. If a change needs to update one of those crates, make sure there's at least an issue open for all other users to coordinate migration so we don't ship duplicate code.
|
||
* Carefully check any `thread_local` use. Leaf code may be called from different C++ threads in sequence, so thread-local variables won't be consistent.
|
||
* No IO or system calls are allowed
|
||
* Any use of `autocfg` in dependencies must be patched out and replaced by config settings in `BUILD.gn` based on variables there. Since we don't use cargo, most of these checks won't work, or will produce the wrong values. See [here](https://github.com/brave/brave-core/commit/29fc07ef291593b5c4b9b2587ca184ab3d890650) for an example handling these issues.
|