Appendix A: Building Qbs
Qbs can be installed from binary packages or built from sources, as described in this appendix. In addition, this appendix describes how to use Docker images for developing Qbs.
Supported Platforms
Qbs can be installed and run on the following platforms:
- Windows 7, or later
- Linux (tested on Debian 8 and 9, Ubuntu 16.04, OpenSuSE 13.2, and Arch Linux)
- macOS 10.7, or later
System Requirements
To build Qbs from the source, you need:
- Qt 5.14, or later
- Windows: MinGW with GCC 4.9 or Microsoft Visual Studio 2015, or later
- Linux: GCC 4.9, or later, or Clang 3.9.0, or later
- macOS: Xcode 6.2, or later
An installed toolchain has to match the one that Qt was compiled with.
Documentation
Building the Qbs documentation requires Python 2.7 or 3.2 or above, as well as some third party Python modules. These can be installed via pip:
pip install beautifulsoup4 lxml
Regenerating the man page requires the help2man tool.
Building Qbs with СMake
To build Qbs, enter the following commands:
mkdir build && cd build cmake -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ .. make
Where ${QT_DIR} is the directory where Qt is installed. Passing the Qt5_DIR option is not necessary if qmake is present in PATH.
Depending on your platform, you might use mingw32-make, nmake, or jom instead of make.
Alternatively, you can use the Ninja generator:
cmake -GNinja -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ .. ninja
CMake Configure Options
Qbs recognizes the following CMake options (passed to CMake in the form of -DOPTION=value) to customize the build:
| Option | Notes | Default value | |
|---|---|---|---|
| WITH_TESTS | Enable autotests. | ON | |
| WITH_UNIT_TESTS | Enable additional autotests. | OFF | OFF |
| INSTALL_PUBLIC_HEADERS | Whether to install public headers. | ON |
Using ccache with CMake
To enable using ccache when building Qbs, pass the following options to CMake:
cmake -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache ..
Building Qbs with QMake
To build Qbs, enter the following command:
qmake -r qbs.pro && make
Depending on your platform, you might use mingw32-make, nmake, or jom instead of make.
Installation by using make install is usually not needed. It is however possible, by entering the following command.
make install INSTALL_ROOT=$INSTALL_DIRECTORY
QMake Configure Options
Qbs recognizes the following qmake CONFIG options to customize the build:
| Option | Notes |
|---|---|
| qbs_enable_unit_tests | Enable additional autotests. |
| qbs_disable_rpath | Disable the use of rpath. This can be used when packaging Qbs for distributions which do not permit the use of rpath, such as Fedora. |
| qbs_no_dev_install | Exclude header files from installation, that is, perform a non-developer build. |
| qbs_no_man_install | Exclude the man page from installation. |
| qbs_use_bundled_qtscript | Use the bundled QtScript library. |
In addition, you can set the QBS_SYSTEM_SETTINGS_DIR environment variable before running qmake to specify a custom location for Qbs to look for its system-level settings.
Building Qbs with Qbs
It is also possible to build Qbs with the previously installed Qbs version. To build Qbs, enter the following command in the source directory:
qbs
This will use the defaultProfile or pick up the Qt version and the toolchain from the PATH if the defaultProfile is not set. See Configuring Profiles and Preferences for details about profiles.
To run automatic tests, the autotest-runner product should be built:
qbs build -p autotest-runner
Qbs will use an empty profile when running tests which means it will try to autodetect toolchains, Qt versions and other things based on the system environment. It is possible to specify which profile should be used during the test-run by passing the QBS_AUTOTEST_PROFILE environment variable. This variable should be set prior to building Qbs itself; otherwise the resolve command should be used to update the environment stored in the buildgraph:
export QBS_AUTOTEST_PROFILE=qt qbs resolve qbs build -p autotest-runner
It is also possible to set up a separate profile for a particular testsuite. A profile for the tst_blackbox_android suite can be set up as follows:
qbs setup-android pie export QBS_AUTOTEST_PROFILE_BLACKBOX_ANDROID=pie
It might be useful to set up the directory with the Qbs settings to isolate the test environment:
export QBS_AUTOTEST_SETTINGS_DIR=~/path/to/qbs/settings
Qbs Build Options
The qbsbuildconfig module can be used to customize the build. Properties of that module can be passed using command line as follows:
qbs build modules.qbsbuildconfig.enableAddressSanitizer:true
Qbs recognizes the following properties:
| Property | Default value | Notes |
|---|---|---|
| enableAddressSanitizer | false | Whether to use address sanitizer or not. Enabling this option will add the -fsanitize=address flag. |
| enableUnitTests | false | Enable additional autotests. Enabling this option will export some symbols that would otherwise be private. |
| enableRPath | true | Use this property to disable the use of rpath. This can be used when packaging Qbs for distributions which do not permit the use of rpath, such as Fedora. |
| installApiHeaders | true | Holds whether to install the header files for the Qbs libraries or not. This option is required to build against the Qbs libraries. |
| enableBundledQt | false | Holds whether the Qt libraries that Qbs depends on will be bundled with Qbs during the install step. This option is only implemented on macOS. |
| useBundledQtScript | false | Use the bundled QtScript module instead of the one shipped with Qt. In that case, QtScript should be checked out as a git submodule. |
| libDirName | "lib" | Directory name used by libInstallDir and importLibInstallDir properties. |
| appInstallDir | "bin" | Relative directory path under the install prefix path to put application binaries. |
| libInstallDir | "bin" on Windows, libDirName otherwise | Relative directory path under the install prefix path where to put shared libraries (excluding plugins, see the relativePluginsPath property). |
| importLibInstallDir | libDirName | Relative directory path under the install prefix path where to put import libs. |
| libexecInstallDir | appInstallDir on Windows, "libexec/qbs" otherwise | Relative directory path under the install prefix path where to put auxiliary binaries executed by the Qbs libraries. |
| systemSettingsDir | undefined | Directory that will be used by Qbs to store its settings. If not specified, a default platform-dependent directory is used. |
| installManPage | true on Unix, false otherwise | Whether to install man pages. |
| installHtml | true | Whether to install HTML help pages. |
| installQch | false | Whether to install qch files. See The Qt Help Framework for details about qch files. |
| generatePkgConfigFiles | auto-detected | Whether to generate files for pkg-config. |
| generateQbsModules | auto-detected | Whether to generate Qbs modules for the exported Qbs libraries. Use this when building another product against Qbs libraries using Qbs as build system. |
| docInstallDir | "share/doc/qbs/html" | Relative directory path under the install prefix path where to put documentation. |
| pkgConfigInstallDir | libDirName + "/pkgconfig" | Relative directory path under the install prefix path where to put pkg-config files. |
| qbsModulesBaseDir | libDirName + "/qbs/modules" | Relative directory path under the install prefix path where to put Qbs modules. Applies only when generateQbsModules is true. |
| relativeLibexecPath | "../" + libexecInstallDir | Path to the auxiliary binaries relative to the application binary. |
| relativePluginsPath | "../" + libDirName | Path to plugin libraries relative to the application binary. |
| relativeSearchPath | ".." | Relative path to the directory where to look for Qbs development modules and items. |
| libRPaths | auto-detected | List of rpaths. |
| resourcesInstallDir | "" | Relative directory path under the install prefix path where to put shared resources like documentation, Qbs user modules and items. |
| pluginsInstallDir | libDirName + "/qbs/plugins" | Relative path to the directory where to put plugins to. |
Using Docker
A set of Docker images for developing Qbs (which are maintained by the Qbs team) is available on Docker Hub. Both Windows 10 and Debian Linux container types are available.
Note: The source code for the Qbs development Docker images is located in the docker/ directory of the Qbs source tree, if you wish to build them yourself.
Linux Containers
The easiest way to get started is to build Qbs using a Linux container. These types of containers are supported out of the box on all the supported host platforms: Windows, macOS, and Linux.
The images provide everything that is necessary to build and test Qbs:
- Qt SDK for building Qbs with
qmake - Latest stable release of Qbs for building Qbs with Qbs
We are using docker-compose for building and running the Docker images because it simplifies the Docker command line and ensures that the correct image tag is used. All available images are listed in the docker-compose.yml file in the project root directory.
Run the following command to download the Qbs development image based on Ubuntu 20.04 Focal:
docker-compose pull focal
You can then create a new container with the Qbs source directory mounted from your host machine's file system, by running:
docker-compose run --rm focal
You will now be in an interactive Linux shell where you can develop and build Qbs.
Windows Containers
To build Qbs for Windows using Windows containers, your host OS must be running Windows 10 Pro and have Hyper-V enabled. Switch your Docker environment to use Windows containers.
We are using docker-compose for building and running the Docker images because it simplifies the Docker command line and ensures that the correct image tag is used. All available images are listed in the docker-compose.yml file in the project root directory.
Run the following command to download the Qbs development image based on Windows 10:
docker-compose pull windows
You can then create a new container with the Qbs source directory mounted from your host machine's file system, by running:
docker-compose run --rm windows
If you want to use Windows containers on a macOS or Linux host, you will have to create a virtual machine running Windows 10 and register it with docker-machine. There is at least one Open Source project that helps to facilitate this by using using Packer, Vagrant, and VirtualBox.
The docker run command to spawn a Windows container on a Unix host will look slightly different (assuming windows is the name of the Docker machine associated with the Windows container hosting VM):
eval $(docker-machine env windows) docker-compose run --rm windows
Building Release Packages
Release packages for Qbs for Windows can be built using the following command on Windows:
docker-compose run --rm windows cmd /c scripts\make-release-archives
For building release packages for Windows on macOS or Linux:
eval $(docker-machine env windows) docker-compose run --rm windows cmd /c scripts\\make-release-archives