Repository files navigation

There are several copies of this repo on GitHub,facebook/starlark-rust is thecanonical one.

This project provides a Rust implementation of theStarlark language.Starlark (formerly codenamed Skylark) is a deterministic language inspired byPython3, used for configuration in the build systemsBazel,Buck andBuck2, of which Buck2 depends on this library. Thisproject was originally developedin this repo, which contains a moreextensive history.

There are at least three implementations of Starlark,one in Java,one in Go, and this one in Rust. Wemostly follow the Starlark standard. If you are interested in trying out RustStarlark, you can clone this repo and run:

$ curl --proto'=https' --tlsv1.2 -sSf https://sh.rustup.rs| sh$ cargo run$> 1+23

This project was started byDamien Martin-Guillerez. Version 0.4.0 of thislibrary changed ownershipfrom Googleto Facebook.

Readthis blog postfor an overview of the library, the reasons behind Starlark, and how it mightfit in to your project. There is also a2 minute introductory video.

This project features:

• Easy interoperability between Rust types and Starlark.
• Rust-friendly types, so frozen values areSend/Sync, while non-frozenvalues aren't.
• Garbage collected values allocated ona heap.
• Optional runtime-checkedtypes.
• A linter, to detect code issues in Starlark.
• IDE integration in the form ofLSP.
• Extensive testing, includingfuzz testing.
• DAP support.

This project also has three non-goals:

• We donot aim for API stability between releases, preferring to iteratequickly and refine the API as much as possible. But we dofollow SemVer.
• We donot aim for minimal dependencies, preferring to keep one package withlots of power. But if some dependencies prove tricky, we might add featureflags.

There are six components:

• starlark_derive, a proc-macro crate that defines the necessary macros forStarlark. This library is a dependency ofstarlark the library, whichreexports all the relevant pieces, and should not be used directly.
• starlark_map, a library with memory-efficient ordered/unordered maps/setsand 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, debuggersupport and lots of other pieces. Projects wishing to embed Starlark in theirenvironment (with additional types, library functions and features) will makeuse of this library. This library reexports the relevant pieces ofstarlark_derive,starlark_map and most ofstarlark_syntax.
• starlark_lsp, a library providing anLSP.
• starlark_bin the binary, which provides interactive evaluation, IDE featuresand linter, exposed through a command line. Useful if you want to use vanillaStarlark (but if you do, consider Python3 instead) or as a test-bed forexperimenting. Most projects will end up implementing some of thisfunctionality themselves over thestarlark andstarlark_lsp libraries,incorporating their specific extra types etc.

In particular thestarlark_bin binarycan be effectively used as a linter.But for the REPL, evaluator and IDE features thestarlark_bin binary is onlyaware of standard Starlark. Most Starlark embeddings supply extra functions anddata types to work with domain-specific concerns, and the lack of these bindingswill cause the REPL/evaluator to fail if they are used, and will give a subparIDE experience. In most cases you should write your own binary depending on thestarlark library, integrating your domain-specific pieces, and then using thebundled LSP functions to produce your own IDE/REPL/evaluator on top of those.You should still be able to use theVS Code extension.

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

• We have plenty of extensions, e.g. type annotations, recursion, top-levelfor.
• We don't yet support later additions to Starlark, such asbytes.
• In some cases creating circular data structures may lead to stack overflows.

1. Check theGitHub Actionsare green.
2. UpdateCHANGELOG.md with the changes since the last release.This linkcan help (update to compare against the last release).
3. Update the version numbers of the twoCargo.toml files. Bump them by 0.0.1if there are no incompatible changes, or 0.1.0 if there are. Bump thedependency instarlark to point at the lateststarlark_derive version.
4. Copy the filesCHANGELOG.md,LICENSE andREADME.md into eachsubdirectory.
5. Runcargo publish --allow-dirty --dry-run, then without the--dry-run, ineach of the component directories in theorder above.
6. Create aGitHub release withv0.X.Y, using thestarlark version as the name.

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