Starpls

starpls is a language server for Starlark, the configuration language used by Bazel and Buck2.

Installation

VSCode

Make sure you have at least the 0.10.0 version of the vscode-bazel extension installed, as it adds support for launching a language server.

If you're on a Mac with Apple Silicon, then you can install starpls with Homebrew and skip ahead to the section about configuring VSCode:

brew install withered-magic/brew/starpls

Otherwise, you can grab a release from the releases page. Make sure to download the appropriate version for your OS and architecture! After downloading the binary, make sure to adjust its permissions to make it executable, e.g.

chmod +x starpls-darwin-arm64

Additionally, on Mac OS, you may see an error similar to

“starpls-darwin-arm64” can’t be opened because Apple cannot check it for malicious software.

To fix this, click Show in Finder, then right-click on the starpls-darwin-arm64 executable, click Open, and select Open in the warning that comes up. This will cause the com.apple.quarantine xattr to be removed from the executable and will stop the warning from appearing further.

Either way, at this point you can put the executable somewhere on your $PATH.

Once done, add the following to your VSCode configuration and reload VSCode for it to take effect:

{
  "bazel.lsp.command": "starpls"
}

Experimental features are enabled through flags on the starpls server subcommand. For example:

{
    "bazel.lsp.command": "starpls",
    // Note the first argument is "server", which is required because the flags exist only
    // on the "starpls server" subcommand (and not the top-level "starpls" command).
    "bazel.lsp.args": ["server", "--experimental_infer_ctx_attributes"]
}

Note: If you don't put starpls directly on the $PATH, then for bazel.lsp.command you'll have to specify the absolute path to the starpls executable instead. Additionally, if your VSCode setup also has any tasks that run Bazel commands on open, those might temporarily block the server from starting up because of the Bazel lock; the server will still spin up once it is able to acquire the lock.

Alternatively, you can build starpls with Bazel:

bazel run -c opt //editors/code:copy_starpls

This builds the executable and copies it to <repository_root>/editors/code/bin/starpls. From there, you can add it to the $PATH or copy it to a different directory, remembering to update the extension settings as detailed above.

Zed

Install the zed-starlark extension.

Neovim via nvim-lspconfig

Make sure you've installed and configured nvim-lspconfig in a way that works for you.

Install using homebrew as described above, then do the following in your init.lua:

require("lspconfig").starpls.setup { }

You can see the config info here.

Tips and Tricks

Make sure to use PEP 484 type comments to document your function signatures. This helps a ton with autocomplete for situations like rule implementation functions. For example, if you add a type comment as in the following...

def _impl(ctx):
    # type: (ctx) -> Unknown
    ctx.
    #  ^ and this period was just typed...

then you'll get autocomplete suggestions for the attributes on ctx, like ctx.actions, ctx.attr, and so on!

Experimental features

Starpls has a number of experimental features that can be enabled via command-line arguments:

--experimental_infer_ctx_attributes

Infer attributes on a rule implementation function's ctx parameter.

def _foo_impl(ctx):
    ctx.attr.bar # type: int

foo = rule(
    implementation = _foo_impl,
    attrs = {
        "bar": attr.int(),
    },
)

--experimental_use_code_flow_analysis

Use code flow analysis to determine additional information about types.

if cond:
    x = 1
else:
    x = "abc"

x # type: int | string

--experimental_enable_label_completions

Enables completions for labels within Bazel files. For example, given the following BUILD.bazel file at the repository root:

my_rule(
    name = "foo"
)

my_rule(
    name = "bar",
    srcs = ["//:"],
              # ^ ... If the cursor is here, "foo" will be suggested.
)

Roadmap

Development

starpls currently requires a nightly build of Rust, due to usage of trait_upcasting as specified by RFC3324.

Prerequisites

Steps to get up and running:

  1. Run pnpm install in editors/code.
  2. Open VSCode, Run and Debug > Run Extension (Debug Build).
  3. In the extension development host, open a .star file and enjoy syntax highlighting and error messages!

Known Issues

Acknowledgements