附录A：构建Qbs

Qbs可以从二进制软件包安装或从源码构建，具体方法在本附录中描述。此外，本附录还说明如何使用Docker镜像来开发Qbs。

支持平台

Qbs可以在以下平台上安装和运行

Windows 7或更高版本
Linux（已测试于Debian 8和9、Ubuntu 16.04、OpenSuSE 13.2和Arch Linux）
macOS 10.7或更高版本

系统要求

要从源代码构建Qbs，您需要

Qt 5.15或更高版本
Windows：MinGW的GCC 4.9或Microsoft Visual Studio 2015或更高版本
Linux：GCC 4.9或更高版本或Clang 3.9.0或更高版本
macOS：Xcode 6.2或更高版本

已安装的工具链必须与Qt编译时使用的一样。

文档

构建Qbs文档需要Python 2.7或3.2或更高版本，以及一些第三方Python模块。这些可以通过pip安装

pip install beautifulsoup4 lxml

生成man页面需要help2man工具。

使用CMake构建Qbs

要构建Qbs，请执行以下命令

mkdir build && cd build
cmake -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ ..
make

${QT_DIR}是Qt安装的目录。如果PATH中已存在qmake，则不需要传递Qt5_DIR选项。

根据您的平台，您可能需要使用mingw32-make、nmake或jom而不是make。

或者，您可以使用Ninja生成器

cmake -GNinja -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ ..
ninja

CMake配置选项

Qbs识别以下CMake选项（以-DOPTION=value的形式传递给CMake），以自定义构建

选项	说明	默认值
WITH_TESTS	启用自动测试。	`ON`
WITH_UNIT_TESTS	启用额外的自动测试。	`OFF`	`OFF`
INSTALL_PUBLIC_HEADERS	是否安装公共头文件。	`ON`

使用ccache与CMake

要启用在构建Qbs时使用ccache，请将以下选项传递给CMake

cmake -DQt5_DIR=${QT_DIR}/lib/cmake/Qt5/ -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache ..

使用QMake构建Qbs

要构建Qbs，请执行以下命令

qmake -r qbs.pro && make

根据您的平台，您可能需要使用mingw32-make、nmake或jom而不是make。

使用make install进行安装通常不是必需的。但是可以通过执行以下命令来实现。

make install INSTALL_ROOT=$INSTALL_DIRECTORY

QMake配置选项

Qbs识别以下qmake CONFIG选项以自定义构建

选项	说明
qbs_enable_unit_tests	启用额外的自动测试。
qbs_disable_rpath	禁用rpath的使用。这可以在为不允许使用rpath的分发版打包Qbs时使用，例如Fedora。
qbs_no_dev_install	排除头文件安装，即进行非开发者构建。
qbs_no_man_install	排除man页面安装。

此外，您还可以在运行 qmake 之前设置 QBS_SYSTEM_SETTINGS_DIR 环境变量，以指定 Qbs 在系统级设置中查找的自定义位置。

使用 Qbs 构建 Qbs

也可以使用之前安装的 Qbs 版本来构建 Qbs。要构建 Qbs，请在源目录下输入以下命令

qbs

这将使用 defaultProfile 或拾取 PATH 中的 Qt 版本和工具链，如果未设置 defaultProfile。有关配置文件的详细信息，请参阅配置配置文件和首选项。

要运行自动测试，应构建 autotest-runner 产品

qbs build -p autotest-runner

Qbs 在运行测试时会使用空配置文件，这意味着它将尝试根据系统环境自动检测工具链、Qt 版本和其他内容。可以通过传递 QBS_AUTOTEST_PROFILE 环境变量来指定在测试运行期间应使用哪个配置文件。应在构建 Qbs 之前设置此变量；否则，应使用 resolve 命令更新存储在构建图中的环境。

export QBS_AUTOTEST_PROFILE=qt
qbs resolve
qbs build -p autotest-runner

还可以为特定测试套件设置一个单独的配置文件。可以为 tst_blackbox_android 套件设置配置文件，如下所示

qbs setup-android pie
export QBS_AUTOTEST_PROFILE_BLACKBOX_ANDROID=pie

设置包含 Qbs 设置的目录可能有设置为隔离测试环境的有用之处

export QBS_AUTOTEST_SETTINGS_DIR=~/path/to/qbs/settings

Qbs 构建选项

可以使用 qbsbuildconfig 模块来自定义构建。可以使用以下方式通过命令行传递该模块的属性

qbs build modules.qbsbuildconfig.enableAddressSanitizer:true

Qbs 识别以下属性

属性	默认值	说明
enableAddressSanitizer	`false`	是否使用地址 sanitizer。启用此选项将为添加 -fsanitize=address 标志。
enableUnitTests	`false`	启用额外的自测。启用此选项将导出一些原本是私有的符号。
enableRPath	`true`	使用此属性禁用 rpath 的使用。当为不允许使用 rpath 的发行版打包 Qbs（如 Fedora）时，可以使用此项。
installApiHeaders	`true`	持是否有安装 Qbs 库的头部文件。此选项是为针对 Qbs 库构建所必需的。
enableBundledQt	`false`	定义 Qbs 依赖的 Qt 库是否在 `install` 步骤与 Qbs 一起打包。此选项仅在 macOS 上实现。
libDirName	`"lib"`	由 `libInstallDir` 和 `importLibInstallDir` 属性使用的目录名称。
appInstallDir	`"bin"`	安装在安装前缀路径下的应用程序二进制文件的相对目录路径。
libInstallDir	Windows 上为 `"bin"`，否则为 `libDirName`	安装在安装前缀路径下的共享库（不包括插件，请参阅 `relativePluginsPath` 属性）的相对目录路径。
importLibInstallDir	`libDirName`	安装在安装前缀路径下的导入库的相对目录路径。
libexecInstallDir	Windows 上为 `appInstallDir`，否则为 `"libexec/qbs"`	安装在安装前缀路径下由 Qbs 库执行的有用二进制文件的相对目录路径。
systemSettingsDir	`undefined`	Qbs 将用于存储其设置的目录。如果未指定，将使用默认的平台相关目录。
installManPage	Unix 上为 `true`，否则为 `false`	是否安装手册页。
installHtml	`true`	是否安装 HTML 帮助页面。
installQch	`false`	是否安装 qch 文件。有关 qch 文件的详细信息，请参阅 Qt 帮助框架。
generatePkgConfigFiles	自动检测	是否生成 pkg-config 文件。
generateQbsModules	自动检测	是否为导出的 Qbs 库生成 Qbs 模块。在用 Qbs 作为构建系统构建其他产品时使用此功能。
docInstallDir	`"share/doc/qbs/html"`	在安装前缀路径下，将文档放入的相对目录路径。
pkgConfigInstallDir	`libDirName` + `"/pkgconfig"`	在安装前缀路径下放置 pkg-config 文件的相对目录路径。
qbsModulesBaseDir	`libDirName` + `"/qbs/modules"`	在安装前缀路径下放置 Qbs 模块的相对目录路径。仅当 `generateQbsModules` 为 `true` 时适用。
relativeLibexecPath	`"../"` + `libexecInstallDir`	相对于应用程序二进制文件的辅助二进制文件的路径。
relativePluginsPath	`"../"` + `libDirName`	相对于应用程序二进制文件放置插件库的路径。
relativeSearchPath	`".."`	查找 Qbs 开发模块和项的目录的相对路径。
libRPaths	自动检测	rpaths 的列表。
resourcesInstallDir	`""`	在安装前缀路径下放置共享资源（如文档、Qbs 用户模块和项）的相对目录路径。
pluginsInstallDir	`libDirName` + `"/qbs/plugins"`	放置插件的目录的相对路径。

使用 Docker

一组用于开发 Qbs 的 Docker 镜像（由 Qbs 团队维护）可在 Docker Hub 上获得。提供 Windows 10 和 Debian Linux 容器类型。

注意：Qbs 开发 Docker 镜像的源代码位于 Qbs 源树中的 docker/ 目录，如果您想自己构建它们。

Linux 容器

开始使用的最简单方法是使用 Linux 容器构建 Qbs。这些类型的容器在所有受支持的宿主平台（Windows、macOS 和 Linux）上预先安装。

这些镜像提供了构建和测试 Qbs 所需的一切。

使用 qmake 构建 Qbs 的 Qt SDK
用于使用 Qbs 构建 Qbs 的最新稳定版本的 Qbs

我们使用 docker-compose 构建 Docker 镜像并运行，因为它简化了 Docker 命令行，并确保使用了正确的镜像标签。所有可用的镜像都列在项目根目录中的 docker-compose.yml 文件中。

运行以下命令下载基于 Ubuntu 20.04 Focal 的 Qbs 开发图像：

docker-compose pull focal

然后，您可以通过运行以下命令从您的宿主机文件系统挂载 Qbs 源目录来创建一个新的容器：

docker-compose run --rm focal

现在，您将处于一个交互式 Linux shell 中，您可以在此开发并构建 Qbs。

Windows 容器

为了使用 Windows 内容器构建 Qbs，您的宿主操作系统必须运行 Windows 10 专业版并且已启用 Hyper-V。请切换您的 Docker 环境，使用 Windows 内容器。

运行以下命令下载基于 Windows 10 的 Qbs 开发图像：

docker-compose pull windows

然后，您可以通过运行以下命令从您的宿主机文件系统挂载 Qbs 源目录来创建一个新的容器：

docker-compose run --rm windows

如果您想在 macOS 或 Linux 宿主机上使用 Windows 容器，您需要创建一个运行 Windows 10 的虚拟机，并将其注册到 docker-machine。至少有一个开源项目通过使用 Packer、Vagrant 和 VirtualBox 来帮助简化这一过程。

在 Unix 宿主机上启动 Windows 容器的 docker run 命令将与 Windows 容器宿主机的 Docker 机器名称（假设为 windows）略有不同

eval $(docker-machine env windows)
docker-compose run --rm windows

构建发布包

在 Windows 上使用以下命令构建 Qbs 的发布包

docker-compose run --rm windows cmd /c scripts\make-release-archives

在 macOS 或 Linux 上构建 Windows 的发布包

eval $(docker-machine env windows)
docker-compose run --rm windows cmd /c scripts\\make-release-archives

参考附录 B：从其他构建系统迁移