Commands

BenchBuild provides an abstraction for binaries that are provided by a project, after compilation. These Command objects carry the path to the binary, customizable output paramters and support for dynamic tokens inside the path generation.

Besides these features, a command behaves identical to any other binary command that you make use of inside BenchBuild, e.g., benchbuild.utils.cmd.

Usage inside Projects

For now, you make use of BenchBuild’s commands inside a project’s WORKLOADS attribute. Let’s have a look at the following example:

from benchbuild import Project
from benchbuild.command import Command, WorkloadSet, SourceRoot

class MyProject(Project):
  ...
  SOURCE = [
    Git(
      remote="https://github.com/myproject.git",
      local="myproject.git",
      limit=1,
      refspec="HEAD"
  ]

  WORKLOADS = {
    WorkloadSet("compression"): [
      Command(SourceRoot("myproject.git") / "myprj")
    ]
  }

Here we have a Command that belongs to the WorkloadSet with the name compression that points to the binary myprj inside the project’s source directory of the git source myproject.git. What concrete path this will be is only known after this project has been instanced inside an experiment and is not known before.

This is done using tokens inside the commands’ path representation. One example of an available token is the above SourceRoot.

Tokens

BenchBuild offers project authors a way to tokenize path components for commands. These can be used to refer to a project’s root directory or source directory in a generic way.

Module: command

class benchbuild.command.ArgsRenderStrategy(*args, **kwargs)

Bases: Protocol

Rendering strategy protocol for command line argument tokens.

rendered(**kwargs)

Renders this strategy.

Return type:

Tuple[str, ...]

property unrendered: str

Returns an unrendered representation of this strategy.

class benchbuild.command.ArgsToken(renderer)

Bases: object

Base class for tokens that can be rendered into command-line arguments.

classmethod make_token(renderer)

Return type:

ArgsToken

render(**kwargs)

Renders the PathToken as a standard pathlib Path.

Any kwargs will be forwarded to the PathRenderStrategy.

Return type:

Tuple[str, ...]

renderer: ArgsRenderStrategy

class benchbuild.command.BackupFn(*args, **kwargs)

Bases: Protocol

Backup callback function protocol.

class benchbuild.command.BuilddirRenderer

Bases: object

Renders the build directory of the assigned project.

rendered(project=None, **kwargs)

Render the project’s build directory.

If rendering is not possible, the unrendered representation is provided and an error will be loggged.

Parameters:

project (Optional[benchbuild.project.Project]) – the project to render the build directory from.

Return type:

Path

property unrendered: str

class benchbuild.command.Command(path, *args, output=None, output_param=None, label=None, creates=None, consumes=None, **kwargs)

Bases: object

A command wrapper for benchbuild’s commands.

Commands are defined by a path to an executable binary and it’s arguments. Optional, commands can provide output and output_param parameters to declare the Command’s output behavior.

path

The binary path of the command

\*args

Command arguments.

output_param

A format string that encodes the output parameter argument using the output attribute.

Example: output_param = f”–out {output}”. BenchBuild will construct the output argument from this.

output

An optional PathToken to declare an output file of the command.

label

An optional Label that can be used to name a command.

creates

A list of PathToken that encodes any artifacts that are created by this command. This will include the output PathToken automatically. Any additional PathTokens provided will be provided for cleanup.

consumes

A list of PathToken that holds any artifacts that will be consumed by this command.

\*\*kwargs

Any remaining kwargs will be added as environment variables to the command.

Base command path: >>> ROOT = PathToken.make_token() >>> base_c = Command(ROOT / “bin” / “true”) >>> base_c Command(path=/bin/true) >>> str(base_c) ‘/bin/true’

Test environment representations: >>> env_c = Command(ROOT / “bin”/ “true”, BB_ENV_TEST=1) >>> env_c Command(path=/bin/true env={‘BB_ENV_TEST’: 1}) >>> str(env_c) ‘BB_ENV_TEST=1 /bin/true’

Argument representations: >>> args_c = Command(ROOT / “bin” / “true”, “–arg1”, “–arg2”) >>> args_c Command(path=/bin/true args=(’–arg1’, ‘–arg2’)) >>> str(args_c) ‘/bin/true –arg1 –arg2’

Use str for creates: >>> cmd = Command(ROOT / “bin” / “true”, creates=[“tmp/foo”]) >>> cmd.creates [<builddir>/tmp/foo]

Use absolute path-str for creates: >>> cmd = Command(ROOT / “bin” / “true”, creates=[“/tmp/foo”]) >>> cmd.creates [/tmp/foo]

as_plumbum(**kwargs)

Convert this command into a plumbum compatible command.

This renders all tokens in the command’s path and creates a new plumbum command with the given parameters and environment.

Parameters:

**kwargs (Any) – parameters passed to the path renderers.

Return type:

BoundEnvCommand

Returns:

An executable plumbum command.

property consumes: Sequence[PathToken]

property creates: Sequence[PathToken]

property dirname: Path

env(**kwargs)

Return type:

None

property label: str

property name: str

property output: PathToken | None

property path: PathToken

rendered_args(**kwargs)

Return type:

Tuple[str, ...]

class benchbuild.command.ConstStrRenderer(value)

Bases: object

Renders a constant string defined by the user.

rendered(**kwargs)

Return type:

Path

property unrendered: str

value: str

class benchbuild.command.OnlyIn(rev_range, workload_set)

Bases: object

Provide a filled WorkloadSet only if, given revision is inside the range.

This makes use of the unwrap protocol and returns the given WorkloadSet, iff, the Project’s revision is included in the range specified by the RevisionRange.

rev_range: RevisionRange

unwrap(project)

Provide the store WorkloadSet only if our revision is in the range.

Return type:

WorkloadSet

workload_set: WorkloadSet

class benchbuild.command.PathRenderStrategy(*args, **kwargs)

Bases: Protocol

Rendering strategy protocol for path components.

rendered(**kwargs)

Renders this strategy.

Return type:

Path

property unrendered: str

Returns an unrendered representation of this strategy.

class benchbuild.command.PathToken(renderer, left=None, right=None)

Bases: object

Base class used for command token substitution.

A path token can use similar to pathlib’s Path components. However, each token can render dynamically based on the given render context.

property dirname: Path

exists()

Return type:

bool

left: Optional[PathToken]

classmethod make_token(renderer=None)

Return type:

PathToken

property name: str

render(**kwargs)

Renders the PathToken as a standard pathlib Path.

Any kwargs will be forwarded to the PathRenderStrategy.

Return type:

Path

renderer: PathRenderStrategy

right: Optional[PathToken]

class benchbuild.command.ProjectCommand(project, command)

Bases: object

ProjectCommands associate a command to a benchbuild project.

A project command can wrap the given command with the assigned runtime extension. If the binary is located inside a subdirectory relative to one of the project’s sources, you can provide a path relative to it’s local directory. A project command will always try to resolve any reference to a local source directory in a command’s path.

A call to a project command will drop the current configuration inside the project’s build directory and confine the run into the project’s build directory. The binary will be replaced with a wrapper that calls the project’s runtime_extension.

command: Command

property path: Path

project: benchbuild.project.Project

benchbuild.command.ProjectRoot()

Return type:

PathToken

class benchbuild.command.PruneFn(*args, **kwargs)

Bases: Protocol

Prune function protocol.

class benchbuild.command.RestoreFn(*args, **kwargs)

Bases: Protocol

Restore function protocol.

class benchbuild.command.RootRenderer

Bases: object

Renders the root directory.

rendered(**kwargs)

Return type:

Path

property unrendered: str

benchbuild.command.SourceRoot(local_name)

Create a SourceRoot token for the given name.

Parameters:

local_name (str) – The source’s local name to access.

Return type:

PathToken

class benchbuild.command.SourceRootRenderer(local_name)

Bases: object

Renders the source root of the given local source name.

The attribute ‘local’ refers to the local attribute in a project’s source definition. If the local name cannot be found inside the project’s source definition, it will concatenate the project’s builddir with the given name.

local: str

rendered(project=None, **kwargs)

Render the project’s source directory.

If rendering is not possible, the unrendered representation is provided and an error will be loggged.

Parameters:

project (Optional[benchbuild.project.Project]) – the project to render the build directory from.

Return type:

Path

property unrendered: str

class benchbuild.command.SupportsUnwrap(*args, **kwargs)

Bases: Protocol

Support unwrapping a WorkloadSet.

Unwrapping ensures access to a WorkloadSet from any wrapper object.

unwrap(project)

Return type:

WorkloadSet

class benchbuild.command.WorkloadSet(*args)

Bases: object

An immutable set of workload descriptors.

A WorkloadSet is immutable and usable as a key in a job mapping. WorkloadSets support composition through intersection and union.

Example: >>> WorkloadSet(1, 0) & WorkloadSet(1) WorkloadSet({1}) >>> WorkloadSet(1, 0) & WorkloadSet(2) WorkloadSet({}) >>> WorkloadSet(1, 0) | WorkloadSet(2) WorkloadSet({0, 1, 2}) >>> WorkloadSet(1, 0) | WorkloadSet(“1”) WorkloadSet({0, 1, 1})

A workload set is not sorted, therefore, requires no comparability between inserted values.

unwrap(project)

Implement the SupportsUnwrap protocol.

WorkloadSets only implement identity.

Return type:

WorkloadSet

benchbuild.command.cleanup(project_command, backup=<function _default_backup>, restore=<function _default_restore>, prune=<function _default_prune>)

Encapsulate a command in automatic backup, restore and prune.

This will wrap a ProjectCommand inside a contextmanager. All consumed files inside the project’s build directory will be backed up by benchbuild. You can then run your command as usual. When you leave the context, all created paths are deleted and all consumed paths restored.

benchbuild.command.filter_workload_index(only, index)

Yield only commands from the index that match the filter.

This removes all command lists from the index not matching only.

Return type:

Generator[List[Command], None, None]

benchbuild.command.project_root()

Return type:

PathToken

benchbuild.command.source_root(local_name)

Create a SourceRoot token for the given name.

Parameters:

local_name (str) – The source’s local name to access.

Return type:

PathToken

benchbuild.command.unwrap(index, project)

Unwrap all keys in a workload index.

‘Empty’ WorkloadSets will be removed. A WorkloadSet is empty, if it’s boolean representation evaluates to False.

Return type:

MutableMapping[WorkloadSet, List[Command]]