From 5b901d4d5c9c97b49a5cfe4d0ce27b84dc233ddf Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Mon, 25 May 2026 17:13:07 +0000
Subject: [PATCH] docs: clarify FetchContent runtime rpath requirements

Agent-Logs-Url: https://github.com/Z3Prover/z3/sessions/c364dcd3-231e-42bf-b928-60673cd045c0

Co-authored-by: NikolajBjorner <3085284+NikolajBjorner@users.noreply.github.com>
---
 README-CMake.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README-CMake.md b/README-CMake.md
index c9edb9378..873631fd7 100644
--- a/README-CMake.md
+++ b/README-CMake.md
@@ -120,10 +120,32 @@ Once fetched, you can link the z3 library to your target:
 target_link_libraries(yourTarget PRIVATE libz3)
 ```
 
+If `yourTarget` is an executable or test that runs directly from the build tree,
+you may also need to add the directory containing the fetched `libz3` shared
+library to that target's build-time runtime search path. This is especially
+important on macOS, where `libz3` uses an `@rpath` install name:
+
+```cmake
+target_link_libraries(yourTarget PRIVATE libz3)
+
+if(TARGET libz3)
+    set_property(TARGET yourTarget APPEND PROPERTY
+        BUILD_RPATH "$<TARGET_FILE_DIR:libz3>"
+    )
+endif()
+```
+
+If Z3 is pulled in by an intermediate library, set the `BUILD_RPATH` on the
+final executable, test, or other runtime target that loads `libz3`, not just on
+the intermediate library. If you install your binaries, also set
+`INSTALL_RPATH` to match your installation layout.
+
 **Important notes for FetchContent approach**:
 - The target name is `libz3` (referring to the library target from `src/CMakeLists.txt`)
 - An additional include directory for `src/api/c++` is added to enable `#include "z3++.h"` in C++ code
 - Without the additional include directory, you would need `#include "c++/z3++.h"` instead
+- For build-tree execution, you may need to add `"$<TARGET_FILE_DIR:libz3>"` to the
+  consuming executable's `BUILD_RPATH`
 
 **Recommended: Create an alias for consistency with system installs**:
 
@@ -219,6 +241,8 @@ target_link_libraries(yourTarget PRIVATE z3::libz3)
 - Use `z3::libz3` target instead of raw library names for better CMake integration
 - The target automatically provides the correct include directories, so no need for manual `target_include_directories`
 - When using FetchContent, an alias is created to ensure target name consistency
+- If the FetchContent path is used and your executable runs from the build tree, you may need
+  to add `"$<TARGET_FILE_DIR:libz3>"` to that executable's `BUILD_RPATH`
 - Set `QUIET` in `find_package` to avoid error messages when Z3 isn't found