Bazel: 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 https://github.com/bazelbuild/bazel/issues/552.

[sergetron]

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:
https://github.com/bazelbuild/intellij/issues/368

On Thu, Nov 1, 2018 at 7:52 PM Paul Draper [e-mail] 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
https://github.com/bazelbuild/bazel/issues/4517#issuecomment-435123499,
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).

[jin]

A year on, do we have consensus on this? Are we officially recommending projects to use BUILD.bazel over BUILD?

[andyscott]

Seconded. Consensus would be great on this issue, as we're in the process of Bazelifying a lot more of Stripe's codebase and it's not clear which file name is most idiomatic.

Additionally, it would be great if Bazel's own codebase embraced the recommended naming convention.

[pauldraper]

As for Jan 20, 2020, the BUILD alliance is delivering an overwhelming victory against the BUILD.bazel coalition.

Much to the disappointment of the Bazel documentation writers, resistance is limited to a mere handful of web and Go projects.

This decisive outcome once again proves the eternal truth:

Convenience is King

BUILD (42)

• apple_support
• bazel-blog
• bazel-buildfarm
• bazel-cc
• bazel-gazelle
• bazel-integration-testing
• bazel-skylib
• bazel-toolchains
• bazel-watcher
• bazel-website
• bazel
• bazelisk
• codelabs
• intellij
• java_tools
• platforms
• rules_android
• rules_appengine
• rules_apple
• rules_closure
• rules_d
• rules_docker
• rules_dotnet
• rules_foreign_cc
• rules_groovy
• rules_gwt
• rules_java
• rules_jsonnet
• rules_jvm_external
• rules_k8s
• rules_kotlin
• rules_perl
• rules_pkg
• rules_postcss
• rules_proto
• rules_python
• rules_scala
• rules_swift
• skydoc
• stardoc
• tools_android
• tools_remote

BUILD.bazel (7)

• buildtools
• remote-apis-sdks
• rules_go
• rules_nodejs
• rules_sass
• rules_typescript
• rules_webtesting

[ittaiz]

Internally We (Wix) use only BUILD.bazel because of conflicts we had with
BUILD files and directories.

IMHO the stats below aren’t the real story because rulesets usually live in
a clean bazel only world where you won’t have interferences with other
stacks.

In real life and large codebase this interference is annoying. I’d actually
like to be able to turn off support for BUILD file via flag (probably need
a warn flag also so that I can go ask my rule sets to make these changes as
well).

On Tue, 21 Jan 2020 at 0:19 Paul Draper [e-mail] wrote:

As for Jan 20, 2020, the BUILD alliance is delivering an overwhelming
victory against the BUILD.bazel coalition.

Much to the disappointment of the Bazel documentation writers, resistance
is limited to a mere handful of web and Go projects. (Though it would seem
not even Bazel documentation
https://github.com/bazelbuild/bazel/tree/master/site itself can resist
the power of the great BUILD.)

This decisive outcome once again proves the maxim:
Convenience is King BUILD (42)

• apple_support https://github.com/bazelbuild/apple_support
• bazel-blog https://github.com/bazelbuild/bazel-blog
• bazel-buildfarm https://github.com/bazelbuild/bazel-buildfarm
• bazel-cc https://github.com/bazelbuild/rules_cc
• bazel-gazelle https://github.com/bazelbuild/bazel-gazelle
• bazel-integration-testing
  https://github.com/bazelbuild/bazel-integration-testing
• bazel-skylib https://github.com/bazelbuild/bazel-skylib
• bazel-toolchains https://github.com/bazelbuild/bazel-toolchains
• bazel-watcher https://github.com/bazelbuild/bazel-watcher
• bazel-website https://github.com/bazelbuild/bazel-website
• bazel https://github.com/bazelbuild/bazel
• bazelisk https://github.com/bazelbuild/bazelisk
• codelabs https://github.com/bazelbuild/java_tools
• intellij https://github.com/bazelbuild/intellij
• java_tools https://github.com/bazelbuild/java_tools
• platforms https://github.com/bazelbuild/platforms
• rules_android https://github.com/bazelbuild/rules_android
• rules_appengine https://github.com/bazelbuild/rules_appengine
• rules_apple
  https://github.com/bazelbuild/rules_apple/tree/master/apple
• rules_closure https://github.com/bazelbuild/rules_closure
• rules_d https://github.com/bazelbuild/rules_d
• rules_docker https://github.com/bazelbuild/rules_docker
• rules_dotnet https://github.com/bazelbuild/rules_dotnet
• rules_foreign_css https://github.com/bazelbuild/rules_foreign_cc
• rules_groovy https://github.com/bazelbuild/rules_groovy
• rules_gwt https://github.com/bazelbuild/rules_gwt
• rules_java https://github.com/bazelbuild/rules_java
• rules_jsonnet https://github.com/bazelbuild/rules_jsonnet
• rules_jvm_external https://github.com/bazelbuild/rules_jvm_external
• rules_k8s https://github.com/bazelbuild/rules_k8s
• rules_kotlin https://github.com/bazelbuild/rules_kotlin
• rules_perl https://github.com/bazelbuild/rules_perl
• rules_pkg https://github.com/bazelbuild/rules_pkg
• rules_postcss https://github.com/bazelbuild/rules_postcss
• rules_proto https://github.com/bazelbuild/rules_proto
• rules_python https://github.com/bazelbuild/rules_python
• rules_scala https://github.com/bazelbuild/rules_scala
• rules_swift https://github.com/bazelbuild/rules_swift
• skydoc https://github.com/bazelbuild/skydoc
• stardoc https://github.com/bazelbuild/stardoc
• tools_android https://github.com/bazelbuild/tools_android
• tools_remote https://github.com/bazelbuild/tools_remote

BUILD.bazel (7)

• buildtools https://github.com/bazelbuild/buildtools
• remote-apis-sdks https://github.com/bazelbuild/remote-apis-sdks
• rules_go https://github.com/bazelbuild/rules_go
• rules_nodejs https://github.com/bazelbuild/rules_nodejs
• rules_sass https://github.com/bazelbuild/rules_sass
• rules_typescript https://github.com/bazelbuild/rules_typescript
• rules_webtesting https://github.com/bazelbuild/rules_webtesting

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/bazelbuild/bazel/issues/4517?email_source=notifications&email_token=AAKQQF4FMOE6TWQHPZYF67TQ6YPN5A5CNFSM4ENOR6MKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEJN6DGI#issuecomment-576446873,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AAKQQF2NIDWHESPUEU35UYDQ6YPN5ANCNFSM4ENOR6MA
.

[pauldraper]

FWIW, I agree BUILD.bazel is objectively better:

1. Better file-type detection for IDEs
2. Doesn't conflict with Buck and Pants which also use BUILD
3. Lower chance of conflict generally, especially on case insensitive file systems

(I also predict BUILD will always be more popular, though I'd like to be wrong.)

[ittaiz]

Deprecate BUILD for bazel (obviously for blaze it’s not an option) and see
how it’s solved :)

On Fri, 24 Jan 2020 at 21:59 Paul Draper [e-mail] wrote:

I agree BUILD.bazel is better:

1. Better file-type detection for IDEs
2. Lower chance of conflict, especially on case insensitive file
   systems

(My prediction is that BUILD will also be most popular, but I'd like to be
proven wrong.)

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/bazelbuild/bazel/issues/4517?email_source=notifications&email_token=AAKQQF5EXM27J2FZDCEUYBDQ7NCAXA5CNFSM4ENOR6MKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEJ35LCY#issuecomment-578278795,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AAKQQFY2LOH46PHLVPHS5RTQ7NCAXANCNFSM4ENOR6MA
.

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