An Overview of the Starlark Language(laurent.le-brun.eu)
laurent.le-brun.eu
An Overview of the Starlark Language
https://laurent.le-brun.eu/blog/an-overview-of-starlark
12 comments
The biggest feature I want out of Starlark the language (not Bazel the build system) is to allow optional type annotations. They don’t have to do anything, they don’t have to specified, it just needs to be syntactically valid to put type annotations somewhere. If there were syntax for type annotations that tools like Bazel ignored, it would be possible for some enterprising soul who’s forced to use Bazel at work to throw up an initial prototype of a type checker and a language server for Starlark in Bazel. The language is not that complicated that a type checker couldn’t be written by a hobbiest.
My biggest frustration when using Bazel is not even Bazel—it’s the fact that when I’m looking at code like this[1], everything comes from a single, unannotated `rctx` variable that has no type annotation. So when I’m trying to read the code, it’s a matter of constantly grepping the repo, grepping the bazel docs, and grepping the bazel source code to get any new code written.
Why can’t I just hover and see the docs? Why can’t I press `rctx.` and see all the attributes available?
I frequently hear “why do you need types? the language is Turing complete just run it and see if it fails” but that misses the point that I have want to use types to guide what code to write in the first place.
[1] https://github.com/bazel-contrib/toolchains_llvm/blob/master...
My biggest frustration when using Bazel is not even Bazel—it’s the fact that when I’m looking at code like this[1], everything comes from a single, unannotated `rctx` variable that has no type annotation. So when I’m trying to read the code, it’s a matter of constantly grepping the repo, grepping the bazel docs, and grepping the bazel source code to get any new code written.
Why can’t I just hover and see the docs? Why can’t I press `rctx.` and see all the attributes available?
I frequently hear “why do you need types? the language is Turing complete just run it and see if it fails” but that misses the point that I have want to use types to guide what code to write in the first place.
[1] https://github.com/bazel-contrib/toolchains_llvm/blob/master...
starlark-rust (used by Buck2) supports this! They're immensely useful for grokking complex build code, as you said. https://github.com/facebook/starlark-rust/blob/main/docs/typ...
This is something that came up multiple times. I think type information is especially valuable in combination with other IDE features (code completion).
My idea was to do type checking in a separate tool (e.g. built on top of Buildifier) and let the interpreter ignore the types. So it could be completely optional. The type system could be gradual, like in Typescript.
I don't know when/if it will happen (I'm no longer working at Google, so it's harder to make large contributions like this).
My idea was to do type checking in a separate tool (e.g. built on top of Buildifier) and let the interpreter ignore the types. So it could be completely optional. The type system could be gradual, like in Typescript.
I don't know when/if it will happen (I'm no longer working at Google, so it's harder to make large contributions like this).
Having done some nontrivial Bazel/Starlark hacking, I completely agree that lightweight static types would be a good usability improvement. But I want to point out that Starlark is actually not Turing complete, which is imo one of the more interesting characteristics it has. Recursion is forbidden (https://github.com/bazelbuild/starlark/blob/master/spec.md#f...) and loops must be structural; there is no while loop or other unbounded iteration construct. Starlark is one of the more capable and mainstream non-Turing-complete languages out there, and doesn't resemble the other common ones which mostly show up in theorem provers. On the one hand I think the logic in a build system that needs to reason about incremental builds absolutely should be guaranteed to terminate, but in some particularly painful situations I've had to resort to iteration over smart-contract-style "gas" parameters.
EDIT: as a parting shot, dhall is another non-Turing-complete language in common usage, but its claim to fame is that it gets used in places that arguably shouldn't be doing any computation at all.
EDIT: as a parting shot, dhall is another non-Turing-complete language in common usage, but its claim to fame is that it gets used in places that arguably shouldn't be doing any computation at all.
A type system is a very good thing, but it directly contradicts one of the goals for this language, simplicity. As someone who has written type inference code for plain Hindley-Milner type systems and those with subtyping, I can tell you this is very much an open research problem.
Inferred types, understandable type errors, expressive language: choose two out of three. If you sacrifice good type inference and require users to specify type annotations themselves they will not like it especially considering users' mental model of this language comes from Python; if you sacrifice understandable type errors, users will reject the whole system as soon as they encounter a type error; if you sacrifice expressiveness you are taking away features users want like subtyping.
If you want something that's ignored by Bazel and only used by some other tools you already have it: docstrings. You can enforce docstrings to be of a certain format and contain type annotations. Be the solution you want to see: be that hobbyist that writes a type checker and language server.
Inferred types, understandable type errors, expressive language: choose two out of three. If you sacrifice good type inference and require users to specify type annotations themselves they will not like it especially considering users' mental model of this language comes from Python; if you sacrifice understandable type errors, users will reject the whole system as soon as they encounter a type error; if you sacrifice expressiveness you are taking away features users want like subtyping.
If you want something that's ignored by Bazel and only used by some other tools you already have it: docstrings. You can enforce docstrings to be of a certain format and contain type annotations. Be the solution you want to see: be that hobbyist that writes a type checker and language server.
I don’t get this argument as it seems at odds with the existence proof of Python itself having optional typing, type inference, understandable type errors and an expressive language. What am I missing?
Here's an elementary litmus test that anyone slightly experienced with type systems will know.
How do you type the omega combinator in Python?
In case you claim this is impractical functional programming, bear in mind you can write the same thing using classes in object-oriented programming.
---
Okay let's not even talk about these weird-looking "combinators" even though they have a rich history. Consider this function:
How do you type the omega combinator in Python?
lambda x: x(x)
(lambda x: x(x))(lambda x: x(x))
lambda f: (lambda x: f(x(x)))(lambda x: f(x(x)))
In case you claim this is impractical functional programming, bear in mind you can write the same thing using classes in object-oriented programming.
---
Okay let's not even talk about these weird-looking "combinators" even though they have a rich history. Consider this function:
lambda x: {'this': x, 'next': x + 1}
This seems like a very weird technical explanation that doesn’t actually address my question. Python typing works well in practice and doesn’t suffer from any of the problems you listed.
Also, from a brief investigation, according to [1] Haskell also isn’t able to express the omega combinator in its type system (& indeed the answer says very few type systems are able to do so). This suggests this is a very bad litmus test if almost no languages can actually pass it even though a) languages exist with explainable type errors b) the languages are general purpose and fairly expressive c) they support type inference. An obvious example of this is Rust.
[1] https://stackoverflow.com/questions/33546004/is-it-possible-...
Also, from a brief investigation, according to [1] Haskell also isn’t able to express the omega combinator in its type system (& indeed the answer says very few type systems are able to do so). This suggests this is a very bad litmus test if almost no languages can actually pass it even though a) languages exist with explainable type errors b) the languages are general purpose and fairly expressive c) they support type inference. An obvious example of this is Rust.
[1] https://stackoverflow.com/questions/33546004/is-it-possible-...
You have a different definition of "works well" and also a different definition of "type inference" here. Rust doesn't have global type inference. C++'s `auto` doesn't count. Go's `:=` syntax doesn't count.
Why not? Because you are adding typing retroactively to a dynamically typed language like Python. If a language was built with typing, you can do this because your initial choice of a type system already constrains the set of valid programs. But a Python-like language where users are already used to having no restrictions on runtime types? Absolutely not. Especially not in a language that encourages duck typing. Let's go back to the omega combinator example. The Stack Overflow link is correct: Haskell cannot assign a type to it. That means the type system is purposefully designed weak enough that the omega combinator cannot be written in the first place! No valid Haskell program has it! Therefore you can totally disregard it. Python is different. You can already write the omega combinator in it. I wrote it three times in this thread. So a bolt-on type system needs to assign a type to it. And you can't.
Python does not have a type system that "works well" and will never have one.
Why not? Because you are adding typing retroactively to a dynamically typed language like Python. If a language was built with typing, you can do this because your initial choice of a type system already constrains the set of valid programs. But a Python-like language where users are already used to having no restrictions on runtime types? Absolutely not. Especially not in a language that encourages duck typing. Let's go back to the omega combinator example. The Stack Overflow link is correct: Haskell cannot assign a type to it. That means the type system is purposefully designed weak enough that the omega combinator cannot be written in the first place! No valid Haskell program has it! Therefore you can totally disregard it. Python is different. You can already write the omega combinator in it. I wrote it three times in this thread. So a bolt-on type system needs to assign a type to it. And you can't.
Python does not have a type system that "works well" and will never have one.
I think the disagreement is about what “works well” means. You are approaching it from some kind of theoretical purity whereas most people approach it from the perspective of “works for every program I am likely to encounter”. Omega combinators aren’t an example of something typically written in Python. I think you’re making a similar decision about global type inference as the only “true” definition of type inference when clearly more limited type inference already adds a significant amount of utility & there’s not typically that much lost in an inability to avoid typing functions - it’s a bit inconvenient in some places, but overall acts as a way to define the explicit contract between the method body and the rest of the code which makes errors faster to spot and the language compile more quickly.
You are correct that the holy grail you’re trying to reach is impossible, but relaxing some constraints still yields a heck of a lot of practical benefit.
You are correct that the holy grail you’re trying to reach is impossible, but relaxing some constraints still yields a heck of a lot of practical benefit.
The problem with "works for every program I am likely to encounter" is that you don't know what kind of programs your users are writing.
Well, now that I think more about it, except when you are Google or Meta and you have a giant monorepo full of code that users of this language has actually written. So if Starlark were to gain a type system, the type system designer would probably just run it through the entire Starlark code at Google.
Speaking of Meta, this suddenly reminds me of Flow https://flow.org/ an effort at Meta to add a bolt-on type system to JavaScript. Naturally it doesn't aim to "work well" 100% of the time but maybe working 80% of the time is already valuable enough for them to use and announce it.
Well, now that I think more about it, except when you are Google or Meta and you have a giant monorepo full of code that users of this language has actually written. So if Starlark were to gain a type system, the type system designer would probably just run it through the entire Starlark code at Google.
Speaking of Meta, this suddenly reminds me of Flow https://flow.org/ an effort at Meta to add a bolt-on type system to JavaScript. Naturally it doesn't aim to "work well" 100% of the time but maybe working 80% of the time is already valuable enough for them to use and announce it.
> is that you don't know what kind of programs your users are writing
Except we have lots of easily accessible OSS code available via GitHub/GitLab etc in addition to self-reporting from closed repos. Can you find any instance of an omega combinator in use? I'm not even sure omega combinator is relevant to Starlark given that Starlark is a more limited language derived from Python. For example, it doesn't typically allow for recursion which I believe would be required to express an Omega combinator within it. Yes I know the definition of the combinator says it's not recursive, but that's in a pure CS sense. In a practical sense, there's not much difference between a function being passed itself as an argument and then invoking it vs invoking itself directly, particularly from an enforcement perspective. Indeed, you can verify it'll fail the recursion prevention code in Starlark [1]
[1] https://github.com/bazelbuild/bazel/blob/e1a73e6e89a082e3d80...
Except we have lots of easily accessible OSS code available via GitHub/GitLab etc in addition to self-reporting from closed repos. Can you find any instance of an omega combinator in use? I'm not even sure omega combinator is relevant to Starlark given that Starlark is a more limited language derived from Python. For example, it doesn't typically allow for recursion which I believe would be required to express an Omega combinator within it. Yes I know the definition of the combinator says it's not recursive, but that's in a pure CS sense. In a practical sense, there's not much difference between a function being passed itself as an argument and then invoking it vs invoking itself directly, particularly from an enforcement perspective. Indeed, you can verify it'll fail the recursion prevention code in Starlark [1]
[1] https://github.com/bazelbuild/bazel/blob/e1a73e6e89a082e3d80...
Global inference is a nightmare, you simply don't want global inference. It means that the minimum understandable system is the entire system, if you don't understand the entire system you don't understand any of it, this can't scale.
When weird type theory people insist you want global inference and that you should sacrifice something you actually value to get it, treat them the same as if Hannibal Lecter was explaining why you should let him kill and eat your best friend. Maybe Hannibal sincerely believes this is a good idea, that doesn't make it a good idea, it just further underscores that Hannibal is crazy.
When weird type theory people insist you want global inference and that you should sacrifice something you actually value to get it, treat them the same as if Hannibal Lecter was explaining why you should let him kill and eat your best friend. Maybe Hannibal sincerely believes this is a good idea, that doesn't make it a good idea, it just further underscores that Hannibal is crazy.
As a user of languages that do global inference, I have yet to see much killing and eating in the programs I work on. They mostly make sense.
Your dichotomy between type systems that are too restrictive and type systems that are too complex only appears because you implicitly require soundness.
In Python, all your examples can be typed as "Any" https://docs.python.org/3/library/typing.html#the-any-type
It's an extremely simple type that never leads to hard-to-understand type errors, because it never produces type errors. And you can use it for any real-world program, including malformed ones.
Of course that means the type system is unsound and accepts programs that will fail at runtime. But that is perfectly fine as long as the type checker can spot some issues and gets out of your way otherwise.
In Python, all your examples can be typed as "Any" https://docs.python.org/3/library/typing.html#the-any-type
It's an extremely simple type that never leads to hard-to-understand type errors, because it never produces type errors. And you can use it for any real-world program, including malformed ones.
Of course that means the type system is unsound and accepts programs that will fail at runtime. But that is perfectly fine as long as the type checker can spot some issues and gets out of your way otherwise.
And it works great for incremental typing! You start with almost everything (except constant literals and functions that return then) having a type "Any" and let users add typing incrementally.
Python typing is so basic that it didn't even support a proper JSON type until a year ago (!), and yet it brings value to millions of Python programmers around the world.
Python typing is so basic that it didn't even support a proper JSON type until a year ago (!), and yet it brings value to millions of Python programmers around the world.
[deleted]
Given that “types” are passed around like values in Bazel this may prove complicated to support.
Given that is deterministic, it should be possible to just run the code and record the set of types that reach every parameter and variable.
A bit expensive, perhaps. And it breaks down if the code is in an intermediate state. Like, "I just deleted a comma, where did my type annotations go?"
A bit expensive, perhaps. And it breaks down if the code is in an intermediate state. Like, "I just deleted a comma, where did my type annotations go?"
Are you saying that every function can only be called with a consistent set of types in the parameters? It’s not possible to call a function two times and supply parameters that have different fields on them?
Unless that is true, the end result might not be ideal. You could certainly record the information that is there at every line of code at runtime, and you could probably calculate the union of the parameter types to find only the fields that are always there, which would be fairly okay I guess.
Unless that is true, the end result might not be ideal. You could certainly record the information that is there at every line of code at runtime, and you could probably calculate the union of the parameter types to find only the fields that are always there, which would be fairly okay I guess.
A type system that doesn't do anything? It has that, it's called comments.
Before you try to tell me that it's somehow different, consider that the main thing a type system has to be for consistency is accurate. If they types aren't checked by a compiler or interpreter, then someone can change the way the variable is assigned or what the function will work with, and the annotation will just be wrong.
The idea is to have gradual typing, like Python does. Most annotations in Python have no impact on runtime (e.g. parameter types aren't checked), but they are still valuable for external tools to perform type checking. A program with the wrong types will still run, but you will get type errors from the checker.
One difference is that Python specifies the type system in PEPs (basically Python's RFCs), while OP didn't ask for that here. This would mean whatever tool is implemented would define the type system.
One difference is that Python specifies the type system in PEPs (basically Python's RFCs), while OP didn't ask for that here. This would mean whatever tool is implemented would define the type system.
OP did also say "They wouldn't even have to be specified", which is the big difference here needed for a type checker to actually use them over comments.
I never felt before that I am wasting brain cells as much as when I have to do something in bazel. The hermecicity thing it does relatively well but god does the documentation suck, at some point you can only get farther if you just read the java code implementing it...
I think bazel is only worthwhile when you are big enough to have a team that builds and maintains the bazel setup in a company/team. At Google it works fantastically, but I've also tried putting it into a project from scratch and it was too much.
It’s been many years since last time i had to do anything in bazel’s java code. Most warts have been massively improved and only require occasional starlark hack or the right incantation of flags. The docs are honestly not too bad but the system is so massive and deals with so much inherent complexity that it always going to be missing something
This is my experience too. Just waiting for bzlmod to finally be supported by all the commonly used libraries. Looking at you, gRPC.
Cheat codes breaking Bazel 7’s sandbox: ‘cd -P’.
sudo give me my files.
sudo give me my files.
> Deterministic evaluation. If you execute the same code twice, you will get the same results. In Python, the code won’t be deterministic if it relies on the output of functions like “id”, “hash”, if it iterates over a hashtable, if it has race conditions, or if it measures the execution time.
> if it has race conditions
Does this mean starlark cannot generate a race condition? If so, how does threading work?
> if it has race conditions
Does this mean starlark cannot generate a race condition? If so, how does threading work?
Yes. See my other comment - https://news.ycombinator.com/item?id=40595125
In short: Evaluating a file has no visible side-effect. The evaluation returns a set of frozen values. These values that can accessed by other threads become immutable.
In short: Evaluating a file has no visible side-effect. The evaluation returns a set of frozen values. These values that can accessed by other threads become immutable.
> how does threading work?
Basic answer: there is no threading, at least not for the user.
The build system runs a thread per BUILD file (in bazel). Since the BUILD files are written in starlark and starlark has no threads -- there is no problem.
Basic answer: there is no threading, at least not for the user.
The build system runs a thread per BUILD file (in bazel). Since the BUILD files are written in starlark and starlark has no threads -- there is no problem.
You can define a value (let's say a dictionary) in a .bzl file and load it from multiple BUILD files. This is safe only because the dictionary becomes immutable before it is shared.
Bazel is massively parallel. It has to evaluate a potentially large number of BUILD files; each file can have multiple load statements. You end up with a graph of dependencies and Bazel will evaluate as many files as possible in parallel.
Bazel is massively parallel. It has to evaluate a potentially large number of BUILD files; each file can have multiple load statements. You end up with a graph of dependencies and Bazel will evaluate as many files as possible in parallel.
It's really interesting that the original author compares it to Lua. I've never heard that comparison, but I've been recently considering building a similar build system. Mimicking starlark files would be easy: all you would have to do is use Lua's load[1] method with a highly constraint environment and you would have the deterministic environment that starlark has (you would have to inject deterministic iteration functions and importing/etc obviously).
[1]: https://lua.org/manual/5.4/manual.html#pdf-load
[1]: https://lua.org/manual/5.4/manual.html#pdf-load
I have a hobby project that forwards qBittorent's logs to Telegram in Go, and uses Starlark to configure the filtering rules without hard coding the expression in Go. Pretty trivial to implement using the Go implementation of Starlark.
What I miss in some of these cripting/embedded languages is coroutines where one coroutine is in the embedded language and the other is in the host language...
That would be very helpful !
So are there languages that do that ?
So are there languages that do that ?
I rtfa excited to learn about another uPython in the “embedded” space. Alas, they meant embedded in a different way. Wish we had better terms for different variants of embedded.
Starlark needs metering so you can do fair polling when embedded in an application, then resume the paused processes.
Polling for events sounds like the polar opposite of hermetic execution.
It sounds like OP just wants the ability to suspend and resume Starlark execution. To first approximation they can just send SIGSTOP and SIGCONT signals to it, but they are probably asking for a more integrated way.
How do they guarantee both deterministic results and parallelism?
The evaluation of a file happens in a single thread.
At the end of the file evaluation, Starlark exports the values and functions defined in the file. All values are frozen, meaning they won't ever be mutated.
Since no shared object can be modified, you can have any number of threads reading the object. So you can safely evaluate many files in parallel.
Caveat: this assumes the interpreter doesn't expose functions like reading/writing on a disk, etc.
At the end of the file evaluation, Starlark exports the values and functions defined in the file. All values are frozen, meaning they won't ever be mutated.
Since no shared object can be modified, you can have any number of threads reading the object. So you can safely evaluate many files in parallel.
Caveat: this assumes the interpreter doesn't expose functions like reading/writing on a disk, etc.
Determinism: via sandboxing builds, it’s a little leaky by default (but getting better). See https://bazel.build/basics/hermeticity
Parallelism: Easier with sandboxing, but the build declares all inputs/outputs so it builds a merkle tree and strictly inforces a DAG. This way you can parallelize independent subgraphs and cache at a fine grained level.
Parallelism: Easier with sandboxing, but the build declares all inputs/outputs so it builds a merkle tree and strictly inforces a DAG. This way you can parallelize independent subgraphs and cache at a fine grained level.
"Some people might say it’s a bit like Lua with Python syntax"
ye gods
ye gods
I can appreciate that it might not sound that appetizing but it’s really pretty good.
I worked on the original Buck and kind of caught the “principled and performant polyglot build system” bug and I’ve been diving down that rabbit hole since.
There are still usability and adoption challenges, but it’s the future and between buck2 and bazel7/bzlmod the gap to slow, non-deterministic alternatives is closing fast.
I wouldn’t write it off.
I worked on the original Buck and kind of caught the “principled and performant polyglot build system” bug and I’ve been diving down that rabbit hole since.
There are still usability and adoption challenges, but it’s the future and between buck2 and bazel7/bzlmod the gap to slow, non-deterministic alternatives is closing fast.
I wouldn’t write it off.
[deleted]
Why do you call out bzlmod? I haven't heard great things about it.
To the extent there’s a real issue with ‘MODULE.bazel’ (aka bzlmod), it’s that Bazel has such a rich ecosystem even on the old, janky ‘WORKSPACE’-style that the slick new thing that always works is impossible to migrate in one go.
The Bazel team flags things off by default for years, and then things on for years, because they’re engineers and try hard not to break people’s shit.
Are feature flags and migration paths and interim solutions more work? Yeah, no doubt.
But for all their recent fumbles in AI and steadily downward trajectory on search and all the things that happens when a big company is run by people who were never all that technical?
Google still has a hard core of the baddest hackers you don’t want to mess with.
The Bazel team flags things off by default for years, and then things on for years, because they’re engineers and try hard not to break people’s shit.
Are feature flags and migration paths and interim solutions more work? Yeah, no doubt.
But for all their recent fumbles in AI and steadily downward trajectory on search and all the things that happens when a big company is run by people who were never all that technical?
Google still has a hard core of the baddest hackers you don’t want to mess with.
I'm happy with bzlmod.
What I hate about it is that not every bazel ruleset I use has yet been ported to it. But it's getting there.
For example in my monorepo I'm only missing rule_distroless and I migrated all my deps to bzlmod.
The modules lock file situation has been greatly improved since 7.2.0-rc1. The lock file contains much less digests in it and its less likely to cause spurious merge conflicts
With bazelisk and .bazelversion we managed to have everybody use the same version of bazel and thus we could cheaply try out the rc1 and so far is working fine.
What I hate about it is that not every bazel ruleset I use has yet been ported to it. But it's getting there.
For example in my monorepo I'm only missing rule_distroless and I migrated all my deps to bzlmod.
The modules lock file situation has been greatly improved since 7.2.0-rc1. The lock file contains much less digests in it and its less likely to cause spurious merge conflicts
With bazelisk and .bazelversion we managed to have everybody use the same version of bazel and thus we could cheaply try out the rc1 and so far is working fine.
One challenge with Starlark was not having exceptions, which by itself is a good thing. But not having go-style multi-value returns in Starlark makes error handling verbose. Since the errors originate in plugin calls to go code, the solution I implemented was a thread-local to store the last error and handle that on the next plugin call if the error was not explicitly handled in the code [3]. Worked out pretty well in my test apps. For example, this app [4] implements a bookmark manager, with minimal error handling required in the code.
Starlark is great for adding dynamic behavior for go applications. I was worried about performance when I started but perf has not been a concern in the context of a web app server.
[1] https://github.com/google/starlark-go
[2] https://github.com/claceio/clace
[3] https://clace.io/docs/plugins/overview/#automatic-error-hand...
[4] https://github.com/claceio/apps/blob/main/utils/bookmarks/ap...