README.md
1# cargo_embargo
2
3`cargo_embargo` is a tool to generate `Android.bp` files automatically for external Rust crates
4which are intended to build with cargo. It can be built with `m cargo_embargo` and run with
5`cargo_embargo generate cargo_embargo.json` in a directory containing one or more Rust packages. If
6successful this will write out an `Android.bp` file.
7
8## Configuration
9
10`cargo_embargo` is configured with a JSON configuration file usually called `cargo_embargo.json`.
11This can contain a number of options, specified at several levels. A config may cover one or more
12packages, and have one or more variants. All packages under `external/rust/crates` use a separate
13`cargo_embargo.json` file per package, but other users (such as crosvm) may use a single
14`cargo_embargo.json` for a tree of many packages. Most configurations have a single variant, but
15multiple variants are used in some cases to provide both `std` and `no_std` variants of a package.
16
17The overall structure of a config file looks like this:
18
19```json
20{
21 // Top-level options, for all packages and variants.
22 "package": {
23 "package_name": {
24 // Options for all variants of a package.
25 },
26 "another_package_name": {
27 // ...
28 }
29 },
30 "variants": [
31 {
32 // Options for a specific variant of all packages.
33 "package": {
34 "package_name": {
35 // Options for a specific variant of a specific package.
36 }
37 }
38 },
39 {
40 // Options for another variant.
41 }
42 ]
43}
44```
45
46If a package is not included in the `package` map then it is assumed to use default options. If the
47`package` map is omitted then all packages will use default options. If `variants` is omitted then
48there is assumed to be a single variant. Thus `{}` is a valid config file for a single variant with
49all default options.
50
51A typical config file for a simple package may look like:
52
53```json
54{
55 "run_cargo": false,
56 "tests": true
57}
58```
59
60This expands to a single variant with the given options, and all packages (i.e. the only one) using
61default options.
62
63### Top-level configuration options
64
65These options may all be specified at the top level of the config file, or overridden per variant.
66
67| Name | Type | Default | Meaning |
68| -------------------------- | ------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
69| `tests` | boolean | `false` | Whether to output `rust_test` modules. |
70| `features` | list of strings | - | Set of features to enable. If not set, uses the default crate features. |
71| `workspace` | boolean | `false` | Whether to build with `--workspace`. |
72| `workspace_excludes` | list of strings | `[]` | When workspace is enabled, list of `--exclude` crates. |
73| `global_defaults` | string | - | Value to use for every generated module's `defaults` field. |
74| `apex_available` | list of strings | `["//apex_available:platform", "//apex_available:anyapex"]` | Value to use for every generated library module's `apex_available` field. |
75| `native_bridge_supported` | boolean | `false` | Value to use for every generated library module's `native_bridge_supported` field. |
76| `product_available` | boolean | `true` | Value to use for every generated library module's `product_available` field. |
77| `ramdisk_available` | boolean | `false` | Value to use for every generated library module's `ramdisk_available` field. |
78| `recovery_available` | boolean | `false` | Value to use for every generated library module's `recovery_available` field. |
79| `vendor_available` | boolean | `true` | Value to use for every generated library module's `vendor_available` field. |
80| `vendor_ramdisk_available` | boolean | `false` | Value to use for every generated library module's `vendor_ramdisk_available` field. |
81| `min_sdk_version` | string | - | Minimum SDK version for generated modules' `min_sdk_version` field. |
82| `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. |
83| `cfg_blocklist` | list of strings | `[]` | `cfg` flags in this list will not be included. |
84| `extra_cfg` | list of strings | `[]` | Extra `cfg` flags to enable in output modules. |
85| `module_blocklist` | list of strings | `[]` | Modules in this list will not be generated. |
86| `module_visibility` | string => list of strings | `{}` | Modules name => Soong "visibility" property. |
87| `run_cargo` | boolean | `true` | Whether to run the cargo build and parse its output, rather than just figuring things out from the cargo metadata. |
88
89Of particular note, it is preferable to set `run_cargo` to `false` where possible as it is
90significantly faster. However, this may miss important details in more complicated cases, such as
91packages with a `build.rs`, so it is recommended to run with `run_cargo` set to `true` initially,
92and then compare the output when it is changed to `false`.
93
94### Per-package configuration options
95
96These options may be specified per package. Most may also be overridden per variant. They may not be
97specified outside of a package.
98
99| Name | Type | Default | Per variant | Meaning |
100| ----------------------- | ------------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
101| `add_toplevel_block` | path | - | no | File with content to append to the end of the generated Android.bp. |
102| `patch` | path | - | no | Patch file to apply after Android.bp is generated. |
103| `alloc` | boolean | `false` | yes | Link against `alloc`. Only valid if `no_std` is also true. |
104| `device_supported` | boolean | `true` | yes | Whether to compile for device. Defaults to true. |
105| `host_supported` | boolean | `true` | yes | Whether to compile for host. Defaults to true. |
106| `host_first_multilib` | boolean | `false` | yes | Add a `compile_multilib: "first"` property to host modules. |
107| `force_rlib` | boolean | `false` | yes | Generate "rust_library_rlib" instead of "rust_library". |
108| `no_presubmit` | boolean | `false` | yes | Whether to disable "unit_test" for "rust_test" modules. |
109| `add_module_block` | path | - | yes | File with content to append to the end of each generated module. |
110| `dep_blocklist` | list of strings | `[]` | yes | Modules in this list will not be added as dependencies of generated modules. |
111| `no_std` | boolean | `false` | yes | Don't link against `std`, only `core`. |
112| `copy_out` | boolean | `false` | yes | Copy `build.rs` output to `./out/*` and add a genrule to copy `./out/*` to genrule output. |
113| `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 |
114| `whole_static_libs` | list of strings | `[]` | yes | Static libraries in this list will instead be added as whole_static_libs. |
115| `exported_c_header_dir` | list of paths | `[]` | yes | Directories with headers to export for C usage. |
116
117## Auto-config
118
119For importing a new package, you may start by running cargo_embargo's autoconfig mode:
120
121```
122cargo_embargo autoconfig cargo_embargo.json
123```
124
125This will attempt to generate a suitable `cargo_embargo.json` for the package in the current
126directory, by trying with `run_cargo` both `true` and `false`, and including tests if there are any.
127