Record noteworthy build items into extension metadata

[holly-cummins]

How do we know which extensions provide a dev service? At the moment, we don't, except by manual inspection. This PR automates the generation of metadata about noteworthy extension capabilities, that we might want to surface into aggregated lists or filters on http://extensions.quarkus.io and http://code.quarkus.io.

This metadata is needed to implement quarkusio/extensions#983. It could also potentially help with quarkusio/quarkusio.github.io#1869. At the moment we maintain the guide page listing extensions with dev services manually, but that page could have generated content injected into it, once we have the right metadata.

For now, I've focussed on dev services, but this capability could be useful for other extension abilities that we might want to surface.

Outstanding work

• Add tests and (probably) implementation for List<DevServicesResultBuildItem>
• Completely re-architect how we build extensions to avoid circular dependencies (uh oh)

Externals

A build item can be annotated with

@AddToMetadata("dev-service")

and that will be converted into the following line in quarkus-extension.yaml:

provides-dev-service=true 

(can change to more detailed values)

(I went with a 'provides' verb since feature and capabilties are already taken :) )

Under the hood

I've used the annotation processor to inspect the build item annotations and generate a noteworthy-build-items.list file if one is found.

The extension descriptor mojo then reads the file and generates the appropriate yaml.

Circular dependency woe

At the moment, this only generates the right information if it's not built on a clean machine. That's ... unfortunate.

The noteworthy-build-items.list file is generated in the deployment module, and the Quarkus-extension.yaml file which uses it is generated in the runtime module … which gets built first.

On some earlier iterations of this change, I thought everything was working, but it was actually only working because the runtime module was picking up dirty content from earlier deployment builds. Because phases are not interleaved in a multi-module project, mvn clean install on an extension gave me the expected result, but it's not actually representative of a build on a clean machine. For that, it needs to be mvn clean && mvn install, and with that command, the metadata is not generated. :(

For example, to try out the bad sequence,

cd /extensions/elasticsearch-rest-client-common
mvn -f deployment clean && mvn -f runtime clean install && grep provide runtime/target/classes/META-INF/quarkus-extension.yaml

A solution is needed, hence marking this as draft. I cannot see any mechanism to interleave phases in a multi-module project, which is what's needed here. The only way to do it seems to be multiple invocations (for example, mvn compile && mvn install), which is seriously non-ideal.

Next steps (once/if the circular problem is fixed)

I think this same mechanism could be useful for lifting the restriction that, in order to be visible to the tools, capabilities have to be registered in the pom.xml rather than returned as CapabilityBuildItems in an extension processor. Doing that would need a small amount of extra notation and a small externals change, so that a processor would return something like

@Name “something-something” CapabilityDevService

and the yaml entry would be something like

provides-capabilities=something-something

I will leave that as a follow-on.

Minor other changes

I noticed that


```



BUILD_STEPS_PATH = META_INF + "/quarkus-build-steps.list";

didn’t seem to be used anywhere. But then I found a loose string literal, so I’ve swapped the literal for the constant.

[quarkus-bot]

Status for workflow Quarkus Documentation CI

This is the status report for running Quarkus Documentation CI on commit 9d36be5.

Failing Jobs

⚠️ Artifacts of the workflow run were not available thus the report misses some details.

Status	Name	Step	Failures	Logs	Raw logs	Build scan
✖	Documentation Build	Build	⚠️ Check →	Logs	Raw logs	🚧

[aloubyansky]

I think this same mechanism could be useful for lifting the restriction that, in order to be visible to the tools, capabilities have to be registered in the pom.xml rather than returned as CapabilityBuildItems in an extension processor.

Just a note that following the review of build item and steps best practices, it's questionable that CapabilityBuildItem should exist. We may want to keep this restriction and expose the capability metadata to build steps in a different way.

[holly-cummins]

This has been open for a while and will, of course, need rework post-#42141. That's not going to be a nice merge. :)