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.11, 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 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_enable_project_file_updatesEnable API for updating project files. This implies a dependency to the Qt GUI module.
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.
enableProjectFileUpdatesfalseEnable API for updating project files. This is required for an IDE and implies a dependency to the Qt GUI module that would not be needed for the Qbs command-line tool.
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.
enableBundledQttrueHolds 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 Server Core 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

Run the following command to download the Qbs development image based on Debian 9 Stretch:

docker pull qbsbuild/qbsdev:stretch

You can then create a new container with the Qbs source directory mounted from your host machine's file system, by running:

docker run -it -v ${PWD}:/qbs -w /qbs qbsbuild/qbsdev:stretch

You will now be in an interactive Linux shell where you can develop and build Qbs.

For convenience, you can also run docker-compose from the project root directory:

docker-compose run --rm stretch

This will download and run the container in one go and mount the project root directory to /qbs in the container.

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, then run the following command to download the Windows 10 Qbs development image:

docker pull qbsbuild/qbsdev:windowsservercore

You can then create a new container with the Qbs source directory mounted from your host machine's file system, by running:

docker run -it -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore

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 run -it -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore

Building Release Packages

Release packages for Qbs for Windows can be built using the following command on Windows:

docker run --rm -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\make-release-archives

For building release packages for Windows on macOS or Linux:

eval $(docker-machine env windows)
docker run --rm -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\\make-release-archives

© 2018 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.