1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
This directory contains tools for importing third-party Rust crates and
constructing BUILD.gn files from them.
# Depending on third-party crates
The `//third_party/rust/third_party.toml` crate defines the set of crates
depended on from first-party code. Any transitive dependencies will be found
from those listed there. The file is a subset of a
[standard `Cargo.toml` file](https://doc.rust-lang.org/cargo/reference/manifest.html),
but only listing the `[dependencies]` section.
To use a third-party crate "bar" version 3 from first party code, add the
following to `//third_party/rust/third_party.toml` in `[dependencies]`:
```toml
[dependencies]
bar = "3"
```
To enable a feature "spaceships" in the crate, change the entry in
`//third_party/rust/third_party.toml` to include the feature:
```toml
[dependencies]
bar = { version = "3", features = [ "spaceships" ] }
```
# Generating `BUILD.gn` files for third-party crates
To generate `BUILD.gn` files for all third-party crates, and find missing
transitive dependencies to download, use the `gnrt` tool:
1. Build `gnrt` to run on host machine, e.g. `ninja -C out/Default gnrt`.
1. Change directory to the root src/ dir of Chromium.
2. Run `gnrt`: e.g. `out/Default/gnrt`.
This will generate a `BUILD.gn` file for each third-party crate and apply the
patch at `//third_party/rust/gnrt_build_patch`. The `BUILD.gn` file changes
will be visible in `git status` and can be added with `git add`.
The `gnrt_build_patch` file allows fixing generated build rules as well as
adding missing `BUILD.gn` files which result from bugs. The patch should *only*
contain `BUILD.gn` file changes. [Other patches](#patching-third-party-crates)
should be placed in a crate's `patches` subdirectory.
# Downloading missing third-party crates
To download crate "foo", at the latest release of major version 4.x:
1. Change directory to the root src/ dir of Chromium.
1. `tools/crates/crates.py download foo 4`
This will download the crate and unpack it into
`//third_party/rust/foo/v4/crate`. The entire `v4` directory, which includes the
`crate` subdirectory as well as a generated `README.chromium` file, should be
added to the repository with `git add third_party/rust/foo/v4`.
Once all the crates are downloaded and `crates.py gen` completes, a CL can be
uploaded to go through third-party review.
# Patching third-party crates.
You may patch a crate in tree, but save any changes made into a diff file in
a `patches/` directory for the crate. The diff file should be generated by
`git-format-patch` each new patch numbered consecutively so that they can be
applied in order. For example, these files might exist if the "foo" crate was
patched with a couple of changes:
```
//third_party/rust/foo/v4/patches/0001-Edit-the-Cargo-toml.diff
//third_party/rust/foo/v4/patches/0002-Other-changes.diff
```
# Updating existing third-party crates
To update a crate "foo" to the latest version you must just re-import it at this
time. To update from version "1.2" to "1.3":
1. Build `gnrt` before making any changes to `//third_party/rust`.
1. Remove the `//third_party/rust/foo/v1/crate` directory, which contains the
upstream code.
1. Re-download the crate with `tools/crates/crates.py download foo 1`. This will
find the latest matching version on https://crates.io. If a more specific
version is desired, you may specify the full version.
1. If there are any, re-apply local patches with
`for i in $(find third_party/rust/foo/v1/patches/*); do patch -p1 < $i; done`
1. Run `out/<conf>/gnrt` to re-generate all third-party `BUILD.gn` files.
1. Re-build `gnrt` and `gnrt_unittests`. Run `gnrt` and ensure no further
`BUILD.gn` outputs are the same as before. Run `gnrt_unittests`.
# Directory structure for third-party crates
The directory structure for a crate "foo" version 3.4.2 is:
```
//third_party/
rust/
foo/
v3/
BUILD.gn (generated by crates.py)
README.chromium
crate/
Cargo.toml
src/
...etc...
patches/
0001-Edit-the-Cargo-toml.diff
0002-Other-changes.diff
```
|
