Start with the boundary that failed.
Installation, package discovery, target admission, and execution are separate checks. Keep the first typed failure intact and fix that boundary before retrying.
Read the typed result first
if (!result) {
const std::string_view message = result.error();
std::fprintf(stderr, "runD failure (code=%u): %.*s\n",
static_cast<unsigned>(result.code()),
static_cast<int>(message.size()), message.data());
return result.exit_code();
}
This fragment expects <cstdio>, <string_view>, and
a typed runD result in scope. The complete Quick Start program includes the same logging.
| Need | Use |
|---|---|
| Branch, retry, or classify | code() or the domain's typed reason. |
| Show a person what failed | error(), a stable derived text projection. |
| Return from a process | The failing value's exit_code(). |
| Signal an application assertion | Exit 2, only after every product result succeeded. |
Do not compare or parse error() text for control flow.
Verifier failures
| Symptom | Likely cause | Fix |
|---|---|---|
| Checksum or seal mismatch | Files came from different releases or one download changed. | Delete all three files and download the archive, checksum, and verifier from the same release. |
| Destination or prefix exists | The verifier will not overwrite a versioned prefix. | Use an existing parent directory whose rund-sdk-1.0.4-darwin-arm64 child does not exist. |
| Host tuple mismatch | Architecture, compiler, standard library, Apple SDK, or deployment target differs. | Run the copyable probe in the exact Darwin 1.0.4 tuple. There is no supported bypass; use a matching host/toolchain or a newer rebuilt SDK. |
| Backend dependency mismatch | One or more sealed MoltenVK/Vulkan formula versions or resolved library identities differ. | Compare against the same tuple authority. 1.0.4 has no supported fresh binary route when it differs. |
A failed verifier publishes no usable SDK prefix. The fix is a coherent release tuple, not a manual copy of headers or libraries.
CMake and linking
find_package(runD) cannot find the SDK
cmake -S . -B build \
-DCMAKE_PREFIX_PATH="$PWD/rund-sdk-1.0.4-darwin-arm64"
Point at the verified prefix, not the archive, a source checkout, an application build
directory, or a copied include/ folder. The prefix must contain
lib/cmake/runD/runDConfig.cmake.
Header or symbol errors
- Use
find_package(runD 1.0.4 EXACT CONFIG REQUIRED). - Link the application or implementation-only library
PRIVATE runD::sdk. - Use
PUBLIC runD::sdkonly when a public header exposes runD types or templates. - Delete the application build directory after switching SDK artifacts.
add_subdirectory(runD), source-tree include paths, vendored source, and direct
subsystem targets are not supported consumption paths.
Backend and execution failures
| Failure class | What it means | Action |
|---|---|---|
| Unsupported | The requested operation or policy is outside the implementation contract. | Change the operation or policy to one documented as admitted; changing backend alone does not fix this class. |
| Unavailable | The target exists but its device or runtime cannot be opened now. | Check the host dependency and device state, then retry the same target. |
| Admission or capacity failure | A type, shape, count, graph, buffer, queue, or bounded resource contract was rejected. | Inspect the typed code and change the declared bound or workload shape. |
| Device or execution failure | The admitted path failed after selection. | Record target, graph/output evidence, SDK tuple, and the original typed code. |
runD never turns these failures into a successful CPU execution. See Platforms for the exact current tuple and API & Errors for result ownership.
Report a useful issue
Include:
- operation and selected target;
- typed code/reason and its derived error text;
- SDK version, artifact identity, architecture, compiler, and Apple SDK;
- MoltenVK/Vulkan package identity when that path is involved;
- the smallest input shape and complete reproduction.
Do not attach secret input or private protocol bytes. Open a GitHub issue only after reducing the failure to a shareable case.