Skip to main content
Version: 2.17.x

adhoc_tool

Execute any runnable target for its side effects.

Example BUILD file:

adhoc_tool(
    runnable=":python_source",
    args=[""],
    execution_dependencies=[":scripts"],
    output_directories=["results/"],
    output_files=["logs/my-script.log"],
)

shell_sources(name="scripts")

Backend: pants.backend.experimental.adhoc

tags​

field.type_hint
required

Arbitrary strings to describe a target.

For example, you may tag some test targets with 'integration_test' so that you could run scie-pants-linux-x86_64 --tag='integration_test' test :: to only run on targets with that tag.

description​

field.type_hint
required

A human-readable description of the target.

Use scie-pants-linux-x86_64 list --documented :: to see all targets with descriptions.

runnable​

field.type_hint
required

Address to a target that can be invoked by the run goal (and does not set run_in_sandbox_behavior=NOT_SUPPORTED). This will be executed along with any arguments specified by args, in a sandbox with that target's transitive dependencies, along with the transitive dependencies specified by execution_dependencies.

args​

field.type_hint
default: ()

Extra arguments to pass into the runnable field.

execution_dependencies​

field.type_hint
required

The execution dependencies for this command.

Dependencies specified here are those required to make the command complete successfully (e.g. file inputs, packages compiled from other targets, etc), but NOT required to make the outputs of the command useful. Dependencies that are required to use the outputs produced by this command should be specified using the output_dependencies field.

If this field is specified, dependencies from output_dependencies will not be added to the execution sandbox.

See also output_dependencies and runnable_dependencies.

output_dependencies​

field.type_hint
required

Any dependencies that need to be present (as transitive dependencies) whenever the outputs of this target are consumed (including as dependencies).

See also execution_dependencies and runnable_dependencies.

runnable_dependencies​

field.type_hint
required

The runnable dependencies for this command.

Dependencies specified here are those required to exist on the PATH to make the command complete successfully (interpreters specified in a #! command, etc). Note that these dependencies will be made available on the PATH with the name of the target.

See also output_dependencies and execution_dependencies.

log_output​

field.type_hint
default: False

Set to true if you want the output logged to the console.

output_files​

field.type_hint
default: ()

Specify the output files to capture, relative to the value of workdir.

For directories, use output_directories. At least one of output_files andoutput_directories must be specified.

Relative paths (including ..) may be used, as long as the path does not ascend further than the build root.

output_directories​

field.type_hint
default: ()

Specify full directories (including recursive descendants) of output to capture, relative to the value of workdir.

For individual files, use output_files. At least one of output_files andoutput_directories must be specified.

Relative paths (including ..) may be used, as long as the path does not ascend further than the build root.

timeout​

field.type_hint
default: 30

Command execution timeout (in seconds).

extra_env_vars​

field.type_hint
required

Additional environment variables to provide to the process.

Entries are strings in the form ENV_VAR=value to use explicitly; or just ENV_VAR to copy the value of a variable in Pants's own environment.

workdir​

field.type_hint
default: '.'

Sets the working directory for the process.

Values are relative to the build root, except in the following cases:

  • . specifies the location of the BUILD file.
  • Values beginning with ./ are relative to the location of the BUILD file.
  • / or the empty string specifies the build root.
  • Values beginning with / are also relative to the build root.

root_output_directory​

field.type_hint
default: '/'

Adjusts the location of files output by this target, when consumed as a dependency.

Values are relative to the build root, except in the following cases:

  • . specifies the location of the BUILD file.
  • Values beginning with ./ are relative to the location of the BUILD file.
  • / or the empty string specifies the build root.
  • Values beginning with / are also relative to the build root.

stdout​

field.type_hint
required

A filename to capture the contents of stdout to. Relative paths are relative to the value of workdir, absolute paths start at the build root.

stderr​

field.type_hint
required

A filename to capture the contents of stderr to. Relative paths are relative to the value of workdir, absolute paths start at the build root.

environment​

field.type_hint
default: '__local__'

Specify which environment target to consume environment-sensitive options from.

Once environments are defined in [environments-preview].names, you can specify the environment for this target by its name. Any fields that are defined in that environment will override the values from options set by pants.toml, command line values, or environment variables.

You can specify multiple valid environments by using parametrize. If __local__ is specified, Pants will fall back to the local_environment defined for the current platform, or no environment if no such environment exists.