Doc: Add packaging recommendations for Linux distributions

Task-number: QTBUG-89170
Change-Id: I1ca40fec43860603e39723b99462fcff119539b3
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 5aa42c9bb6f1b37586bf15972bf2e883b6d9387f)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 73 insertions, 0 deletions

diff --git a/doc/src/platforms/linux.qdoc b/doc/src/platforms/linux.qdoc
index fccc8b2ff..730e43abf 100644
--- a/doc/src/platforms/linux.qdoc
+++ b/doc/src/platforms/linux.qdoc
@@ -375,6 +375,9 @@
     Qt for X11 has some requirements that are given in more detail
     in the \l{Qt for X11 Requirements} document.
 
+    Distribution packagers can find information how to package Qt in the
+    \l{Qt Packaging Recommendations}{packaging recommendations}.
+
     \section1 Step 1: Unpacking the Archive
         Unpack the archive if you have not done so already. For example,
         if you have the \c{qt-everywhere-opensource-src-%VERSION%.tar.gz}
diff --git a/doc/src/platforms/packaging.qdoc b/doc/src/platforms/packaging.qdoc
new file mode 100644
index 000000000..c5d460e75
--- /dev/null
+++ b/doc/src/platforms/packaging.qdoc
@@ -0,0 +1,70 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $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$
+**
+****************************************************************************/
+
+/*!
+    \page packaging-recommendations.html
+    \title Qt Packaging Recommendations
+
+    Distributions might want to package multiple different Qt versions. By
+    taking the example of a Linux distribution, we recommend the following
+    approach:
+
+    \list
+
+    \li Configure Qt to install executables to \c{/usr/qt6/bin}.
+
+    \li Create symlinks with version suffixes in \c{/usr/bin} to user-facing
+        applications that reside in \c{/usr/qt6/bin}. For example, create the
+        symlink \c{/usr/bin/designer6} that points to \c{/usr/qt6/bin/designer}.
+
+    \endlist
+
+    User-facing applications are Qt tools that are supposed to be started by the
+    user. This includes qmake, Qt Designer, Qt Linguist, and others. Other
+    tools, such as moc, rcc, and uic are usually not manually invoked by the
+    user but from the build system of user projects.
+
+    In Qt's build system, tools that we consider as user-facing are marked as
+    such, and that information can be extracted and used as follows.
+
+    Configure Qt with the CMake arguments:
+    \badcode
+    -DCMAKE_INSTALL_PREFIX=/usr
+    -DINSTALL_BINDIR=/usr/qt6/bin
+    -DINSTALL_PUBLICBINDIR=/usr/bin
+    \endcode
+
+    This will create a file called \c{user_facing_tool_links.txt} in Qt's build
+    directory. It contains on each line the path of a user-facing tool in
+    \c{INSTALL_BINDIR} and, separated by one space, the path to the versioned
+    link in \c{INSTALL_PUBLICDIR}.
+
+    This file can be used to create all versioned symlinks:
+    \badcode
+    xargs ln -s < user_facing_tool_links.txt
+    \endcode
+*/