Qt Build System Glossary: Difference between revisions
No edit summary |
(add framework builds) |
||
| Line 3: | Line 3: | ||
To be on the same page when talking about Qt build system related topics, we're offering here a collection of used terms. | To be on the same page when talking about Qt build system related topics, we're offering here a collection of used terms. | ||
=== Build System === | ===Build System=== | ||
The build system of Qt is the collection of files that describe how to build Qt from source. | The build system of Qt is the collection of files that describe how to build Qt from source. | ||
| Line 10: | Line 10: | ||
It does not include QMake, CMake, make or ninja. | It does not include QMake, CMake, make or ninja. | ||
=== Build Tool === | ===Build Tool=== | ||
In the widest sense, those are tools that contribute to the build. | In the widest sense, those are tools that contribute to the build. | ||
| Line 17: | Line 17: | ||
We can count build system generators to the the build tools. | We can count build system generators to the the build tools. | ||
=== Build System Generator === | ===Build System Generator=== | ||
Build system generators are tools that take a high-level project description as input (e.g. a qmake project file) and output a lower level build system (e.g. a Makefile). Examples are QMake, CMake, gyp or gn. | Build system generators are tools that take a high-level project description as input (e.g. a qmake project file) and output a lower level build system (e.g. a Makefile). Examples are QMake, CMake, gyp or gn. | ||
=== In-source Build === | ===In-source Build=== | ||
This means that your build directory is the same as your source directory. | This means that your build directory is the same as your source directory. | ||
This is also called in-tree build. | This is also called in-tree build. | ||
| Line 30: | Line 30: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
=== Out-of-source Build === | ===Out-of-source Build=== | ||
This means that your build directory is outside your source directory.<syntaxhighlight lang="bash"> | This means that your build directory is outside your source directory.<syntaxhighlight lang="bash"> | ||
$ mkdir qt-build-dir | $ mkdir qt-build-dir | ||
| Line 42: | Line 42: | ||
Also, it's very easy to do a fresh build by purging your build directory. | Also, it's very easy to do a fresh build by purging your build directory. | ||
=== Shadow Build === | ===Shadow Build=== | ||
This is just another name for out-of-source build. | This is just another name for out-of-source build. | ||
=== Developer Build === | ===Developer Build=== | ||
A developer build of Qt is meant for developers '''of''' Qt. | A developer build of Qt is meant for developers '''of''' Qt. | ||
It differs from a non-developer build in two details: | It differs from a non-developer build in two details: | ||
* It's a non-prefix build if the -prefix configure option is omitted. See below for non-prefix builds. | *It's a non-prefix build if the -prefix configure option is omitted. See below for non-prefix builds. | ||
* It enables private tests. Those are autotests that require symbols to be exported that would be hidden under normal circumstances. | *It enables private tests. Those are autotests that require symbols to be exported that would be hidden under normal circumstances. | ||
<syntaxhighlight lang="bash"> | <syntaxhighlight lang="bash"> | ||
$ mkdir qt-build-dir | $ mkdir qt-build-dir | ||
| Line 67: | Line 67: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
=== Prefix Build === | ===Prefix Build=== | ||
This means that you configured Qt '''with''' an installation '''prefix'''.<syntaxhighlight lang="bash"> | This means that you configured Qt '''with''' an installation '''prefix'''.<syntaxhighlight lang="bash"> | ||
$ mkdir qt-build-dir | $ mkdir qt-build-dir | ||
| Line 79: | Line 79: | ||
Note that, by default, configure uses /usr/local as installation prefix. Unless -developer-build is specified. See below. | Note that, by default, configure uses /usr/local as installation prefix. Unless -developer-build is specified. See below. | ||
=== Non-prefix Build === | ===Non-prefix Build=== | ||
This means that you configured Qt '''without''' an installation '''prefix'''. | This means that you configured Qt '''without''' an installation '''prefix'''. | ||
| Line 92: | Line 92: | ||
Technically, the install prefix is set to the build dir, and care is taken by the build system that the necessary files are copied/built into the right place. | Technically, the install prefix is set to the build dir, and care is taken by the build system that the necessary files are copied/built into the right place. | ||
=== Top-level Build === | ===Top-level Build=== | ||
As you probably know, Qt is split into several repositories: qtbase, qtdeclarative, qttools and so on. There's also a "super" repository called "qt5" that bundles everything as git submodules. | As you probably know, Qt is split into several repositories: qtbase, qtdeclarative, qttools and so on. There's also a "super" repository called "qt5" that bundles everything as git submodules. | ||
| Line 99: | Line 99: | ||
Dependencies between the single repositories are automatically resolved by the build system. | Dependencies between the single repositories are automatically resolved by the build system. | ||
=== Per-repository Build === | ===Per-repository Build=== | ||
This is building Qt's single repositories one by one. | This is building Qt's single repositories one by one. | ||
| Line 138: | Line 138: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
=== debug-and-release build === | ===debug-and-release build=== | ||
This means that Qt (or some other project) is configured for building the Debug and Release configurations in the same build directory. | This means that Qt (or some other project) is configured for building the Debug and Release configurations in the same build directory. | ||
| Line 146: | Line 146: | ||
For CMake projects, Multi-Config generators (e.g. Ninja Multi-Config) support the build of multiple configurations per build directory. | For CMake projects, Multi-Config generators (e.g. Ninja Multi-Config) support the build of multiple configurations per build directory. | ||
=== Qt tests === | === Framework Build === | ||
On Apple platforms, the Qt libraries are built by default as [https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html frameworks]. | |||
The <install-prefix>/lib/Qt6Core.framework then contains the library and all related header files. | |||
Qt can also be configured as non-framework build by passing -no-framework to configure. | |||
In this case, <install-prefix>/lib contains the libraries as .dylib files, and the header files are placed below <install-prefix>/include. | |||
===Qt tests=== | |||
Starting with Qt 6, Qt's tests can be built in a few ways: | Starting with Qt 6, Qt's tests can be built in a few ways: | ||
* all tests defined in a repository are built in-tree with the Qt build directory (henceforth called ''''in-tree'''') | *all tests defined in a repository are built in-tree with the Qt build directory (henceforth called '<nowiki/>'''in-tree'''') | ||
* all tests defined in a repository are built in a standalone build directory (called ''''standalone tests'''') | *all tests defined in a repository are built in a standalone build directory (called '<nowiki/>'''standalone tests'''') | ||
* one specific test is built in a standalone build directory (called ''''standalone tes'''t') | *one specific test is built in a standalone build directory (called ''''standalone tes'''t') | ||
==== In-tree tests ==== | ====In-tree tests==== | ||
To build tests in-tree with the Qt build itself, you need to pass the following configure argument when configuring Qt | To build tests in-tree with the Qt build itself, you need to pass the following configure argument when configuring Qt | ||
| Line 169: | Line 178: | ||
The disadvantage is that configuration time and total build time will be longer. | The disadvantage is that configuration time and total build time will be longer. | ||
==== Standalone tests ==== | ====Standalone tests==== | ||
To build standalone tests in a separate build directory you first need to build at least qtbase, and then you need to use a special shell script provided by the qtbase installation: | To build standalone tests in a separate build directory you first need to build at least qtbase, and then you need to use a special shell script provided by the qtbase installation: | ||
| Line 190: | Line 199: | ||
The disadvantage is that you have to go through a few steps more than usual. | The disadvantage is that you have to go through a few steps more than usual. | ||
==== Single standalone test ==== | ====Single standalone test==== | ||
Sometimes you just want to build one single test, outside your Qt build directory. You can do that with a special 'qt-cmake-standalone' shell script. | Sometimes you just want to build one single test, outside your Qt build directory. You can do that with a special 'qt-cmake-standalone' shell script. | ||
| Line 209: | Line 218: | ||
The advantage of this approach is that the configuration time and build time of one test is very fast. | The advantage of this approach is that the configuration time and build time of one test is very fast. | ||
=== qmake trace file === | ===qmake trace file=== | ||
A qmake trace file for a qmake-based project is produced by passing three -d arguments to qmake: | A qmake trace file for a qmake-based project is produced by passing three -d arguments to qmake: | ||
| Line 217: | Line 226: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
=== CMake trace file === | ===CMake trace file=== | ||
A CMake trace file for a CMake-based project is produced like this: | A CMake trace file for a CMake-based project is produced like this: | ||
Revision as of 08:46, 22 April 2021
To be on the same page when talking about Qt build system related topics, we're offering here a collection of used terms.
Build System
The build system of Qt is the collection of files that describe how to build Qt from source.
This includes, among others, the project files and all configure-related files.
It does not include QMake, CMake, make or ninja.
Build Tool
In the widest sense, those are tools that contribute to the build.
Common build tools are ninja, make, nmake and jom.
We can count build system generators to the the build tools.
Build System Generator
Build system generators are tools that take a high-level project description as input (e.g. a qmake project file) and output a lower level build system (e.g. a Makefile). Examples are QMake, CMake, gyp or gn.
In-source Build
This means that your build directory is the same as your source directory. This is also called in-tree build.
$ cd qt-source-dir
$ ./configure
$ cmake --build .
$ cmake --install .
Out-of-source Build
This means that your build directory is outside your source directory.
$ mkdir qt-build-dir
$ cd qt-build-dir
$ ../qt-source-dir/configure
$ cmake --build .
$ cmake --install .
This has the advantage that you can have multiple builds of the same source.
Also, it's very easy to do a fresh build by purging your build directory.
Shadow Build
This is just another name for out-of-source build.
Developer Build
A developer build of Qt is meant for developers of Qt.
It differs from a non-developer build in two details:
- It's a non-prefix build if the -prefix configure option is omitted. See below for non-prefix builds.
- It enables private tests. Those are autotests that require symbols to be exported that would be hidden under normal circumstances.
$ mkdir qt-build-dir
$ cd qt-build-dir
$ ../qt-source-dir/configure -developer-build
$ cmake --build .
It's perfectly possible to have a developer prefix build:
$ mkdir qt-build-dir
$ cd qt-build-dir
$ ../qt-source-dir/configure -developer-build -prefix ~/Qt
$ cmake --build .
$ cmake --install .
Prefix Build
This means that you configured Qt with an installation prefix.
$ mkdir qt-build-dir
$ cd qt-build-dir
$ ../qt-source-dir/configure -prefix /opt/qt6
$ cmake --build .
$ cmake --install .
Prefix builds require that you install after building.
Note that, by default, configure uses /usr/local as installation prefix. Unless -developer-build is specified. See below.
Non-prefix Build
This means that you configured Qt without an installation prefix.
This is only possible for developer builds.
$ mkdir qt-build-dir
$ cd qt-build-dir
$ ../qt-source-dir/configure -developer-build
$ cmake --build .
There's no point in installing a non-prefix build.
Technically, the install prefix is set to the build dir, and care is taken by the build system that the necessary files are copied/built into the right place.
Top-level Build
As you probably know, Qt is split into several repositories: qtbase, qtdeclarative, qttools and so on. There's also a "super" repository called "qt5" that bundles everything as git submodules.
A top-level build means building the "super" repository.
Dependencies between the single repositories are automatically resolved by the build system.
Per-repository Build
This is building Qt's single repositories one by one.
Dependencies have to be resolved by the user doing the build.
Per-repository builds can be configured as either prefix or non-prefix builds.
An out-of-source non-prefix build example:
$ mkdir qtbase-build-dir
$ cd qtbase-build-dir
$ ../qtbase-source-dir/configure -developer-build
$ cmake --build .
$ cd ..
$ mkdir qtdeclarative-build-dir
$ cd qtdeclarative-build-dir
$ ../qtbase-build-dir/bin/qt-configure-module ../qtdeclarative
$ cmake --build .
# Repeat for other needed repositories
An out-of-source prefix build example:
$ mkdir qtbase-build-dir
$ cd qtbase-build-dir
$ ../qtbase-source-dir/configure -prefix /opt/qt6
$ cmake --build .
$ cmake --install .
$ cd ..
$ mkdir qtdeclarative-build-dir
$ cd qtdeclarative-build-dir
$ /opt/qt6/bin/qt-configure-module ../qtdeclarative
$ cmake --build .
$ cmake --install .
# Repeat for other needed repositories
debug-and-release build
This means that Qt (or some other project) is configured for building the Debug and Release configurations in the same build directory.
QMake has in-built support for that. Out of the box, two fixed configs are available: debug and release.
For CMake projects, Multi-Config generators (e.g. Ninja Multi-Config) support the build of multiple configurations per build directory.
Framework Build
On Apple platforms, the Qt libraries are built by default as frameworks.
The <install-prefix>/lib/Qt6Core.framework then contains the library and all related header files.
Qt can also be configured as non-framework build by passing -no-framework to configure.
In this case, <install-prefix>/lib contains the libraries as .dylib files, and the header files are placed below <install-prefix>/include.
Qt tests
Starting with Qt 6, Qt's tests can be built in a few ways:
- all tests defined in a repository are built in-tree with the Qt build directory (henceforth called 'in-tree')
- all tests defined in a repository are built in a standalone build directory (called 'standalone tests')
- one specific test is built in a standalone build directory (called 'standalone test')
In-tree tests
To build tests in-tree with the Qt build itself, you need to pass the following configure argument when configuring Qt
$ mkdir qt-build-dir
$ cd qt-build-dir
$ ../qt-source-dir/configure -make tests
$ cmake --build .
$ ctest # to run the tests
The advantage of this approach is that you can build and run the tests from the same build directory as your Qt build directory. The disadvantage is that configuration time and total build time will be longer.
Standalone tests
To build standalone tests in a separate build directory you first need to build at least qtbase, and then you need to use a special shell script provided by the qtbase installation:
$ mkdir qt-build-dir
$ cd qt-build-dir
$ ../qt-source-dir/configure -developer-build
$ cmake --build .
$ cd ..
$ mkdir qtbase-standalone-tests
$ cd qtbase-standalone-tests
$ ../qt-build-dir/bin/qt-internal-configure-tests ../qt-source-dir
$ cmake --build .
$ ctest # to run the tests
The advantage of this approach is that you can build and run the tests from a separate build directory, without affecting overall Qt build times. This approach is what Qt's CI is currently using. The disadvantage is that you have to go through a few steps more than usual.
Single standalone test
Sometimes you just want to build one single test, outside your Qt build directory. You can do that with a special 'qt-cmake-standalone' shell script.
$ mkdir qt-build-dir
$ cd qt-build-dir
$ ../qt-source-dir/configure -developer-build
$ cmake --build .
$ cd ..
$ mkdir tst_qwidget-build-dir
$ cd tst_qwidget-build-dir
$ ../qt-build-dir/bin/qt-cmake-standalone-test ../qt-source-dir/tests/auto/widgets/kernel/qwidget
$ cmake --build .
$ ctest # to run the test
The advantage of this approach is that the configuration time and build time of one test is very fast.
qmake trace file
A qmake trace file for a qmake-based project is produced by passing three -d arguments to qmake:
$ qmake /my/project/sources -d -d -d >qmake.trace 2>&1
CMake trace file
A CMake trace file for a CMake-based project is produced like this:
$ cmake /my/project/sources --trace-expand --trace-redirect=cmake.trace
For a Qt build you would do
$ configure ...more options... -- --trace-expand --trace-redirect=cmake.trace