:code:`globals` ================= .. py:module:: globals .. py:class:: Cache A Cache provides a simple, concurrency-safe string -> value map for use by dawn programs. .. py:method:: 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. .. py:class:: Target A Target represents a dawn build target. Targets are created using the target function. .. py:attribute:: Target.label The target's label. .. py:attribute:: Target.always True if the target should always be considered out-of-date. .. py:attribute:: Target.env The target's environment (its globals, defaults, and free variables). .. py:attribute:: Target.dependencies A list of the target's dependencies as stringified labels. .. py:attribute:: Target.sources A list of the target's sources as absolute host paths. .. py:attribute:: Target.generates A list of the files generated by the target as absolute host paths. .. py:attribute:: host Provides information about the host on which dawn is running. .. py:attribute:: package The name of the package that contains the executing Starlark module. .. py:function:: path(label: str) -> str Returns the absolute OS path that corresponds to the given label. .. py:function:: label(path: str) -> str Returns the label that corresponds to the given project-relative path, if any. .. py:function:: 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). .. py:function:: 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. :param name: the name of the flag. :param default: the default value for the flag, if any. :param type: the type to which the flag's argument should be converted. Defaults to str. :param choices: the valid values for the flag. Defaults to any value. :param required: True if the flag must be set. :param help: the help string for the flag. :returns: the flag's value. .. py:function:: 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. :param name: the name of the target. :param deps: the target's dependencies. Must be a sequence whose elements are either labels or other build targets. :param 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). :param generates: any files generated by the targets. Must be a sequence of strings. Paths are interpreted identically to those in the sources parameter. :param function: the target's callback function. If this parameter is None, target returns a decorator function rather than a target. :param default: True if the target is its package's default target. :param always: True if the target should always be considered out-of-date. :param 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. .. py:function:: 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. :param include: the patterns to include. :param exclude: the patterns to exclude. :param dirs: True to include directory names in the result. :returns: the matched paths .. py:function:: fail(message: str) Fails the calling target with the given message. .. py:function:: 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. .. py:function:: flags() -> list[Flag] Lists the project's flags. .. py:function:: targets() -> list[Target] Lists the project's targets. .. py:function:: sources() -> list[str] Lists the project's sources. .. py:function:: run(label_or_target, always: bool=None, dry_run: bool=None, callback: callable=None) -> None Builds a target. :param label_or_target: the label or target to run. :param always: True if all targets should be considered out-of-date. :param dry_run: True if the targets to run should be displayed but not run. :param callback: a callback that receives build events. If absent, events will be displayed using the default renderer.