Add a BUILD_RPATH target property specifying build-tree RPATH entries

Users may need to add custom `RPATH` entries to be able to run binaries
from their build tree without setting `LD_LIBRARY_PATH`.  Provide a way
to do this that does not affect the install-tree `RPATH`.

Help/manual/cmake-properties.7.rst

@@ -121,6 +121,7 @@ Properties on Targets
    /prop_tgt/AUTORCC
    /prop_tgt/AUTORCC_OPTIONS
    /prop_tgt/BINARY_DIR
+   /prop_tgt/BUILD_RPATH
    /prop_tgt/BUILD_WITH_INSTALL_RPATH
    /prop_tgt/BUNDLE_EXTENSION
    /prop_tgt/BUNDLE

Help/manual/cmake-variables.7.rst

@@ -257,6 +257,7 @@ Variables that Control the Build
    /variable/CMAKE_AUTORCC_OPTIONS
    /variable/CMAKE_AUTOUIC
    /variable/CMAKE_AUTOUIC_OPTIONS
+   /variable/CMAKE_BUILD_RPATH
    /variable/CMAKE_BUILD_WITH_INSTALL_RPATH
    /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
    /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG

Help/prop_tgt/BUILD_RPATH.rst

@@ -0,0 +1,10 @@
+BUILD_RPATH
+-----------
+
+A :ref:`;-list <CMake Language Lists>` specifying runtime path (``RPATH``)
+entries to add to binaries linked in the build tree (for platforms that
+support it).  The entries will *not* be used for binaries in the install
+tree.  See also the :prop_tgt:`INSTALL_RPATH` target property.
+
+This property is initialized by the value of the variable
+:variable:`CMAKE_BUILD_RPATH` if it is set when a target is created.

Help/release/dev/add-BUILD_RPATH.rst

@@ -0,0 +1,6 @@
+add-BUILD_RPATH
+---------------
+
+* A :variable:`CMAKE_BUILD_RPATH` variable and corresponding
+  :prop_tgt:`BUILD_RPATH` target property were added to support custom
+  ``RPATH`` locations to be added to binaries in the build tree.

Help/variable/CMAKE_BUILD_RPATH.rst

@@ -0,0 +1,10 @@
+CMAKE_BUILD_RPATH
+-----------------
+
+A :ref:`;-list <CMake Language Lists>` specifying runtime path (``RPATH``)
+entries to add to binaries linked in the build tree (for platforms that
+support it).  The entries will *not* be used for binaries in the install
+tree.  See also the :variable:`CMAKE_INSTALL_RPATH` variable.
+
+This is used to initialize the :prop_tgt:`BUILD_RPATH` target property
+for all targets.

Source/cmComputeLinkInformation.cxx

@@ -1710,6 +1710,12 @@ void cmComputeLinkInformation::GetRPath(std::vector<std::string>& runtimeDirs,
     const char* install_rpath = this->Target->GetProperty("INSTALL_RPATH");
     cmCLI_ExpandListUnique(install_rpath, runtimeDirs, emitted);
   }
+  if (use_build_rpath) {
+    // Add directories explicitly specified by user
+    if (const char* build_rpath = this->Target->GetProperty("BUILD_RPATH")) {
+      cmCLI_ExpandListUnique(build_rpath, runtimeDirs, emitted);
+    }
+  }
   if (use_build_rpath || use_link_rpath) {
     std::string rootPath = this->Makefile->GetSafeDefinition("CMAKE_SYSROOT");
     const char* stagePath =

Source/cmGeneratorTarget.cxx

@@ -4965,6 +4965,9 @@ bool cmGeneratorTarget::HaveBuildTreeRPATH(const std::string& config) const
   if (this->GetPropertyAsBool("SKIP_BUILD_RPATH")) {
     return false;
   }
+  if (this->GetProperty("BUILD_RPATH")) {
+    return true;
+  }
   if (cmLinkImplementationLibraries const* impl =
         this->GetLinkImplementationLibraries(config)) {
     return !impl->Libraries.empty();

Source/cmTarget.cxx

@@ -102,6 +102,7 @@ cmTarget::cmTarget(std::string const& name, cmState::TargetType type,
     this->SetPropertyDefault("ANDROID_JAR_DEPENDENCIES", CM_NULLPTR);
     this->SetPropertyDefault("ANDROID_ASSETS_DIRECTORIES", CM_NULLPTR);
     this->SetPropertyDefault("ANDROID_ANT_ADDITIONAL_OPTIONS", CM_NULLPTR);
+    this->SetPropertyDefault("BUILD_RPATH", CM_NULLPTR);
     this->SetPropertyDefault("INSTALL_NAME_DIR", CM_NULLPTR);
     this->SetPropertyDefault("INSTALL_RPATH", "");
     this->SetPropertyDefault("INSTALL_RPATH_USE_LINK_PATH", "OFF");

Tests/MacRuntimePath/A/CMakeLists.txt

@@ -40,21 +40,30 @@ target_link_libraries(test3 framework)
 add_executable(test4 test1.cpp)
 target_link_libraries(test4 shared2)
 
+# executable to test a shared library dependency with build rpath
+add_executable(test5 test1.cpp)
+
+# avoid linking by 'target_link_libraries' so CMake
+# will not be able to set correct RPATH automatically
+add_dependencies(test5 shared)
+target_link_libraries(test5 "$<TARGET_FILE:shared>")
+set_target_properties(test5 PROPERTIES BUILD_RPATH "@loader_path/../lib")
+
 set_target_properties(shared shared2 framework PROPERTIES
   LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/lib")
-set_target_properties(test1 test2 test3 test4 PROPERTIES
+set_target_properties(test1 test2 test3 test4 test5 PROPERTIES
   RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/bin")
 foreach(config ${CMAKE_CONFIGURATION_TYPES})
   string(TOUPPER ${config} CONFIG)
   set_target_properties(shared shared2 framework PROPERTIES
     LIBRARY_OUTPUT_DIRECTORY_${CONFIG}
       "${CMAKE_CURRENT_BINARY_DIR}/${config}/lib")
-  set_target_properties(test1 test2 test3 test4 PROPERTIES
+  set_target_properties(test1 test2 test3 test4 test5 PROPERTIES
     RUNTIME_OUTPUT_DIRECTORY_${CONFIG}
       "${CMAKE_CURRENT_BINARY_DIR}/${config}/bin")
 endforeach()
 
-foreach(test test1 test2 test3 test4)
+foreach(test test1 test2 test3 test4 test5)
   add_custom_target(${test}_run  ALL
     COMMAND ${test}
     DEPENDS ${test}