Setting up Pants

How to set up Pants for local development.

---

Step 1: Fork and clone pantsbuild/pants

We use the popular forking workflow typically used by open source projects. See https://guides.github.com/activities/forking/ for a guide on how to fork pantsbuild/pants, then clone it to your local machine.

macOS users: install a newer openssl

Pants requires a more modern OpenSSL version than the one that comes with macOS. To get all dependencies to resolve correctly, run these commands:

$ brew install openssl
$ echo 'export PATH="/usr/local/opt/openssl/bin:$PATH"' >> ~/.bashrc
$ echo 'export LDFLAGS="-L/usr/local/opt/openssl/lib"' >> ~/.bashrc
$ echo 'export CPPFLAGS="-I/usr/local/opt/openssl/include"' >> ~/.bashrc

(If you don't have brew installed, see https://brew.sh.)

Step 2: Set up Git hooks

We use two Git hooks:

1. If you didn't touch any Rust code, we add [ci skip-rust] to your commit message. If you didn't touch any of our release-related code, we add [ci skip-build-wheels] to your commit message.
2. Every time you run git commit, we run some checks and lints.

To install these, run:

$ build-support/bin/setup.sh

You can manually run the pre-commit check by running:

$ build-support/githooks/pre-commit

How to temporarily skip the pre-commit checks

Use git commit --no-verify to skip the checks.

We do not recommend this, though! The Python formatter Black frequently needs to make changes, and you'll need to do an entire new CI run if there are any formatting or linting issues.

Step 3: Bootstrap the Rust engine

Run ./pants.

Pants will download Rust and compile the engine. This command will also set up the Python virtual environment.

This will take several minutes

Rust compilation is really slow. Fortunately, this step gets cached, so you will only need to wait the first time.

If this takes more than 25 minutes, please comment on https://github.com/pantsbuild/pants/issues/9822 with the time it took for you to compile. (It's extra helpful if you are willing to share your CPU's speed and # of cores.)

Want a faster compile?

We default to compiling with Rust's release mode, instead of its debug mode, because this makes Pants substantially faster. However, this results in the compile taking 5-10x longer.

If you are okay with Pants running much slower when iterating, set the environment variable MODE=debug and rerun ./pants to compile in debug mode.

Rust compilation can use lots of storage

Downloading Rust and compiling the engine typically results in several gigabytes (~7-10 GB) of storage.

We have also not yet implemented automated garbage collection for building the engine because contributors are the only ones to need to compile Rust, not every-day users. Whenever we upgrade versions of Rust or make changes to the Rust code, the old files will stay around.

To free up space, run these commands:

rm -rf src/rust/engine/target
rm -rf ~/.cache/pants/bin
rm -rf ~/.cache/pants/rust

Warning: this will cause Rust to redownload and recompile everything.

Configure your IDE (optional)

Hooking up the Python virtual environment

Most IDEs allow you to configure a Python virtual environment so that the editor understands your Python import statements.

Pants sets up its virtualenv at build-support/virtualenvs/<arch>/pants_dev_deps.py{version}.venv. Point your editor to the bin/python file in this folder, e.g. build-support/virtualenvs/Darwin/pants_dev_deps.py36.venv/bin/python.

Pycharm guide

1. Use "New project" and click the option "Existing interpreter". Point the interpreter to the virtual environment location described above.
2. In your project tree (the list of folders and files), secondary click the folder src/python. Click "Mark directory as" and choose "Source Roots".

VSCode guide

Add this to your settings.json file inside the build root's .vscode folder:

settings.json

{
  "python.analysis.extraPaths": ["src/python"],
  "python.formatting.provider": "black",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.linting.flake8Args": ["--config=build-support/flake8/.flake8"]
}

python.analysis.extraPaths lets VSCode know where to find Pants's source root. The other config enables black and flake8.

Help us to document how to set up your favorite editor

We'd love your help. You can either click "Suggest edits" in the top right corner of this page or message us on Slack.