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.15, 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:

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:

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:

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.

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