qmake 手册 003 创建项目文件

项目文件包含 qmake 构建应用程序、库或插件所需的所有信息。通常，我们使用一系列声明来指定项目中的资源，但是，对简单编程构造的支持使我们能够描述不同平台和环境的不同构建过程。

1. 项目文件元素

qmake 使用的项目文件格式既可以用于支持简单的构建系统，也可以用于支持相当复杂的构建系统。简单的项目文件使用简单的声明式风格，定义标准变量来指示项目中使用的源文件和头文件。复杂的项目可以使用控制流结构来微调构建过程。

以下各节介绍项目文件中使用的不同类型的元素。

1.1 变量

在项目文件中，变量用于保存字符串列表。在最简单的项目中，这些变量通知 qmake 有关要使用的配置选项，或者提供要在构建过程中使用的文件名和路径。

qmake 查找每个项目文件中的某些变量，并且它使用这些变量的内容来确定它应该写入 Makefile 的内容。例如，HEADERS 和 SOURCES 变量中的值列表用于告诉 qmake 关于与项目文件位于同一目录中的头和源文件。

1.1.1 扩展变量值

变量还可用于内部存储临时值列表，并且可以用新值覆盖或扩展现有的值列表。

以下代码段说明了如何将值列表分配给变量：

HEADERS = mainwindow.h paintwidget.h

变量中的值列表以下列方式扩展：

SOURCES = main.cpp mainwindow.cpp \
          paintwidget.cpp
CONFIG += console

注意：第一个赋值仅包括与 HEADERS 变量在同一行上指定的值。第二个赋值使用反斜杠 （\） 跨行拆分 SOURCES 变量中的值。

CONFIG 变量是 qmake 生成 Makefile 时使用的另一个特殊变量。我们将在常规配置中讨论它。在上面的代码段中，console 将添加到 CONFIG 中包含的现有值列表中。

1.1.2 常用变量

下表列出了一些常用的变量并简单描述了它们的内容。有关变量及其描述的完整列表，请参见 Variables。

变量	内容
CONFIG	常规项目配置选项
DESTDIR	可执行文件或二进制文件将存放的目录
FORMS	用户界面编译器 (uic)要处理的 UI 文件的列表
HEADERS	构建项目时使用的头文件(.h)文件名列表
QT	项目中使用的 Qt 模块的列表
RESOURCES	要包含在最终项目中的资源 （.qrc） 文件的列表。有关这些文件的详细信息，请参阅 Qt 资源系统
SOURCES	生成项目时要使用的源代码文件的列表
TEMPLATE	用于项目的模板。这决定了构建过程的输出是应用程序、库还是插件

1.1.3 读取变量值

变量的内容可以通过在变量名前面加上 $$ 来读取。这可以用来将一个变量的内容分配给另一个变量:

TEMP_SOURCES = $$SOURCES

$$ 操作符与对字符串和值列表进行操作的内置函数一起被广泛使用。有关更多信息，请参见 qmake 语言

1.2 空格

通常，空格用于分隔为变量分配的值。要指定包含空格的值，必须用双引号将包含空格的值括起来：

DEST = "Program Files"

引号引用的文本在变量持有的值列表中被视为单个项。类似的方法也可用于处理包含空格的路径，尤其是在为 Windows 平台定义 INCLUDEPATH 和 LIBS 变量时：

win32:INCLUDEPATH += "C:/mylibs/extra headers"
unix:INCLUDEPATH += "/home/user/extra headers"

1.3 注释

可以在项目文件添加注释。注释以 # 字符开始，并一直延续到其所在行的末尾。例如:

# Comments usually start at the beginning of a line, but they
# can also follow other content on the same line.

要在变量赋值中包含 # 字符，需要使用内置的 LITERAL_HASH 变量的内容。

1.4 内置功能和控制流程

qmake 提供了许多内置函数，以便处理变量的内容。在简单的项目文件中最常用的函数是 include() 函数，该函数将文件名作为参数。给定文件的内容包含在项目文件中使用include函数的位置。include 函数最常用来包含其他项目文件:

include(other.pro)

对条件结构的支持是通过作用域提供的，作用域的行为类似于编程语言中的 if 语句:

win32 {
    SOURCES += paintwidget_win.cpp
}

仅当条件为 true 时，才在大括号内分配。在这种情况下，必须设置 win32 CONFIG 选项。这在 Windows 上会自动发生。开口支架必须与条件位于同一行上。

只有在条件为真时，大括号内的赋值才会执行。在这种情况下，必须添加 win32 的 CONFIG 设置选项。这在 Windows 上是自动发生的，无需主动添加。注意左大括号必须与条件位于同一行上。

对通常需要循环的变量或更复杂的操作由内置函数，如 find()、unique() 和 count() 提供。这些函数以及其他许多函数用于操作字符串和路径、支持用户输入和调用外部工具。有关使用函数的更多信息，请参见 qmake 语言。有关所有函数及其描述的列表，请参见 替换功能 和 测试功能。

2. 项目模板

TEMPLATE 变量用于定义将要构建的项目的类型。如果在项目文件中没有声明它，qmake 假设应该构建一个应用程序，并将生成一个适当的 Makefile（或等效文件）。

下表总结了可用的项目类型，并描述了 qmake 将为每个项目生成的文件：

Template	qmake 输出
app (default)	构建一个应用程序的 Makefile
lib	构建一个库的 Makefile
aux	什么都不做。如果不需要调用编译器来创建目标，则使用此方法，例如，我们的项目可能是用解释语言编写的。 注意：此模板类型仅适用于基于 Makefile 的生成器。特别是，它不适用于 vcxproj 和 Xcode 生成器。
subdirs	包含使用 SUBDIRS 变量指定的子目录的规则的 Makefile。每个子目录必须包含自己的项目文件
vcapp	用于构建一个应用程序的 Visual Studio 项目文件
vclib	用于构建一个库的 Visual Studio 项目文件
vcsubdirs	在子目录中构建项目的 Visual Studio 解决方案文件

有关为使用 app 和 lib 模板的项目编写项目文件的建议，请参阅构建常见项目类型。

当使用 subdirs 模板时，qmake 生成一个 Makefile 来检查每个指定的子目录，处理它在其中找到的任何项目文件，并在新创建的 Makefile 上运行平台的 make 工具。SUBDIRS 变量可用于包含要处理的所有子目录的列表。

3. 常规配置

CONFIG 变量指定项目应该配置的选项和特性。

项目可以在 debug 或 release 模式下构建，也可以同时在 debug 和 release 模式下构建。如果同时指定了 debug 和 release，则最后一个将生效。如果您指定 debug_and_release 选项来构建项目的 debug 和 release 版本，那么 qmake 生成的 Makefile 包含生成两个版本的规则。这可以通过以下方式调用:

make all

将 build_all 选项添加到 CONFIG 变量会使该规则成为构建项目时的默认规则。

注意: CONFIG 变量中指定的每个选项也可以用作范围条件。我们可以使用内置的 CONFIG() 函数来测试某些配置选项是否存在。例如，下面几行代码将该函数显示为作用域中的条件，以测试是否使用了 opengl 这个选项:

CONFIG(opengl) {
    message(Building with OpenGL support.)
} else {
    message(OpenGL support is not available.)
}

这允许为 debug 和 release 构建定义不同的配置。有关更多信息，请参见 使用条件域。

以下选项定义要构建的项目类型。

注意:其中一些选项只有在相关平台上使用时才生效。

选项	描述
qt	该项目是一个 Qt 应用程序，应针对 Qt 库进行链接。我们可以使用 QT 变量来控制应用程序所需的任何其他 Qt 模块。默认情况下，此值将添加，但我们可以将其删除以用于非 Qt 项目
x11	该项目是一个 X11 应用程序或库。如果目标使用 Qt，则不需要此值

应用程序和库项目模板 为我们提供了更专门的配置选项来优化构建过程。选项将在 构建常见项目类型 中详细说明。

例如，如果我们的应用程序使用 Qt 库，并且我们希望在调试模式下构建它，那么我们的项目文件可以包含以下行:

CONFIG += qt debug

注意: 我们必须使用“+=”，而不是“=”，否则 qmake 将无法使用 Qt 的配置来确定我们的项目所需的设置。

4. 声明 Qt 库

如果 CONFIG 变量包含 qt 值，则启用 qmake 对 qt 应用程序的支持。这样，这样就可以对应用程序使用的 Qt 模块进行微调。这是使用 QT 变量实现的，该变量可用于声明所需的扩展模块。例如，我们可以以下列方式启用 XML 和网络模块：

QT += network xml

注意：QT 默认包含 core 模块和 gui 模块，因此上面的声明将网络和 XML 模块添加到这个默认列表中。以下分配省略了默认模块，并且在编译应用程序的源代码时将导致错误：

QT = network xml # 省略了core 模块和 gui 模块

如果我们想要构建一个没有 gui 模块的项目，我们需要使用“-=”操作符来排除它。默认情况下，QT同时包含 core 模块和 gui 模块，所以下面这行代码将生成一个小一些的 QT 项目:

QT -= gui # 仅使用 core 模块

有关可以添加到 QT 变量的 Qt 模块列表，请参阅 QT 。

5. 配置功能

qmake 可以使用 feature (.prf) 文件中指定的额外配置功能来设置。这些额外的特性通常为构建过程中使用的自定义工具提供支持。要在构建过程中添加要素，将要素名称（要素文件名的词干）追加到 CONFIG 变量中。

例如，qmake 可以配置生成过程，以利用 pkg-config 支持的外部库（如 D-Bus 和 ogg ，使用以下代码行:

CONFIG += link_pkgconfig
PKGCONFIG += ogg dbus-1

有关添加功能部件的更多信息，请参见添加新配置功能部件。

6. 声明其他库

如果除了使用 Qt 提供的库外，我们还使用了其他库，则需要在项目文件中指定它们。

qmake 搜索库的路径和要链接到的特定库可以添加到 LIBS 变量中的值列表中。我们可以指定库的路径，或使用 Unix 样式表示法来指定库和路径。

例如，下面几行显示了如何指定库：

LIBS += -L/usr/local/lib -lmath

可以使用 INCLUDEPATH 变量以类似方式指定包含头文件的路径。

例如，添加几个路径来搜索头文件：

INCLUDEPATH = c:/msdev/include d:/stl/include