In Docs: clarify BUILD vs. BUILD.bazel

[davidstanke]

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?

[ixdy]

before commenting on that issue, I also confirmed that bazel seems to prefer BUILD.bazel; if you have a BUILD.bazel file and a BUILD file, it'll ignore the latter.

[ixdy]

for cross-reference, the original BUILD.bazel discussion was in #552.

[tualeron]

This will be a massive search-and-replace effort on both docs.bazel.build and GitHub. Prioritizing low unless someone objects.

[mhsmith]

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]

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]

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]

BUILD.bazel is more explicit. If you have a BUILD.bazel file 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]

This will be a massive search-and-replace effort on both docs.bazel.build and GitHub.

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]

BTW, intellij bazel plugin still creates BUILD files and doesn't even allow customizing the default option: bazelbuild/intellij#368

…

On Thu, Nov 1, 2018 at 7:52 PM Paul Draper ***@***.***> wrote: This will be a massive search-and-replace effort on both docs.bazel.build and GitHub. At the very least, documentation can include @katre <https://github.com/katre> and @laurentlb <https://github.com/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. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#4517 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABUIF3qnKWppOMWNsUTlXR7c64Xrgkd7ks5uqzTCgaJpZM4Rro-Y> .

[laurentlb]

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

[kylecordes]

Particularly when adding Bazel to existing projects, the BUILD.bazel name is often necessary to avoid conflicts with existing things named build - as others said, especially on case insensitive file systems. As more existing projects out there make the move, more people will encounter this friction.

[laurentlb]

I'm happy to review PRs for this.

[ittaiz]

@laurentlb a PR for docs?
What do you think about being able to turn off support for BUILD?

[softprops]

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.

[saraadams]

#18251 is now live and improves the documentation on BUILD file names.