3 releases (breaking)
0.12.0 | Feb 9, 2024 |
---|---|
0.11.0 | Jan 19, 2024 |
0.10.0 | Oct 17, 2023 |
#2907 in Parser implementations
12,470 downloads per month
Used in 6 crates
(2 directly)
485KB
12K
SLoC
Starlark in Rust
There are several copies of this repo on GitHub, facebookexperimental/starlark-rust is the canonical one.
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, Buck and Buck2, of which Buck2 depends on this library. 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. If you are interested in trying out Rust Starlark, you can clone this repo and run:
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ cargo run
$> 1+2
3
This project was started by Damien Martin-Guillerez. Version 0.4.0 of this library changed ownership from Google to Facebook.
Learn More
Read this blog post for an overview of the library, the reasons behind Starlark, and how it might fit in to your project. There is also a 2 minute introductory video.
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.
- Extensive testing, including fuzz testing.
- 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.
Components
There are six components:
starlark_derive
, a proc-macro crate that defines the necessary macros for Starlark. This library is a dependency ofstarlark
the library, which reexports all the relevant pieces, and should not be used directly.starlark_map
, a library with memory-efficient ordered/unordered maps/sets and various other data structures useful in Starlark.starlark_syntax
, a library with the AST of Starlark and parsing functions. Only use if you want to manipulate the AST directly.starlark
the main library, with evaluator, standard library, debugger support and lots of other pieces. Projects wishing to embed Starlark in their environment (with additional types, library functions and features) will make use of this library. This library reexports the relevant pieces ofstarlark_derive
,starlark_map
and most ofstarlark_syntax
.starlark_lsp
, a library providing an LSP.starlark_bin
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 thestarlark
andstarlark_lsp
libraries, incorporating their specific extra types etc.
In particular the starlark_bin
binary can be effectively used as a linter.
But for the REPL, evaluator and IDE features the starlark_bin
binary is only
aware of standard Starlark. Most Starlark embeddings supply extra functions and
data types to work with domain-specific concerns, and the lack of these bindings
will cause the REPL/evaluator to fail if they are used, and will give a subpar
IDE experience. In most cases you should write your own binary depending on the
starlark
library, integrating your domain-specific pieces, and then using the
bundled LSP functions to produce your own IDE/REPL/evaluator on top of those.
You should still be able to use the VS Code extension.
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 bytes.
- In some cases creating circular data structures may lead to stack overflows.
Making a release
- Check the GitHub Actions are green.
- Update
CHANGELOG.md
with the changes since the last release. This link can help (update to compare against the last release). - 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 instarlark
to point at the lateststarlark_derive
version. - Copy the files
CHANGELOG.md
,LICENSE
andREADME.md
into each subdirectory. - Run
cargo publish --allow-dirty --dry-run
, then without the--dry-run
, in each of the component directories in the order above. - Create a
GitHub release
with
v0.X.Y
, using thestarlark
version as the name.
License
Starlark Rust is Apache License, Version 2.0 licensed, as found in the LICENSE file.
Dependencies
~8–12MB
~164K SLoC