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

apkBuild an android bundle with compiled code and assets.
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.
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.
compile-changedFind and compile changed targets.
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.
eclipseCreate an Eclipse project from the given targets.
ensimeCreate an Ensime project from the given targets.
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.
ideaCreate an IntelliJ IDEA project from the given targets.
idea-pluginInvoke IntelliJ Pants plugin (installation required) to create a project.
importsResolve external source dependencies.
invalidateInvalidate the entire build.
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.
listLists all targets matching the target specs.
list-ownersPrint targets that own a source file.
markdownGenerate HTML from Markdown docs.
minimizePrint a minimal covering set of targets.
ng-killallKill running nailgun servers.
optionsDisplay meta-information about options.
pathFind a dependency path from one target to another.
pathdepsList all paths containing BUILD files the target depends on.
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.
repl2
resolveResolve external binary dependencies.
resourcesPrepare resources.
rootsList the repo's registered source roots.
runInvoke a binary.
run-dirtyInvoke a binary, skipping compilation.
run2
serverRun the reporting server.
setup-pyGenerate setup.py-based Python projects.
signSign Android packages with keystores using the jarsigner tool.
sitegenGenerate the Pants static web site.
sortTopologically sort the targets.
targetsList available target types.
testRun tests.
test-changedFind and test changed targets.
thrift-linterPrint linter warnings for thrift files.
unpack-jarsUnpack artifacts specified by unpacked_jars() targets.

Option Reference