`globals`

class globals.Cache: A Cache provides a simple, concurrency-safe string -> value map for use by dawn programs.

Cache.once(key: str, callable: callable)

once calls the given callable if and only if key is not present in the cache.

The result is stored in the cache under the given key.

Returns the result of the call or the cached value.

class globals.Target: A Target represents a dawn build target. Targets are created using the target function.

Target.label: The target’s label.

Target.always: True if the target should always be considered out-of-date.

Target.env: The target’s environment (its globals, defaults, and free variables).

Target.dependencies: A list of the target’s dependencies as stringified labels.

Target.sources: A list of the target’s sources as absolute host paths.

Target.generates: A list of the files generated by the target as absolute host paths.

globals.host: Provides information about the host on which dawn is running.

globals.package: The name of the package that contains the executing Starlark module.

globals.path(label: str) → str: Returns the absolute OS path that corresponds to the given label.

globals.label(path: str) → str: Returns the label that corresponds to the given project-relative path, if any.

globals.contains(path: str) → tuple[str | None, bool]: Returns the label that corresponds to the given OS path if the path is contained in the current project. If the path is not contained in the current project, contains returns (None, False).

globals.parse_flag(name: str, default=None, type: callable = None, choices: list = None, required: bool = None, help: str = None)

Defines and parses a new project flag in the current package.

Parameters:

name – the name of the flag.
default – the default value for the flag, if any.
type – the type to which the flag’s argument should be converted. Defaults to str.
choices – the valid values for the flag. Defaults to any value.
required – True if the flag must be set.
help – the help string for the flag.

Returns:

the flag’s value.

globals.target(name: str = None, deps: list = None, sources: list[str] = None, generates: list[str] = None, function: function = None, default: bool = None, always: bool = None, docs: str = None) → Target

Defines a new build target in the current package. Typically used as a decorator, in which case the decorated function is treated as the value of the function parameter.

Parameters:

name – the name of the target.
deps – the target’s dependencies. Must be a sequence whose elements are either labels or other build targets.
sources – the target’s source files. Must be a sequence of strings. Each string will be interpreted relative to the package’s directory (if the path is relative) or project root (if the path is absolute).
generates – any files generated by the targets. Must be a sequence of strings. Paths are interpreted identically to those in the sources parameter.
function – the target’s callback function. If this parameter is None, target returns a decorator function rather than a target.
default – True if the target is its package’s default target.
always – True if the target should always be considered out-of-date.
docs – the docs for the target. Normally picked up from the function’s docstring.

Returns:

the new build target object or a decorator if function is None.

globals.glob(include: list[str], exclude: list[str] = None, dirs: bool = None) → list[str]

Return a list of paths relative to the calling module’s directory that match the given include and exclude patterns. Typically passed to the sources parameter of target.

A particular path matches if any of the include patterns matches and none of the exclude patterns match.

The pattern syntax is:

pattern:: pathTerm { ‘/’ pathTerm }
pathTerm:: ‘**’ matches any sequence of directory names, including the empty sequence { term } matches a sequence of terms against a name
term:: ‘*’ matches any sequence of non-/ characters ‘?’ matches any single non-/ character ‘[’ [ ‘^’ ] { character-range } ‘]’ character class (must be non-empty) c matches character c (c != ‘*’, ‘?’, ‘', ‘[‘) ‘' c matches character c
character-range:: c matches character c (c != ‘', ‘-’, ‘]’) ‘' c matches character c lo ‘-’ hi matches character c for lo <= c <= hi

Patterns require that path terms match all of a component, not just a substring.

Parameters:

include – the patterns to include.
exclude – the patterns to exclude.
dirs – True to include directory names in the result.

Returns:

the matched paths

globals.fail(message: str): Fails the calling target with the given message.

globals.get_target(label: str) → Target

Gets the target with the given label, if it exists.

Param:: label: the target’s label.
Returns:: the target with the given label.

globals.flags() → list[Flag]: Lists the project’s flags.

globals.targets() → list[Target]: Lists the project’s targets.

globals.sources() → list[str]: Lists the project’s sources.

globals.run(label_or_target, always: bool = None, dry_run: bool = None, callback: callable = None) → None

Builds a target.

Parameters:

label_or_target – the label or target to run.
always – True if all targets should be considered out-of-date.
dry_run – True if the targets to run should be displayed but not run.
callback – a callback that receives build events. If absent, events will be displayed using the default renderer.

globals

`globals`