moby
Mention of build args for Dockerfile frontend
This is already documented at the bottom of the page.
BUILDKIT_SYNTAX is only for testing/dev purposes. Regular users should always use #syntax. A Dockerfile author defines what frontend version the file they have written is based on. The caller is not supposed to know it and if they use the wrong version they could get unexpected results.
@tonistiigi
Documenting #syntax in the second section and BUILDKIT_SYNTAX on the second last line is confusing, and it is useful to have a reference from one to the other. Do you disagree? It seems that you are trying to block PRs for the sake of it.
Why are builtin args for testing/dev purposes? Maybe you should expand on this PR by documenting that, I couldn't see it in the docs either. This proposed change does not indicate the "purpose" of the features, it just invites the user to read more about an overlapping feature and expands on the (previously undocumented) precedence.
BUILDKIT_SYNTAX is more flexible than #syntax, so regardless of how you would prefer it to be used, the system invites users to use it in a particular way. This is a problem with directives. If you want directives to be used instead of builtin args, it needs to be a) documented b) equally or more usable than alternatives. This is not a valid argument against improving documentation. Unless this PR introduces confusion or removes some information, it should be merged.
Maybe you should expand on this PR by documenting that
Yes, you can update the current BUILDX_SYNTAX var documentation with the note that this arg should only be used for dev/test purposes and recommended way is to declare the version the specific Dockerfile expects by using #syntax as explained in the usage section.
should only be used for dev/test purposes
Is there a reference for this? You are the only person I have heard recommend this.
@CreativeCactus https://github.com/moby/moby/pull/41331#issuecomment-671254912
@tonistiigi That's a question. The subsequent posts don't seem very committed to the purpose you are proposing now. Given recent discussions about the usability and maintainability of directives, I think more consideration is required than a few comments from 2 years ago.
Two maintainers that let this feature in did it on a condition that it will not change anything about the recommendation for users to only use #syntax (initially it was even an undocumented override). I'm not sure what higher authority than that do you expect?
"Using external Dockerfile frontend" section has been moved to https://docs.docker.com/build/buildkit/dockerfile-frontend/
