qmake 手册：创建项目文件

官方链接：https://doc.qt.io/qt-6/qmake-project-files.html

创建项目文件

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

项目文件元素

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

以下部分描述了项目文件中使用的不同类型的元素。

变量

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

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

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

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

HEADERS = mainwindow.h paintwidget.h

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

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

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

CONFIG 变量是 qmake 在生成 Makefile 时使用的另一个特殊变量。一般配置中对此进行了讨论。在上面的代码片段中，console 被添加到 CONFIG。

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

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

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

TEMP_SOURCES = $$SOURCES

该 $$ 运算符广泛用于对字符串和值列表进行操作的内置函数。有关更多信息，请参阅qmake 语言。

空格

通常，空格分隔变量赋值中的值。要指定包含空格的值，您必须将值括在双引号中：

DEST = "Program Files"

引用的文本被视为变量保存的值列表中的单个项目。类似的方法用于处理包含空格的路径，特别是在为 Windows 平台定义 INCLUDEPATH 和 LIBS 变量时：

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

注释

您可以向项目文件添加注释。注释以字符 # 开头，一直到同一行的末尾。例如：

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

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

内置函数和控制流程

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

include(other.pro)

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

win32 {
    SOURCES += paintwidget_win.cpp
}

大括号内的赋值仅在条件为真时进行。在这种情况下，必须设置 win32 CONFIG 选项。这在 Windows 上自动发生。左大括号必须与条件位于同一行。

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

项目模板

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

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

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

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

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

一般配置

CONFIG 变量指定项目应配置的选项和功能。

项目可以在发布模式或调试模式下构建，或两者兼而有之。如果同时指定了 debug 和 release，则最后一个生效。如果您指定 debug_and_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.)
}

这使得可以为 release 和 debug 构建定义不同的配置。有关更多信息，请参阅使用作用域。

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

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

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

应用程序和库项目模板为您提供更专业的配置选项来微调构建过程。这些选项在构建通用项目类型中进行了详细说明。

例如，如果您的应用程序使用 Qt 库并且您想在debug模式下构建它，您的项目文件将包含以下行：

CONFIG += qt debug

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

声明 Qt 库

如果 CONFIG 变量包含该 qt 值，则启用 qmake 对 Qt 应用程序的支持。这使得微调您的应用程序使用哪些 Qt 模块成为可能。这是通过 QT 变量实现的，该变量可用于声明所需的扩展模块。例如，我们可以通过以下方式启用 XML 和网络模块：

QT += network xml

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

QT = network xml # This will omit the core and gui modules.

如果要构建没有模块的项目，则 gui 需要使用 “-=” 运算符将其排除。默认情况下，QT 同时包含 core 和 gui，因此以下行将生成一个最小的 Qt 项目：

QT -= gui # Only the core module is used.

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

配置特性

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

例如，qmake 可以配置构建过程以利用 pkg-config 支持的外部库，例如 D-Bus 和 ogg 库，具有以下几行：

CONFIG += link_pkgconfig 
PKGCONFIG += ogg dbus - 1

有关添加特性的更多信息，请参阅添加新配置特性。

声明其他库

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

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

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

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

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

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

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