From 72ca557cc47f112fde76722764b69e8815ec076e Mon Sep 17 00:00:00 2001 From: Sara Adams Date: Thu, 4 May 2023 05:11:50 -0700 Subject: [PATCH] [Documentation] Clarify `BUILD` file names 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 https://github.com/bazelbuild/bazel/issues/4517 Closes #18251. PiperOrigin-RevId: 529378158 Change-Id: If74903e0a9ffd4410a9c65c1fc9f3e5959fe83a7 --- site/en/concepts/build-files.md | 9 ++++++++- site/en/concepts/build-ref.md | 10 +++++----- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/site/en/concepts/build-files.md b/site/en/concepts/build-files.md index 9bcc8d29d9af16..77d88c741e10f2 100644 --- a/site/en/concepts/build-files.md +++ b/site/en/concepts/build-files.md @@ -10,7 +10,14 @@ build dependency graph abstractly. This section describes the concrete syntax used to define a package. By definition, every package contains a `BUILD` file, which is a short -program. `BUILD` files are evaluated using an imperative language, +program. + +Note: The `BUILD` file can be named either `BUILD` or `BUILD.bazel`. If both +files exist, `BUILD.bazel` takes precedence over `BUILD`. +For simplicity's sake, the documentation refers to these files simply as `BUILD` +files. + +`BUILD` files are evaluated using an imperative language, [Starlark](https://github.com/bazelbuild/starlark/){: .external}. They are interpreted as a sequential list of statements. diff --git a/site/en/concepts/build-ref.md b/site/en/concepts/build-ref.md index 0849177ec9916a..c9b87b38112116 100644 --- a/site/en/concepts/build-ref.md +++ b/site/en/concepts/build-ref.md @@ -49,11 +49,11 @@ The primary unit of code organization in a repository is the _package_. A package is a collection of related files and a specification of how they can be used to produce output artifacts. -A package is defined as a directory containing a file named `BUILD` (or -`BUILD.bazel`). A package includes all files in its directory, plus all -subdirectories beneath it, except those which themselves contain a `BUILD` file. -From this definition, no file or directory may be a part of two different -packages. +A package is defined as a directory containing a +[`BUILD` file](/concepts/build-files) named either `BUILD` or `BUILD.bazel`. A +package includes all files in its directory, plus all subdirectories beneath it, +except those which themselves contain a `BUILD` file. From this definition, no +file or directory may be a part of two different packages. For example, in the following directory tree there are two packages, `my/app`, and the subpackage `my/app/tests`. Note that `my/app/data` is not a package, but