Qbs Manual | Appendix A: Building Qbs

Qbs 1.12.1

Reference ◦ Appendix B: Migrating from Other Build Systems

# 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.9, 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

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

## 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_enable_project_file_updates | Enable API for updating project files. This implies a dependency to the Qt GUI module.
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.

## 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. Run the following 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

Or with a slightly different syntax for Windows:

      docker run -it -v %CD%:/qbs -w /qbs qbsbuild/qbsdev:stretch

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, 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

Reference ◦ Appendix B: Migrating from Other Build Systems