doc: Add How-To about cpp.rpaths

Task-number: QBS-1204
Change-Id: I2d04ccb0cbcd7c1a6b5a5f251e70d34b3a960da7
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

2 files changed, 41 insertions, 0 deletions

diff --git a/doc/howtos.qdoc b/doc/howtos.qdoc
index 696c444cb..7e01624a0 100644
--- a/doc/howtos.qdoc
+++ b/doc/howtos.qdoc
@@ -40,6 +40,7 @@
     \li \l{How do I build release with debug information?}
     \li \l{How do I separate and install debugging symbols?}
     \li \l{How do I use precompiled headers?}
+    \li \l{How do I make use of rpaths?}
     \li \l{How do I make sure my generated sources are getting compiled?}
     \li \l{How do I run my autotests?}
     \li \l{How do I use ccache?}
@@ -237,6 +238,42 @@
     }
     \endcode
 
+    \section1 How do I make use of rpaths?
+
+    rpath designates the run-time search path used by the dynamic linker when loading
+    libraries on UNIX platforms. This concept does not apply to Windows.
+
+    Suppose you have a project with two dynamic library products \c LibraryA and \c LibraryB
+    and one dependent application product. Also, \c LibraryB depends on \c LibraryA. The
+    application is installed to the \c bin folder and the libraries are installed to the
+    \c lib folder next to the \c bin folder. You want the application to be able to find the
+    dependent libraries relative to its own location. This can be achieved by usage of the
+    \l{cpp::rpaths}{cpp.rpaths} property.
+
+    First, you need to set \l{cpp::rpaths}{cpp.rpaths} in your libraries so they can
+    find dependent libraries in the same folder where they are located. This can be
+    done as follows:
+
+    \snippet ../examples/rpaths/rpaths.qbs 0
+
+    We are setting \l{cpp::rpaths}{cpp.rpaths} to \l{cpp::rpathOrigin}{cpp.rpathOrigin} which
+    expands to \c "$ORIGIN" on Linux and to \c "@loader_path" on macOS.
+
+    On macOS you also need to set \l{cpp::sonamePrefix}{cpp.sonamePrefix} to \c "@rpath" to
+    tell the dynamic linker to use RPATHs when loading this library.
+
+    \c LibraryB looks exactly the same:
+
+    \snippet ../examples/rpaths/rpaths.qbs 1
+
+    In a real project, it might be a good idea to move common properties to some base item
+    and inherit it in library items.
+
+    The application item is a bit different. It sets \l{cpp::rpaths}{cpp.rpaths} to the
+    \c "lib" folder which is located one level up from the \c bin folder:
+
+    \snippet ../examples/rpaths/rpaths.qbs 2
+
     \section1 How do I make sure my generated sources are getting compiled?
 
     The rules in a \QBS project do not care whether its inputs are actual source files
diff --git a/doc/reference/modules/cpp-module.qdoc b/doc/reference/modules/cpp-module.qdoc
index 3c1744e09..f5f43f0f9 100644
--- a/doc/reference/modules/cpp-module.qdoc
+++ b/doc/reference/modules/cpp-module.qdoc
@@ -1370,6 +1370,8 @@
     \l{cpp::}{systemRunPaths} are ignored.
 
     \nodefaultvalue
+
+    \sa{How do I make use of rpaths?}
 */
 
 /*!
@@ -1406,6 +1408,8 @@
     install names.
 
     \nodefaultvalue
+
+    \sa{How do I make use of rpaths?}
 */
 
 /*!