doc: Add How-To about cpp.rpaths

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

7 files changed, 288 insertions, 0 deletions

diff --git a/examples/examples.qbs b/examples/examples.qbs
index 2b1c0933b..18205d67a 100644
--- a/examples/examples.qbs
+++ b/examples/examples.qbs
@@ -68,5 +68,6 @@ Project {
         // "protobuf/addressbook_objc/addressbook_objc.qbs",
         "baremetal/baremetal.qbs",
         "rule/rule.qbs",
+        "rpaths/rpaths.qbs",
     ]
 }
diff --git a/examples/rpaths/main.cpp b/examples/rpaths/main.cpp
new file mode 100644
index 000000000..aaaebfbf6
--- /dev/null
+++ b/examples/rpaths/main.cpp
@@ -0,0 +1,45 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 Ivan Komissarov (abbapoh@gmail.com)
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qbs.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "objecta.h"
+#include "objectb.h"
+
+#include <iostream>
+
+int main(int argc, char *argv[])
+{
+    (void)argc;
+    (void)argv;
+
+    std::cout << ObjectA::className() << std::endl;
+    std::cout << ObjectB::className() << std::endl;
+
+    ObjectB b;
+    std::cout << b.getA().name() << std::endl;
+
+    return 0;
+}
diff --git a/examples/rpaths/objecta.cpp b/examples/rpaths/objecta.cpp
new file mode 100644
index 000000000..bf6266653
--- /dev/null
+++ b/examples/rpaths/objecta.cpp
@@ -0,0 +1,48 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 Ivan Komissarov (abbapoh@gmail.com)
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qbs.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "objecta.h"
+
+ObjectA::ObjectA(std::string name) :
+    m_name(std::move(name))
+{
+}
+
+std::string ObjectA::className()
+{
+    return "ObjectA";
+}
+
+const std::string &ObjectA::name() const
+{
+    return m_name;
+}
+
+void ObjectA::setName(std::string name)
+{
+    m_name = std::move(name);
+}
diff --git a/examples/rpaths/objecta.h b/examples/rpaths/objecta.h
new file mode 100644
index 000000000..69b78fbc2
--- /dev/null
+++ b/examples/rpaths/objecta.h
@@ -0,0 +1,47 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 Ivan Komissarov (abbapoh@gmail.com)
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qbs.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef OBJECTA_H
+#define OBJECTA_H
+
+#include <string>
+
+class ObjectA
+{
+public:
+    explicit ObjectA(std::string name);
+
+    static std::string className();
+
+    const std::string &name() const;
+    void setName(std::string name);
+
+private:
+    std::string m_name;
+};
+
+#endif // OBJECTA_H
diff --git a/examples/rpaths/objectb.cpp b/examples/rpaths/objectb.cpp
new file mode 100644
index 000000000..758fe09cf
--- /dev/null
+++ b/examples/rpaths/objectb.cpp
@@ -0,0 +1,41 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 Ivan Komissarov (abbapoh@gmail.com)
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qbs.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "objectb.h"
+
+ObjectB::ObjectB() = default;
+
+std::string ObjectB::className()
+{
+    return "ObjectB";
+}
+
+const ObjectA &ObjectB::getA() const
+{
+    return objectA;
+}
+
diff --git a/examples/rpaths/objectb.h b/examples/rpaths/objectb.h
new file mode 100644
index 000000000..5a63de5eb
--- /dev/null
+++ b/examples/rpaths/objectb.h
@@ -0,0 +1,48 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 Ivan Komissarov (abbapoh@gmail.com)
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qbs.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef OBJECTB_H
+#define OBJECTB_H
+
+#include <string>
+
+#include "objecta.h"
+
+class ObjectB
+{
+public:
+    ObjectB();
+
+    static std::string className();
+
+    const ObjectA &getA() const;
+
+private:
+    ObjectA objectA{"A"};
+};
+
+#endif // OBJECTB_H
diff --git a/examples/rpaths/rpaths.qbs b/examples/rpaths/rpaths.qbs
new file mode 100644
index 000000000..1e5411468
--- /dev/null
+++ b/examples/rpaths/rpaths.qbs
@@ -0,0 +1,58 @@
+import qbs.FileInfo
+
+Project {
+    condition: qbs.targetOS.contains("unix")
+
+    //! [0]
+    DynamicLibrary {
+        Depends { name: "cpp" }
+        Depends { name: "bundle" }
+        name: "LibraryA"
+        bundle.isBundle: false
+        cpp.sonamePrefix: qbs.targetOS.contains("macos") ? "@rpath" : undefined
+        cpp.rpaths: cpp.rpathOrigin
+        cpp.cxxLanguageVersion: "c++11"
+        files: [
+            "objecta.cpp",
+            "objecta.h",
+        ]
+        install: true
+        installDir: "examples/lib"
+    }
+    //! [0]
+
+    //! [1]
+    DynamicLibrary {
+        Depends { name: "cpp" }
+        Depends { name: "bundle" }
+        Depends { name: "LibraryA" }
+        name: "LibraryB"
+        bundle.isBundle: false
+        cpp.cxxLanguageVersion: "c++11"
+        cpp.sonamePrefix: qbs.targetOS.contains("macos") ? "@rpath" : undefined
+        cpp.rpaths: cpp.rpathOrigin
+        files: [
+            "objectb.cpp",
+            "objectb.h",
+        ]
+        install: true
+        installDir: "examples/lib"
+    }
+    //! [1]
+
+    //! [2]
+    CppApplication {
+        Depends { name: "bundle" }
+        Depends { name: "LibraryA" }
+        Depends { name: "LibraryB" }
+        name: "rpaths-app"
+        files: "main.cpp"
+        consoleApplication: true
+        bundle.isBundle: false
+        cpp.rpaths: FileInfo.joinPaths(cpp.rpathOrigin, "..", "lib")
+        cpp.cxxLanguageVersion: "c++11"
+        install: true
+        installDir: "examples/bin"
+    }
+    //! [2]
+}