serde_starlark
==============
[
](https://github.com/dtolnay/serde-starlark)
[
](https://crates.io/crates/serde_starlark)
[
](https://docs.rs/serde_starlark)
[
](https://github.com/dtolnay/serde-starlark/actions?query=branch%3Amaster)
Serde serializer for generating syntactically valid Starlark, the declarative
format used for describing build targets in build systems including [Bazel],
[Buck], [Pants], and [Please].
[Bazel]: https://bazel.build
[Buck]: https://buck.build
[Pants]: https://www.pantsbuild.org
[Please]: https://please.build
## 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({…})`.
```rust
#[derive(Serialize)]
#[serde(rename = "rust_library")]
pub struct RustLibrary {
pub name: String,
pub srcs: Glob,
pub crate_features: BTreeSet,
pub edition: u16,
pub deps: BTreeSet,
}
#[derive(Serialize)]
#[serde(rename = "glob")]
pub struct Glob(pub BTreeSet);
fn main() {
let rust_library = RustLibrary { ... };
print!("{}", serde_starlark::to_string(&rust_library).unwrap());
}
```
```bzl
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:
```rust
#[derive(Serialize)]
#[serde(rename = "rust_library")]
pub struct RustLibrary {
pub name: String,
pub edition: u16,
}
```
```bzl
rust_library(
name = "syn",
edition = 2018,
)
```
Rust newtype structs and tuple structs serialize to Starlark "function calls"
with positional arguments:
```rust
#[derive(Serialize)]
#[serde(rename = "select")]
pub struct Select(pub BTreeMap);
```
```bzl
select({
"//conditions:default": [],
})
```
To make a newtype struct which does not appear as a function call, use the
`serde(transparent)` attribute.
```rust
#[derive(Serialize)]
#[serde(transparent)]
pub struct Dependency(pub String);
```
Fields of type `Option` 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.
#### License
Licensed under either of Apache License, Version
2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.