This page discusses advanced usage when invoking Pants on the command line. We assume you already know the basic command-line structure.
- For details on how to specify target addresses, see Target Addresses.
- For details on how to specify options, see Options.
- For a list of Pants' goals and their options, see the Options Reference.
Order of Arguments
A simple Pants command line looks like
./pants goal target. E.g.,
./pants compile src/java/::.
The full command line specification is:
./pants <global and fully-qualified flags> \ <goal1.task1> <shorthand flags for task1> \ <goal2.task2> <shorthand flags for task2> \ ... \ <target1> <target2> ... [-- passthrough options for last goal]
Fully qualified flags can be passed anywhere on the command line
-- separator for passthrough args, but
shorthand flags must immediately follow the goal they apply to.
Consider the following command:
./pants --level=debug compile.zinc --no-delete-scratch --resolve-ivy-open src::
--levelis a global flag.
- The goal and task to run are
--no-delete-scratchis shorthand for the
--resolve-ivy-opencommand is a fully qualified flag and applies to the
resolve.ivytask. Although the task
resolve.ivyisn't specified on the command line it implicitly runs because
compile.zinctask depends on it.
You can pass options to pants using the a config file, the environment, or command line flags. See the Options page for more details.
How to Use Shorthand Flags
Either fully qualified or shorthand flags can be used to pass an
option to a task. The fully qualified (or long form) options are
listed in the
help output and the Options Reference.
The long form is more foolproof to use because it can go almost anywhere on
the command line, but the shorthand version can save typing.
For many goals, there is only a single task registered. For example,
to specify the
--list-sep option for the
list goal you could use
the long form:
./pants list --list-sep='|' examples/src/python/example:
or you could use the short form:
./pants list --sep='|' examples/src/python/example:
When a goal has multiple tasks registered, you must fully specify the
task and goal name to use the short form flag. Here's an example of
using the long form to pass an option to the
./pants --no-compile-zinc-delete-scratch compile src::
To use the shorthand form of the option, specify both goal and task
./pants compile.zinc --no-delete-scratch src::
This is especially handy if you have lots of options to type:
./pants publish.jar --named-snapshot=1.2.3-SNAPSHOT --no-dryrun --force src/java::
You can use shorthand even when you want to pass options to multiple tasks by listing each task. For example:
./pants compile --compile-zinc-no-delete-scratch --resolve-ivy-open src::
can also be expressed using shorthand flags:
./pants --level=debug compile.zinc --no-delete-scratch resolve.ivy --open src::
In some cases Pants allows you to pass arguments directly through to the underlying tool it invokes. These are specified last on the command line after a double-hyphen, and are passed through the last goal specified.
E.g., to pass
-k foo to
pytest (to say "only run tests whose names contain
./pants test.pytest tests/python/pants_test/tasks -- -k foo
You can use
test instead of
test.pytest above; Pants then applies the passthrough args
through all tasks in
test that support them. In this case, it would pass them to JUnit as well.
So it only makes sense to do this if you know that JUnit won't be invoked in practice (because
you're not invoking Pants on any Java tests).
The Pants Daemon
1.3.0 release of pants includes an alpha release of a daemon to accelerate common
graph operations including build file parsing and source fingerprinting.
The daemon caches many filesystem operations run over run, and uses watchman to invalidate that cache. This can significantly improve the performance of incremental and noop builds (ie, cases where relatively small portions of the repo have changed since the previous build).
In this "alpha" release, there are two significant caveats to using the daemon:
- Changes to
pants.inirequire running clean-all in order to force re-reading configuration. While this is unlikely to happen directly within your branch, it will occasionally happen when switching back and forth between branches.
./pants runare not yet supported.
To enable the daemon, see the example in
pants.daemon.ini in the root of the pantsbuild repo:
# A config override that enables use of pantsd + watchman + buildgraph caching via the new engine. # # N.B. This is currently recommended only for development use. # # Development Usage: # # # Launch the daemon via an initial invocation with
-ldebugfor better logging: # $ ./pants -ldebug --pants-config-files=pants.daemon.ini help # # # In another window, tail the pantsd log file: # $ tail -F .pants.d/pantsd/pantsd.log # # # Populate the resident scheduler with an initial pantsd-based run: # $ ./pants --pants-config-files=pants.daemon.ini list 3rdparty:: # # # Re-run to utilize the buildgraph caching: # $ ./pants --pants-config-files=pants.daemon.ini list 3rdparty:: # # # Kill pantsd and watchman: # $ ./pants -ldebug --pants-config-files=pants.daemon.ini clean-all # # You can also export this for all pants runs using environment variables: # # $ export PANTS_CONFIG_FILES="$(pwd)/pants.daemon.ini" # [GLOBAL] enable_pantsd: True
The daemon will be in "alpha" until the Caveats mentioned above are addressed, after which we
hope to move it into a "beta" period where we recommend its use more widely. Finally, we hope to
enable the daemon by default for the
1.4.0 release of pants.