Qt Creator 源码学习 04：qtcreator.pri

2K

上一章我们已经分析过项目文件 qtcreator.pro。我们看到，qtcreator.pro 中很多重要的功能都使用了来自 qtcreator.pri 中定义的函数或者变量。本章我们就来看看 qtcreator.pri 是怎么写的。

!isEmpty(QTCREATOR_PRI_INCLUDED):error("qtcreator.pri already included")
QTCREATOR_PRI_INCLUDED = 1

第一行，如果存在QTCREATOR_PRI_INCLUDED，则抛出错误。下面一行则设置了QTCREATOR_PRI_INCLUDED。这两行类防止将 qtcreator.pri 引入多次。

QTCREATOR_VERSION = 4.1.82
QTCREATOR_COMPAT_VERSION = 4.1.82
VERSION = $QTCREATOR_VERSION
BINARY_ARTIFACTS_BRANCH = master

接下来定义了几个变量：QTCREATOR_VERSION即 Qt Creator 的版本；QTCREATOR_COMPAT_VERSION是插件所兼容的 Qt Creator 版本；VERSION同样被赋值为 Qt Creator 的版本；BINARY_ARTIFACTS_BRANCH指定的是 git 的分支。值得说明的是VERSION。这其实是 qmake 定义的变量，当template是app时，用于指定应用程序的版本号；当template是lib时，用于指定库的版本号。在 Windows 平台，如果没有指定RC_FILE和RES_FILE变量，则会自动生成一个 .rc 文件。该文件包含FILEVERSION和PRODUCTVERSION两个字段。VERSION应该由主版本号、次版本号、补丁号和构建版本号等组成。每一项都是 0 到 65535 之间的整型。例如：

win32:VERSION = 1.2.3.4 # major.minor.patch.build
else:VERSION = 1.2.3    # major.minor.patch

下面是两个重要的函数定义。这两个函数都是用于生成库名字的。

defineReplace(qtLibraryTargetName) {
   unset(LIBRARY_NAME)
   LIBRARY_NAME = $1
   CONFIG(debug, debug|release) {
      !debug_and_release|build_pass {
          mac:RET = $member(LIBRARY_NAME, 0)_debug
              else:win32:RET = $member(LIBRARY_NAME, 0)d
      }
   }
   isEmpty(RET):RET = $LIBRARY_NAME
   return($RET)
}

defineReplace(qtLibraryName) {
   RET = $qtLibraryTargetName($1)
   win32 {
      VERSION_LIST = $split(QTCREATOR_VERSION, .)
      RET = $RET$first(VERSION_LIST)
   }
   return($RET)
}

说重要，是因为这两个函数在 Qt Creator 中使用了多次，并且完全可以拷贝复制到其它项目继续使用。

前面我们说过，qmake 提供了替换函数和测试函数。这里就是自定义替换函数。定义替换函数使用的语句是defineReplace，其参数是函数名字。例如，上面我们定义了qtLibraryTargetName这个函数，那么就可以在后面直接使用：

message($qtLibraryTargetName(LIB_NAME))

注意，我们说过，qmake 是按照从上到下顺序解析，所以在使用必须在定义之后才能正常执行。

下面来看qtLibraryTargetName是如何定义的。首先，取消LIBRARY_NAME的定义，然后使用语句LIBRARY_NAME = $$1赋值。定义函数时可以有参数，使用$$1即获取该参数。这里，我们将$$1，也就是第一个参数，赋值给变量LIBRARY_NAME。下面是CONFIG测试函数，该函数可以用于检测CONFIG变量中的值。CONFIG是一个重要变量，用于指定编译参数，例如我们可以在这里设置 debug 或 release；其可选值可以查阅相关文档。如下面语句：

CONFIG = debug

CONFIG可以使用 scope 语法来判断，例如

debug {
    message(IN DEBUG MODE)
}

也可以使用CONFIG测试函数。CONFIG测试函数的优势在于，可以使用第二个参数来从一组值中选取一个需要的。要理解这一点，先看如下语句：

CONFIG = debug
CONFIG += release

上面语句中，CONFIG首先被设置为 debug，其后又被设置为 release。CONFIG的赋值顺序非常重要，在一组互斥的值之间（例如 debug 和 release），最后面的会被认为是激活的。正如上面语句，CONFIG会被认为是 release 的。CONFIG测试函数的第二个参数，正是用于指定这一组值。例如，

CONFIG = debug
CONFIG += release
CONFIG(release, debug|release):message(Release build!) #will print
CONFIG(debug, debug|release):message(Debug build!) #no print

CONFIG函数指定仅测试 debug 和 release 两个值，而 release 是激活的，因此会输出“Release build!”。通常情况下，第二个参数不大需要，但是如果需要针对某些特殊互斥值进行测试，就可以使用这个参数。

回过头来看 qtcreator.pri 中的语句。CONFIG函数测试如果是 debug，则执行后面的语句。!debug_and_release|build_pass是 scope 语法，即当不是 release_and_release 或者 build_pass 时，对于 mac，将RET赋值为$$member(LIBRARY_NAME, 0)_debug，win 则是RET = $$member(LIBRARY_NAME, 0)d。release_and_release 意味着同时编译 debug 和 release 两个版本；build_pass 即构建过程。member(variablename, position)是一个替换函数，返回variablename中第position个元素；没有找到的话则返回空串。variablename是必须的，position默认是 0，也就是会返回第一个元素。仔细研究$$member(LIBRARY_NAME, 0)_debug语句，如果LIBRARY_NAME为 core 的话，那么，语句的返回值将是core_debug。接下来，如果RET为空，也就是不是 debug 的情况下，直接将其赋值为LIBRARY_NAME；这是为了防止得到一个空的RET。最后将RET返回。

综上所述，qtLibraryTargetName函数实现了这样一种功能：当使用 debug 环境编译时，在 mac 下生成的库名称将被重命名追加_debug，win 下则追加d。因此，当我们使用如下语句时，

message($qtLibraryTargetName(core))

在 debug 环境下，结果是 core_debug 或者 cored；否则是 core。值得说明的是，这并不是唯一的实现方法。另外的版本中往往使用下面语句：

CONFIG(debug, debug|release) {
    mac: TARGET = $join(TARGET,,,_debug)
    else: TARGET = $join(TARGET,,,d)
}

该实现与上面结果一致，只是使用了join函数。函数原型为join(variablename, glue, before, after)，会将variablename使用glue连接起来，同时在连接之后的字符串前面添加before，后面添加after。注意看这里的使用，$$join(TARGET,,,_debug)，第二个参数为空，因此将variablename与空串相连，由于这是传入的是TARGET，是一个字符串而不是列表，与空串相连结果还是其本身；before为空，即前面不增加内容；after为_debug，即最后增加_debug后缀。由此看出，使用这种语句也可以达到相同的目的。

qtLibraryName替换函数与此类似。首先，它会获得qtLibraryTargetName的返回值。如果 win32 环境下，使用split将前面定义的QTCREATOR_VERSION以.为分隔符分成列表，然后使用$$RET$$first(VERSION_LIST)语句，将RET与VERSION_LIST的第一个元素，也就是 major 值，拼接后返回。这是因为，在 Windows 平台，为了避免出现 dll hell，Qt 会自动为生成的 dll 增加版本号。而我们一般只需要主版本一致即可，所以会重新生成新的名字。dll hell 只发生在 Windows 平台，因此这里只需要判断 win32 即可。

接下来定义了一个测试函数：

defineTest(minQtVersion) {
    maj = $1
    min = $2
    patch = $3
    isEqual(QT_MAJOR_VERSION, $maj) {
        isEqual(QT_MINOR_VERSION, $min) {
            isEqual(QT_PATCH_VERSION, $patch) {
                return(true)
            }
            greaterThan(QT_PATCH_VERSION, $patch) {
                return(true)
            }
        }
        greaterThan(QT_MINOR_VERSION, $min) {
            return(true)
        }
    }
    greaterThan(QT_MAJOR_VERSION, $maj) {
        return(true)
    }
    return(false)
}

与替换函数类似，定义测试函数使用defineTest语句。defineTest(minQtVersion)定义了一个名为minQtVersion的测试函数。该函数有三个参数，这可以从下面的三行看出来。这个函数的定义很简单，只不过使用了几个 qmake 预定义的宏进行判断。不过这些也可以从名字看出其实际含义。

下面又定义了一个替换函数：

# For use in custom compilers which just copy files
defineReplace(stripSrcDir) {
    return($relative_path($absolute_path($1, $OUT_PWD), $_PRO_FILE_PWD_))
}

按照注释的说明，这个函数用于自定义编译器复制文件。函数absolute_path(path[, base])返回参数path的绝对路径；如果没有传入base，则将当前目录作为path的 base。与此类似，函数relative_path(filePath[, base])返回参数path的相对路径。

有关“PWD”的几个内置变量是非常常用的。很多时候，我们希望在构建时自动复制一些文件到目标路径，往往需要使用这些变量。这些变量有：

PWD	使用该变量PWD的文件（.pro 文件或者 .pri 文件）所在目录。
_PRO_FILE_PWD_	.pro 文件所在目录；即使该变量出现在 .pri 文件，也是指包含该 .pri 文件的 .pro 文件所在目录。
_PRO_FILE_	.pro 文件完整路径。
OUT_PWD	生成的 makefile 所在目录。

注意，由于 qmake 无法使用只读变量，因此必须时刻警惕不要覆盖这些内置变量的值，否则会发生未知的错误。

下面几行，

QTC_BUILD_TESTS = $(QTC_BUILD_TESTS)
!isEmpty(QTC_BUILD_TESTS):TEST = $QTC_BUILD_TESTS

...

即使用用户传入值，如果没有，则需要设置一个默认值。这些我们前面已经提到过，这里不再赘述。

下面开始重要的构建路径部分。说重要，是因为 Qt Creator 编译之后生成的文件应该保存在哪里，都是在这里定义的。

IDE_SOURCE_TREE = $PWD
isEmpty(IDE_BUILD_TREE) {
    sub_dir = $_PRO_FILE_PWD_
    sub_dir ~= s,^$re_escape($PWD),,
    IDE_BUILD_TREE = $clean_path($OUT_PWD)
    IDE_BUILD_TREE ~= s,$re_escape($sub_dir)$,,
}

IDE_SOURCE_TREE即源代码所在目录。注意我们使用了$$PWD变量直接赋值：这个值会随着 .pro 文件或 .pri 文件的不同位置而有所不同，但都应由此找到源代码树。这是目录组织中需要注意的问题。

函数re_escape(string)将参数string中出现的所有正则表达式中的保留字进行转义。例如，()是正则表达式的保留字，那么，$$re_escape(f(x))的返回值将是f\\(x\\)。这一函数的目的是保证获得一个合法的正则表达式。函数re_escape(path)将参数path中的.以及..等占位符移除，获得一个明确的路径。我们用下面的实验来证明这一点。目录结构如下：

/test
|-application.pro(TEMPLATE=subdirs; SUBDIRS=src)
|-application.pri
|-src
   |-src.pro(TEMPLATE=subdirs; SUBDIRS=app)
   |-app
      |-app.pro(TEMPLATE=app; include(../../application.pri))

其中，application.pri 内容如下：

isEmpty(IDE_BUILD_TREE) {
    sub_dir = $_PRO_FILE_PWD_
message($_PRO_FILE_PWD_) # 输出=E:/Workspace/test/src/app
message($PWD) # 输出=E:/Workspace/test
    sub_dir ~= s,^$re_escape($PWD),,
message($sub_dir) # 输出=/src/app
    IDE_BUILD_TREE = $clean_path($OUT_PWD)
    IDE_BUILD_TREE ~= s,$re_escape($sub_dir)$,,
message($OUT_PWD) # 输出=E:/Workspace/build-test-Desktop_Qt_5_7_0_MSVC2015_64bit-Debug/src/app
message($IDE_BUILD_TREE) # 输出=E:/Workspace/build-test-Desktop_Qt_5_7_0_MSVC2015_64bit-Debug
}

仔细观察以上输出，可以看到，IDE_BUILD_TREE最终得到的是输出根目录。不管是否启用了 shadow build，这一段代码都能够适用。因此，我们也不妨将其添加到我们自己的工具库中，以便在未来项目中使用。

下面一行

IDE_APP_PATH = $IDE_BUILD_TREE/bin

设置了最终输出的二进制文件的位置，也就是在根目录下的 bin 目录中。接下来很多行都是设置目录位置，因为语法都很简单，这里不再详细介绍。可以看出，Qt Creator 编译过程中所有的输出位置，都是基于IDE_BUILD_TREE这个变量。由此顺利组织我们所需要的输出文件夹树，是很有用的。

INCLUDEPATH += \
    $IDE_BUILD_TREE/src \ # for <app/app_version.h> in case of actual build directory
    $IDE_SOURCE_TREE/src \ # for <app/app_version.h> in case of binary package with dev package
    $IDE_SOURCE_TREE/src/libs \
    $IDE_SOURCE_TREE/tools

INCLUDEPATH给出了头文件检索目录。这有利于我们#include头文件。如果不是设置该值，在#include时需要给出全路径。例如目录结构如下：

/
|-core
|   |-include
|      |-global.h
|-lib
    |-library.cpp

如果 library.cpp 中需要#include core 的 global.h，需要写作

#include "../core/include/global.h"

如果添加

INCLUDEPATH += core

那么只需要写作

#include "include/global.h"

即可。

下面来看 Qt Creator 是怎么做的。由于 Qt Creator 会在每次编译时自动生成一个 app_version.h，包含 Qt Creator 的版本信息（每次自动更新构建版本号，具体生成过程会在后文详细介绍），所有自动生成的代码文件都会出现在$$IDE_BUILD_TREE/src，因此，Qt Creator 首先将$$IDE_BUILD_TREE/src添加到了INCLUDEPATH。然后，Qt Creator 中的 libs 会被各个插件使用，这是库文件而不属于插件，为了能够使用类似

#include "extensionsystem/pluginmanager.h"

这样的语句，而不是一连串的“../../../libs/extensionsystem/pluginmanager.h”，Qt Creator 会将$$IDE_SOURCE_TREE/src/libs添加到INCLUDEPATH。

下面的语句

QTC_PLUGIN_DIRS_FROM_ENVIRONMENT = $(QTC_PLUGIN_DIRS)
QTC_PLUGIN_DIRS += $split(QTC_PLUGIN_DIRS_FROM_ENVIRONMENT, $QMAKE_DIRLIST_SEP)
QTC_PLUGIN_DIRS += $IDE_SOURCE_TREE/src/plugins
for(dir, QTC_PLUGIN_DIRS) {
    INCLUDEPATH += $dir
}

展示了for语法的使用，这非常类似于 C++ 的for_each循环。

LIBS *= -L$LINK_LIBRARY_PATH  # Qt Creator libraries
exists($IDE_LIBRARY_PATH): LIBS *= -L$IDE_LIBRARY_PATH  # library path from output path

LIBS是 qmake 连接第三方库的配置。-L指定了第三方库所在的目录；-l指定了第三方库的名字。如果没有-l，则会连接-L指定的目录中所有的库。这正是 Qt Creator 的用法。Qt Creator 需要使用LINK_LIBRARY_PATH中所有库。注意，因为我们使用按顺序编译的方式，所以 qmake 能够保证先生成再链接这些库文件。

DEFINES += QT_CREATOR QT_NO_CAST_TO_ASCII QT_RESTRICTED_CAST_FROM_ASCII
!macx:DEFINES += QT_USE_FAST_OPERATOR_PLUS QT_USE_FAST_CONCATENATION

DEFINES类似于宏定义，相当于使用类似

gcc -DQT_CREATOR

这样的语句。因此，我们可以在源代码中使用$ifdef条件编译。

注意在使用中，有的是+=运算符，有的是*=运算符。前者是追加；后者是没有则追加，有则不作操作，也就是保持存在且唯一。

最后我们来看一段复杂的代码：

# recursively resolve plugin deps
done_plugins =
for(ever) {
    isEmpty(QTC_PLUGIN_DEPENDS): \
        break()
    done_plugins += $QTC_PLUGIN_DEPENDS
    for(dep, QTC_PLUGIN_DEPENDS) {
        dependencies_file =
        for(dir, QTC_PLUGIN_DIRS) {
            exists($dir/$dep/${dep}_dependencies.pri) {
                dependencies_file = $dir/$dep/${dep}_dependencies.pri
                break()
            }
        }
        isEmpty(dependencies_file): \
            error("Plugin dependency $dep not found")
        include($dependencies_file)
        LIBS += -l$qtLibraryName($QTC_PLUGIN_NAME)
    }
    QTC_PLUGIN_DEPENDS = $unique(QTC_PLUGIN_DEPENDS)
    QTC_PLUGIN_DEPENDS -= $unique(done_plugins)
}

按照注释，这是递归处理插件依赖。ever是一个常量，永远不会为false或空值，因此for(ever)是无限循环，直到使用break()跳出。如果QTC_PLUGIN_DEPENDS为空，则直接退出循环。事实上，QTC_PLUGIN_DEPENDS默认没有设置，所以这段代码其实并没有使用。这段代码的目的是，允许用户在编译时直接通过QTC_PLUGIN_DEPENDS指定插件依赖。如果没有，则根据每个插件自己的依赖处理。后面的for循环遍历QTC_PLUGIN_DEPENDS中指定的每一个依赖，然后用另外一个嵌套的循环遍历$$QTC_PLUGIN_DIRS指定的插件目录中的每一个目录，找出对应的插件，取其对应的 .pri 文件，即dependencies_file。注意循环的最后，使用-=运算符移除每次处理的依赖，直到最后QTC_PLUGIN_DEPENDS为空，退出循环。

最末的done_libs的处理与此类似。