Pants Reference

This page documents Pants goals, tasks, subsystems and options.

Goals

A goal is an action that can be taken on build targets. It represents some high-level goal that you wish to accomplish, such as compiling your code. Goals are how you tell Pants what to do on the command line. E.g., this is how you invoke the compile goal:

  ./pants compile examples/src/java/org/pantsbuild/example/hello/main
Goals may depend on other goals, and Pants will invoke those dependencies before invoking the goal you requested. For example, the run goal depends on the compile goal, so these commands are equivalent:
    ./pants compile run examples/src/java/org/pantsbuild/example/hello/main
    ./pants run examples/src/java/org/pantsbuild/example/hello/main

Tasks

A goal is made up of one or more tasks. For example, the compile.zinc task compiles JVM code using the Zinc compiler, and is installed in the compile goal.

Many goals are naturally 'singletons', i.e., they contain only one task. For example the clean-all goal, which deletes all build byproducts. In these cases we often casually elide the distinction between the goal and its task. E.g., we refer to the clean-all task, not the clean-all.clean-all task.

Subsystems

A subsystem is some configurable part of Pants that can be used across multiple tasks and other parts of the system, including other subsystems. Examples include a JVM, a remote code repository or a build cache.

There may be multiple instances of subsystem configuration. Tasks and other subsystems that use a subsystem may either use its global instance or they may instantiate their own instance, overriding its global config. For example, a task may use the global JVM configuration, or it may use its own specialized JVM configuration.

Options and Scopes

Tasks and subsystems can be configured using options. Option values may be specified using command line flags, environment variables or the pants.ini config file.

Pants has many tasks and subsystems, and therefore it has many options. For organizational purposes, the options are grouped into scopes:

  • The options for task foo in goal bar belong to scope bar.foo.
  • If a task foo has the same name as its goal then it belongs to scope foo (rather than foo.foo). This provides convenience and brevity in the case of 'singleton' goals.
  • The global instance of subsystem foo belongs to scope foo.
  • The specialized instance of subsystem foo used by scope bar.baz belongs to scope foo.bar.baz.

Scopes are used as qualifiers when specifying option values. For example, to set the value of option foo in scope bar.baz:

  • Set the value of key foo in section bar.baz in pants.ini:
          [bar.baz]
          foo = 42
  • Set the value of environment variable PANTS_BAR_BAZ_FOO:
          PANTS_BAR_BAZ_FOO=42 ./pants compile examples/src/java/org/pantsbuild/example/hello/main
  • Set the value of command line flag --bar-baz-foo:
          ./pants --bar-baz-foo=42 compile examples/src/java/org/pantsbuild/example/hello/main
          ./pants compile --bar-baz-foo=42 examples/src/java/org/pantsbuild/example/hello/main

For convenience, you can qualify a command-line goal with a task, followed by the unqualified form of command line flags belonging to that task. E.g., this:

      ./pants compile.zinc --foo --bar run.jvm --baz \
        examples/src/java/org/pantsbuild/example/hello/main

is equivalent to this:

      ./pants run --compile-zinc-foo --compile-zinc-bar --run-jvm-baz \
        examples/src/java/org/pantsbuild/example/hello/main

Pants also has a few global options, for basic systemwide configuration.


Available Goals

bash-completionGenerate a Bash shell script that teaches Bash how to autocomplete pants command lines.
benchRun benchmarks.
binaryCreate a runnable binary.
bootstrapBootstrap tools needed by subsequent build steps.
buildgenAutomatically generate BUILD files.
buildozerManipulate BUILD files.
bundleCreate a deployable application bundle.
check-published-depsFind references to outdated JVM artifacts.
classmapPrint a mapping from class name to the owning target from target's runtime classpath.
clean-allDelete all build products, creating a clean workspace.
clocPrint counts of lines of code.
compileCompile source code.
confluenceA task to publish Page targets to Confluence wikis.
deferred-sourcesMap DeferredSourcesFields to files that produce the product 'unpacked_archives'.
dep-usageCollect target dependency usage data.
dependeesList all targets that depend on any of the input targets.
dependenciesPrint the target's dependencies.
depmapDepict the target's dependencies.
detect-duplicatesDetect JVM classes and resources with the same qualified name on the classpath.
docGenerate documentation.
exportExport project information in JSON format.
export-classpathCreate stable symlinks for runtime classpath entries for JVM targets.
filedepsList all source and BUILD files a target transitively depends on.
filemapPrint a mapping from source file to the target that owns the source file.
filterFilter the input targets based on various criteria.
fmtAutoformat source code.
genGenerate code.
goRuns an arbitrary go command against zero or more go targets.
go-envRuns an arbitrary command in a go workspace defined by zero or more go targets.
goalsList available goals.
idea-pluginInvoke IntelliJ Pants plugin (installation required) to create a project.
importsResolve external source dependencies.
index
invalidate
jar
jvm-platform-explainConsole task which provides helpful analysis about jvm platform dependencies.
jvm-platform-validateValidation step that runs well in advance of jvm compile.
kill-pantsdTerminate the pants daemon.
killserverKill the reporting server.
lintFind formatting errors in source code.
listLists all targets matching the target specs.
list-ownersPrint targets that own a source file.
markdownGenerate HTML from Markdown docs.
meta-renameRename a target and update its dependees' dependencies with the new target name
minimizePrint a minimal covering set of targets.
mypyInvoke the mypy static type analyzer for Python.
ng-killallKill running nailgun servers.
optionsDisplay meta-information about options.
outdated
pathFind a dependency path from one target to another.
pathsList all dependency paths from one target to another.
publishPublish a build artifact.
pyprep
referenceGenerate Pants reference documentation.
replRun a REPL.
repl-dirtyRun a REPL, skipping compilation.
resolveResolve external binary dependencies.
resourcesPrepare resources.
rootsList the repo's registered source roots.
runInvoke a binary.
run-dirtyInvoke a binary, skipping compilation.
serverRun the reporting server.
setup-pyGenerate setup.py-based Python projects.
sitegenGenerate the Pants static web site.
sortTopologically sort the targets.
targetsList available target types.
testRun tests.
thrift-linterPrint lint warnings for thrift files.
unpack-jarsUnpack artifacts specified by unpacked_jars() targets.

Option Reference


Generated by publish_docs from dist/reference/pants_reference_body.html 2018-05-03T17:02:34.275429