I'm starting to familiarize myself with Bazel. But even at the beginning of the Getting Started page I am running into a conceptual difficulty.
On the first Getting Started page a Workspace
is defined as a directory tree with a WORKSPACE
or WORKSPACE.bazel
file in the top-level directory. When defining Repository
, this same directory is called the root
of the repository. To me, this sounds like two names for the same thing. Is there a difference between these terms that just isn't being made clear on this page?
You always have exactly one workspace in use. It's the first folder containing a WORKSPACE
or WORKSPACE.bazel
file found by traversing the (recursive) parents of the directory where you run the bazel
command. It includes all of the files in that folder (recursively), except in folders containing their own WORKSPACE
or WORKSPACE.bazel
, or a few other exceptions.
A repository is any folder containing a WORKSPACE
or WORKSPACE.bazel
file. The workspace is the "main repository", the rest are "external repositories". The WORKSPACE
files for external repositories are only checked for their name, they are not used for anything else.
The current workspace's WORKSPACE
file specifies which external repositories to load via workspace rules. Some of these rules use a WORKSPACE
file from the external repository, others will create a minimal WORKSPACE
file themselves.
I think the use of "root" in the page you linked is a bit confusing. That term has another meaning to the internals of Bazel, which is different from how it's used in that page. Most of the Bazel documentation just refers to the folder itself as "workspace" or "repository" without a separate term.