Update and overhaul README

Our binaries no longer support Ubuntu 16.
Update LLVM requirements.
Move build instructions to use CMake and overhaul the complicated
Windows instructions.

Change-Id: Idf139fd76b0cfb91dbce11f7b814ec8abd9b21f6
Reviewed-by: David Schulz <david.schulz@qt.io>

1 files changed, 74 insertions, 193 deletions

diff --git a/README.md b/README.md
index 88e3afa568..86e9b1eb78 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ https://doc.qt.io/qtcreator/creator-overview.html
 The standalone binary packages support the following platforms:
 
 * Windows 7 or later
-* (K)Ubuntu Linux 16.04 (64-bit) or later
+* (K)Ubuntu Linux 18.04 (64-bit) or later
 * macOS 10.13 or later
 
 ## Contributing
@@ -38,203 +38,112 @@ Prerequisites:
 * Qt 5.14.0 or later
 * Qt WebEngine module for QtWebEngine based help viewer
 * On Windows:
-    * ActiveState Active Perl
     * MinGW with GCC 7 or Visual Studio 2017 or later
-    * jom
     * Python 3.5 or later (optional, needed for the python enabled debug helper)
+    * Debugging Tools for Windows (optional, for MSVC debugging support with CDB)
 * On Mac OS X: latest Xcode
 * On Linux: GCC 7 or later
-* LLVM/Clang 8.0.0 or later (optional, needed for the Clang Code Model, Clang Tools, ClangFormat,
-  Clang PCH Manager and Clang Refactoring plugins, see the section
-  "Get LLVM/Clang for the Clang Code Model". The LLVM C++ API provides no compatibility garantee,
-  so if later versions don't compile we don't support that version.)
-* CMake (for manual builds of LLVM/Clang, and Qt Creator itself)
-* Ninja (optional, recommended for building with CMake)
-* Qbs 1.7.x (optional, sources also contain Qbs itself)
+* LLVM/Clang 10 or later (optional, LLVM/Clang 11 is recommended.
+  See the section "Getting LLVM/Clang for the Clang Code Model".
+  The ClangFormat, ClangPchManager and ClangRefactoring use the LLVM C++ API.
+  Since the LLVM C++ API provides no compatibility guarantee,
+  if later versions don't compile we don't support that version.)
+* CMake
+* Ninja (recommended)
 
 The installed toolchains have to match the one Qt was compiled with.
 
-You can build Qt Creator with
+### Linux and macOS
 
-    # Optional, needed for the Clang Code Model if llvm-config is not in PATH:
-    export LLVM_INSTALL_DIR=/path/to/llvm (or "set" on Windows)
-    # Optional, disable Clang Refactoring
-    export QTC_DISABLE_CLANG_REFACTORING=1
-    # Optional, needed to let the QbsProjectManager plugin use system Qbs:
-    export QBS_INSTALL_DIR=/path/to/qbs
-    # Optional, needed for the Python enabled dumper on Windows
-    set PYTHON_INSTALL_DIR=C:\path\to\python
-    # Optional, needed to use system KSyntaxHighlighting:
-    set KSYNTAXHIGHLIGHTING_LIB_DIR to folder holding the KSyntaxHighlighting library
-    # if automatic deducing of include folder fails set KSYNTAXHIGHLIGHTING_INCLUDE_DIR as well
-    # both variables can also be passed as qmake variables
-
-    cd $SOURCE_DIRECTORY
-    qmake -r
-    make (or mingw32-make or nmake or jom, depending on your platform)
-
-Installation ("make install") is not needed. It is however possible, using
-
-    make install INSTALL_ROOT=$INSTALL_DIRECTORY
-
-## Compiling Qt and Qt Creator on Windows
+These instructions assume that Ninja is installed and in the `PATH`, Qt Creator
+sources are located at `/path/to/qtcreator_sources`, Qt is installed in
+`/path/to/Qt`, and LLVM is installed in `/path/to/llvm`.
 
-This section provides step by step instructions for compiling the latest
-versions of Qt and Qt Creator on Windows. Alternatively, to avoid having to
-compile Qt yourself, you can use one of the versions of Qt shipped with the Qt
-SDK (release builds of Qt using MinGW and Visual C++ 2017 or later).
-For detailed information on the supported compilers, see
-<https://wiki.qt.io/Building_Qt_5_from_Git> .
-
-   1.  Decide which compiler to use: MinGW or Microsoft Visual Studio. If you
-       plan to contribute to Qt Creator, you should compile your changes with
-       both compilers.
-
-   2.  Install Git for Windows from <https://git-for-windows.github.io/>. If you plan to
-       use the MinGW compiler suite, do not choose to put git in the
-       default path of Windows command prompts. For more information, see
-       step 9.
+Note that if you install Qt via the online installer, the path to Qt must
+include the version number and compiler ABI. The path to the online installer
+content is not enough.
 
-   3.  Create a working directory under which to check out Qt and Qt Creator,
-       for example, `c:\work`. If you plan to use MinGW and Microsoft Visual
-       Studio simultaneously or mix different Qt versions, we recommend
-       creating a directory structure which reflects that. For example:
-       `C:\work\qt5.14.0-vs17, C:\work\qt5.14.0-mingw`.
-
-   4.  Download and install Perl from <https://www.activestate.com/activeperl>
-       and check that perl.exe is added to the path. Run `perl -v` to verify
-       that the version displayed is 5.10 or later. Note that git ships
-       an outdated version 5.8 which cannot be used for Qt.
-
-   5.  In the working directory, check out the respective branch of Qt from
-       <https://code.qt.io/cgit/qt/qt5.git> (we recommend the highest released version).
-
-   6.  Check out Qt Creator (master branch or latest version, see
-       <https://code.qt.io/cgit/qt-creator/qt-creator.git>).
-       You should now have the directories qt and creator under your working
-       directory.
-
-   7.  Install a compiler:
-       - For a MinGW toolchain for Qt, see <https://wiki.qt.io/MinGW> .
-
-       - For Microsoft Visual C++, install the Windows SDK and the "Debugging
-         Tools for Windows" from the SDK image. We strongly recommend using the
-         64-bit version and 64-bit compilers on 64-bit systems.
-
-         For the Visual C++ compilers, it is recommended to use the tool 'jom'.
-         It is a replacement for nmake that utilizes all CPU cores and thus
-         speeds up compilation significantly. Download it from
-         <https://download.qt.io/official_releases/jom>
-         and add the executable to the path.
-
-   8.  For convenience, we recommend creating shell prompts with the correct
-       environment. This can be done by creating a .bat-file
-       (such as, `<working_directory>\qtvars.bat`) that contains the environment
-       variable settings.
-       A `.bat`-file for MinGW looks like:
+See "Getting LLVM/Clang for the Clang Code Model" for instructions on how to
+get LLVM.
 
-         set PATH=<path_to_qt>\[qtbase\]bin;<path_to_mingw>\bin;<working_directory>\creator\bin;%PATH%
-         set QMAKESPEC=win32-g++
+    mkdir qtcreator_build
+    cd qtcreator_build
 
-       For the Visual C++ compilers, call the `.bat` file that sets up the
-       environment for the compiler (provided by the Windows SDK or the
-       compiler):
+    cmake -DCMAKE_BUILD_TYPE=Debug -G Ninja "-DCMAKE_PREFIX_PATH=/path/to/Qt;/path/to/llvm" /path/to/qtcreator_sources
+    cmake --build .
 
-         CALL "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64
-         set PATH=<path_to_qt>\[qtbase\]bin;<working_directory>\creator\bin;%PATH%
-         set QMAKESPEC=win32-msvc2013
+### Windows
 
-       You can create desktop links to the `.bat` files using the working
-       directory and specifying
+These instructions assume that Ninja is installed and in the `PATH`, Qt Creator
+sources are located at `\path\to\qtcreator_sources`, Qt is installed in
+`\path\to\Qt`, and LLVM is installed in `\path\to\llvm`.
 
-        %SystemRoot%\system32\cmd.exe /E:ON /V:ON  /k <working_directory>\qtvars.bat
+Note that if you install Qt via the online installer, the path to Qt must
+include the version number and compiler ABI. The path to the online installer
+content is not enough.
 
-   9.  When using MinGW, open the shell prompt and enter:
+See "Getting LLVM/Clang for the Clang Code Model" for instructions on how to
+get LLVM.
 
-        sh.exe
+Decide which compiler to use: MinGW or Microsoft Visual Studio.
 
-       That should result in a `sh is not recognized as internal or external
-       command...` error. If a `sh.exe` is found, the compile process will fail.
-       You have to remove it from the path.
-
-   10. To make use of the Clang Code Model:
-
-       * Install LLVM/Clang - see the section "Get LLVM/Clang for the Clang
-         Code Model".
-       * Set the environment variable LLVM_INSTALL_DIR to the LLVM/Clang
-         installation directory if llvm-config is not in PATH.
-       * Before you launch Qt Creator you may prepend the PATH with
-         the location of libclang.dll/.so that you want to be used.
-         See more info in the section "Prebuilt LLVM/Clang packages".
+MinGW is available via the Qt online installer, for other options see
+<https://wiki.qt.io/MinGW>. Run the commands below in a shell prompt that has
+`<path_to_mingw>\bin` in the `PATH`.
 
-   11. You are now ready to configure and build Qt and Qt Creator.
-       Please see <https://wiki.qt.io/Building_Qt_5_from_Git> for
-       recommended configure-options for Qt 5.
-       To use MinGW, open the the shell prompt and enter:
+For Microsoft Visual C++ you can use the "Build Tools for Visual Studio". Also
+install the "Debugging Tools for Windows" from the Windows SDK installer. We
+strongly recommend using the 64-bit version and 64-bit compilers on 64-bit
+systems. Open the `x64 Native Tools Command Prompt for VS <version>` from the
+start menu items that were created for Visual Studio, and run the commands
+below in it.
 
-         cd <path_to_qt>
-         configure <configure_options> && mingw32-make -s
-         cd ..\creator
-         qmake && mingw32-make -s
+    md qtcreator_build
+    cd qtcreator_build
 
-       To use the Visual C++ compilers, enter:
+    cmake -DCMAKE_BUILD_TYPE=Debug -G Ninja "-DCMAKE_PREFIX_PATH=/path/to/Qt;/path/to/llvm" \path\to\qtcreator_sources
+    cmake --build .
 
-         cd <path_to_qt>
-         configure <configure_options> && jom
-         cd ..\creator
-         qmake && jom
+Qt Creator can be registered as a post-mortem debugger. This can be done in the
+options page or by running the tool qtcdebugger with administrative privileges
+passing the command line options -register/unregister, respectively.
+Alternatively, the required registry entries
 
-   12. To launch Qt Creator, enter:
-       qtcreator
+    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug
+    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug
 
-   13. To test the Clang-based code model, verify that backend process
-         bin\clangbackend.exe
-       launches (displaying its usage).
+can be modified using the registry editor regedt32 to contain
 
-       The library libclang.dll needs to be copied to the bin directory if
-       Clang cannot be found in the path.
+    qtcreator_build\bin\qtcdebugger %ld %ld
 
-   14. When using  Visual C++ with the "Debugging Tools for Windows" installed,
-       the extension library `qtcreatorcdbext.dll` to be loaded into the
-       Windows console debugger (`cdb.exe`) should have been built under
-       `lib\qtcreatorcdbext32` or `lib\qtcreatorcdbext64`.
-       When using a 32 bit-build of Qt Creator with the 64 bit version of the
-       "Debugging Tools for Windows" the library should also be built with
-       a 64 bit compiler (rebuild `src\libs\qtcreatorcdbext` using a 64 bit
-       compiler).
+When using a self-built version of Qt Creator as post-mortem debugger, it needs
+to be able to find all dependent Qt-libraries and plugins when being launched
+by the system. The easiest way to do this is to create a self-contained Qt
+Creator by installing it and installing its dependencies. See "Options" below
+for details.
 
-       If you are building 32 bit and running on a 64 bit
-       Windows, you can obtain the 64 bit versions of the extension library
-       and the binary `win64interrupt.exe`, which is required for
-       debugging from the repository
-       <https://code.qt.io/cgit/qt-creator/binary-artifacts.git/tree> .
-
-   15. Qt Creator can be registered as a post-mortem debugger. This
-       can be done in the options page or by running the tool qtcdebugger
-       with administrative privileges passing the command line options
-       -register/unregister, respectively. Alternatively,
-       the required registry entries
+Note that unlike on Unix, you cannot overwrite executables that are running.
+Thus, if you want to work on Qt Creator using Qt Creator, you need a separate
+installation of it. We recommend using a separate, release-built version of Qt
+Creator to work on a debug-built version of Qt Creator.
 
-        HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug
-        HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug
+### Options
 
-       can be modified using the registry editor regedt32 to contain
+If you do not have Ninja installed and in the `PATH`, remove `-G Ninja` from
+the first `cmake` call. If you want to build in release mode, change the build
+type to `-DCMAKE_BUILD_TYPE=Release`. You can also build with release
+optimizations but debug information with `-DCMAKE_BUILD_TYPE=RelWithDebInfo`.
 
-        <path>\qt-creator\bin\qtcdebugger %ld %ld
+Installation is not needed. It is however possible, using
 
-       When using a self-built version of Qt Creator as post-mortem debugger, it needs to be
-       able to find all dependent Qt-libraries and plugins when being launched by the
-       system. The easiest way to provide them for Qt 5 is to run the tool windeployqt:
+    cmake --install . --prefix /path/to/qtcreator_install
 
-        windeployqt -quick -qmldir share\qtcreator\welcomescreen -qmldir src\plugins\qmlprofiler bin\qtcreator.exe lib\qtcreator lib\qtcreator\plugins
+To create a self-contained Qt Creator installation, including all dependencies
+like Qt and LLVM, additionally run
 
-Note that unlike on Unix, you cannot overwrite executables that are running.
-Thus, if you want to work on Qt Creator using Qt Creator, you need a
-separate build of it. We recommend using a separate, release-built version
-of Qt and Qt Creator to work on a debug-built version of Qt and Qt Creator
-or using shadow builds.
+    cmake --install . --prefix /path/to/qtcreator_install --component Dependencies
 
-## Get LLVM/Clang for the Clang Code Model
+## Getting LLVM/Clang for the Clang Code Model
 
 The Clang Code Model depends on the LLVM/Clang libraries. The currently
 supported LLVM/Clang version is 8.0.
@@ -266,7 +175,7 @@ http://llvm.org/docs/GettingStarted.html#git-mirror:
 
    1. Clone LLVM/Clang and checkout a suitable branch
 
-          git clone -b release_100-based --recursive https://code.qt.io/clang/llvm-project.git
+          git clone -b release_110-based --recursive https://code.qt.io/clang/llvm-project.git
 
    2. Build and install LLVM/Clang
 
@@ -304,34 +213,6 @@ While the plugin builds without it, it will be disabled on start with an error m
 
 Note that the plugin is disabled by default.
 
-### Building Qt Creator with CMake
-
-Qt Creator can also be built with CMake. The main Qt Creator dependencies, Qt and LLVM/Clang, both
-offer CMake find packages, which reduce the steps of configuring Qt Creator to a minimum.
-
-   Configure and build Qt Creator:
-
-      mkdir build
-      cd build
-
-    For Linux/macOS:
-
-      cmake \
-        -G Ninja \
-        -D CMAKE_BUILD_TYPE=Release \
-        -D CMAKE_PREFIX_PATH=~/Qt/5.14.2/gcc_64;~/llvm \
-        ../qt-creator
-      cmake --build .
-
-    For Windows:
-
-      cmake ^
-        -G Ninja ^
-        -D CMAKE_BUILD_TYPE=Release ^
-        -D CMAKE_PREFIX_PATH=c:\Qt\5.14.2\msvc2017_64;c:\llvm ^
-        ..\qt-creator
-      cmake --build .
-
 ## Third-party Components
 
 Qt Creator includes the following third-party components,