dockerfile: expose TARGETSTAGE as builtin argument

[tonistiigi]

closes docker/buildx#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? 😅

[crazy-max]

I'm not sure if we should have default if target not set. I think best would be to leave it empty.

[tonistiigi]

Empty value could cause some breakage maybe. We do name stage default in the --call=targets output as well. Another option would be to use numbers as we still support them for access, but might be quite confusing.

[crazy-max]

We do name stage default in the --call=targets output as well.

Ah I forgot about this subrequest, so yeah default is good. I was just wondering if default could be used as TARGETSTAGE but that would not make sense.

[ByteNybbler]

I could see it going either way.

--call=targets annotates whatever the final build stage is with (default), regardless of whether the build stage's name is an empty string or not.

I think having TARGETSTAGE be default when the Dockerfile's targeted build stage doesn't have a name might help avoid some potentially surprising behaviors. For example, there could be a scenario where the value of TARGETSTAGE ends up getting used as a directory name.

On the other hand, a Dockerfile can have a build stage named default which isn't the final build stage, so applying a default value for TARGETSTAGE here might be surprising in its own way. But that sounds like a pretty unusual Dockerfile.

I think just going with default will be applicable to the vast majority of use cases.

[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.