Document materialization of artifacts referenced by string parameter …

[cbarrete]

…macros

Closes #1166.

[meta-codesync]

@facebook-github-bot has imported this pull request. If you are a Meta employee, you can view this in D88573758. (Because this pull request was imported automatically, there will not be any future comments.)

[cormacrelf]

I don't really see how this is specific to string parameter macros. I practically never use string parameter macros and I still need to know this. It's perhaps better placed on RunInfo because being a runtime dependency is the main reason you need something materialized, or in the docs on materialization generally.

For RunInfo, you also have the ability to put hidden artifacts in RunInfo's cmd_args. I am not sure whether we materialize DefaultInfo (and other_outputs) when you run an associated RunInfo, but you could check and document what we do.

[cbarrete]

I don't really see how this is specific to string parameter macros. I practically never use string parameter macros and I still need to know this. It's perhaps better placed on RunInfo because being a runtime dependency is the main reason you need something materialized, or in the docs on materialization generally.

I guess this really depends on use cases. For example, the most common use case in my org is to actually expose shared libraries, not binaries, so DefaultInfo is relevant, not RunInfo. But more importantly, end users barely know/care about providers, they care about what they actually use, which is SPM. They will not even think of checking out the docs for providers, because it is not the level of abstraction that they operate at.

So while I don't mind also adding a page on materialization (there doesn't seem to be one yet, only https://buck2.build/docs/users/advanced/deferred_materialization/), I think that it is important to have this here as well.

For RunInfo, you also have the ability to put hidden artifacts in RunInfo's cmd_args. I am not sure whether we materialize DefaultInfo (and other_outputs) when you run an associated RunInfo, but you could check and document what we do.

DefaultInfo does not get built, much less materialized, when calling buck2 run.