pants: Add st2_shell_sources_and_resources() macro to pants-plugins/macros.py

[cognifloyd]

Background

This is another part of introducing pants, as discussed in various TSC meetings.

Related PRs can be found in:

• pantsbuild milestone (which includes PRs since Initialize pantsbuild #5713)
• pantsbuild label (which also includes preparatory PRs that came before adding pantsbuild)

Overview of this PR

This PR adds our first pants macro: st2_shell_sources_and_resources()

I'm planning to add 3 more macros to help with building our python_distribution targets (for buildling wheels) in future PRs. This just introduces the concept of macros.

Macros

Macros are useful to reduce boilerplate in BUILD files.
...
Macros are defined in Python files that act like a normal BUILD file. They have access to all the symbols you normally have registered in a BUILD file, such as all of your target types.

Macros cannot import other modules, just like BUILD files cannot have import statements.

https://www.pantsbuild.org/docs/macros

Our macro file is pants-plugins/macros.py, and we tell pants about it with [GLOBAL].build_file_prelude_globs in pants.toml:

st2/pants.toml

Line 11 in eb6902f

build_file_prelude_globs = ["pants-plugins/macros.py"]

This PR only introduces one macro. The key parts of this macro function are shell_sources(...) and resources(...) - ie, that's where our macro adds the normal pants targets using the kwargs passed to it.

st2/pants-plugins/macros.py

Lines 16 to 28 in eb6902f

	def st2_shell_sources_and_resources(**kwargs):
	"""This creates a shell_sources and a resources target.
	This is needed because python_sources dependencies on shell_sources
	are silently ignored. So, we also need the resources target
	to allow depending on them.
	"""
	shell_sources(**kwargs) # noqa: F821
	kwargs.pop("skip_shellcheck", None)
	kwargs["name"] += "_resources"
	resources(**kwargs) # noqa: F821

And then we use the macro just like a regular target in a BUILD file:

st2/st2actions/bin/BUILD

Lines 8 to 12 in eb6902f

	st2_shell_sources_and_resources(
	name="shell",
	sources=["*.sh"],
	skip_shellcheck=True,
	)

[cognifloyd]

Rebased and added pants-plugins/README.md entry.