BUILD.toml

The BUILD.toml sits in the root of a Package and helps us define the dependency graph of the Workspace.

The minimal BUILD.toml simply uses the [package] header:

[package]

Dependencies

BUILD.toml has two optional keys that allow defining the dependency, depends_on and runtimes.

depends_on

depends_on allows specifying the path to any packages this package requires. It is generic and language-agnostic.

In our Sample Monorepo Structure, //services/backend depends upon //libs/py/common, we can specify this by:

[package]
depends_on = [
    "//libs/py/common",
]

runtimes

However, we often will also be specify relative dependencies in the language-specific package management files (pyproject.toml, packages.json, etc). In this case, the depends_on is duplicating, so we can use a Supported Runtime to parse the dependency file and dynamically create the dependencies

If our //services/backend/pyproject.toml has a relative dependency to //libs/py/common:

[tool.poetry.dependencies]
 python = "~3.10"
 "sampleproject.common" = {path = "../../libs/py/common", develop = true}

The BUILD.toml can skip the depends_on and just define a runtimes:

[package]
runtimes = ["python"]

runtimes and depends_on can be mixed together, expecially if there is not yet a Supported Runtime.