docs: document manual CMake build and ctest workflow for C++ tests#19387
docs: document manual CMake build and ctest workflow for C++ tests#19387AswaniSahoo wants to merge 3 commits intopytorch:mainfrom
Conversation
🔗 Helpful Links🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/19387
Note: Links to docs will display an error until the docs builds have been completed. ❗ 1 Active SEVsThere are 1 currently active SEVs. If your PR is affected, please view them below: ❌ 11 Awaiting Approval, 1 New FailureAs of commit 2ff32a3 with merge base a49171d ( AWAITING APPROVAL - The following workflows need approval before CI can run:
NEW FAILURE - The following job has failed:
This comment was automatically generated by Dr. CI and updates every 15 minutes. |
There was a problem hiding this comment.
Pull request overview
Adds contributor documentation for a manual CMake-based workflow to build and run ExecuTorch C++ tests locally, complementing the existing test/run_oss_cpp_tests.sh helper and enabling more iterative workflows (e.g., keeping a persistent build dir, running a single test via ctest).
Changes:
- Document a manual CMake configure/build/install flow for C++ tests under
cmake-out. - Document using
ctestto list tests and run tests by regex from the build directory. - Add brief guidance on extending the configuration with additional
-DEXECUTORCH_BUILD_*options as needed.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| To build C++ tests manually with CMake, run the following from the repository root: | ||
|
|
||
| ```bash | ||
| cmake . -Bcmake-out -DCMAKE_INSTALL_PREFIX=cmake-out -DEXECUTORCH_BUILD_TESTS=ON | ||
| cmake --build cmake-out -j9 --target install | ||
| ``` | ||
|
|
||
| You can then use `ctest` to list or run individual C++ tests directly: | ||
|
|
||
| ```bash | ||
| ctest --test-dir cmake-out -N | ||
| ctest --test-dir cmake-out -R <test_name_regex> --output-on-failure | ||
| ``` |
|
@pytorchbot label "release notes: none" |
|
|
||
| ```bash | ||
| ctest --test-dir cmake-out -N | ||
| ctest --test-dir cmake-out -R <test_name_regex> --output-on-failure |
Summary
Adds documentation to the Testing section of
CONTRIBUTING.mdshowing how to build C++ tests manually with CMake and run individual tests usingctest. This covers a practical workflow that is useful for attaching a debugger, running a single test in isolation, and keeping a build directory around for quick rebuild cycles.The CMake invocation and flags are consistent with what
test/run_oss_cpp_tests.shalready uses internally.Fixes #11979
Test plan
test/run_oss_cpp_tests.shsphinx-build -b html docs/source docs/_build/html)git diff --checkpasses (no trailing whitespace)cc @GregoryComer @AlannaBurke @mergennachin