diff --git a/README.md b/README.md index 88e3afa568f..86e9b1eb787 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 +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`. - cd $SOURCE_DIRECTORY - qmake -r - make (or mingw32-make or nmake or jom, depending on your platform) +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. -Installation ("make install") is not needed. It is however possible, using +See "Getting LLVM/Clang for the Clang Code Model" for instructions on how to +get LLVM. - make install INSTALL_ROOT=$INSTALL_DIRECTORY + mkdir qtcreator_build + cd qtcreator_build -## Compiling Qt and Qt Creator on Windows + cmake -DCMAKE_BUILD_TYPE=Debug -G Ninja "-DCMAKE_PREFIX_PATH=/path/to/Qt;/path/to/llvm" /path/to/qtcreator_sources + cmake --build . -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 - . +### Windows - 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. +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`. - 2. Install Git for Windows from . 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`. +See "Getting LLVM/Clang for the Clang Code Model" for instructions on how to +get LLVM. - 4. Download and install Perl from - 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. +Decide which compiler to use: MinGW or Microsoft Visual Studio. - 5. In the working directory, check out the respective branch of Qt from - (we recommend the highest released version). +MinGW is available via the Qt online installer, for other options see +. Run the commands below in a shell prompt that has +`\bin` in the `PATH`. - 6. Check out Qt Creator (master branch or latest version, see - ). - You should now have the directories qt and creator under your working - directory. +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 ` from the +start menu items that were created for Visual Studio, and run the commands +below in it. - 7. Install a compiler: - - For a MinGW toolchain for Qt, see . + md qtcreator_build + cd qtcreator_build - - 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. + cmake -DCMAKE_BUILD_TYPE=Debug -G Ninja "-DCMAKE_PREFIX_PATH=/path/to/Qt;/path/to/llvm" \path\to\qtcreator_sources + cmake --build . - 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 - - and add the executable to the path. +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 - 8. For convenience, we recommend creating shell prompts with the correct - environment. This can be done by creating a .bat-file - (such as, `\qtvars.bat`) that contains the environment - variable settings. - A `.bat`-file for MinGW looks like: + HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug + HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug - set PATH=\[qtbase\]bin;\bin;\creator\bin;%PATH% - set QMAKESPEC=win32-g++ +can be modified using the registry editor regedt32 to contain - 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): + qtcreator_build\bin\qtcdebugger %ld %ld - CALL "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64 - set PATH=\[qtbase\]bin;\creator\bin;%PATH% - set QMAKESPEC=win32-msvc2013 - - You can create desktop links to the `.bat` files using the working - directory and specifying - - %SystemRoot%\system32\cmd.exe /E:ON /V:ON /k \qtvars.bat - - 9. When using MinGW, open the shell prompt and enter: - - sh.exe - - 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". - - 11. You are now ready to configure and build Qt and Qt Creator. - Please see for - recommended configure-options for Qt 5. - To use MinGW, open the the shell prompt and enter: - - cd - configure && mingw32-make -s - cd ..\creator - qmake && mingw32-make -s - - To use the Visual C++ compilers, enter: - - cd - configure && jom - cd ..\creator - qmake && jom - - 12. To launch Qt Creator, enter: - qtcreator - - 13. To test the Clang-based code model, verify that backend process - bin\clangbackend.exe - launches (displaying its usage). - - The library libclang.dll needs to be copied to the bin directory if - Clang cannot be found in the path. - - 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). - - 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 - . - - 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 - - HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug - HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug - - can be modified using the registry editor regedt32 to contain - - \qt-creator\bin\qtcdebugger %ld %ld - - 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: - - windeployqt -quick -qmldir share\qtcreator\welcomescreen -qmldir src\plugins\qmlprofiler bin\qtcreator.exe lib\qtcreator lib\qtcreator\plugins +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. 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. +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. -## Get LLVM/Clang for the Clang Code Model +### Options + +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`. + +Installation is not needed. It is however possible, using + + cmake --install . --prefix /path/to/qtcreator_install + +To create a self-contained Qt Creator installation, including all dependencies +like Qt and LLVM, additionally run + + cmake --install . --prefix /path/to/qtcreator_install --component Dependencies + +## 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,