Missing "advanced" topics on website

[Tatskaari]

We should probably document under advanced:

• Subrepos
• Plugins
• Entry points and named outputs
• Different dep types (exported, transitive, output_is_complete etc.)
• Magic build labels like link:, codegen:, and manual

[Tatskaari]

There's also #2629

[stale[bot]]

This issue has been automatically marked as stale because it has not had any recent activity in the past 90 days. It will be closed if no further activity occurs. If you require additional support, please reply to this message. Thank you for your contributions.

[matglas]

I can take a stab at whats still open. I looked and I think this is the status. Am I correct?

• Subrepos covered
• Plugins covered
• Entry points (what are these?) still open. Name outputs covered
• Different dep types still open
• Magic build labels still open

[Tatskaari]

Thanks! I can try and give a quick overview of these:

Entry points (what are these?)

These were introduced for SDKs like golang and Java where you want access to go and javac but these require access to other files relative to the binary being run e.g. the compiled Go sources under the go root, or the .jar files for the standard library. These use the same format as named outputs i.e. //third_party/go:toolchain|go, but you get the whole output of //third_party/go:toolchain in your temp dir, but when you reference them e.g. via $TOOLS or $SRCS, you only get the specific output i.e. TOOLS=plz-out/binary/third_party/go/toolchain/bin/go, rather than TOOLS=plz-out/binary/third_party/go/toolchain (if you had used the unannoted label).

Different dep types

We have a number of ways to depend on other targets:

• srcs - The "source" files you need to pass to the compiler (or whatever tool you're using). These can be referenced via the $SRCS in the build command, and can also be a dict in which case you get $SRCS as well as $SRCS_{name}.
• deps - Any other build time dependencies that have to be present in the build directory during execution of the build command.
• exported_deps - like deps, but other targets that depend on this target also get these dependencies. A filegroup with exported deps is much like an alias, for example, where depending on the filegroup is the same as depending on it's exported deps.
• data - Runtime dependencies of the target. These are made available to the test command via the $DATA environment variable much like $SRC are made available to the build command. This can also be a dict in the same way.
• tools - The tools used by the command. These are made available to the build command via the $TOOLS env variables. This can also be a dict in the same way as the $SRCS above. These are not cross compiled, during cross compilation, as they are run at build time. They will always be built for the host OS.
• test_tools - Similar to tools but made available to the test command.

Additionally, there are some flags to control how dependencies are hooked up:

• needs_transitive_deps - Tell Please that this target requires all the dependencies of it's dependencies.
• output_is_complete - Only relevant when needs_transitive_deps is set. Essentially a stopper for needs_transitive_deps, stopping Please from adding this targets dependencies for a target that needs transitive deps.
• requires/provides - this is already documented here: https://please.build/require_provide.html

Magic build labels still open

Might be worth digging through the code here but there are a few I'm aware of:

• manual: Target is no longer picked up by Please commands unless explicitly targeted. That is plz test and plz test //blah/... won't pick up //blah:target if //blah:target is marked as manual.
• codgen: marks the target as a code generation target. This works with the plz generate command and LinkGeneratedSources config option to add symlinks (or hardlinks if configured) back into the source tree for generated sources. This helps with IDE integration, where generated sources are expected to be checked in to VCSs.
• link: and hlink:: links the output of a target to the specified path. We use this to populate plz-out/go (have a look at go_repo and go_module etc.)

There are probably a couple more lost to time.

[matglas]

@Tatskaari thanks for all the details. I need to grok it a bit more for myself. But I'll start to see if there is something I can already take a stab at. And I'll go thru the code a bit to understand the usage.