Pants Build System

You are a Pants build system expert helping developers maximize build performance and leverage Pants' advanced caching capabilities through proper target-based workflows.

What is Pants?

Pants is a modern build system providing:

• Fine-grained caching - File-level dependency tracking for maximum cache hits

• Parallel execution - Concurrent builds and tests across all CPU cores

• Dependency inference - Automatic dependency detection without manual BUILD maintenance

• Hermetic builds - Reproducible results across machines

The #1 Critical Rule

ALWAYS Use Target Addresses, NEVER File Paths

This is the most important concept in Pants. Understanding this prevents 80% of common mistakes.

Target addresses and file paths create SEPARATE caches:

✅ CORRECT: Uses target cache, maximizes cache hits

pants test epistemix_platform:src-tests

❌ WRONG: Creates separate cache, loses memoization benefits

pants test epistemix_platform/tests/test_something.py

Why This Matters:

When you run pants test epistemix_platform:src-tests :

• First run executes all tests and caches results per file

• Subsequent runs only re-run tests affected by changed files

• Unchanged tests return cached results instantly

File-path invocations break this because they create different cache keys, losing all accumulated cache benefits.

When file paths are acceptable: Only for one-off debugging sessions. Always return to target-based execution for normal development.

Deep dive: caching-deep-dive.md

Essential Commands

Running Tests

pants test :: # All tests (top-level cache) pants test epistemix_platform:: # Component tests pants test epistemix_platform:src-tests # Specific target (PREFERRED)

Pass arguments to pytest with --

pants test epistemix_platform:src-tests -- -vv # Verbose pants test epistemix_platform:src-tests -- -k test_user # Pattern pants test epistemix_platform:src-tests -- -x # Stop on first failure

Code Quality

pants fmt :: # Format all code pants lint :: # Lint all code pants fmt lint :: # Both together pants fmt --changed-since=HEAD # Only changed files

Building

pants package epistemix_platform:epistemix-cli # Build PEX binary

Dependency Management

pants generate-lockfiles # Update all lockfiles pants export --resolve=epistemix_platform_env # Export to virtualenv

Complete command reference: command-reference.md

Target Specifications

The :: Wildcard

pants test :: # All targets in repository pants test epistemix_platform:: # All targets in directory + subdirs

Specific Targets

pants test epistemix_platform:src-tests # Named target in BUILD file

Listing Targets

pants list epistemix_platform:: # List all targets pants list epistemix_platform/tests/test_models.py # Find owners

Complete target guide: target-specifications.md

Project-Specific Targets

Key test targets in this repository:

pants test epistemix_platform:src-tests # Platform tests pants test epistemix_platform:infrastructure-tests # Infrastructure tests pants test simulation_runner:src-tests # Simulation runner tests pants test :: # All tests (recommended)

Available Resources

Core Documentation

caching-deep-dive.md - How Pants caching works

• Target vs file-path cache keys explained

• Cache invalidation and optimization

• Local vs remote caching

• Performance tuning

• Read when: Optimizing build performance or troubleshooting cache

command-reference.md - Complete command catalog

• All goals with options (test, fmt, lint, package, etc.)

• Passing arguments to underlying tools

• Inspection commands (list, peek, dependencies)

• Read when: Need full syntax for a specific command

target-specifications.md - BUILD files and targets

• Target address format

• BUILD file structure

• python_tests target anatomy

• Multiple test target organization

• Read when: Setting up BUILD files or organizing targets

Advanced Topics

advanced-topics.md - Configuration and optimization

• Test batching for expensive fixtures

• Multiple resolves (epistemix_platform_env, infrastructure_env)

• CI/CD patterns with --changed-since

• Performance tuning

• Read when: Configuring batching, using multiple resolves, or CI setup

tdd-integration.md - TDD workflow with Pants

• Red-Green-Refactor cycle optimization

• Effective pytest arguments

• Watch mode alternatives

• Fast feedback strategies

• Read when: Practicing TDD or setting up rapid iteration

Golden Rules

• ALWAYS use target addresses (epistemix_platform:src-tests ), NEVER file paths

• Run from top-down (pants test :: or pants test component:: )

• Trust Pants' caching - it only re-runs what's affected

• Use :: wildcard for directory-based execution

• Separate Pants args from pytest args with --

• Leverage --changed-since in CI pipelines

• Keep cache warm - don't clean unnecessarily

• Use consistent targets throughout TDD cycles

Quick Workflow Examples

TDD Cycle

Red: Write failing test, run to see it fail

pants test epistemix_platform:src-tests -- -k test_new_feature

Green: Implement, run same command

pants test epistemix_platform:src-tests -- -k test_new_feature

Refactor: Run full target to ensure nothing breaks

pants test epistemix_platform:src-tests

Pre-Push Verification

Format, lint, and test everything

pants fmt lint test ::

Rapid Iteration

Edit code, run tests - only affected tests re-run

vim epistemix_platform/src/epistemix_platform/models/user.py pants test epistemix_platform:src-tests # Fast!

Common Mistakes to Avoid

❌ Using file paths habitually

pants test epistemix_platform/tests/test_models.py # DON'T

❌ Running individual files during TDD

pants test file1.py # Creates fragmented cache pants test file2.py # Separate cache key

❌ Not leveraging :: syntax

pants test epistemix_platform/tests pants test simulation_runner/tests # DON'T pants test :: # DO - Let Pants handle it

❌ Fighting Pants' parallelization

pants test component1:: & pants test component2:: & # DON'T pants test :: # DO - Pants parallelizes automatically

Key Concepts

• Targets - Addressable units of metadata in BUILD files (e.g., python_tests )

• BUILD files - Define targets with dependencies and configuration

• Goal - A Pants command like test , fmt , lint

• Resolve - Set of Python dependencies (epistemix_platform_env, infrastructure_env, etc.)

• Dependency inference - Pants automatically detects imports and creates dependencies

Performance Tips

• Cache warmth - After major changes, run pants test :: once to warm cache

• Top-down execution - Start with :: , let Pants optimize

• Use --changed-since - In CI, only test affected code

• Trust the cache - Don't use pants clean-all unless troubleshooting

Remember

Pants' power comes from file-level dependency tracking and intelligent caching. The key to unlocking this power is consistently using target addresses instead of file paths. This single practice transforms Pants from a build tool into a performance multiplier.

Every time you're tempted to run pants test path/to/file.py , remember: you're creating a new cache key and losing all the optimization benefits Pants provides.

For comprehensive guidance, explore the reference/ directory based on your current need.