Doc: Rewrite Qt for Linux/X11 - Building from Source page

Adapt the structure of the Windows page by first detailing
where to get the sources, and explicitly listing the required
build tools.

Inline code snippets, and use the \QtVersion macro to give the
real path instead of relying on %VERSION%.

Remove some outdated information.

Change-Id: Ic7cc60182a9f7f08d656e12ba76af3b4f0602b95
Reviewed-by: Andreas Eliasson <andreas.eliasson@qt.io>
(cherry picked from commit 1434284aff4f547a34a2f87eb871b2acf9a5a0de)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 93 insertions, 93 deletions

diff --git a/doc/src/platforms/linux.qdoc b/doc/src/platforms/linux.qdoc
index 63cb742e..22ca6603 100644
--- a/doc/src/platforms/linux.qdoc
+++ b/doc/src/platforms/linux.qdoc
@@ -347,87 +347,126 @@
     \title Qt for Linux/X11 - Building from Source
     \brief How to configure and build Qt on Linux/X11 platforms.
 
-    You can download the Qt sources from the \l Downloads page. For more
-    information, visit the \l{Getting Started with Qt} page.
-
-    Qt for X11 has some requirements that are given in more detail
-    in the \l{Qt for X11 Requirements} document.
+    This page describes configuring and building \l{Qt for Linux/X11} from
+    sources. Note that it is typically easier to install the pre-built Qt
+    libraries and tools via the \l{Online Installer}. A lot of Linux
+    distributions also provide Qt packages through their package manager.
+    Build Qt from sources, however, if you want to customize Qt further or are
+    using a distribution for which no binary Qt packages (in the right version)
+    are available.
+
+    Distribution packagers can find further information on how to package Qt in
+    the \l{Qt Packaging Recommendations}{packaging recommendations}.
+
+    \section1 Step 1: Getting the Sources
+
+    Qt sources can be installed in the Qt Online Installer. Source packages are
+    also available as \l{https://code.qt.io}{Git repositories}, as archives in
+    the \l{Qt Account} (commercial users), and on
+    \l{https://download.qt.io/official_releases/qt/}{download.qt.io}
+    (open-source users).
+
+    If you install the sources through the Qt Online Installer, they will
+    be available in the Qt installation directory, for example
+    \tt{$HOME/Qt/\QtVersion/Src}.
+
+    If you downloaded the single source archive, extract it to a directory of
+    your choice:
+
+    \badcode \QtVersion
+    cd ~/dev
+    tar xf ~/Downloads/qt-everywhere-src-\1.tar.xz
+    \endcode
 
-    Distribution packagers can find information how to package Qt in the
-    \l{Qt Packaging Recommendations}{packaging recommendations}.
+    \section1 Step 2: Install Build Requirements
 
-    \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-src-%VERSION%.tar.gz}
-        package, type the following commands at a command line prompt:
+    Building Qt requires a build environment with tools, compilers, and
+    development packages.
 
-    \snippet snippets/code/doc_src_installation.qdoc 0
+    \section2 Build Tools
 
-        This creates the directory \c{/tmp/qt-everywhere-src-%VERSION%}
-        containing the files from the archive. We only support the GNU version of
-        the tar archiving utility. Note that on some systems it is called gtar.
+    \table 80%
+    \header \li Tool \li Supported Versions
+    \row
+        \li CMake
+        \li Version 3.16 and newer (3.21 and newer for \c{-static} builds).
+    \row
+        \li Ninja
+        \li -
+    \row
+        \li Python
+        \li Version 3
+    \endtable
 
-    \section1 Step 2: Build the Qt Library
+    \include use-ninja-note.qdocinc ninja-note
 
-        To configure the Qt library for your machine type, run the
-        \c{./configure} script in the package directory.
+    \section2 Compilers & Development Packages
 
-        By default, Qt is configured for installation in the
-        \c{/usr/local/Qt-%VERSION%} directory, but this can be
-        changed by using the \c{-prefix} option.
+    The following compilers and configurations are supported in Qt \QtVer:
 
-        The \l{Qt Configure Options}{Configure Options} page contains more
-        information about the configure options.
+    \include supported-platforms.qdocinc linux
 
-    \snippet snippets/code/doc_src_installation.qdoc 1
+    Other compilers and configurations might work but are not actively tested.
 
-    \include use-ninja-note.qdocinc ninja-note
+    Qt also relies on the availability of various libraries and development
+    packages, which are typically installed by the package manager of the
+    respective resolution. See \l{Qt for X11 Requirements} for the details.
 
-        The \l{Qt Configure Options}{Configure Options} page contains more
-        information about the configure options.
+    \section1 Step 3: Build the Qt Libraries and Tools
 
-        To create the library and compile all the examples, tools,
-        and tutorials, type:
+    Run the \c{./configure} script in the package directory to configure
+    your build:
 
-    \snippet snippets/code/doc_src_installation.qdoc 2
-
-        If \c{-prefix} is outside the build directory, you need to install
-        the library, examples, tools, and tutorials in the appropriate
-        place. To do this (as root if necessary), type:
+    \badcode \QtVersion
+    cd /tmp/qt-everywhere-src-\1
+    ./configure
+    \endcode
 
-    \snippet snippets/code/doc_src_installation.qdoc 3
+    By default, Qt is configured for installation in the
+    \tt{/usr/local/Qt-\QtVersion} directory. This can be changed by using the
+    \c{-prefix} option. See the list of \l{Qt Configure Options}{configure options}
+    to tweak further.
 
-        Note that on some systems the make utility is named differently, like gmake.
-        The configure script tells you which make utility to use.
+    Did \c{configure} run successfully? Then proceed with building the libraries
+    and tools:
 
-        \note Later, if you need to reconfigure and rebuild Qt from the same location,
-        ensure that all traces of the previous configuration are removed. To do so, from
-        the build directory, type \c{make confclean} before running \c configure again.
+    \badcode
+    cmake --build . --parallel
+    \endcode
 
-    \section1 Step 3: Set the Environment Variables
+    After building, you need to install the libraries and tools in the
+    appropriate place (unless you enabled a
+    \l{Developer Builds}{developer build}):
 
-        To use Qt, some environment variables need to be extended.
+    \badcode
+    cmake --install .
+    \endcode
 
-    \snippet snippets/code/doc_src_installation.qdoc 4
+    Note that this might require root access.
 
-        This is done as follows:
+    \section1 Step 4: Using Qt
 
-        In \c{.profile} (if your shell is bash, ksh, zsh or sh), add the
-        following lines:
+    After Qt is installed, you can start building applications with it.
 
-    \snippet snippets/code/doc_src_installation.qdoc 5
+    If you work from the command line, consider adding the Qt tools to your
+    default \c PATH. This is done as follows:
 
-        In \c{.login} (if your shell is csh or tcsh), add the following line:
+    In \c{.profile} (if your shell is bash, ksh, zsh or sh), add the
+    following lines:
 
-    \snippet snippets/code/doc_src_installation.qdoc 6
+    \badcode \QtVersion
+    PATH=/usr/local/Qt-\1/bin:$PATH
+    export PATH
+    \endcode
 
-        If you use a different shell, modify your environment variables accordingly.
+    In \c{.login} (if your shell is csh or tcsh), add the following line:
 
-        For compilers that do not support rpath you must also extend the
-        \c LD_LIBRARY_PATH environment variable to include
-        \c{/usr/local/Qt-%VERSION%/lib}. On Linux with GCC this step
-        is not needed.
+    \badcode \QtVersion
+    setenv PATH /usr/local/Qt-\1/bin:$PATH
+    \endcode
 
+    If you plan to use Qt from an IDE, you need to register the Qt version
+    explicitly there. For Qt Creator, see \l{Qt Creator: Adding Qt Versions}.
 */
 
 /*!
diff --git a/doc/src/snippets/code/doc_src_installation.qdoc b/doc/src/snippets/code/doc_src_installation.qdoc
index 285abeee..23deff42 100644
--- a/doc/src/snippets/code/doc_src_installation.qdoc
+++ b/doc/src/snippets/code/doc_src_installation.qdoc
@@ -1,45 +1,6 @@
 // Copyright (C) 2019 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
-//! [0]
-cd /tmp
-gunzip qt-everywhere-src-%VERSION%.tar.gz        # uncompress the archive
-tar xvf qt-everywhere-src-%VERSION%.tar          # unpack it
-//! [0]
-
-
-//! [1]
-cd /tmp/qt-everywhere-src-%VERSION%
-./configure
-//! [1]
-
-
-//! [2]
-cmake --build . --parallel
-//! [2]
-
-
-//! [3]
-cmake --install .
-//! [3]
-
-
-//! [4]
-PATH               - to locate qmake, moc and other Qt tools
-//! [4]
-
-
-//! [5]
-PATH=/usr/local/Qt-%VERSION%/bin:$PATH
-export PATH
-//! [5]
-
-
-//! [6]
-setenv PATH /usr/local/Qt-%VERSION%/bin:$PATH
-//! [6]
-
-
 //! [11]
 cd /tmp
 gunzip qt-everywhere-src-%VERSION%.tar.gz        # uncompress the archive