Crate serde_starlark
source ·Expand description
Serde serializer for generating syntactically valid Starlark, the declarative format used for describing build targets in build systems including Bazel, Buck, Pants, and Please.
Example
The following example serializes a minimal Bazel target for the syn
crate.
The tests/bazel.rs test in this repo has a somewhat more fleshed out
example of this use case, including things like load(…)
,
package(default_visibility = …)
, distinct include
and exclude
arguments to glob(…)
, and select({…})
.
#[derive(Serialize)]
#[serde(rename = "rust_library")]
pub struct RustLibrary {
pub name: String,
pub srcs: Glob,
pub crate_features: BTreeSet<String>,
pub edition: u16,
pub deps: BTreeSet<String>,
}
#[derive(Serialize)]
#[serde(rename = "glob")]
pub struct Glob(pub BTreeSet<String>);
fn main() {
let rust_library = RustLibrary { ... };
print!("{}", serde_starlark::to_string(&rust_library).unwrap());
}
rust_library(
name = "syn",
srcs = glob(["**/*.rs"]),
crate_features = [
"default",
"full",
],
edition = 2018,
deps = [
":proc-macro2",
":quote",
":unicode-ident",
],
)
Data model
The primitive types (integers, boolean, string) serialize in the obvious way to Starlark.
Serde sequences serialize to Starlark arrays. Serde maps serialize to Starlark maps.
Rust structs with named fields serialize to Starlark “function calls” with named arguments:
#[derive(Serialize)]
#[serde(rename = "rust_library")]
pub struct RustLibrary {
pub name: String,
pub edition: u16,
}
rust_library(
name = "syn",
edition = 2018,
)
Rust newtype structs and tuple structs serialize to Starlark “function calls” with positional arguments:
#[derive(Serialize)]
#[serde(rename = "select")]
pub struct Select<T>(pub BTreeMap<String, T>);
select({
"//conditions:default": [],
})
To make a newtype struct which does not appear as a function call, use the
serde(transparent)
attribute.
#[derive(Serialize)]
#[serde(transparent)]
pub struct Dependency(pub String);
Fields of type Option<T>
serialize as either None
or the value if
present. Consider using serde(skip_serializing_if = "Option::is_none")
to
omit fields with value None
from the serialized output.
Modules
- For “deserialization”, consider using https://github.com/facebookexperimental/starlark-rust.
Structs
- Serialize a value as an assigment to an identifier.
- Serialize a map as a function call.
- Serialize a line comment on the end of the current line.
- Serializer whose output
Ok
type is Starlark.
Constants
- Format a function call, array, or map with all values on their own line.
- Format a function call, array, or map with all values on one line.