Concepts
The core concepts of Targets and Fields.
The Target API defines how you interact with targets in your plugin. For example, you would use the Target API to read the source
/ sources
field of a target to know which files to run on.
The Target API can also be used to add new target types—such as adding support for a new language. Additionally, the Target API can be used to extend existing target types.
Targets and Fields - the core building blocks
Definition of target
As described in Targets and BUILD files, a target is an addressable set of metadata describing some of your code.
For example, this BUILD file defines a PythonTestTarget
target with Address("project", target_name="app_test")
.
python_test(
name="app_test",
source="app_test.py",
timeout=120,
)
Definition of field
A field is a single value of metadata belonging to a target, such as source
and timeout
above. (name
is a special thing used to create the Address
.)
Each field has a Python class that defines its BUILD file alias, data type, and optional settings like default values. For example:
from pants.engine.target import IntField
class PythonTestTimeoutField(IntField):
alias = "timeout"
default = 60
Target == alias + combination of fields
Alternatively, you can think of a target as simply an alias and a combination of fields:
from pants.engine.target import Dependencies, SingleSourceField, Target, Tags
class CustomTarget(Target):
alias = "custom_target"
core_fields = (SingleSourceField, Dependencies, Tags)
A target's fields should make sense together. For example, it does not make sense for a python_source
target to have a haskell_version
field.
Any unrecognized fields will cause an exception when used in a BUILD file.