I am trying to write a "rule" (I assume I am on the correct path) so learn about plugins with the ultimate aim of writing some nice versioning backend logic that brings in many different versioning strategies (semver, calver, gitcommish, conventional-commits-semver) To get there I want to build up a few practical examples: The first place I wanted to understand is how plugins works and specifically, want to just tag a docker image.

docker_image(
    name="docker_image",
    repository="my-image-name",
    image_tags=[the_version()],
    dependencies=[":the_python_pkg", ":docker_resources"],
)

where

the_version()

is coming from a rule generated in a plugin This is the "test plugin" i have written:

# pants-plugin/versioning/register.py
import os
from pants.engine.rules import collect_rules, rule

@rule
async def the_version() -> str:
    return os.popen('git --no-pager describe --always --dirty --broken').read()

def rules():
    return collect_rules()

However when

./pants package path/to:docker

is run I am expecting the docker_image tag to pickup the "string" from the

the_version()

however pant` does not register the rule as a symbol ? (maybe it's not a rule I need)

MappingError: Failed to parse ./services/my-image/BUILD:
Name 'the_version' is not defined.

If you expect to see more symbols activated in the below list, refer to <https://www.pantsbuild.org/v2.13/docs/enabling-backends> for all available backends to activate.

All registered symbols: ['_generator_sources_helper', 'archive', 'build_file_dir', 'docker_image', 'experimental_run_shell_command', 'experimental_shell_command', 'file', 'files', 'helm_artifact', 'helm_chart', 'helm_unittest_test', 'helm_unittest_tests', 'http_source', 'parametrize', 'pex_binaries', 'pex_binary', 'pipenv_requirements', 'poetry_requirements', 'python_artifact', 'python_distribution', 'python_requirement', 'python_requirements', 'python_source', 'python_sources', 'python_test', 'python_test_utils', 'python_tests', 'relocated_files', 'resource', 'resources', 'setup_py', 'shell_source', 'shell_sources', 'shunit2_test', 'shunit2_tests', 'target']

My goal for this first step is to get

pants

to "auto collect" the "GIT_COMMIT" version ref: https://www.pantsbuild.org/v2.11/docs/tagging-docker-images#using-env-vars-to-include-dynamic-data-in-tags and provide it as a variable or via a function (like I tried above). Such that

./pants package src/example:demo

Builds a docker image with

demo:$(git rev-parse HEAD)

So a fundamental fact of the Pants rule system is that it only exposes types and not functions. You can request an instance of the type an @rule returns but you cannot call any @rule by name (and you definitely can't call rules from BUILD files! its the other way around - rules can read data defined in BUILD files). This is pretty central to the pluggability of the system currently but it also makes things not straight forward to grok when you first encounter plugins and rules. Although Core Concepts https://www.pantsbuild.org/docs/plugins-overview#core-concepts does outline core concepts there is no real high level overview afaict that shows how you add new data to act on (https://www.pantsbuild.org/docs/target-api-concepts) and then read that data in a rule and plug that rule's results into an existing goal . There are more specific guides for more narrow tasks: https://www.pantsbuild.org/docs/common-plugin-tasks but yours is not directly covered by those.

I'll add, part of the rule engine is cacheability as well. As your rule stands, the inputs to the rule dont' change when

git

state changes, so the result might be cached when you change commits. You might try using the type defined here as an input to your rule.

Thanks Joshua. Is there any documentation on the state lifecycle (phase X before phase Y) ? So what I am thinking is (a few things). environment fields need to be read in 'at some point' and cached. where in the lifecycle does that occur - and are ENV vars "monitored" the same way Files are (which i observe from time to time)

The rule graph itself represents the "phases". All of your inputs will be computed (or cached) before your rule runs. And your inputs are your function's parameters (annotated)