feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Update and overhaul README

Browse Source 
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>
This commit is contained in:
Eike Ziller
2020-12-09 14:38:35 +01:00
parent 064740e1b7
commit e2a2af5d18
1 changed files with 79 additions and 198 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
README.md
View File

@@ -17,7 +17,7 @@ https://doc.qt.io/qtcreator/creator-overview.html
The standalone binary packages support the following platforms: The standalone binary packages support the following platforms:
* Windows 7 or later * 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 * macOS 10.13 or later
## Contributing ## Contributing
@@ -38,203 +38,112 @@ Prerequisites:
* Qt 5.14.0 or later * Qt 5.14.0 or later
* Qt WebEngine module for QtWebEngine based help viewer * Qt WebEngine module for QtWebEngine based help viewer
* On Windows: * On Windows:
* ActiveState Active Perl
* MinGW with GCC 7 or Visual Studio 2017 or later * MinGW with GCC 7 or Visual Studio 2017 or later
* jom
* Python 3.5 or later (optional, needed for the python enabled debug helper) * 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 Mac OS X: latest Xcode
* On Linux: GCC 7 or later * On Linux: GCC 7 or later
* LLVM/Clang 8.0.0 or later (optional, needed for the Clang Code Model, Clang Tools, ClangFormat, * LLVM/Clang 10 or later (optional, LLVM/Clang 11 is recommended.
Clang PCH Manager and Clang Refactoring plugins, see the section See the section "Getting LLVM/Clang for the Clang Code Model".
"Get LLVM/Clang for the Clang Code Model". The LLVM C++ API provides no compatibility garantee, The ClangFormat, ClangPchManager and ClangRefactoring use the LLVM C++ API.
so if later versions don't compile we don't support that version.) Since the LLVM C++ API provides no compatibility guarantee,
* CMake (for manual builds of LLVM/Clang, and Qt Creator itself) if later versions don't compile we don't support that version.)
* Ninja (optional, recommended for building with CMake) * CMake
* Qbs 1.7.x (optional, sources also contain Qbs itself) * Ninja (recommended)
The installed toolchains have to match the one Qt was compiled with. 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: These instructions assume that Ninja is installed and in the `PATH`, Qt Creator
export LLVM_INSTALL_DIR=/path/to/llvm (or "set" on Windows) sources are located at `/path/to/qtcreator_sources`, Qt is installed in
# Optional, disable Clang Refactoring `/path/to/Qt`, and LLVM is installed in `/path/to/llvm`.
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 Note that if you install Qt via the online installer, the path to Qt must
qmake -r include the version number and compiler ABI. The path to the online installer
make (or mingw32-make or nmake or jom, depending on your platform) 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 ### Windows
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 These instructions assume that Ninja is installed and in the `PATH`, Qt Creator
plan to contribute to Qt Creator, you should compile your changes with sources are located at `\path\to\qtcreator_sources`, Qt is installed in
both compilers. `\path\to\Qt`, and LLVM is installed in `\path\to\llvm`.
2. Install Git for Windows from <https://git-for-windows.github.io/>. If you plan to Note that if you install Qt via the online installer, the path to Qt must
use the MinGW compiler suite, do not choose to put git in the include the version number and compiler ABI. The path to the online installer
default path of Windows command prompts. For more information, see content is not enough.
step 9.
3. Create a working directory under which to check out Qt and Qt Creator, See "Getting LLVM/Clang for the Clang Code Model" for instructions on how to
for example, `c:\work`. If you plan to use MinGW and Microsoft Visual get LLVM.
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> Decide which compiler to use: MinGW or Microsoft Visual Studio.
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 MinGW is available via the Qt online installer, for other options see
<https://code.qt.io/cgit/qt/qt5.git> (we recommend the highest released version). <https://wiki.qt.io/MinGW>. Run the commands below in a shell prompt that has
`<path_to_mingw>\bin` in the `PATH`.
6. Check out Qt Creator (master branch or latest version, see For Microsoft Visual C++ you can use the "Build Tools for Visual Studio". Also
<https://code.qt.io/cgit/qt-creator/qt-creator.git>). install the "Debugging Tools for Windows" from the Windows SDK installer. We
You should now have the directories qt and creator under your working strongly recommend using the 64-bit version and 64-bit compilers on 64-bit
directory. 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.
7. Install a compiler: md qtcreator_build
- For a MinGW toolchain for Qt, see <https://wiki.qt.io/MinGW> . cd qtcreator_build
- For Microsoft Visual C++, install the Windows SDK and the "Debugging cmake -DCMAKE_BUILD_TYPE=Debug -G Ninja "-DCMAKE_PREFIX_PATH=/path/to/Qt;/path/to/llvm" \path\to\qtcreator_sources
Tools for Windows" from the SDK image. We strongly recommend using the cmake --build .
64-bit version and 64-bit compilers on 64-bit systems.
For the Visual C++ compilers, it is recommended to use the tool 'jom'. Qt Creator can be registered as a post-mortem debugger. This can be done in the
It is a replacement for nmake that utilizes all CPU cores and thus options page or by running the tool qtcdebugger with administrative privileges
speeds up compilation significantly. Download it from passing the command line options -register/unregister, respectively.
<https://download.qt.io/official_releases/jom> Alternatively, the required registry entries
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:
set PATH=<path_to_qt>\[qtbase\]bin;<path_to_mingw>\bin;<working_directory>\creator\bin;%PATH%
set QMAKESPEC=win32-g++
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):
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
You can create desktop links to the `.bat` files using the working
directory and specifying
%SystemRoot%\system32\cmd.exe /E:ON /V:ON /k <working_directory>\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 <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:
cd <path_to_qt>
configure <configure_options> && mingw32-make -s
cd ..\creator
qmake && mingw32-make -s
To use the Visual C++ compilers, enter:
cd <path_to_qt>
configure <configure_options> && 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
<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
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\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 can be modified using the registry editor regedt32 to contain
<path>\qt-creator\bin\qtcdebugger %ld %ld qtcreator_build\bin\qtcdebugger %ld %ld
When using a self-built version of Qt Creator as post-mortem debugger, it needs to be When using a self-built version of Qt Creator as post-mortem debugger, it needs
able to find all dependent Qt-libraries and plugins when being launched by the to be able to find all dependent Qt-libraries and plugins when being launched
system. The easiest way to provide them for Qt 5 is to run the tool windeployqt: 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
windeployqt -quick -qmldir share\qtcreator\welcomescreen -qmldir src\plugins\qmlprofiler bin\qtcreator.exe lib\qtcreator lib\qtcreator\plugins for details.
Note that unlike on Unix, you cannot overwrite executables that are running. 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 Thus, if you want to work on Qt Creator using Qt Creator, you need a separate
separate build of it. We recommend using a separate, release-built version installation of it. We recommend using a separate, release-built version of Qt
of Qt and Qt Creator to work on a debug-built version of Qt and Qt Creator Creator to work on a debug-built version of Qt Creator.
or using shadow builds.
## 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 The Clang Code Model depends on the LLVM/Clang libraries. The currently
supported LLVM/Clang version is 8.0. 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 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 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. 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 ## Third-party Components
Qt Creator includes the following third-party components, Qt Creator includes the following third-party components,