Are there any resources to help with understanding 'secondary variants'? There's no official docs on them, and I've previously found them very difficult to use (they cause CC bugs, and there's lots of undocumented behaviour). Is using a secondary variant to share files significantly different from just making multiple 'top-level' configurations? Are secondary variants just for show, but functionally they work the same? Why would you use a secondary variant over a top level variant?

Let me quote the docs:

It also shows secondary variants, which are exclusive to Gradle projects and not published. For example, the secondary variant classes from apiElements is what allows Gradle to skip the JAR creation when compiling against a java-library project.

:-)