dockerfile: expose TARGETSTAGE as builtin argument

[tonistiigi]

closes https://github.com/docker/buildx/issues/2646

Allows capturing what build stage is currently being built for patterns with better base stage reuse.

[thaJeztah]

This probably needs documentation changes to add this to the list of builtin args? 😅

[tonistiigi]

@ByteNybbler, any input on the comments above?

[ByteNybbler]

Yes, thank you so much for working on this! I'm very excited to have access to this feature!

[thaJeztah]

Would setting a value by default (if not set) make it harder to do constructs where the user wants to set a default value? echo ${TARGETSTAGE:-development} (or similar constructs)

[tonistiigi]

Would setting a value by default (if not set) make it harder to do constructs where the user wants to set a default value? echo ${TARGETSTAGE:-development} (or similar constructs)

Yeah, but if you look at the current TARGET* BUILD* default args then they are also always guaranteed to have a defined value. So I think it is more consistent this way, where it is always set by the builder and not left for the user to initialize in any case.

[ByteNybbler]

The only time TARGETSTAGE could ever use some possible default value (at least for how I'm imagining this will work) would be when the final build stage is unnamed in the Dockerfile. If the user wants to control the "default" value of TARGETSTAGE, they can do that by giving the final build stage an appropriate name in the Dockerfile, since the final build stage is what docker build targets by default when no --target option is provided. TARGETSTAGE should match the name of that target.

[tonistiigi]

Updated to read the default stage name from Dockerfile if not passed by the user.