Pants Reference

Available Goals Option 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.rsc 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.toml 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.toml: 
          [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.rsc --foo --bar run.jvm --baz \
        examples/src/java/org/pantsbuild/example/hello/main

is equivalent to this: 

      ./pants run --compile-rsc-foo --compile-rsc-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

analysis
awslambda
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. The clean-all method allows for both synchronous and asynchronous options with the --async option.
cloc
compileCompile source code.
confluenceA task to publish Page targets to Confluence wikis.
deferred-sourcesMap `remote_sources()` to files that produce the product `UnpackedArchives`. If you want a task to be able to map sources like this, make it require the 'deferred_sources' product.
dep-usageCollect target dependency usage data.
dependeesList all targets that depend on any of the input targets.
dependees2
dependenciesPrint the target's dependencies.
dependencies2
depmapDepict the target's dependencies. Generates either a textual dependency tree or a graphviz digraph dot file for the dependency set of a target.
detect-duplicatesDetect JVM classes and resources with the same qualified name on the classpath.
docGenerate documentation.
exportExport project information in JSON format. Intended for exporting project information for IDE, such as the IntelliJ Pants plugin.
export-classpathCreate stable symlinks for runtime classpath entries for JVM targets.
export-dep-as-jar[Experimental] Create project info for IntelliJ with dependencies treated as jars. This is an experimental task that mimics export but uses the jars for jvm dependencies instead of sources. This goal affects the contents of the runtime_classpath, and should not be combined with any other goals on the command line.
filedepsList all source and BUILD files a target transitively depends on. Files may be listed with absolute or relative paths and any BUILD files implied in the transitive closure of targets are also included.
filedeps2
filemapPrint a mapping from source file to the target that owns the source file.
filterFilter the input targets based on various criteria. Each of the filtering options below is a comma-separated list of filtering criteria, with an implied logical OR between them, so that a target passes the filter if it matches any of the criteria in the list. A '-' prefix inverts the sense of the entire comma-separated list, so that a target passes the filter only if it matches none of the criteria in the list. Each of the filtering options may be specified multiple times, with an implied logical AND between them.
filter2
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.
idea-pluginInvoke IntelliJ Pants plugin (installation required) to create a project. The ideal workflow is to programmatically open idea -> select import -> import as pants project -> select project path, but IDEA does not have CLI support for "select import" and "import as pants project" once it is opened. Therefore, this task takes another approach to embed the target specs into a `iws` workspace file along with an skeleton `ipr` project file. Sample `iws`: ******************************************************** <?xml version="1.0"?> <project version="4"> <component name="PropertiesComponent"> <property name="targets" value="[&quot;/Users/me/workspace/pants/testprojects/tests/scala/org/pantsbuild/testproject/cp-directories/::&quot;]" /> <property name="project_path" value="/Users/me/workspace/pants/testprojects/tests/scala/org/pantsbuild/testproject/cp-directories/" /> </component> </project> ******************************************************** Once pants plugin sees `targets` and `project_path`, it will simulate the import process on and populate the existing skeleton project into a Pants project as if user is importing these targets.
importsResolve external source dependencies.
invalidate
jar
jvm-platform-explainConsole task which provides helpful analysis about jvm platform dependencies. This can be very useful when debugging inter-dependencies in large sets of targets with a variety of jvm platforms. By default, this calculates the minimum and maximum possible -target level of each JvmTarget specified, printing the range for each one on the console. This is determined by a target's dependencies and dependees: a target cannot have a higher -target level than its dependees, and it cannot have a lower -target level than any of its dependencies. Additional flags fine-tune this output, including printing more detailed analysis of which dependencies/dependees are limiting a target, or filtering the output to only targets you care about. Besides this functionality, --upgradeable and --downgradeable can print lists of targets which can (again, based on the limits of their dependencies and dependees) afford to be upgraded or downgraded to a different version.
jvm-platform-validateValidation step that runs well in advance of jvm compile. Ensures that no jvm targets depend on other targets which use a newer platform.
kill-pantsdTerminate the pants daemon.
killserverKill the reporting server.
link
lintFind formatting errors in source code.
list
list-and-die-for-testing
loginTask to auth against some identity provider. :API: public
markdownGenerate HTML from Markdown docs.
minimizePrint a minimal covering set of targets. For a given set of input targets, the output targets transitive dependency set will include all the input targets without gaps.
native-compile
ng-killallKill running nailgun servers.
node-installInstalls a node_module target into the directory that the target is defined in. Note: Running the node install on an example_project will install into the local source dir rather than in the typical .pants.d working directory. This task is intended to set up the environment for development purposes rather than to run tests or other isolated tasks. Example: ./pants node-install src/node/example_project:example_project This will produce a node_modules dir in `src/node/example_project/node_modules`
optionsDisplay meta-information about options. This "meta-information" includes what values options have, and what values they *used* to have before they were overridden by a higher-rank value (eg, a HARDCODED value overridden by a CONFIG value and then a cli FLAG value).
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. Specifically, generates two files: a build dictionary detailing all the directive that can appear in BUILD files, and a reference listing all available goals and options.
replRun a REPL.
repl-dirtyRun a REPL, skipping compilation.
resolveResolve external binary dependencies.
resourcesPrepare resources.
roots
runInvoke a binary.
run-dirtyInvoke a binary, skipping compilation.
serverRun the reporting server.
setup-pyGenerate setup.py-based Python projects.
setup-py2
sitegenGenerate the Pants static web site.
sortTopologically sort the targets.
target-types
targetsList available target types.
test
unpack-jarsUnpack artifacts specified by unpacked_jars() targets. Adds an entry to SourceRoot for the contents. :API: public
unpack-wheelsExtract native code from `NativePythonWheel` targets for use by downstream C/C++ sources.
validate

Option Reference

[ Expand All | Collapse All ]
Generated by publish_docs from dist/reference/pants_reference_body.html 2022-12-03T01:09:00.272438