compilersutra-perf 0.2.0__tar.gz → 0.3.0__tar.gz

{compilersutra_perf-0.2.0 → compilersutra_perf-0.3.0}/PKG-INFO

@@ -1,14 +1,11 @@
 Metadata-Version: 2.4
 Name: compilersutra-perf
-Version: 0.2.0
+Version: 0.3.0
 Summary: Alpha CLI for compiler and GPU performance experiments — compile, profile, diff, and export JSON/CSV results
 Author-email: Priya Pandey <osc@compilersutra.com>, CompilerSutra <osc@compilersutra.com>
 License-Expression: Apache-2.0
-Project-URL: Homepage, https://github.com/compilersutra/CompilerSutraPerfTool
-Project-URL: Documentation, https://github.com/compilersutra/CompilerSutraPerfTool/blob/main/docs/USAGE.md
-Project-URL: Repository, https://github.com/compilersutra/CompilerSutraPerfTool
-Project-URL: Issues, https://github.com/compilersutra/CompilerSutraPerfTool/issues
-Project-URL: Changelog, https://github.com/compilersutra/CompilerSutraPerfTool/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://www.compilersutra.com
+Project-URL: Documentation, https://www.compilersutra.com/docs/project/compilersutra-perf/getting-started/
 Project-URL: Author, https://www.linkedin.com/in/priya-pandey-54a5a22aa/
 Keywords: benchmarking,compiler,gpu,hip,llvm,opencl,performance,profiling,systems,vulkan
 Classifier: Development Status :: 3 - Alpha
@@ -39,19 +36,19 @@ Requires-Dist: pip-audit>=2.7; extra == "dev"
 Requires-Dist: urllib3>=2.7; extra == "dev"
 Requires-Dist: click>=8.3.3; extra == "dev"
 Requires-Dist: cryptography>=50.0.0; extra == "dev"
-Requires-Dist: GitPython>=3.1.57; extra == "dev"
+Requires-Dist: GitPython>=3.1.59; extra == "dev"
 Requires-Dist: idna>=3.15; extra == "dev"
 Requires-Dist: Pillow>=12.3.0; extra == "dev"
 Requires-Dist: Pygments>=2.20.0; extra == "dev"
 Requires-Dist: requests>=2.33.0; extra == "dev"
-Requires-Dist: tornado>=6.5.7; extra == "dev"
+Requires-Dist: tornado>=6.5.8; extra == "dev"
 Provides-Extra: excel
 Requires-Dist: openpyxl>=3.1; extra == "excel"
 Provides-Extra: visualize
 Requires-Dist: streamlit>=1.33; extra == "visualize"
 Requires-Dist: plotly>=5.20; extra == "visualize"
 Provides-Extra: pdf
-Requires-Dist: weasyprint>=62; extra == "pdf"
+Requires-Dist: weasyprint>=70.0; extra == "pdf"
 Provides-Extra: track
 Requires-Dist: mlflow>=2.11; extra == "track"
 Provides-Extra: tune
@@ -74,6 +71,8 @@ Compile, run, profile, compare, and export structured JSON/CSV/XLSX artifacts
 
 **Status:** Alpha MVP (0.2.0). Suitable for local experimentation; not yet validated for production CI regression gates. See [limitations](#limitations) and [docs/METHODOLOGY.md](docs/METHODOLOGY.md).
 
+**Research goal:** a unified CPU/GPU hardware & compiler observatory layer — orchestrate existing toolchains, normalize results, and keep static vs measured evidence honest. See [docs/OBSERVATORY.md](docs/OBSERVATORY.md).
+
 ---
 
 ## Install
@@ -93,7 +92,7 @@ pip install 'compilersutra-perf[dev]'         # pytest
 
 **Requirements:** Python 3.11+. Linux wheels ship prebuilt native runners for CPU (and Vulkan, where available), so CPU workloads run out of the box. Other platforms (or exotic Python builds) fall back to building the runner on demand, which needs a C/C++ toolchain and `cmake` on `PATH`; `perf` is also recommended for full CPU profiling on Linux. GPU backends need their respective runtimes (ROCm, OpenCL, Vulkan) installed separately.
 
-**Platform wheels and old distributions:** wheels are tagged for the glibc they were built on (e.g. `linux_x86_64`), so a wheel built on Ubuntu 24.04 may fail to load its bundled runner on Ubuntu 22.04 or older (newer glibc). The loader probes the bundled runner at startup and automatically falls back to an on-demand local build, so only an older toolchain is needed there. Hardware counter events are probed per-CPU, so vendor-specific events never break collection on other vendors (Intel vs AMD).
+**Platform wheels and old distributions:** release wheels use a `manylinux` tag (e.g. `manylinux_2_39_x86_64`) for the glibc they were built on, so a wheel built on Ubuntu 24.04 may fail to load its bundled runner on Ubuntu 22.04 or older (newer glibc). The loader probes the bundled runner at startup and automatically falls back to an on-demand local build, so only an older toolchain is needed there. Hardware counter events are probed per-CPU, so vendor-specific events never break collection on other vendors (Intel vs AMD).
 
 **Native Windows:** not yet supported. The runner uses POSIX APIs (`fork`, `sched_setaffinity`) and won't build on Windows natively — use [WSL2](docs/WINDOWS_WSL2.md). Result artifacts (JSON/CSV/XLSX/HTML reports) open fine on Windows.
 
@@ -101,17 +100,16 @@ Check that every system tool csperf needs is present, and install whatever is mi
 
 ```bash
 csperf quickstart --output-dir results/quickstart   # doctor + example + report
-csperf doctor              # report missing tools
+csperf doctor              # report missing tools; exit 1 if a required tool is missing
 csperf doctor --install    # install missing required tools (apt/dnf/pacman/apk/brew)
 csperf doctor --install --all   # also install optional GPU/profiling tools
 ```
 
 See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for perf, energy, and GPU fixes.
 
-Develop from source:
+Develop from source (private checkout if you have access):
 
 ```bash
-git clone https://github.com/compilersutra/CompilerSutraPerfTool.git
 cd CompilerSutraPerfTool
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e '.[dev]'
@@ -155,7 +153,7 @@ Each `run` writes `results/<name>.json`, `.csv`, and `.xlsx` (when `openpyxl` is
 | **CPU** | Execute + profile | Native C++ runner, LLVM IR (clang), Linux `perf` counters, warmup/repeat, optional `--cpu-affinity` |
 | **HIP** | Execute + profile | `hipcc` compile-and-run, ROCm devices, `rocprofv3` (then v2/v1) |
 | **OpenCL** | Execute | Native kernel launch, device selection, warmup/repeat |
-| **Vulkan** | Compile + validate | GLSL → SPIR-V, shader-module validation |
+| **Vulkan** | Execute via csrun / validate | Prefer CompilerSutraRun YAML execute (`CSRUN_BIN`); else GLSL → SPIR-V + module validation |
 | **`gpu` alias** | Auto-route | `.hip` → HIP, `.cl` → OpenCL, shaders → Vulkan |
 | **CUDA / Metal** | Planned | Listed in registry but not executable |
 | **macOS CPU** | Experimental | Execution works; profiling uses `powermetrics` (needs passwordless `sudo`) |
@@ -303,11 +301,11 @@ Read these before trusting numbers in papers or CI:
 - **Alpha** — methodology and backend coverage are still evolving.
 - CPU runs support `--execution-timeout` to bound workload execution.
 - CPU runs support repeated `--program-arg` values and `--stdin-file`; manifests can define the same settings.
-- **`--experiment` / `--opt-config`** — apply compile macros and optional extra flags; plugin entry points remain [#24](https://github.com/compilersutra/CompilerSutraPerfTool/issues/24) / 0.3.0.
+- **`--experiment` / `--opt-config`** — apply compile macros and optional extra flags; plugin entry points remain planned for 0.3.0.
 - Optional extras `track`, `tune`, and `distributed` are reserved for later releases and are not wired into the CLI.
-- **OpenCL** — program may recompile each trial; interpret kernel times carefully ([#38](https://github.com/compilersutra/CompilerSutraPerfTool/issues/38)).
+- **OpenCL** — program may recompile each trial; interpret kernel times carefully.
 - **CUDA / Metal** — not implemented despite registry entries.
-- **Native runners** — PyPI wheel does not bundle C++ binaries; build from source or install runners separately for full execution.
+- **Native runners** — Linux wheels bundle prebuilt native runners; other platforms build on demand from the bundled sources (needs a C/C++ toolchain and `cmake`).
 
 Best supported today: **Linux CPU** compile/run/profile with `perf` configured, plus HIP/OpenCL exploration with manual interpretation.
 
@@ -315,7 +313,11 @@ Best supported today: **Linux CPU** compile/run/profile with `perf` configured,
 
 ## Documentation
 
-Full guides live in the repository:
+Public getting started guide:
+
+https://www.compilersutra.com/docs/project/compilersutra-perf/getting-started/
+
+In-tree guides (source checkout):
 
 | Doc | Topic |
 | --- | --- |
@@ -329,8 +331,6 @@ Full guides live in the repository:
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Contributions |
 | [CHANGELOG.md](CHANGELOG.md) | Release notes |
 
-Repository: https://github.com/compilersutra/CompilerSutraPerfTool
-
 ---
 
 ## License

{compilersutra_perf-0.2.0 → compilersutra_perf-0.3.0}/README.md

@@ -10,6 +10,8 @@ Compile, run, profile, compare, and export structured JSON/CSV/XLSX artifacts
 
 **Status:** Alpha MVP (0.2.0). Suitable for local experimentation; not yet validated for production CI regression gates. See [limitations](#limitations) and [docs/METHODOLOGY.md](docs/METHODOLOGY.md).
 
+**Research goal:** a unified CPU/GPU hardware & compiler observatory layer — orchestrate existing toolchains, normalize results, and keep static vs measured evidence honest. See [docs/OBSERVATORY.md](docs/OBSERVATORY.md).
+
 ---
 
 ## Install
@@ -29,7 +31,7 @@ pip install 'compilersutra-perf[dev]'         # pytest
 
 **Requirements:** Python 3.11+. Linux wheels ship prebuilt native runners for CPU (and Vulkan, where available), so CPU workloads run out of the box. Other platforms (or exotic Python builds) fall back to building the runner on demand, which needs a C/C++ toolchain and `cmake` on `PATH`; `perf` is also recommended for full CPU profiling on Linux. GPU backends need their respective runtimes (ROCm, OpenCL, Vulkan) installed separately.
 
-**Platform wheels and old distributions:** wheels are tagged for the glibc they were built on (e.g. `linux_x86_64`), so a wheel built on Ubuntu 24.04 may fail to load its bundled runner on Ubuntu 22.04 or older (newer glibc). The loader probes the bundled runner at startup and automatically falls back to an on-demand local build, so only an older toolchain is needed there. Hardware counter events are probed per-CPU, so vendor-specific events never break collection on other vendors (Intel vs AMD).
+**Platform wheels and old distributions:** release wheels use a `manylinux` tag (e.g. `manylinux_2_39_x86_64`) for the glibc they were built on, so a wheel built on Ubuntu 24.04 may fail to load its bundled runner on Ubuntu 22.04 or older (newer glibc). The loader probes the bundled runner at startup and automatically falls back to an on-demand local build, so only an older toolchain is needed there. Hardware counter events are probed per-CPU, so vendor-specific events never break collection on other vendors (Intel vs AMD).
 
 **Native Windows:** not yet supported. The runner uses POSIX APIs (`fork`, `sched_setaffinity`) and won't build on Windows natively — use [WSL2](docs/WINDOWS_WSL2.md). Result artifacts (JSON/CSV/XLSX/HTML reports) open fine on Windows.
 
@@ -37,17 +39,16 @@ Check that every system tool csperf needs is present, and install whatever is mi
 
 ```bash
 csperf quickstart --output-dir results/quickstart   # doctor + example + report
-csperf doctor              # report missing tools
+csperf doctor              # report missing tools; exit 1 if a required tool is missing
 csperf doctor --install    # install missing required tools (apt/dnf/pacman/apk/brew)
 csperf doctor --install --all   # also install optional GPU/profiling tools
 ```
 
 See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for perf, energy, and GPU fixes.
 
-Develop from source:
+Develop from source (private checkout if you have access):
 
 ```bash
-git clone https://github.com/compilersutra/CompilerSutraPerfTool.git
 cd CompilerSutraPerfTool
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e '.[dev]'
@@ -91,7 +92,7 @@ Each `run` writes `results/<name>.json`, `.csv`, and `.xlsx` (when `openpyxl` is
 | **CPU** | Execute + profile | Native C++ runner, LLVM IR (clang), Linux `perf` counters, warmup/repeat, optional `--cpu-affinity` |
 | **HIP** | Execute + profile | `hipcc` compile-and-run, ROCm devices, `rocprofv3` (then v2/v1) |
 | **OpenCL** | Execute | Native kernel launch, device selection, warmup/repeat |
-| **Vulkan** | Compile + validate | GLSL → SPIR-V, shader-module validation |
+| **Vulkan** | Execute via csrun / validate | Prefer CompilerSutraRun YAML execute (`CSRUN_BIN`); else GLSL → SPIR-V + module validation |
 | **`gpu` alias** | Auto-route | `.hip` → HIP, `.cl` → OpenCL, shaders → Vulkan |
 | **CUDA / Metal** | Planned | Listed in registry but not executable |
 | **macOS CPU** | Experimental | Execution works; profiling uses `powermetrics` (needs passwordless `sudo`) |
@@ -239,11 +240,11 @@ Read these before trusting numbers in papers or CI:
 - **Alpha** — methodology and backend coverage are still evolving.
 - CPU runs support `--execution-timeout` to bound workload execution.
 - CPU runs support repeated `--program-arg` values and `--stdin-file`; manifests can define the same settings.
-- **`--experiment` / `--opt-config`** — apply compile macros and optional extra flags; plugin entry points remain [#24](https://github.com/compilersutra/CompilerSutraPerfTool/issues/24) / 0.3.0.
+- **`--experiment` / `--opt-config`** — apply compile macros and optional extra flags; plugin entry points remain planned for 0.3.0.
 - Optional extras `track`, `tune`, and `distributed` are reserved for later releases and are not wired into the CLI.
-- **OpenCL** — program may recompile each trial; interpret kernel times carefully ([#38](https://github.com/compilersutra/CompilerSutraPerfTool/issues/38)).
+- **OpenCL** — program may recompile each trial; interpret kernel times carefully.
 - **CUDA / Metal** — not implemented despite registry entries.
-- **Native runners** — PyPI wheel does not bundle C++ binaries; build from source or install runners separately for full execution.
+- **Native runners** — Linux wheels bundle prebuilt native runners; other platforms build on demand from the bundled sources (needs a C/C++ toolchain and `cmake`).
 
 Best supported today: **Linux CPU** compile/run/profile with `perf` configured, plus HIP/OpenCL exploration with manual interpretation.
 
@@ -251,7 +252,11 @@ Best supported today: **Linux CPU** compile/run/profile with `perf` configured,
 
 ## Documentation
 
-Full guides live in the repository:
+Public getting started guide:
+
+https://www.compilersutra.com/docs/project/compilersutra-perf/getting-started/
+
+In-tree guides (source checkout):
 
 | Doc | Topic |
 | --- | --- |
@@ -265,8 +270,6 @@ Full guides live in the repository:
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Contributions |
 | [CHANGELOG.md](CHANGELOG.md) | Release notes |
 
-Repository: https://github.com/compilersutra/CompilerSutraPerfTool
-
 ---
 
 ## License

{compilersutra_perf-0.2.0 → compilersutra_perf-0.3.0}/native/runtime/lib/Runtime/Process.cpp

@@ -13,7 +13,6 @@
 #include <sstream>
 #include <stdexcept>
 #include <string>
-#include <sys/ptrace.h>
 #include <sys/types.h>
 #include <sys/wait.h>
 #include <thread>
@@ -22,6 +21,7 @@
 
 #if defined(__linux__)
 #include <sched.h>
+#include <sys/ptrace.h>
 #endif
 
 namespace csperf::runtime {
@@ -51,6 +51,7 @@ bool wait_for_stop(pid_t pid, int* status) {
     }
 }
 
+#if defined(__linux__)
 bool stop_child_at_exec(pid_t pid) {
     if (ptrace(PTRACE_SETOPTIONS, pid, nullptr, PTRACE_O_TRACEEXEC) != 0) {
         return false;
@@ -81,6 +82,16 @@ void resume_child(pid_t pid, bool traced) {
     }
     kill(pid, SIGCONT);
 }
+#else
+// macOS / BSD: no Linux PTRACE_O_TRACEEXEC. Pause with SIGSTOP only.
+bool stop_child_at_exec(pid_t /*pid*/) {
+    return false;
+}
+
+void resume_child(pid_t pid, bool /*traced*/) {
+    kill(pid, SIGCONT);
+}
+#endif
 
 }  // namespace
 
@@ -133,7 +144,9 @@ ProcessResult run_binary(
         }
         argv.push_back(nullptr);
         if (pause_for_parent) {
+#if defined(__linux__)
             ptrace(PTRACE_TRACEME, 0, nullptr, nullptr);
+#endif
             raise(SIGSTOP);
         }
         execv(binary_path.c_str(), argv.data());

{compilersutra_perf-0.2.0 → compilersutra_perf-0.3.0}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "compilersutra-perf"
-version = "0.2.0"
+version = "0.3.0"
 description = "Alpha CLI for compiler and GPU performance experiments — compile, profile, diff, and export JSON/CSV results"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
@@ -48,11 +48,8 @@ classifiers = [
 dependencies = []
 
 [project.urls]
-Homepage = "https://github.com/compilersutra/CompilerSutraPerfTool"
-Documentation = "https://github.com/compilersutra/CompilerSutraPerfTool/blob/main/docs/USAGE.md"
-Repository = "https://github.com/compilersutra/CompilerSutraPerfTool"
-Issues = "https://github.com/compilersutra/CompilerSutraPerfTool/issues"
-Changelog = "https://github.com/compilersutra/CompilerSutraPerfTool/blob/main/CHANGELOG.md"
+Homepage = "https://www.compilersutra.com"
+Documentation = "https://www.compilersutra.com/docs/project/compilersutra-perf/getting-started/"
 Author = "https://www.linkedin.com/in/priya-pandey-54a5a22aa/"
 
 [project.optional-dependencies]
@@ -67,16 +64,16 @@ dev = [
   "urllib3>=2.7",
   "click>=8.3.3",
   "cryptography>=50.0.0",
-  "GitPython>=3.1.57",
+  "GitPython>=3.1.59",
   "idna>=3.15",
   "Pillow>=12.3.0",
   "Pygments>=2.20.0",
   "requests>=2.33.0",
-  "tornado>=6.5.7",
+  "tornado>=6.5.8",
 ]
 excel = ["openpyxl>=3.1"]
 visualize = ["streamlit>=1.33", "plotly>=5.20"]
-pdf = ["weasyprint>=62"]
+pdf = ["weasyprint>=70.0"]
 track = ["mlflow>=2.11"]  # reserved; not wired into the CLI
 tune = ["optuna>=3.5", "nevergrad>=1.0.5"]  # reserved; not wired into the CLI
 distributed = ["ray>=2.10", "dask>=2024.3.1"]  # reserved; not wired into the CLI
@@ -84,6 +81,25 @@ distributed = ["ray>=2.10", "dask>=2024.3.1"]  # reserved; not wired into the CL
 [project.scripts]
 csperf = "csperf.cli:main"
 
+[project.entry-points."csperf.experiments"]
+# Built-in experiments remain in csperf.experiments.registry; third-party
+# packages register additional names here (see examples/hello_csperf_plugin).
+
+[project.entry-points."csperf.backends"]
+# Executable BackendRunner factories register here (see csperf.execution.runners).
+
+[project.entry-points."csperf.report_exporters"]
+# Optional out-of-tree report exporters.
+
+[project.entry-points."csperf.gpu_profilers"]
+# Optional GPU profiler plugins.
+
+[project.entry-points."csperf.visualizers"]
+# Optional visualizer / dashboard plugins.
+
+[project.entry-points."csperf.toolchains"]
+system = "csperf.plugins.toolchains:SystemToolchainProvider"
+
 [tool.setuptools]
 package-dir = {"" = "src"}
 
@@ -92,6 +108,10 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+markers = [
+    "hardware: requires perf and a supported CPU PMU (skipped on hosts without perf)",
+    "slow: takes more than a few seconds to run",
+]
 
 [tool.ruff]
 line-length = 100

{compilersutra_perf-0.2.0 → compilersutra_perf-0.3.0}/setup.py

@@ -19,8 +19,8 @@ from pathlib import Path
 from shutil import copy2, copytree
 
 from setuptools import setup
-from setuptools.command.build_py import build_py as _build_py
 from setuptools.command.bdist_wheel import bdist_wheel as _bdist_wheel
+from setuptools.command.build_py import build_py as _build_py
 
 BUILD_TOOL = "cmake"
 RUNNER_TARGETS = (
@@ -73,10 +73,18 @@ class build_py(_build_py):
             raise RuntimeError("CSPERF_BUNDLE_NATIVE=1 requires cmake on PATH")
         build_dir = Path(os.environ.get("CSPERF_NATIVE_BUILD_DIR", "build-native-wheel"))
         build_dir.mkdir(parents=True, exist_ok=True)
-        subprocess.run(
-            [BUILD_TOOL, "-S", str(project_root), "-B", str(build_dir)],
-            check=True,
-        )
+        # Keep wheel binaries baseline x86-64 so auditwheel/manylinux can repair
+        # them (GH runners often default to x86_64_v3 otherwise).
+        cmake_cmd = [BUILD_TOOL, "-S", str(project_root), "-B", str(build_dir)]
+        machine = platform.machine().lower()
+        if machine in {"x86_64", "amd64"}:
+            cmake_cmd.extend(
+                [
+                    "-DCMAKE_C_FLAGS=-march=x86-64 -mtune=generic",
+                    "-DCMAKE_CXX_FLAGS=-march=x86-64 -mtune=generic",
+                ]
+            )
+        subprocess.run(cmake_cmd, check=True)
         for target in RUNNER_TARGETS:
             binary = build_dir / "bin" / target
             if target == "csperf_opencl_runner" and not _runner_built(build_dir, target):

{compilersutra_perf-0.2.0 → compilersutra_perf-0.3.0}/src/compilersutra_perf.egg-info/PKG-INFO

@@ -1,14 +1,11 @@
 Metadata-Version: 2.4
 Name: compilersutra-perf
-Version: 0.2.0
+Version: 0.3.0
 Summary: Alpha CLI for compiler and GPU performance experiments — compile, profile, diff, and export JSON/CSV results
 Author-email: Priya Pandey <osc@compilersutra.com>, CompilerSutra <osc@compilersutra.com>
 License-Expression: Apache-2.0
-Project-URL: Homepage, https://github.com/compilersutra/CompilerSutraPerfTool
-Project-URL: Documentation, https://github.com/compilersutra/CompilerSutraPerfTool/blob/main/docs/USAGE.md
-Project-URL: Repository, https://github.com/compilersutra/CompilerSutraPerfTool
-Project-URL: Issues, https://github.com/compilersutra/CompilerSutraPerfTool/issues
-Project-URL: Changelog, https://github.com/compilersutra/CompilerSutraPerfTool/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://www.compilersutra.com
+Project-URL: Documentation, https://www.compilersutra.com/docs/project/compilersutra-perf/getting-started/
 Project-URL: Author, https://www.linkedin.com/in/priya-pandey-54a5a22aa/
 Keywords: benchmarking,compiler,gpu,hip,llvm,opencl,performance,profiling,systems,vulkan
 Classifier: Development Status :: 3 - Alpha
@@ -39,19 +36,19 @@ Requires-Dist: pip-audit>=2.7; extra == "dev"
 Requires-Dist: urllib3>=2.7; extra == "dev"
 Requires-Dist: click>=8.3.3; extra == "dev"
 Requires-Dist: cryptography>=50.0.0; extra == "dev"
-Requires-Dist: GitPython>=3.1.57; extra == "dev"
+Requires-Dist: GitPython>=3.1.59; extra == "dev"
 Requires-Dist: idna>=3.15; extra == "dev"
 Requires-Dist: Pillow>=12.3.0; extra == "dev"
 Requires-Dist: Pygments>=2.20.0; extra == "dev"
 Requires-Dist: requests>=2.33.0; extra == "dev"
-Requires-Dist: tornado>=6.5.7; extra == "dev"
+Requires-Dist: tornado>=6.5.8; extra == "dev"
 Provides-Extra: excel
 Requires-Dist: openpyxl>=3.1; extra == "excel"
 Provides-Extra: visualize
 Requires-Dist: streamlit>=1.33; extra == "visualize"
 Requires-Dist: plotly>=5.20; extra == "visualize"
 Provides-Extra: pdf
-Requires-Dist: weasyprint>=62; extra == "pdf"
+Requires-Dist: weasyprint>=70.0; extra == "pdf"
 Provides-Extra: track
 Requires-Dist: mlflow>=2.11; extra == "track"
 Provides-Extra: tune
@@ -74,6 +71,8 @@ Compile, run, profile, compare, and export structured JSON/CSV/XLSX artifacts
 
 **Status:** Alpha MVP (0.2.0). Suitable for local experimentation; not yet validated for production CI regression gates. See [limitations](#limitations) and [docs/METHODOLOGY.md](docs/METHODOLOGY.md).
 
+**Research goal:** a unified CPU/GPU hardware & compiler observatory layer — orchestrate existing toolchains, normalize results, and keep static vs measured evidence honest. See [docs/OBSERVATORY.md](docs/OBSERVATORY.md).
+
 ---
 
 ## Install
@@ -93,7 +92,7 @@ pip install 'compilersutra-perf[dev]'         # pytest
 
 **Requirements:** Python 3.11+. Linux wheels ship prebuilt native runners for CPU (and Vulkan, where available), so CPU workloads run out of the box. Other platforms (or exotic Python builds) fall back to building the runner on demand, which needs a C/C++ toolchain and `cmake` on `PATH`; `perf` is also recommended for full CPU profiling on Linux. GPU backends need their respective runtimes (ROCm, OpenCL, Vulkan) installed separately.
 
-**Platform wheels and old distributions:** wheels are tagged for the glibc they were built on (e.g. `linux_x86_64`), so a wheel built on Ubuntu 24.04 may fail to load its bundled runner on Ubuntu 22.04 or older (newer glibc). The loader probes the bundled runner at startup and automatically falls back to an on-demand local build, so only an older toolchain is needed there. Hardware counter events are probed per-CPU, so vendor-specific events never break collection on other vendors (Intel vs AMD).
+**Platform wheels and old distributions:** release wheels use a `manylinux` tag (e.g. `manylinux_2_39_x86_64`) for the glibc they were built on, so a wheel built on Ubuntu 24.04 may fail to load its bundled runner on Ubuntu 22.04 or older (newer glibc). The loader probes the bundled runner at startup and automatically falls back to an on-demand local build, so only an older toolchain is needed there. Hardware counter events are probed per-CPU, so vendor-specific events never break collection on other vendors (Intel vs AMD).
 
 **Native Windows:** not yet supported. The runner uses POSIX APIs (`fork`, `sched_setaffinity`) and won't build on Windows natively — use [WSL2](docs/WINDOWS_WSL2.md). Result artifacts (JSON/CSV/XLSX/HTML reports) open fine on Windows.
 
@@ -101,17 +100,16 @@ Check that every system tool csperf needs is present, and install whatever is mi
 
 ```bash
 csperf quickstart --output-dir results/quickstart   # doctor + example + report
-csperf doctor              # report missing tools
+csperf doctor              # report missing tools; exit 1 if a required tool is missing
 csperf doctor --install    # install missing required tools (apt/dnf/pacman/apk/brew)
 csperf doctor --install --all   # also install optional GPU/profiling tools
 ```
 
 See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for perf, energy, and GPU fixes.
 
-Develop from source:
+Develop from source (private checkout if you have access):
 
 ```bash
-git clone https://github.com/compilersutra/CompilerSutraPerfTool.git
 cd CompilerSutraPerfTool
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e '.[dev]'
@@ -155,7 +153,7 @@ Each `run` writes `results/<name>.json`, `.csv`, and `.xlsx` (when `openpyxl` is
 | **CPU** | Execute + profile | Native C++ runner, LLVM IR (clang), Linux `perf` counters, warmup/repeat, optional `--cpu-affinity` |
 | **HIP** | Execute + profile | `hipcc` compile-and-run, ROCm devices, `rocprofv3` (then v2/v1) |
 | **OpenCL** | Execute | Native kernel launch, device selection, warmup/repeat |
-| **Vulkan** | Compile + validate | GLSL → SPIR-V, shader-module validation |
+| **Vulkan** | Execute via csrun / validate | Prefer CompilerSutraRun YAML execute (`CSRUN_BIN`); else GLSL → SPIR-V + module validation |
 | **`gpu` alias** | Auto-route | `.hip` → HIP, `.cl` → OpenCL, shaders → Vulkan |
 | **CUDA / Metal** | Planned | Listed in registry but not executable |
 | **macOS CPU** | Experimental | Execution works; profiling uses `powermetrics` (needs passwordless `sudo`) |
@@ -303,11 +301,11 @@ Read these before trusting numbers in papers or CI:
 - **Alpha** — methodology and backend coverage are still evolving.
 - CPU runs support `--execution-timeout` to bound workload execution.
 - CPU runs support repeated `--program-arg` values and `--stdin-file`; manifests can define the same settings.
-- **`--experiment` / `--opt-config`** — apply compile macros and optional extra flags; plugin entry points remain [#24](https://github.com/compilersutra/CompilerSutraPerfTool/issues/24) / 0.3.0.
+- **`--experiment` / `--opt-config`** — apply compile macros and optional extra flags; plugin entry points remain planned for 0.3.0.
 - Optional extras `track`, `tune`, and `distributed` are reserved for later releases and are not wired into the CLI.
-- **OpenCL** — program may recompile each trial; interpret kernel times carefully ([#38](https://github.com/compilersutra/CompilerSutraPerfTool/issues/38)).
+- **OpenCL** — program may recompile each trial; interpret kernel times carefully.
 - **CUDA / Metal** — not implemented despite registry entries.
-- **Native runners** — PyPI wheel does not bundle C++ binaries; build from source or install runners separately for full execution.
+- **Native runners** — Linux wheels bundle prebuilt native runners; other platforms build on demand from the bundled sources (needs a C/C++ toolchain and `cmake`).
 
 Best supported today: **Linux CPU** compile/run/profile with `perf` configured, plus HIP/OpenCL exploration with manual interpretation.
 
@@ -315,7 +313,11 @@ Best supported today: **Linux CPU** compile/run/profile with `perf` configured,
 
 ## Documentation
 
-Full guides live in the repository:
+Public getting started guide:
+
+https://www.compilersutra.com/docs/project/compilersutra-perf/getting-started/
+
+In-tree guides (source checkout):
 
 | Doc | Topic |
 | --- | --- |
@@ -329,8 +331,6 @@ Full guides live in the repository:
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Contributions |
 | [CHANGELOG.md](CHANGELOG.md) | Release notes |
 
-Repository: https://github.com/compilersutra/CompilerSutraPerfTool
-
 ---
 
 ## License

{compilersutra_perf-0.2.0 → compilersutra_perf-0.3.0}/src/compilersutra_perf.egg-info/SOURCES.txt

@@ -77,8 +77,11 @@ src/csperf/models.py
 src/csperf/optimize_diff.py
 src/csperf/perf_env.py
 src/csperf/profile_summary.py
+src/csperf/provenance.py
 src/csperf/quickstart.py
 src/csperf/results.py
+src/csperf/runner_meta.py
+src/csperf/schema_export.py
 src/csperf/toolutils.py
 src/csperf/visualize.py
 src/csperf/backends/__init__.py
@@ -106,20 +109,30 @@ src/csperf/execution/cpu.py
 src/csperf/execution/gpu.py
 src/csperf/execution/hip.py
 src/csperf/execution/opencl.py
+src/csperf/execution/qemu_user.py
+src/csperf/execution/runners.py
 src/csperf/execution/utils.py
 src/csperf/execution/vulkan.py
 src/csperf/experiments/__init__.py
 src/csperf/experiments/apply.py
 src/csperf/experiments/registry.py
+src/csperf/integration/__init__.py
+src/csperf/integration/csrun.py
 src/csperf/lit/__init__.py
 src/csperf/lit/runner.py
 src/csperf/pipelines/__init__.py
 src/csperf/pipelines/base.py
 src/csperf/pipelines/factory.py
+src/csperf/plugins/__init__.py
+src/csperf/plugins/contracts.py
+src/csperf/plugins/loader.py
+src/csperf/plugins/toolchains.py
+src/csperf/plugins/visualizers.py
 src/csperf/power/__init__.py
 src/csperf/power/collect.py
 src/csperf/profiler/__init__.py
 src/csperf/profiler/base.py
+src/csperf/profiler/gpu.py
 src/csperf/profiler/cpu/__init__.py
 src/csperf/profiler/cpu/affinity.py
 src/csperf/profiler/cpu/base.py
@@ -159,6 +172,7 @@ src/csperf/report/template.py
 src/csperf/report/exporters/__init__.py
 src/csperf/report/exporters/html.py
 src/csperf/report/exporters/pdf.py
+tests/test_backend_runners.py
 tests/test_bundled_runners.py
 tests/test_cli_functional.py
 tests/test_cli_helpers.py
@@ -167,9 +181,13 @@ tests/test_cli_smoke.py
 tests/test_collector_registry.py
 tests/test_compile_flags.py
 tests/test_cpu_affinity_collect.py
+tests/test_cpu_arena.py
 tests/test_cpu_measurement.py
+tests/test_cross_platform_matrix.py
+tests/test_csrun_integration.py
 tests/test_detector.py
 tests/test_diff_profiler_warnings.py
+tests/test_diff_significance.py
 tests/test_doctor.py
 tests/test_energy_framework.py
 tests/test_experiments_apply.py
@@ -177,6 +195,8 @@ tests/test_hip_mocked.py
 tests/test_issue51_validation.py
 tests/test_lit_runner.py
 tests/test_macos_collector.py
+tests/test_measurement_validity.py
+tests/test_milestone3_gaps.py
 tests/test_milestone_reliability.py
 tests/test_opencl_inference.py
 tests/test_opencl_measure.py
@@ -188,15 +208,19 @@ tests/test_papi_support.py
 tests/test_perf_env.py
 tests/test_perf_events.py
 tests/test_perf_fallback.py
+tests/test_plugins_loader.py
 tests/test_power_collect.py
 tests/test_process_timeout.py
 tests/test_profile_summary_security.py
+tests/test_provenance.py
+tests/test_qemu_user_riscv.py
 tests/test_quickstart.py
 tests/test_registry.py
 tests/test_report_components.py
 tests/test_report_export.py
 tests/test_report_reproduction.py
 tests/test_results_csv.py
+tests/test_runner_meta.py
 tests/test_toolutils.py
 tests/test_visualize.py
 tests/test_vulkaninfo_parse.py

compilersutra_perf-0.3.0/src/compilersutra_perf.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+csperf = csperf.cli:main
+
+[csperf.toolchains]
+system = csperf.plugins.toolchains:SystemToolchainProvider

{compilersutra_perf-0.2.0 → compilersutra_perf-0.3.0}/src/compilersutra_perf.egg-info/requires.txt

@@ -10,12 +10,12 @@ pip-audit>=2.7
 urllib3>=2.7
 click>=8.3.3
 cryptography>=50.0.0
-GitPython>=3.1.57
+GitPython>=3.1.59
 idna>=3.15
 Pillow>=12.3.0
 Pygments>=2.20.0
 requests>=2.33.0
-tornado>=6.5.7
+tornado>=6.5.8
 
 [distributed]
 ray>=2.10
@@ -25,7 +25,7 @@ dask>=2024.3.1
 openpyxl>=3.1
 
 [pdf]
-weasyprint>=62
+weasyprint>=70.0
 
 [track]
 mlflow>=2.11

{compilersutra_perf-0.2.0 → compilersutra_perf-0.3.0}/src/csperf/__init__.py

@@ -13,7 +13,13 @@ __all__ = ["__version__"]
 
 
 def _project_version() -> str:
-    """Read the canonical version from installed metadata or pyproject.toml."""
+    """Read the canonical version from pyproject.toml.
+
+    Installed metadata can lag behind the source tree (e.g. an editable
+    install from an older release), so pyproject.toml is the single source
+    of truth. Only fall back to installed metadata when pyproject.toml is
+    unavailable (e.g. a wheel installed without the source tree).
+    """
 
     project_file = Path(__file__).resolve().parents[2] / "pyproject.toml"
     try: