Search code examples
bazel

What is the difference between a workspace and repository in Bazel


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?


Solution

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