Skip to content

BenchX target description

urn:benchx:schema:target-description:0.1.0 · version 0.1.0 · schema.json · source

What a target provider hands the workbench about one prepared target (docs/design/system-decomposition.md §3.4). The same document arrives three ways: on a provider's stdout, as a sidecar file .benchx-target.json in a build directory, or assembled by the workbench from the user's own input. The workbench copies target, build, how_built, activation and shell into the work order's target, and labels into the order's labels. Nothing else in a work order comes from a provider.

Implementer note

target and build are $refs into urn:benchx:schema:work-order:0.1.0, so the two cannot drift; a validator must register that schema (and the measurement-result schema it refs) together with this one. Paths are absolute because the workbench and the runner may not share a working directory; the schema enforces this for working_tree and build targets. how_built, activation, shell and provider are $refs into the work-order schema's provenanceText, so a description copies into an order unchanged. how_built and activation are declared provenance text (benchmark-environments.md §3.2): recorded as given, never executed and never checked against anything. The user activates the environment before invoking benchx, and the runner records what it inherited. Absent, null, empty, or whitespace-only means not declared. Neither text enters identity. Both are copied verbatim into results, which may be promoted to a shared store, so neither may hold secrets.

Properties

Property Required Type Description
schema_version yes constant "benchx/target-description/0.1.0"
target yes target The work-order target, unchanged.
build build The declared configuration of the prebuilt target, for facts the runner cannot read from it. The work-order build object, unchanged.
how_built provenanceText.how_built
activation provenanceText.activation
shell provenanceText.shell
labels map of string (min length 1) Caller labels for selecting sides of a comparison, copied to the order's labels. Never enter identity.
provider provenanceText.provider

No other properties are allowed.

Rules:

  • If target.kind is one of "working_tree", "build", then target.path must be string (pattern ^(/|[A-Za-z]:[\\/])); target.source_dir must be string (pattern ^(/|[A-Za-z]:[\\/])).

Examples

{
  "schema_version": "benchx/target-description/0.1.0",
  "target": {
    "kind": "build",
    "path": "/tmp/bench-hardened",
    "source": { "uri": "https://github.com/apache/arrow", "type": "git" },
    "source_dir": "/home/me/arrow"
  },
  "build": { "type": "Release", "options": { "ARROW_HARDENING": "ON" } },
  "how_built": "cmake -S cpp -B /tmp/bench-hardened -GNinja -DCMAKE_BUILD_TYPE=Release -DARROW_BUILD_BENCHMARKS=ON -DARROW_COMPUTE=ON -DARROW_HARDENING=ON\ncmake --build /tmp/bench-hardened --target arrow-compute-vector-selection-benchmark",
  "activation": "export LD_LIBRARY_PATH=/opt/deps/lib:$LD_LIBRARY_PATH",
  "shell": "bash",
  "labels": { "side": "hardened" },
  "provider": { "name": "build-arrow.sh", "version": "3" }
}

{
  "schema_version": "benchx/target-description/0.1.0",
  "target": {
    "kind": "build",
    "path": "/tmp/bench-plain",
    "source": { "uri": "https://github.com/apache/arrow" }
  },
  "how_built": "",
  "activation": null,
  "shell": null
}

{
  "schema_version": "benchx/target-description/0.1.0",
  "target": {
    "kind": "working_tree",
    "path": "/home/me/arrow",
    "source": { "uri": "https://github.com/apache/arrow" }
  }
}