commit	e20efa18ba7db2c11eefeb32fce6a04bb0ee193c	[log] [tgz]
author	Jiacheng Lu <lujc@google.com>	Thu Sep 26 00:00:50 2024 +0000
committer	Jiacheng Lu <lujc@google.com>	Thu Sep 26 00:00:50 2024 +0000
tree	8203478095b4c57e3b9efc4b8ce9bd3a557cea04
parent	db66e16bb69e9eb299a4d3f6273877f482c3baa1 [diff]

tree: 8203478095b4c57e3b9efc4b8ce9bd3a557cea04

README.md

Cargo GNaw

Tooling to convert Cargo.toml files into native GN rules

Install

$ cargo install --path ~/cargo-gnaw

Run

$ cargo gnaw --manifest-path ~/fuchsia/third_party/rust_crates/Cargo.toml -o ~/fuchsia/third_party/rust_crates/BUILD.gn

Options

--skip-root - Skip the root package in the Cargo.toml and treat it's dependencies as the top-level targets
--gn-bin - Path to GN binary for formatting the output

How it works

Cargo GNaw operates on vendored crates to convert them into GN rules. The resulting BUILD.gn file is expected to be vendored with the crates and provides targets for the GN build system to reference.

All top-level crates are given an easy to use GN alias group that references the version exposed in the Cargo.toml. Direct dependencies of the root crate can be “lifted” to the top-level by skipping the default root crate.

Simple Example

[package]
name = "simple"
version = "1.0.25"
authors = ["Benjamin Brittain <bwb@google.com>"]
edition = "2018"

[dependencies]

converts to:


group("simple") {
  deps = [":simple-1-0-25"]
}

rust_library("simple-1-0-25") {
  crate_name = "simple"
  crate_root = "//tools/cargo-gnaw/src/tests/simple/src/lib.rs"
  output_name = "simple-9ac42213326ac72d"

  deps = []

  rustenv = []
  rustflags = ["--cap-lints=allow",
               "--edition=2018",
               "-Cmetadata=9ac42213326ac72d",
               "-Cextra-filename=-9ac42213326ac72d"]
}

Build Scripts

GNaw intentionally does not handle build.rs scripts at compilation time. Any evaluation of a build.rs script is done when the crate is vendored. The resulting configuration which is usually produced by the build.rs script is put into a section in the source Cargo.toml. Simple build.rs scripts (ones that only depend upon Rust's std library) evaluate and automatically provide the author with the expected configuration.

Packages vs. targets vs. crates

The difference between a “package”, “target”, and a “crate” is useful knowledge when working with GNaw:

A Cargo “target” corresponds to source files that can be compiled into a Rust “crate”. There are multiple target types, including library and binary.
A Cargo “package” contains one or more “targets”, and can contain at most one library target.

(Paraphrased from https://doc.rust-lang.org/cargo/reference/cargo-targets.html)

Many Cargo packages only contain a single library target that produces a single library crate. Because of this (and because of the catchiness of the term) “crate” is often used imprecisely to refer to any of those three items depending on the context. However, when packages contain multiple targets, like one or more binaries alongside the library, it becomes important to distinguish between these terms.

GN configs

Some targets, including but not limited to those that use build.rs scripts, require additional configuration that can be specified in the Cargo.toml file. This configuration is consumed by GNaw, not Cargo, and used when generating GN targets.

Basic configuration

Basic configuration for a package's library target is specified as gn.package.<PackageName>.<ExactVersion>. This configuration will be applied to the GN library target unconditionally (for all platforms) and can include the following arrays:

configs - native GN config
deps - native GN dependency
env_vars - environment variables, usually used for pretending to be Cargo
rustflags - flags to pass through to rustc

Example

[gn.package.anyhow."1.0.25"]
rustflags = [ "--cfg=backtrace" ]

Platform-specific configuration

Configuration can also be applied to only specific platforms, for example only when building for Fuchsia or only when building for a specific host platform.

Platforms are specified in the Rust cfg format (e.g. cfg(unix)). The same four configuration fields (configs, deps, env_vars, rustflags) documented above are supported.

Example

[gn.package.foo."1.2.3".platform."cfg(target_os = \"fuchsia\")"]
configs = [ "//some:fuchsia_specific_config" ]

Generating executables for binary targets

GNaw also supports generating GN executable targets for Cargo binary targets. GNaw must be told to generate such targets; none are generated by default.

Platform-independent or -dependent configuration can be specified as well, similar to above. The same four configuration fields (configs, deps, env_vars, rustflags) documented above are supported.

In the example below, my-gn-name will become both the name of the group target to depend upon and the executable's output_name, so usages can assume output_name == target_name (and must since get_target_outputs only works within the same file).

Example

This example generates a group target named my-gn-name and an executable target that produces my-gn-name from the binary my-cargo-target target inside package my-cargo-package version 1.2.3. Also, when building for Unix this example applies an extra GN config.

[gn.package.my-cargo-package."1.2.3".binary.my-cargo-target]
output_name = "my-gn-name"
rustflags = [ "--cfg=feature" ]

[gn.package.my-cargo-package."1.2.3".binary.my-cargo-target.platform."cfg(unix)"]
configs = [ "//some:unix_specific_config" ]