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:

OptionNotesDefault value
WITH_TESTSEnable autotests.ON
WITH_UNIT_TESTSEnable additional autotests.OFFOFF
INSTALL_PUBLIC_HEADERSWhether 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:

OptionNotes
qbs_enable_unit_testsEnable additional autotests.
qbs_disable_rpathDisable 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_installExclude header files from installation, that is, perform a non-developer build.
qbs_no_man_installExclude the man page from installation.
qbs_use_bundled_qtscriptUse 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:

PropertyDefault valueNotes
enableAddressSanitizerfalseWhether to use address sanitizer or not. Enabling this option will add the -fsanitize=address flag.
enableUnitTestsfalseEnable additional autotests. Enabling this option will export some symbols that would otherwise be private.
enableRPathtrueUse 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.
installApiHeaderstrueHolds whether to install the header files for the Qbs libraries or not. This option is required to build against the Qbs libraries.
enableBundledQtfalseHolds whether the Qt libraries that Qbs depends on will be bundled with Qbs during the install step. This option is only implemented on macOS.
useBundledQtScriptfalseUse 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 otherwiseRelative directory path under the install prefix path where to put shared libraries (excluding plugins, see the relativePluginsPath property).
importLibInstallDirlibDirNameRelative directory path under the install prefix path where to put import libs.
libexecInstallDirappInstallDir on Windows, "libexec/qbs" otherwiseRelative directory path under the install prefix path where to put auxiliary binaries executed by the Qbs libraries.
systemSettingsDirundefinedDirectory that will be used by Qbs to store its settings. If not specified, a default platform-dependent directory is used.
installManPagetrue on Unix, false otherwiseWhether to install man pages.
installHtmltrueWhether to install HTML help pages.
installQchfalseWhether to install qch files. See The Qt Help Framework for details about qch files.
generatePkgConfigFilesauto-detectedWhether to generate files for pkg-config.
generateQbsModulesauto-detectedWhether 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.
pkgConfigInstallDirlibDirName + "/pkgconfig"Relative directory path under the install prefix path where to put pkg-config files.
qbsModulesBaseDirlibDirName + "/qbs/modules"Relative directory path under the install prefix path where to put Qbs modules. Applies only when generateQbsModules is true.
relativeLibexecPath"../" + libexecInstallDirPath to the auxiliary binaries relative to the application binary.
relativePluginsPath"../" + libDirNamePath to plugin libraries relative to the application binary.
relativeSearchPath".."Relative path to the directory where to look for Qbs development modules and items.
libRPathsauto-detectedList of rpaths.
resourcesInstallDir""Relative directory path under the install prefix path where to put shared resources like documentation, Qbs user modules and items.
pluginsInstallDirlibDirName + "/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