diff options
author | Ivan Komissarov <abbapoh@gmail.com> | 2020-04-13 17:02:14 +0200 |
---|---|---|
committer | Ivan Komissarov <ABBAPOH@gmail.com> | 2020-07-15 07:25:22 +0000 |
commit | 64a7ee68516e4edfb8c1eda382396b311ec412af (patch) | |
tree | 16d086954396b77880dd7bdb76fc4f5fd111f2b9 /doc | |
parent | 996bc307f34749d31c566da9d2546cc6375f2924 (diff) | |
download | qbs-64a7ee68516e4edfb8c1eda382396b311ec412af.tar.gz |
doc: Add How-To about cpp.rpaths
Task-number: QBS-1204
Change-Id: I2d04ccb0cbcd7c1a6b5a5f251e70d34b3a960da7
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/howtos.qdoc | 37 | ||||
-rw-r--r-- | doc/reference/modules/cpp-module.qdoc | 4 |
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?} */ /*! |