Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

In Docs: clarify BUILD vs. BUILD.bazel #4517

Open
davidstanke opened this issue Jan 24, 2018 · 21 comments
Open

In Docs: clarify BUILD vs. BUILD.bazel #4517

davidstanke opened this issue Jan 24, 2018 · 21 comments
Labels
help wanted Someone outside the Bazel team could own this P3 We're not considering working on this, but happy to review a PR. (No assignee) team-Documentation Documentation improvements that cannot be directly linked to other team labels team-OSS Issues for the Bazel OSS team: installation, release processBazel packaging, website type: documentation (cleanup)

Comments

@davidstanke
Copy link
Contributor

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
Copy link
Contributor

ixdy commented Jan 24, 2018

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
Copy link
Contributor

ixdy commented Jan 24, 2018

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

@tualeron
Copy link
Contributor

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

yongtang added a commit to yongtang/tensorflow that referenced this issue May 24, 2018
Both `BUILD` and `BUILD.bazel` could be used as the bazel project file
and `BUILD.bazel` is preferred (see bazelbuild/bazel#4517 (comment))

This fix changes generated BUILD in third_party packages to `BUILD.bazel`.
This will help avoid conflict with `BUILD` or `build` file/directory names
in third party packages.

For example, while working on 19461 I noticed that apache thrift package
consists of a `build` directory and that causes issues in case-insensitive
systems like macOS. This PR should help avoid such conflict issues.

Signed-off-by: Yong Tang <yong.tang.github@outlook.com>
@mhsmith
Copy link

mhsmith commented 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
Copy link
Contributor

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

@jin jin added untriaged team-Bazel General Bazel product/strategy issues labels Oct 28, 2018
@katre
Copy link
Member

katre commented 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
Copy link
Contributor

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
Copy link
Contributor

pauldraper commented Nov 1, 2018

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
Copy link
Member

ittaiz commented Nov 1, 2018 via email

@laurentlb
Copy link
Contributor

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

realityforge added a commit to react4j/react4j-todomvc that referenced this issue Apr 4, 2019
@dslomov dslomov added the team-OSS Issues for the Bazel OSS team: installation, release processBazel packaging, website label Jul 23, 2019
@dslomov dslomov removed the team-Bazel General Bazel product/strategy issues label Jul 23, 2019
@philwo philwo added P2 We'll consider working on this in future. (Assignee optional) and removed untriaged labels Jul 29, 2019
gibfahn added a commit to gibfahn/bazel-glossary that referenced this issue Jan 9, 2020
I believe this is the current recommended default.

Refs: bazelbuild/bazel#4517
gibfahn added a commit to gibfahn/bazel-glossary that referenced this issue Jan 9, 2020
I believe this is the current recommended default.

Refs: bazelbuild/bazel#4517
@ittaiz
Copy link
Member

ittaiz commented Jan 24, 2020 via email

@kylecordes
Copy link

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
Copy link
Contributor

I'm happy to review PRs for this.

@ittaiz
Copy link
Member

ittaiz commented Jan 27, 2020

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

qtprojectorg pushed a commit to qtqa/gerrit that referenced this issue Feb 2, 2020
Bazel supports both BUILD and BUILD.bazel files and in this issue: [1]
there is a discussion to prefer BUILD.bazel over BUILD naming
convention. Detect BUILD.bazel files as Python code in addition to
BUILD files.

[1] bazelbuild/bazel#4517

Change-Id: Iabc719b914fcd08ef6e73c314f09f924540c3794
@meisterT meisterT added the help wanted Someone outside the Bazel team could own this label May 15, 2020
@philwo philwo added P3 We're not considering working on this, but happy to review a PR. (No assignee) and removed P2 We'll consider working on this in future. (Assignee optional) labels Dec 8, 2020
@softprops
Copy link

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.

hostilefork added a commit to hostilefork/bazel-playground that referenced this issue Apr 8, 2021
Best practices currently suggest calling the files BUILD.bazel and not
simply BUILD.

This is more explicit and creates less contention in projects that
have `build/` directories (which is quite common).  On case-insensitive
filesystems this can be particularly problematic.

Auto-generating tools (such as "Gazelle") are making files called
BUILD.bazel as well, so this is suggested for consistency in all non
legacy projects.

If both BUILD and BUILD.bazel files are present, the BUILD.bazel will
be preferred...further cementing its status as "canon".

bazelbuild/rules_go#866
bazelbuild/bazel#4517
jlisee added a commit to jlisee/Packages that referenced this issue Jun 4, 2021
Highlight files named `BUILD` as if they were Python.  These files will almost
universally contain code written in starlark which is a subset of Python.

While some build systems, like Bazel, are trying to recommend using a suffix
bazelbuild/bazel#4517 like `BUILD.bazel`, consensus is not universal and there
is a large body of code as well as other build systems like Pants which also
default to the extensionless `BUILD` name.

This fix will provide proper syntax highlighting with the `bat` tool.
lngart pushed a commit to lngart/GitSubSep that referenced this issue Oct 5, 2021
Both `BUILD` and `BUILD.bazel` could be used as the bazel project file
and `BUILD.bazel` is preferred (see bazelbuild/bazel#4517 (comment))

This fix changes generated BUILD in third_party packages to `BUILD.bazel`.
This will help avoid conflict with `BUILD` or `build` file/directory names
in third party packages.

For example, while working on 19461 I noticed that apache thrift package
consists of a `build` directory and that causes issues in case-insensitive
systems like macOS. This PR should help avoid such conflict issues.

Signed-off-by: Yong Tang <yong.tang.github@outlook.com>
@ShreeM01 ShreeM01 added the team-Documentation Documentation improvements that cannot be directly linked to other team labels label Dec 5, 2022
GleasonK added a commit to openxla/stablehlo that referenced this issue Jan 30, 2023
Plenty of related issues across GH projects - Bazel supports build files
named either `BUILD` or `BUILD.bazel`. In
bazelbuild/bazel#4517 the community recommends
the more explicit `BUILD.bazel` naming. This will also help us
disambiguate bazel and blaze build file scripts when necessary.
GleasonK added a commit to GleasonK/stablehlo that referenced this issue Feb 10, 2023
Plenty of related issues across GH projects - Bazel supports build files
named either `BUILD` or `BUILD.bazel`. In
bazelbuild/bazel#4517 the community recommends
the more explicit `BUILD.bazel` naming. This will also help us
disambiguate bazel and blaze build file scripts when necessary.
atondwal pushed a commit to atondwal/stablehlo that referenced this issue Mar 3, 2023
Plenty of related issues across GH projects - Bazel supports build files
named either `BUILD` or `BUILD.bazel`. In
bazelbuild/bazel#4517 the community recommends
the more explicit `BUILD.bazel` naming. This will also help us
disambiguate bazel and blaze build file scripts when necessary.
saraadams added a commit to EngFlow/bazel that referenced this issue Apr 28, 2023
The documentation currently refers to `BUILD` files with only
a small side note that the may be called `BUILD.bazel`, namely
where packages are defined.
Instead, add a more prominent note to the page explaining `BUILD`
files and clarify there that both namings are valid, that
`BUILD.bazel` takes precendence, and that the documentation
will talk just about `BUILD` files for simplicity's sake.
Additionally, link to that page from the package definition section.

Progress on bazelbuild#4517
copybara-service bot pushed a commit that referenced this issue May 4, 2023
The documentation currently refers to `BUILD` files with only a small side note that the may be called `BUILD.bazel`, namely where packages are defined.
Instead, add a more prominent note to the page explaining `BUILD` files and clarify there that both namings are valid, that `BUILD.bazel` takes precendence, and that the documentation will talk just about `BUILD` files for simplicity's sake. Additionally, link to that page from the package definition section.

Progress on #4517

Closes #18251.

PiperOrigin-RevId: 529378158
Change-Id: If74903e0a9ffd4410a9c65c1fc9f3e5959fe83a7
@saraadams
Copy link
Contributor

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

fweikert pushed a commit to fweikert/bazel that referenced this issue May 25, 2023
The documentation currently refers to `BUILD` files with only a small side note that the may be called `BUILD.bazel`, namely where packages are defined.
Instead, add a more prominent note to the page explaining `BUILD` files and clarify there that both namings are valid, that `BUILD.bazel` takes precendence, and that the documentation will talk just about `BUILD` files for simplicity's sake. Additionally, link to that page from the package definition section.

Progress on bazelbuild#4517

Closes bazelbuild#18251.

PiperOrigin-RevId: 529378158
Change-Id: If74903e0a9ffd4410a9c65c1fc9f3e5959fe83a7
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted Someone outside the Bazel team could own this P3 We're not considering working on this, but happy to review a PR. (No assignee) team-Documentation Documentation improvements that cannot be directly linked to other team labels team-OSS Issues for the Bazel OSS team: installation, release processBazel packaging, website type: documentation (cleanup)
Projects
None yet
Development

No branches or pull requests