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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
# cargo_embargo
`cargo_embargo` is a tool to generate `Android.bp` files automatically for external Rust crates
which are intended to build with cargo. It can be built with `m cargo_embargo` and run with
`cargo_embargo generate cargo_embargo.json` in a directory containing one or more Rust packages. If
successful this will write out an `Android.bp` file.
## Configuration
`cargo_embargo` is configured with a JSON configuration file usually called `cargo_embargo.json`.
This can contain a number of options, specified at several levels. A config may cover one or more
packages, and have one or more variants. All packages under `external/rust/crates` use a separate
`cargo_embargo.json` file per package, but other users (such as crosvm) may use a single
`cargo_embargo.json` for a tree of many packages. Most configurations have a single variant, but
multiple variants are used in some cases to provide both `std` and `no_std` variants of a package.
The overall structure of a config file looks like this:
```json
{
// Top-level options, for all packages and variants.
"package": {
"package_name": {
// Options for all variants of a package.
},
"another_package_name": {
// ...
}
},
"variants": [
{
// Options for a specific variant of all packages.
"package": {
"package_name": {
// Options for a specific variant of a specific package.
}
}
},
{
// Options for another variant.
}
]
}
```
If a package is not included in the `package` map then it is assumed to use default options. If the
`package` map is omitted then all packages will use default options. If `variants` is omitted then
there is assumed to be a single variant. Thus `{}` is a valid config file for a single variant with
all default options.
A typical config file for a simple package may look like:
```json
{
"run_cargo": false,
"tests": true
}
```
This expands to a single variant with the given options, and all packages (i.e. the only one) using
default options.
### Top-level configuration options
These options may all be specified at the top level of the config file, or overridden per variant.
| Name | Type | Default | Meaning |
| -------------------------- | ------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tests` | boolean | `false` | Whether to output `rust_test` modules. |
| `features` | list of strings | - | Set of features to enable. If not set, uses the default crate features. |
| `workspace` | boolean | `false` | Whether to build with `--workspace`. |
| `workspace_excludes` | list of strings | `[]` | When workspace is enabled, list of `--exclude` crates. |
| `global_defaults` | string | - | Value to use for every generated module's `defaults` field. |
| `apex_available` | list of strings | `["//apex_available:platform", "//apex_available:anyapex"]` | Value to use for every generated library module's `apex_available` field. |
| `native_bridge_supported` | boolean | `false` | Value to use for every generated library module's `native_bridge_supported` field. |
| `product_available` | boolean | `true` | Value to use for every generated library module's `product_available` field. |
| `ramdisk_available` | boolean | `false` | Value to use for every generated library module's `ramdisk_available` field. |
| `recovery_available` | boolean | `false` | Value to use for every generated library module's `recovery_available` field. |
| `vendor_available` | boolean | `true` | Value to use for every generated library module's `vendor_available` field. |
| `vendor_ramdisk_available` | boolean | `false` | Value to use for every generated library module's `vendor_ramdisk_available` field. |
| `min_sdk_version` | string | - | Minimum SDK version for generated modules' `min_sdk_version` field. |
| `module_name_overrides` | string => string | `{}` | Map of renames for modules. For example, if a "libfoo" would be generated and there is an entry ("libfoo", "libbar"), the generated module will be called "libbar" instead. |
| `cfg_blocklist` | list of strings | `[]` | `cfg` flags in this list will not be included. |
| `extra_cfg` | list of strings | `[]` | Extra `cfg` flags to enable in output modules. |
| `module_blocklist` | list of strings | `[]` | Modules in this list will not be generated. |
| `module_visibility` | string => list of strings | `{}` | Modules name => Soong "visibility" property. |
| `run_cargo` | boolean | `true` | Whether to run the cargo build and parse its output, rather than just figuring things out from the cargo metadata. |
Of particular note, it is preferable to set `run_cargo` to `false` where possible as it is
significantly faster. However, this may miss important details in more complicated cases, such as
packages with a `build.rs`, so it is recommended to run with `run_cargo` set to `true` initially,
and then compare the output when it is changed to `false`.
### Per-package configuration options
These options may be specified per package. Most may also be overridden per variant. They may not be
specified outside of a package.
| Name | Type | Default | Per variant | Meaning |
| ----------------------- | ------------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `add_toplevel_block` | path | - | no | File with content to append to the end of the generated Android.bp. |
| `patch` | path | - | no | Patch file to apply after Android.bp is generated. |
| `alloc` | boolean | `false` | yes | Link against `alloc`. Only valid if `no_std` is also true. |
| `device_supported` | boolean | `true` | yes | Whether to compile for device. Defaults to true. |
| `host_supported` | boolean | `true` | yes | Whether to compile for host. Defaults to true. |
| `host_first_multilib` | boolean | `false` | yes | Add a `compile_multilib: "first"` property to host modules. |
| `force_rlib` | boolean | `false` | yes | Generate "rust_library_rlib" instead of "rust_library". |
| `no_presubmit` | boolean | `false` | yes | Whether to disable "unit_test" for "rust_test" modules. |
| `add_module_block` | path | - | yes | File with content to append to the end of each generated module. |
| `dep_blocklist` | list of strings | `[]` | yes | Modules in this list will not be added as dependencies of generated modules. |
| `no_std` | boolean | `false` | yes | Don't link against `std`, only `core`. |
| `copy_out` | boolean | `false` | yes | Copy `build.rs` output to `./out/*` and add a genrule to copy `./out/*` to genrule output. |
| `test_data` | string => list of strings | `{}` | yes | Add the given files to the given tests' `data` property. The key is the test source filename relative to the crate |
| `whole_static_libs` | list of strings | `[]` | yes | Static libraries in this list will instead be added as whole_static_libs. |
| `exported_c_header_dir` | list of paths | `[]` | yes | Directories with headers to export for C usage. |
## Auto-config
For importing a new package, you may start by running cargo_embargo's autoconfig mode:
```
cargo_embargo autoconfig cargo_embargo.json
```
This will attempt to generate a suitable `cargo_embargo.json` for the package in the current
directory, by trying with `run_cargo` both `true` and `false`, and including tests if there are any.
|
