Starlark in Rust

NOTE: Version 0.4.0 of this library changes maintainer from Google to Facebook.

This project provides a Rust implementation of the Starlark language. Starlark (formerly codenamed Skylark) is a deterministic language inspired by Python3, used for configuration in the build systems Bazel and Buck. This project was originally developed in this repo, which contains a more extensive history.

There are at least three implementations of Starlark, one in Java, one in Go, and this one in Rust. We mostly follow the Starlark standard.

Features

This project features:

• Easy interoperability between Rust types and Starlark.
• Rust-friendly types, so frozen values are Send/Sync, while non-frozen values aren't.
• Garbage collected values allocated on a heap.
• Optional runtime-checked types.
• A linter, to detect code issues in Starlark.
• IDE integration in the form of LSP and DAP support.

This project also has three non-goals:

• We do not aim for API stability between releases, preferring to iterate quickly and refine the API as much as possible. But we do follow SemVer.
• We do not aim for minimal dependencies, preferring to keep one package with lots of power. But if some dependencies prove tricky, we might add feature flags.
• We do not aim to work with Rust stable, preferring to take advantage of the unstable features in Rust to improve our code as much as possible. We hope that eventually enough features will be stabilised that using stable is reasonable again.

Components

There are three components:

• starlark_module, a proc-macro crate that defines the #[starlark_module] annotation that can be applied to Rust code to make it available as a Starlark module. This library is a dependency of starlark the library.
• starlark the library, a library that defines the parser, evaluator and standard library. Projects wishing to embed Starlark in their environment (with additional types, library functions and features) will make use of this library.
• starlark the binary, which provides interactive evaluation, IDE features and linter, exposed through a command line. Useful if you want to use vanilla Starlark (but if you do, consider Python3 instead) or as a test-bed for experimenting. Most projects will end up implementing some of this functionality themselves over the starlark library, incorporating their specific extra types etc.

Compatibility

In this section we outline where we don't comply with the Starlark spec.

• We have plenty of extensions, e.g. type annotations, recursion, top-level for.
• We don't yet support later additions to Starlark, such as floats or bytes.
• We are currently limited to 32 bit integers. Constructing larger values will result in Starlark failing with an overflow error.
• Our strings are not compliant in several ways, often returning code points instead of singleton strings, and have poor performance.
• In some cases creating circular data structures may lead to stack overflows.

Making a release

1. Check the GitHub Actions are green.
2. Update CHANGELOG.md with the changes since the last release. This link can help (update to compare against the last release).
3. Update the version numbers of the two Cargo.toml files. Bump them by 0.0.1 if there are no incompatible changes, or 0.1.0 if there are. Bump the dependency in starlark to point at the latest starlark_module version.
4. Copy the files CHANGELOG.md, LICENSE and README.md into each starlark and starlark_module subdirectory.
5. Run cargo publish --dry-run --allow-dirty, then without the --dry-run, first in starlark_module and then starlark directories.
6. Create a GitHub release with v0.X.Y, using the starlark version as the name.

License

Starlark Rust is Apache License, Version 2.0 licensed, as found in the LICENSE file.