qdep

一个非常基本但简单易用的依赖管理工具，用于基于 qmake 的项目。

目录

• qdep
  • 特征
  • 设计目标/范围
  • 安装
    • 准备 qmake
    • 壳牌完成
  • 入门
  • 越来越深
    • 依赖 ID
      • 版本控制
      • 包唯一性和版本冲突
    • 正常依赖
      • 翻译
      • 图书馆支持
      • 创建正常的依赖项
        • 创建 qdep 翻译
        • 资源和钩子
        • 自动导出
    • 项目依赖
      • 创建项目依赖项
  • 文档
    • 命令行界面
      • 公共 API 操作：
      • 私有 API 操作：
    • QMAKE-功能
      • 变量
        • 公共变量
        • 子目录扩展
        • 高级变量
      • 配置值
        • 输入值
        • 输出值
        • 定义
      • 环境变量
      • 公开的目标
      • 内部的
        • 变量
        • 配置值
        • QMAKE 测试功能
        • QMAKE 替换函数

<small>使用 markdown-toc 生成的目录</small>

特征

• 在 qmake 项目中无缝集成 - 无需额外文件
• 使用 git 存储库作为包源的基本依赖管理
• 全局缓存源文件以加快构建速度
• 包是目标项目包含的简单 pri 文件
• 递归依赖解决
• 允许基于分支和标签的版本控制
• 支持 qdep 包的翻译
• 支持从动态库中自动导出 qdep 包
• 即使在静态库中使用时，也可以处理 QRC 资源和启动挂钩
• 支持特殊的“项目依赖项”，允许您将整个 qmake 项目添加到 SUBDIRS 项目
• 可以生成“库导出”pri 文件，这些文件提供了一种简单可靠的方式来链接库
  • 隐式支持导出的 qdep 包和项目

设计目标/范围

qdep 的设计考虑了以下目标：

1. 完整的 qmake 集成：qdep 不需要任何额外的命令来安装包和准备要构建的项目。只需在目标项目上运行 qmake 即可解决此问题
2. 安装简单：使用 python 可以在任何平台上轻松使用该工具。除了安装之外，只需要一个安装命令就可以使 qdep 适用于任何 Qt 安装
3. 完整的 Qt 支持：Qt 的所有功能 - 包括资源、启动挂钩和翻译，都应该为应用程序开发人员提供最少的支持
4. 库导出：由于所有 qdep 包都是基于源的，因此使用同一个包的多个库可能会出现问题。使用 qdep，可以从库中“导出”一个包，使其可供所有其他人使用。
5. 没有额外的服务器基础设施：qdep 不应该需要任何额外的服务器来提供包索引。任何 git 存储库都可以作为一个包提供服务，而无需任何额外的准备工作

请注意，qdep 故意保持较小以完全满足这些目标。不支持其他构建系统或更复杂的包管理功能，并且永远不会支持。在 Qt 公司将其构建系统切换到 CMake 之前，该项目将保持活动状态。届时，该项目将被删除或移植到 CMake，具体取决于当时已经存在哪些替代解决方案。

安装

要安装该软件包，请遵循以下可能性之一。请注意，官方仅支持 Python >= 3.7。早期版本可能也可以，但尚未经过测试。

1. Arch Linux：使用 AUR 包：qdep
2. 任何平台：通过 pip 安装：pip install qdep
3. 任何平台：克隆存储库并直接安装源代码：python setup.py install

准备 qmake

安装后（使用 AUR 包时除外），您必须为要使用 qdep 的每个 Qt-Kit “启用” qdep。这可以通过打开终端并调用：

qdep prfgen --qmake "</path/to/qmake>"

C:\Qt例如，如果您在默认位置（

qdep prfgen --qmake "C:\Qt\5.12.0\msvc2017_64\bin\qmake.exe"

注意：根据相应 Qt-Kit 的安装方式，您可能需要以管理员/sudo 权限运行该命令。或者，如果您没有此类权限，您可以调用该命令--dir /some/path并将该路径作为值导出到环境变量。QMAKEPATH

壳牌完成

对于 Unix 系统，qdep 使用argcomplete为 bash/zsh 提供完成以激活它们，在 shell 初始化脚本中添加以下代码：

对于zsh，将其添加到~/.zshrc：

autoload bashcompinit
bashcompinit
autoload compinit
compinit
eval "$(register-python-argcomplete qdep)"

对于bash，将其添加到~/.bashrc：

eval "$(register-python-argcomplete qdep)"

使用 BASH 时，您也可以使用全局完成 -有关详细信息，请参阅激活全局完成。其他 shell 也可以工作，这取决于 argcomplete 与它们的配合程度。请参阅 argcomplete 文档及其 GitHub 存储库。

入门

qdep 的基本用法非常简单。对于此示例，我们假设您希望通过 qdep 将QHotkey添加到项目中。您所要做的就是安装（并准备）qdep，然后将以下两行添加到您的配置文件中：

QDEP_DEPENDS += Skycoder42/QHotkey
!load(qdep):error("Failed to load qdep feature")

而已！下次你运行 qmake 时，qdep 会自动下载最新版本并将它们添加到你的项目中。只需编译项目，您就可以使用该库。一种更明确的方式来指定包（以及较短的字符串延伸到什么）将是https://github.com/Skycoder42/QHotkey.git@1.2.2/qhotkey.pri

越来越深

除了引用 qdep 包的基本功能之外，qdep 还提供了一些额外的东西来使使用（和开发）更容易。在以下部分中，将详细说明它们。

依赖 ID

Qdep 依赖项由 ID 描述。这些 ID 遵循格式<url>[@<version>[/<path>]]。唯一相关的部分是 URL，它可以是隐式的也可以是显式的。隐式 URL 遵循格式<user>/<repository>并自动扩展为https://github.com/<user>/<repository>.git. 对于显式格式，支持各种 GIT-URL，即 HTTPS、SSH 和 FILE url。

如果您省略了 qdep 包的路径部分，qdep 假定<repository_lower>.pri在存储库根目录中有一个名为 pri 的文件。如果不是这种情况，或者如果一个包有多个不同的 pri 文件可供选择，您可以指定一个相对于该 pri 文件的存储库根目录的路径，以使用该文件而不是自动检测到的文件。

版本控制

Qdep 支持 3 种版本控制：Unversioned、branchs、tags。如果您忽略版本，qdep 将自动查询相应的存储库并获取最新标签（通过“创建”）并使用该标签。如果您确实指定了版本，它可以是 git 标签或 git 分支。如果是标签，qdep 将简单地下载它并假设它是持久的，即从不检查该特定标签的更新。然而，引用一个分支将导致 qdep “跟踪”该分支，并且在每次构建之前，qdep 会拉动分支以在必要时进行更新。

一般来说，建议使用显式标签。隐式版本控制也很好，但是包的更新有时可能会破坏您的构建，您不希望它们这样做。分支版本控制总是很危险的，应该只用于明确稳定的分支或包开发。

包唯一性和版本冲突

在使用递归包依赖项时，有时可能会发生两个不同的包包含同一包的不同版本。qdep 通过使 shure 只包含每个软件包的单个版本来规避此问题。引用的第一个版本是选择的版本。然而，显式包路径不被视为同一个包，即可以包含来自同一个 git 存储库的两个不同的 pri 文件。一般来说，一个包的唯一标识符由它<url>和它决定<path>——两者都不区分大小写。

正常依赖

正常依赖，也就是通过指定的 pri-dependenciesQDEP_DEPENDS是 qdep 的主要依赖类型。它们通常解析为一个简单的 pri 文件，该文件由 qdep 包含在您的项目中。您可以在这些 pri 文件中执行任何操作，也可以在“普通”pri 文件中执行任何操作。但是，当包含 qdep 依赖项时，还有一些额外的事情成为可能。

翻译

第一个功能是对翻译的扩展支持。Qdep 包可以为自己的源提供翻译源文件。这些通常通过QDEP_TRANSLATIONSqmake 变量导出。创建您自己的翻译时，qdep 会在构建时自动将这些与您自己的翻译合并。lrelease但是，如果您使用qt 提供的 qmake 功能，则此 onyl 有效。有关更多详细信息，请参阅QMake TRANSLATIONS和QMake QM_FILES_INSTALL_PAT。

图书馆支持

在静态或动态库中使用 qdep 时，通常需要一些特殊步骤才能使其充分发挥作用。但是，qdep 会处理这些步骤并为您执行它们。您唯一需要做的就是从您的库中启用库导出，然后从您的主项目中导入该导出。例如，假设您具有以下项目结构：

root (subdirs)
 |-library (lib)
 |-app (app)

你有一个依赖于 QHotkey 的库。如果你想从应用程序中使用这个库，你将创建库 pro 文件，如下所示：

TEMPLATE = lib
CONFIG += static  # dynamic libraries are also possible, but dependencies must support exporting for them to work on windows

# ...

QDEP_DEPENDS += Skycoder42/QHotkey
QDEP_EXPORTS += Skycoder42/QHotkey
CONFIG += qdep_link_export
!load(qdep):error("Failed to load qdep feature")

然后在 app pro 文件中引用该库。这还负责将库链接到应用程序，因此不需要额外INCLUDEPATH或LIBS更改：

TEMPLATE = app

# ...

QDEP_LINK_DEPENDS += ../library
!load(qdep):error("Failed to load qdep feature")

就是这样！您现在可以在库和应用程序项目中使用 QHotkey，而无需任何额外工作，因为 qdep 将引用现在嵌入到库项目中的 QHotkey。

注意：这也适用于动态库，但前提是明确支持 qdep 包导出。如果没有，链接至少在 Windows 上会失败，并且可能在其他平台上也是如此。

创建正常的依赖项

本部分适用于想要创建自己的 qdep 包的开发人员。一般来说，与创建普通的 pri 包含不同，您需要做的事情并不多。但是，您可以利用 qdep 中的一些小东西来创建更好的包。它们在以下小节中进行了描述，并且是：

• 翻译生成
• 资源和启动钩子
• 自动导出

创建 qdep 翻译

使用 qdep 创建翻译时的唯一区别是放置它们的位置。代替 TRANSLATIONS，创建一个名为 QDEP_TRANSLATIONS 的 qmake 变量并将所有要生成的 ts 文件添加到其中。接下来，调用以下命令，根据您的 pri 文件实际生成 ts 文件：

qdep lupdate --qmake "</path/to/qmake>" --pri-file "</path/to/project.pri>" [-- <extra lupdate arguments>...]

就是这样。您现在应该能够在 pri 文件中指定的位置找到生成的 TS 文件。

在创建应该使用和不使用 qdep 的包时，您可以将以下内容添加到您的 pri 文件中，如果包含的包没有 qdep，则这些翻译仍然可用：

!qdep_build: EXTRA_TRANSLATIONS += $$QDEP_TRANSLATIONS

资源和钩子

可能有问题的一件事，尤其是在使用静态库时，是使用 RESOURCES 和启动挂钩。为了让它工作，qdep 会自动生成代码来加载它们。对于资源，作为包开发人员，您无需做任何特别的事情。

然而，对于钩子，那是另一回事。假设您具有以下要运行的功能Q_COREAPP_STARTUP_FUNCTION：

void my_package_startup_hook()
{
    doStuff();
}

您必须将以下行添加到您的 qdep pri 文件中以使 shure 这个钩子实际被调用：

QDEP_HOOK_FNS += my_package_startup_hook

这样，qdep 将自动生成调用此方法所需的代码Q_COREAPP_STARTUP_FUNCTION。

在创建应该使用和不使用 qdep 的包时，您可以将以下内容添加到包含挂钩函数的 cpp 文件中，以使其适用于非静态项目，即使包含的包没有 qdep：

#ifndef QDEP_BUILD
#include <QCoreApplication>
Q_COREAPP_STARTUP_FUNCTION(my_package_startup_hook)
#endif

自动导出

另一个非常有用的工具是自动包导出。这允许 qdep 自动从动态库中导出 qdep 包，因此链接到该库的其他应用程序可以使用导出的 qdep 包 API。这基本上等同于以下内容：

#ifdef BUILD_PACKAGE_AS_LIBRARY
	#ifdef IS_DLL_BUILD
		#define MY_PACKAGE_EXPORT Q_DECL_EXPORT
	#else
		#define MY_PACKAGE_EXPORT Q_DECL_IMPORT
	#endif
#else
	#define MY_PACKAGE_EXPORT
#endif

class MY_PACKAGE_EXPORT MyClass {
	// ...
};

qdep 基本上自动化了定义部分，因此您不必关心正确定义所有这些宏，并且您的代码可以简化为：

class MY_PACKAGE_EXPORT MyClass {
	// ...
};

要使其工作，只需将以下内容添加到您的 pri 文件中：

QDEP_PACKAGE_EXPORTS += MY_PACKAGE_EXPORT

就是这样！正常使用包时，qdep 会自动添加一个空定义，将 MY_PACKAGE_EXPORT 定义为空。当构建动态库并且最终用户想要导出包时，它被定义为 Q_DECL_EXPORT（以及用于消费应用程序的 Q_DECL_IMPORT）。

在创建应该使用和不使用 qdep 的包时，您可以将以下内容添加到 pri 文件中以手动将宏定义为空，即使该包在没有 qdep 的情况下包含在内：

!qdep_build: DEFINES += "MY_PACKAGE_EXPORT="

项目依赖

除了正常的 pri 依赖之外，qdep 的另一面是完整的项目依赖。在这种情况下，您将一个完整的 qmake 项目作为 SUBDIRS 项目的子项目包含到您的树中。这允许使用 qdep 包导出 pri 文件轻松链接到这些项目。要使用此功能，您必须使用引用 pro 依赖项的子目录项目，以及链接到它的普通项目。使用项目依赖项的一大优势是，它们可以引用它们所依赖的其他项目依赖项，这意味着即使对于完整的项目，qdep 也会为您解决递归依赖项。

首先，假设以下项目结构：

root (subdirs)
  |--libs (subdirs)
  |    |--lib (lib)
  |--app (app)

假设 lib 和 app 都依赖于理论上的 qdep 项目依赖名Skycoder42/SuperLib，但 app 也依赖于 lib。

第一步是选择一个子目录项目来添加依赖项。对于此示例，选择了 libs 项目。添加以下行以添加依赖项：

TEMPLATE = subdirs
SUBDIRS += lib

# ....

QDEP_PROJECT_SUBDIRS += Skycoder42/SuperLib
lib.qdep_depends += Skycoder42/SuperLib
!load(qdep):error("Failed to load qdep feature")

QDEP_PROJECT_SUBDIRS用于实际拉入项目依赖项，而将其添加到仅lib.qdep_depends 确保qdep 依赖项在 lib 之前构建。如果 lib 不依赖于 qdep 依赖项，则不需要这样做。但是，建议始终为 qdep 依赖项创建一个单独的子目录项目，即对于这个具体示例，最好将 lib 项目上移一级或在引用 qdep 依赖项的 libs 中创建另一个子目录项目。

接下来，我们需要在 app/lib 中引用库本身。两者的过程相同，因此这里仅以应用项目为例。在 app pro 文件中，添加以下行：

QDEP_PROJECT_ROOT = libs  # Or "./libs" - would be ".." for the lib project
QDEP_PROJECT_LINK_DEPENDS += Skycoder42/SuperLib
!load(qdep):error("Failed to load qdep feature")

QDEP_PROJECT_ROOT告诉 qdep 项目所在的位置，其中包含对实际 qdep 项目依赖项的引用，并QDEP_PROJECT_LINK_DEPENDS列出该项目（应用程序）所依赖的所有依赖项。如果列出的任何依赖项没有在 libs 项目中通过 指定QDEP_PROJECT_SUBDIRS，则构建将失败。

至此，项目依赖项已成功添加和引用。在下一次构建中，项目将被下载、编译并链接到 app/lib。

创建项目依赖项

一般来说，项目依赖只是普通的qmake项目。但是，这样的项目应该始终包含 qdep 功能并添加qdep_link_export到配置中，因为没有生成的导出 pri 文件，它将不能用作 qdep 项目依赖项。但除此之外，您可以做任何您想做的事情，即添加其他正常的 qdep pri 依赖项等，甚至在需要时导出它们。

但是，还有一个附加功能只有 qdep 项目依赖项才有可能：您可以直接引用其他 qdep 项目依赖项。这样做将确保包含该项目的任何子目录项目也将包含依赖项作为子目录，并确保 qmake 构建顺序，以及引用相应的导出 pri 文件。例如Skycoder42/SuperLib，要从 qdep 项目依赖项中引用，请添加以下内容：

QDEP_PROJECT_DEPENDS += Skycoder42/SuperLib
!load(qdep):error("Failed to load qdep feature")

文档

在以下部分中，qdep 的所有函数、变量等都被记录下来以供参考。

命令行界面

qdep 有一个公共的和一个私有的命令行 API。公共 API 旨在供开发人员使用，而内部 API 由 qdep qmake 功能使用以执行各种操作。以下部分列出了所有命令及其简短说明。有关每个命令的更多详细信息，请键入qdep <command> --help

公共 API 操作：

prfgen     Generate a qmake project feature (prf) for the given qmake.
init       Initialize a pro file to use qdep by adding the required lines.
lupdate    Run lupdate for the QDEP_TRANSLATION variable in a given pri
           file.
clear      Remove all sources from the users global cache.
versions   List all known versions/tags of the given package
query      Query details about a given package identifier
get        Download the sources of one ore more packages into the source
           cache.
update     Check for newer versions of used packages and optionally update
           them.

私有 API 操作：

dephash     Generated unique identifying hashes for qdep
            packages.
pkgresolve  Download the given qdep package and extract relevant
            information from it.
hookgen     Generate a header file with a method to load all
            resource hooks.
hookimp     Generate a source file that includes and runs all
            qdep hooks as normal startup hook.
lconvert    Combine ts files with translations from qdep
            packages.
prolink     Resolve the path a linked project dependency would
            be at.

QMAKE-功能

这是由 qdep 生成并通过添加load(qdep)到项目中加载的 qmake 功能的文档。所有变量、配置标志等都记录在下面。

变量

公共变量

子目录扩展

• qdep_depends：可以添加到项目中传递给SUBDIRS的任何变量，用于QDEP_PROJECT_SUBDIRS指定某个子目录项目依赖于该特定包。这不考虑链接等。它只确保生成目标以正确的顺序构建。

高级变量

配置值

输入值

• qdep_force：强制对 qdep 进行全面评估，即使 pro 文件在没有上下文的情况下进行评估（这有潜在危险，除非绝对必要，否则不应使用）
• qdep_no_pull：不要拉取较新版本的基于分支的依赖项。克隆新软件包仍然有效
• qdep_no_clone：不要克隆全新的包或包版本。拉取已经缓存的分支仍然有效
• qdep_no_cache：不缓存没有指定版本的包的使用版本。相反，每次运行都会查询最新版本
• qdep_export_all：导出所有依赖包，即每个包的任何 QDEP_PACKAGE_EXPORTS 都被视为添加到 QDEP_EXPORTS
• qdep_no_link：当从库中导出包时，不要添加 qmake 代码来链接库（以及它的包含）到 generate export.pri 文件
• qdep_no_qm_combine: 不要将 TRANSLATIONS 与 QDEP_TRANSLATIONS 结合使用。而是将 QDEP_TRANSLATIONS 视为 EXTRA_TRANSLATIONS 并为它们生成单独的 qm 文件
• qdep_link_export：强制创建导出 pri 文件。通常只有未定义 qdep_no_link 的库或指定 qdep_export_all 或在 QDEP_EXPORTS 中有值的项目才会生成此类文件
• qdep_no_export_link: 不要在生成的导出 pri 文件中导出 QT、PKGCONFIG 或 QDEP_LIBS 的内容

输出值

• qdep_build：在正确加载并启用 qdep 功能的情况下设置

定义

• QDEP_BUILD：在正确加载并启用 qdep 功能的情况下定义

环境变量

• QDEP_CACHE_DIR：缓存下载源的目录。为每个系统自动确定，但可以用此变量覆盖
• QDEP_SOURCE_OVERRIDE: 允许提供格式的映射<pkg1>;<pkg2>^<pkg3>;<pkg4>。这将使 qdep 自动替换任何出现的pkg1withpkg2等。开发人员可以使用它来临时覆盖包
• QDEP_DEFAULT_PKG_FN：用于将非 url 包解析User/package为完整 url 的模板。默认方法是https://github.com/{}.git-{}替换为短包名称。

公开的目标

• make lupdate：运行该lupdate工具以快速简便的方式更新您的翻译，而无需依赖可能存在错误的配置文件解析。

内部的

变量

• __QDEP_PRIVATE_SEPERATOR: 数据集之间的分隔符
• __QDEP_TUPLE_SEPERATOR: 数据集中值之间的分隔符
• __QDEP_INCLUDE_CACHE: 包含所有类型的依赖项详细信息的对象
• __QDEP_ORIGINAL_TRANSLATIONS：所有在 TRANSLATIONS 中的原始翻译在应用翻译组合与包含包中的 QDEP_TRANSLATIONS
• __QDEP_HOOK_FILES: 包含必须由项目包含和加载的钩子定义的头文件的路径
• __QDEP_EXPORT_QMAKE_INCLUDE_GUARD：包含导出的 pri 文件的缓存，以确保每个文件只包含一次

配置值

• __qdep_script_version: qdep 可执行文件报告的运行时检测到的版本
• __qdep_dump_dependencies: 在构建目录中创建一个名为 qdep_depends.txt 的文件，其中包含项目的所有直接依赖项

QMAKE 测试功能

• qdepCollectDependencies(dependencies ...)：下载所有指定的正常依赖项并将它们添加到__QDEP_INCLUDE_CACHE稍后由 qdep 链接。递归工作
• qdepCollectProjectDependencies(dependencies ...)：下载所有指定的项目依赖项并将它们添加到SUBDIRS. 递归工作
• qdepResolveSubdirDepends(subdir-vars ...)：将qdep_depends传递给函数的所有变量的子变量的值转换为普通子目录depends子变量
• qdepCreateExportPri(path)：创建一个名为 path 的文件并将所有与导出相关的代码添加到其中
• qdepShellQuote(paths ...): 使给定的路径绝对基于_PRO_FILE_PWD_并使用转义它们shell_quote
• qdepDumpUpdateDeps()：在构建目录中创建一个名为 qdep_depends.txt 的文件，其中包含项目的所有直接依赖项

QMAKE 替换函数

• qdepResolveProjectLinkDeps(project-root, link-depends ...)：将所有依赖链接的项目包解析为子目录路径，假设它们由位于项目根目录的项目提供
• qdepOutQuote(name, values)：创建多行 qmake 代码，以安全引用的方式将 values 中的每个值分配给名为 name 的变量
• qdepLinkExpand(path): 将一个缩短的或相对的路径展开到导出依赖项的项目中，获取导出的pri文件的路径
• qdepResolveLinkRoot(path): 搜索顶级 qmake 项目，该项目包含该项目作为项目依赖项并返回该 pro 文件的路径。根据路径启动搜索，路径必须是构建目录