Skip to content

livery.workshop._run

livery.workshop._run

Start a package's executable after a development build of what it needs.

fm run <package>[:<executable>] -- <arguments> names a package and one of the executables its extensions answer under executables (livery.workshop.EXECUTABLES). It first builds the package's dependency closure, dependencies first, each member through the steps its set adds to the build phase's tree side, in the debug configuration, and skips each member whose files and dependencies are unchanged since its last good build in this checkout; the record of those builds lives under .workshop/.cache/run/. Then it runs the run phase through the one walk (livery.workshop._phases.walk_steps): every step the package's set adds to it, except that of the extensions answering executables only the owner's steps run. The engine gives the phase the executable under executable, which a step reads as it reads any engine key, and the words after -- are the context's arguments. The verb exits with the code the step that started the executable recorded.

Functions:

Name Description
run

Build what a package's executable needs, start it, and exit with its code.

start

Run target's executable in the workspace at root; its exit code.

develop

Build package's dependency closure in the build phase; the paths built.

Attributes:

Name Type Description
RECORD
DEVELOP_INPUTS dict[str, dict[str, object]]

RECORD module-attribute

RECORD = Path('.workshop') / '.cache' / 'run' / 'built.json'

DEVELOP_INPUTS module-attribute

DEVELOP_INPUTS: dict[str, dict[str, object]] = {'build': {'isolated': False, 'configuration': 'debug'}}

run

run(target: Annotated[Arg[str], doc('package[:executable]; the package may be left out inside its directory, and the executable when the package has one'), suggest(_targets, strict=False)] = '') -> int

Build what a package's executable needs, start it, and exit with its code.

The build phase's tree side runs over the package's dependency closure first, skipping what is unchanged since its last good build; then the run phase starts the executable with the words after --.

Source code in packages/workshop/src/livery/workshop/_run.py
@task(cwd="asinvoked")
def run(
    target: Annotated[
        Arg[str],
        doc(
            "package[:executable]; the package may be left out inside its directory,"
            " and the executable when the package has one"
        ),
        suggest(_targets, strict=False),
    ] = "",
) -> int:
    """Build what a package's executable needs, start it, and exit with its code.

    The build phase's tree side runs over the package's dependency
    closure first, skipping what is unchanged since its last good
    build; then the run phase starts the executable with the words
    after ``--``.
    """
    from livery.workshop._extensions import workspace_root

    here = cwd()
    root = workspace_root(here)
    if root is None:
        fail("no workspace: no workshop.toml above the working directory")
    return start(root, target, tuple(passthrough()), here)

start

start(root: Path, target: str, arguments: tuple[str, ...], cwd: Path) -> int

Run target's executable in the workspace at root; its exit code.

cwd decides the package a target that names none means. The development build runs first (livery.workshop._run.develop).

Source code in packages/workshop/src/livery/workshop/_run.py
def start(root: Path, target: str, arguments: tuple[str, ...], cwd: Path) -> int:
    """Run *target*'s executable in the workspace at *root*; its exit code.

    *cwd* decides the package a target that names none means. The
    development build runs first ([livery.workshop._run.develop][]).
    """
    from livery.workshop._composition import closure
    from livery.workshop._extensions import installed_declaration
    from livery.workshop._packages import discover_packages
    from livery.workshop._phases import (
        PhaseContext,
        PhaseError,
        phase_steps,
        walk_steps,
    )
    from livery.workshop._queries import EXECUTABLES, QueryError, answer, answers

    packages = discover_packages(root)
    package, executable = _resolve(root, packages, target, cwd)
    try:
        names = answer(package, EXECUTABLES)
    except QueryError as error:
        fail(str(error))
    if not names:
        fail(f"{package.path} has no executable: no extension of its set answers one")
    if not executable:
        if len(names) != 1:
            fail(
                f"{package.path} has the executables {', '.join(names)}; name one:"
                f" `{prog()} run {package.member}:{names[0]}`"
            )
        (executable,) = names
    answering = answers(package, EXECUTABLES)
    owners = {name for name, held in answering.items() if executable in held}
    if not owners:
        fail(
            f"{package.path} has no executable named {executable}; its executables"
            f" are {', '.join(names)}"
        )
    develop(root, package, packages)
    # The run steps of an extension answering executables start them,
    # so of those the owner's run alone; every other extension's run.
    members = closure(package.extensions, installed_declaration)
    steps = tuple(
        record
        for record in phase_steps("run", members, installed_declaration)
        if record.extension not in answering or record.extension in owners
    )
    ctx = PhaseContext(
        root=root,
        packages=(package,),
        package=package,
        phase="run",
        arguments=arguments,
    )
    try:
        ctx = walk_steps(ctx, steps, inputs={"run": {"executable": executable}})
    except PhaseError as error:
        fail(str(error))
    return ctx.exit_code

develop

develop(root: Path, package: Package, packages: tuple[Package, ...]) -> list[str]

Build package's dependency closure in the build phase; the paths built.

Dependencies come first, each through the steps its set adds to the build phase that serve the tree side, in the debug configuration (livery.workshop._run.DEVELOP_INPUTS), run through the one walk as the release train runs a package's phase. A member is built when its files, or the fingerprint of a dependency, differ from its last good build in this checkout, so a dependency that changed rebuilds what depends on it; a member whose set adds no such step is never built. With nothing changed, no build step runs. A checkout git cannot read is built whole, and says so.

Source code in packages/workshop/src/livery/workshop/_run.py
def develop(root: Path, package: Package, packages: tuple[Package, ...]) -> list[str]:
    """Build *package*'s dependency closure in the build phase; the paths built.

    Dependencies come first, each through the steps its set adds to the
    build phase that serve the tree side, in the ``debug``
    configuration ([livery.workshop._run.DEVELOP_INPUTS][]), run
    through the one walk as the release train runs a package's phase.
    A member is built when its files, or the fingerprint of a
    dependency, differ from its last good build in this checkout, so a
    dependency that changed rebuilds what depends on it; a member whose
    set adds no such step is never built. With nothing changed, no
    build step runs. A checkout git cannot read is built whole, and
    says so.
    """
    from livery.workshop._graph import dependencies_closure, order_topologically

    closure = order_topologically(dependencies_closure(packages, {package.path}))
    try:
        tree = git.working_tree_id(root)
    except git.GitError as error:
        print(
            f"  run: git cannot read this checkout, so every member builds: {error}",
            file=sys.stderr,
        )
        tree = ""
    ids = _subtrees(root, tree, closure)
    record = _read(root)
    prints: dict[str, str] = {}
    built: list[str] = []
    for member in closure:
        own = ids.get(member.path, "")
        needs = sorted(
            prints[edge.path] for edge in member.depends if edge.path in prints
        )
        fingerprint = hashlib.sha256("\n".join((own, *needs)).encode()).hexdigest()
        prints[member.path] = fingerprint
        steps = _build_steps(member)
        if not steps or (own and record.get(member.path) == fingerprint):
            continue
        _build(root, member, steps)
        built.append(member.path)
        if own:
            record[member.path] = fingerprint
            _write(root, record)
    return built