Summary
build.py's default output layout moved out-of-tree in #276 (6f77c6da, "ci(build): from-source dependency resolution + cross-platform build.py"), but a lot of docs/config/test code still assumes the old in-repo install/ layout. The two no longer agree, so paths copied from CLAUDE.md / READMEs / test fallbacks point at directories that build.py never creates.
What changed in #276
Before:
INSTALL = ROOT / "install" # in-repo: <repo>/install/{dist,therock,...}
After:
REPO = Path(__file__).resolve().parent
WORKSPACE = REPO.parent
--build_dir default = WORKSPACE/"build"/<repo> # ../build/<repo>/ (+ _therock, _deps)
--install_dir default = WORKSPACE/"install" # ../install/ (siblings of the repo)
And TheRock auto-download lands under the build tree: cmake/deps.cmake → _therock_root = ${CMAKE_BINARY_DIR}/_therock = ../build/<repo>/_therock, never <repo>/install/therock.
#276 updated docs/quick_start.md / docs/quick_start_linux.md, but did not sweep the rest of the tree.
Stale in-repo install/... references that no longer match a default build
- CLAUDE.md — the "Output layout" list (
install/therock/, install/dist/), and multiple gotchas hardcode install/therock/bin / install/dist/bin on PATH (e.g. the TheRock-DLLs-on-PATH gotcha, the model_benchmark.exe env-var example, the "both bin dirs on PATH" note, the HIPDNN_EP_PERF example).
- test/numeric/README.md —
export THEROCK_DIST=$PWD/install/therock, --ep-dll ../../install/dist/bin/....
- test/python/conftest.py —
_ep_runtime_dirs() fallbacks are <repo>/install/dist/bin and <repo>/install/therock/bin. With the new default build these dirs don't exist, so the env-var overrides (MORPHIZEN_EP_BIN, THEROCK_DIST) are effectively mandatory, not optional — the legacy fallback is dead.
- test/python/whisper/whisper_infer.py — error string points users at
install/dist/bin/onnxruntime_morphizen_ep.dll.
- scripts/transcribe_whisper.py — docstring references
install/dist/bin/....
(The Whisper quick-start docs/whisper_quick_start.md was already migrated to a single $ROOT layout + MORPHIZEN_EP_BIN in #283/#266, so it's consistent — this issue is about the rest of the repo.)
Why it's confusing / what breaks
A new user runs the default python build.py (artifacts go to ../build/<repo>/ + ../install/), then follows a CLAUDE.md gotcha that says "add install/therock/bin to PATH" or sets THEROCK_DIST=install/therock — those paths don't exist, so the EP silently falls back to CPU (or tests skip / segfault). The in-tree numeric README env setup is likewise broken against a default build.
Proposed fix (maintainer decision)
Pick one canonical story and make everything reference it:
- Sweep CLAUDE.md,
test/numeric/README.md, whisper_infer.py, transcribe_whisper.py to the out-of-tree layout (../build/<repo>/_therock, ../install or a $ROOT convention), matching docs/quick_start.md.
- Decide whether
conftest._ep_runtime_dirs() should keep the dead in-repo fallback, point the fallback at the new default (WORKSPACE/build/<repo>/_therock, WORKSPACE/install/...), or just require the env vars.
- Consider a single documented convention (the
$ROOT pattern the Whisper guide uses) so build/run/test paths are derived from one variable instead of hardcoded install/... strings scattered across docs.
Origin: noticed while reconciling conftest._ep_runtime_dirs() against the current build during the Whisper work (#283 / #266).
Summary
build.py's default output layout moved out-of-tree in #276 (6f77c6da, "ci(build): from-source dependency resolution + cross-platform build.py"), but a lot of docs/config/test code still assumes the old in-repoinstall/layout. The two no longer agree, so paths copied from CLAUDE.md / READMEs / test fallbacks point at directories thatbuild.pynever creates.What changed in #276
Before:
After:
And TheRock auto-download lands under the build tree:
cmake/deps.cmake→_therock_root = ${CMAKE_BINARY_DIR}/_therock=../build/<repo>/_therock, never<repo>/install/therock.#276 updated
docs/quick_start.md/docs/quick_start_linux.md, but did not sweep the rest of the tree.Stale in-repo
install/...references that no longer match a default buildinstall/therock/,install/dist/), and multiple gotchas hardcodeinstall/therock/bin/install/dist/binon PATH (e.g. the TheRock-DLLs-on-PATH gotcha, themodel_benchmark.exeenv-var example, the "both bin dirs on PATH" note, theHIPDNN_EP_PERFexample).export THEROCK_DIST=$PWD/install/therock,--ep-dll ../../install/dist/bin/...._ep_runtime_dirs()fallbacks are<repo>/install/dist/binand<repo>/install/therock/bin. With the new default build these dirs don't exist, so the env-var overrides (MORPHIZEN_EP_BIN,THEROCK_DIST) are effectively mandatory, not optional — the legacy fallback is dead.install/dist/bin/onnxruntime_morphizen_ep.dll.install/dist/bin/....(The Whisper quick-start
docs/whisper_quick_start.mdwas already migrated to a single$ROOTlayout +MORPHIZEN_EP_BINin #283/#266, so it's consistent — this issue is about the rest of the repo.)Why it's confusing / what breaks
A new user runs the default
python build.py(artifacts go to../build/<repo>/+../install/), then follows a CLAUDE.md gotcha that says "addinstall/therock/binto PATH" or setsTHEROCK_DIST=install/therock— those paths don't exist, so the EP silently falls back to CPU (or tests skip / segfault). The in-tree numeric README env setup is likewise broken against a default build.Proposed fix (maintainer decision)
Pick one canonical story and make everything reference it:
test/numeric/README.md,whisper_infer.py,transcribe_whisper.pyto the out-of-tree layout (../build/<repo>/_therock,../installor a$ROOTconvention), matchingdocs/quick_start.md.conftest._ep_runtime_dirs()should keep the dead in-repo fallback, point the fallback at the new default (WORKSPACE/build/<repo>/_therock,WORKSPACE/install/...), or just require the env vars.$ROOTpattern the Whisper guide uses) so build/run/test paths are derived from one variable instead of hardcodedinstall/...strings scattered across docs.Origin: noticed while reconciling
conftest._ep_runtime_dirs()against the current build during the Whisper work (#283 / #266).