Pants v2: Fast, consistent builds for Python and more

Welcome to the Pants v2 documentation hub!

Pants v2 is a fast, scalable build system for growing codebases. It's currently focused on Python, with support for other languages coming soon.

Here you'll find guides to help you get started with Pants v2, comprehensive documentation on how to configure, run and customize Pants v2, and information on how to get help from the Pants community.

Get Started

Debugging and benchmarking

Some techniques to figure out why Pants is behaving the way it is.

Benchmarking Pants runs with multitime

Doing ... with PySpy

Obtaining Full Thread Backtraces

Pants runs as a Python program that calls into a native Rust library. In debugging locking and deadlock issues, it is useful to capture dumps of the thread stacks in order to figure out where a deadlock may be occurring.

One-time setup:

  1. Ensure that gdb is installed.
  • Ubuntu: sudo apt install gdb
  1. Ensure that the kernel is configured to allow debuggers to attach to processes that are not in the same parent/child process hierarchy.
  • echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
  • To make the change permanent, add a file to /etc/sysctl.d named 99-ptrace.conf with contents kernel.yama.ptrace_scope = 0. Note: This is a security exposure if you are not normally debugging processes across the process hierarchy.
  1. Ensure that the debug info for your system Python binary is installed.
  • Ubuntu: sudo apt install python3-dbg

Dumping thread stacks:

  1. Find the pants binary (which may include pantsd if pantsd is enabled).
  • Run: ps -ef | grep pants
  1. Invoke gdb with the python binary and the process ID:
  • Run: gdb /path/to/python/binary PROCESS_ID
  1. Enable logging to write the thread dump to gdb.txt: set logging on

  2. Dump all thread backtraces: thread apply all bt

  3. If you use pyenv to mange your Python install, a gdb script will exist in the same directory as the Python binary. Source it into gdb:

  • source ~/.pyenv/versions/3.8.5/bin/python3.8-gdb.py (if using version 3.8.5)
  1. Dump all Python stacks: thread apply all py-bt

Updated 2 months ago


Debugging and benchmarking


Some techniques to figure out why Pants is behaving the way it is.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.