Repository navigation
In Docs: clarify BUILD vs. BUILD.bazel #4517
Description
One can use either BUILD or BUILD.bazel as the filename for config files. AIUI, the preferred name is BUILD.bazel (because why? because this?) but the docs mostly reference BUILD. Can we update the docs to use the preferred version, as well as adding information about which one is preferred, and why?
Activity
ixdy commentedon Jan 24, 2018
before commenting on that issue, I also confirmed that bazel seems to prefer
BUILD.bazel; if you have aBUILD.bazelfile and aBUILDfile, it'll ignore the latter.ixdy commentedon Jan 24, 2018
for cross-reference, the original
BUILD.bazeldiscussion was in #552.sergetron commentedon Mar 29, 2018
This will be a massive search-and-replace effort on both docs.bazel.build and GitHub. Prioritizing low unless someone objects.
Use BUILD.bazel for third_party packages
mhsmith commentedon Sep 10, 2018
It doesn't need to be searched-and-replaced, but it does need to be mentioned as an alternative in case an existing project has a name conflict. Right now the BUILD.bazel name doesn't seem to be mentioned on docs.bazel.build at all, except on the Android NDK page, where it's used without explanation.
pauldraper commentedon Oct 27, 2018
I too am confused about which is conventional, or the pros/cons.
What will be least confusing to contributors to my OSS project?
(And for that matter, why does Bazel need both?)
katre commentedon Oct 29, 2018
General advice, I think, should be to always use BUILD.bazel, unless you have an existing codebase that doesn't.
Bazel has both for this reason: we have a very large codebase that uses only "BUILD" files, but there are many legitimate cases where users cannot name files "BUILD", and so they need an alternative.
laurentlb commentedon Oct 31, 2018
BUILD.bazelis more explicit. If you have aBUILD.bazelfile on your GitHub repository, users can understand what it is more easily (or they can find out easily). It also has less risk of collision.Downside: it's more characters to type.
pauldraper commentedon Nov 1, 2018
At the very least, documentation can include @katre and @laurentlb's prescription (unless it is not true).
Pre-1.0 would be a great time to document something as simple as a preferred/recommend file extension.
ittaiz commentedon Nov 1, 2018
laurentlb commentedon Nov 1, 2018
I'll be happy to review a pull request for the documentation (most of the doc is in https://github.com/bazelbuild/bazel/tree/master/site).
19 remaining items
softprops commentedon Mar 7, 2021
To echo previous comments I ran into an issue with a mixed grade build on OS X. Gradle uses a build directory. A BUILD file and build directory cannot coexist in a case insensitive file system
+1 for .bazel. It makes it clear for the uninitiated to draw a line between the existence of a file and what it's used for based on its file extension much like any other file name.
Rename BUILD to BUILD.bazel
Add BUILD extension for bazel/python support
Rename BUILD -> BUILD.bazel (#1023)
Rename BUILD -> BUILD.bazel (openxla#1023)
Rename BUILD -> BUILD.bazel (openxla#1023)
[Documentation] Clarify `BUILD` file names
[Documentation] Clarify `BUILD` file names
saraadams commentedon May 4, 2023
#18251 is now live and improves the documentation on
BUILDfile names.[Documentation] Clarify `BUILD` file names
six8 commentedon Feb 12, 2025
The docs now clarify the technical precedence if both
BUILDandBUILD.bazelexist, but does not clarify what the preferred usage is.I prefer the explicitness of
BUILD.bazelfor all the reasons already mentioned.Without an official recommendation, this is left to "whatever the team prefers". Which has its pros and cons.
We now have a repo of mixed
BUILDandBUILD.bazelbecause even if the team prefersBUILD, some modules have to useBUILD.bazelbecause they have existingbuildfiles or directories. So, on large or legacy projects, "always useBUILD" isn't viable. But "always useBUILD.bazelis".