Qt-QMake官方使用手册（翻译）

最新推荐文章于 2025-05-29 09:09:10 发布

原创

最新推荐文章于 2025-05-29 09:09:10 发布 · 1.1k 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#Qt #qmake #QMake

本文翻译自Qt 4.8官方文档。

一、QMake使用

QMake提供了一个用于管理应用程序、库、其它组件的构建过程的面向工程系统。
QMake扩展了每个工程文件的信息，生成一个执行编译和链接过程的必须命令的MakeFile。

1、描述工程

工程文件.pro描述了工程信息。工程文件信息会被qmake用于生成包含构建过程中所需的所有命令的MakeFile。工程文件通常包含一系列头文件和源文件，通用配置信息以及音乐程序指定的细节，如应用程序的链接库、搜索路径。
工程文件包含一定数量的不同元素，如注释、变量声明、内置函数以及简单的控制结构。在大多数简单的工程中，只需要声明使用简单配置选项构建工程的源文件和头文件即可。

2、构建工程

对于简单的工程，只需要在工程的顶层目录运行qmake。默认情况下，qmake会生成一个构建工程的MakeFile，此时可以运行平台相关的make工具构建工程。
qmake也能用于生成工程文件。

3、预编译头文件

在大型工程中，可以利用预编译头文件的优势加速构建过程。

二、QMake工程文件

1、工程文件基本元素

工程文件包含qmake构建应用、库、插件的所有必须信息。工程使用的资源通常使用一系列声明指定，但支持用于描述不同平台和环境的不同构建过程的简单编程结构。
qmake使用的工程文件格式支持简单和相对复杂的构建系统。简单工程文件使用直接声明风格，定义标准变量指明工程需要的头文件和源文件。复杂工程可能需要使用流控制结构微调构建过程。
工程文件中不同类型的元素如下：
A、变量
工程文件中，变量用于保存字符串列表。简单工程中，变量会告诉qmake使用的配置选项，提供在构建过程中使用的文件名和路径。
qmake会在工程文件中查找某些变量，变量的内容将决定哪些内容会生成到MakeFile。例如，HEADERS和SOURCES变量的列表值会告诉qmake相关的头文件和源文件（工程文件所在目录）。
变量可以用于存储临时的列表值，覆写存在的列表值或是扩展新的值。下列代码显示了如何赋值列表值给变量：
HEADERS = mainwindow.h paintwidget.h
注意：第一种赋值方法只包括同一行指定的值。第二种赋值方法会使用“\”字符分隔列表值的项。
变量的列表值可以使用如下方式扩展：

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

CONFIG是一个qmake生成MakeFile文件时的特殊变量。
qmake会识别下列变量的值，并描述变量的内容。
CONFIG：通用工程配置选项
DESTDIR：可执行文件或库文件的输出目录
FORMS：由uic处理的UI文件列表
HEADERS：构建工程使用的头文件列表
QT：Qt相关配置选项
RESOURCES：包含到最终工程的资源文件列表
SOURCES：用于构建工程的源文件列表
TEMPLATE：构建工程的模板，决定构建过程输出一个应用，一个库或是一个插件
变量的内容可以通过在变量名称前加“$$”符号来访问，用于将一个变量的内容赋值给另一个变量。
TEMP_SOURCES = $$SOURCES
$$操作符可以被扩展用于操作字符串和值列表的内置函数中。
通常，变量用于包含空格分隔符的值列表，但有时需要指定包含空格的值，必须使用双引号包含。
DEST = "Program Files"
引号内的文本在值列表内作为单个值对待。类似的方法可以用于处理包含空格的路径，尤其是在Windows平台定义INCLUDEPATH和LIBS变量。

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

B、注释
可以在工程文件中增加注释。注释需要#符号开头，直到#所在行结束。

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

为了在变量赋值中包括#，必须使用内置变量LITERAL_HASH。
C、内置函数和控制流
qmake提供了多个内置函数用于处理变量内容。在简单工程中，最常使用的函数是使用一个文件名作为参数的include函数。在工程文件中，给定文件的内容会被包含在include函数调用的位置。include函数最常用于包含其它工程文件.pro。
include(other.pro)
通过代码块作用域可以实现类似编程语言中IF语句的行为，支持条件控制结构。

win32 {
        SOURCES += paintwidget_win.cpp}

只有条件为true时，括号内的赋值才会有效。在这个例子中，特殊变量win32必须被设置。在 Windows平台上，win32会自动设置。当在其它平台上，通过运行带-win32参数选项的qmake可以指定win32。左括号必须与条件在同一行。
使用for函数通过遍历列表值可以构建一个简单的循环。下列代码会在目录存在的情况下增加目录到SUBDIRS变量。

EXTRAS = handlers tests docsfor(dir, EXTRAS) {
        exists($$dir) {
        SUBDIRS += $$dir
        }}

对变量进行更复杂的操作可以通过内置函数find、unique、count。内置函数可以提供对字符串、路径的操作，支持用户输入，并调用其它外部工具。

2、工程模板

TEMPLATE变量用于定义构建的工程的类型。如果工程文件中没有声明TEMPLATE变量，qmake会默认构建一个应用程序，并生成一个MakeFile文件。
下列时可用工程类型：
app：创建一个构建应用程序的MakeFile
lib：创建一个构建库的MakeFile
subdirs：创建一个包含使用SUBDIRS变量指定子目录的规则的MakeFile，每个子目录必须包含自己的工程文件。
vcapp：创建一个构建应用程序的Visual Studio平台的工程文件
vclib：创建一个构建库的Visual Studio平台的工程文件
vcsubdirs：创建一个在子目录构建工程的Visual Studio平台的解决方案文件
当使用subdirs模板时，qmake会生成一个MakeFile检查每个子目录，处理查找到的任何工程文件。并且在新生成的MakeFile上运行平台的make工具。SUBDIRS变量用于包含要处理的子目录列表。

3、通用配置

CONFIG变量用于指定编译器使用的选项和属性以及链接库。CONFIG变量可以增加任何选项，但是本节所述选项会被qmake内部识别。
下列选项控制用于构建工程的编译器选项：
release：工程使用release模式构建，如果debug也被指定会被忽略。
debug：工程使用debug模式构建
debug_and_release：工程使用debug和release两种模式构建
debug_and_release_target：工程使用debug和release两种模式构建，目标会被构建到debug和release两个目录下
build_all：如果指定debug_and_release，工程默认使用debug和release两种模式构建
autogen_precompile_source：自动生成.cpp文件，包含在.pro文件中指定的预编译头文件
ordered：当使用subdirs模板时，本选项会指定按照列出的目录给定的顺序处理
warn_on：编译器会尽可能多输出警告信息，如果指定warn_off，警告信息会被忽略
warn_off：编译器尽可能少的输出警告信息
copy_dir_files：打开要复制目录安装规则，而不只复制文件
debug_and_release选项是一个特殊选项，会开启工程的debug和release两种版本构建。qmake生成的MakeFile文件会包含两种版本的构建规则，使用下列方式进行调用：
make all
增加build_all选项到CONFIG变量会生成构建工程的默认规则，并且创建debug和release版本的安装目标。
注意：CONFIG变量指定每个选项可以用于条件作用域。可以使用CONFIG内置函数测试某个配置选项的表现。下列代码将展示CONFIG函数作为作用域的条件，测试opengl选项是否在用。

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

下列选项会定义构建工程的类型，注意，某些选项只有在特定平台才会生效。
qt：工程是一个Qt应用程序，会链接Qt库。可以使用QT变量控制应用程序需要的任何附加Qt模块
thread：工程是一个多线程应用程序
x11：工程是一个X11应用程序或库
当使用应用程序或库的工程模板时，很多配置选项用于微调构建过程。例如，如果应用程序使用Qt库，并且在debug模式构建多线程应用时，工程文件如下：
CONFIG += qt thread debug
注意：必须使用“+=”而不是“=”，否则qmake不会使用Qt配置决定工程需要的设置。

4、声明Qt库

如果CONFIG变量包含qt，qmake对Qt应用程序的支持会开启，这会使微调应用程序的Qt模块变得可能。用于声明需要扩展模块的QT变量可以实现微调。例如，可以使用下列代码开启XML和network模块：

CONFIG += qt
QT += network xml

注意QT默认包含core和gui模块，上述代码会增加network和xml模块到默认值列表。下列代码将会忽略默认模块，这会导致应用程序源码编译时错误。
QT = network xml # This will omit the core and gui modules
如果要不使用gui模块构建工程，可以使用“-=”排除gui模块。默认情况下，QT包含core和gui两个模块，所以下列代码会构建一个最小化工程。
QT -= gui # Only the core module is used.
下列选项可以用于QT变量：
Core：QtCore模块，默认包含
Gui：QtGui模块，默认包含
Network：QtNetwork模块
Opengl：QtOpenGL模块
Sql：QtSql模块
Svg：QtSvg模块
Xml：QtXml模块
Xmlpatterns：QtXmlPatterns
qt3support：Qt3Support模块
注意，增加opengl选项到QT变量会自动促使相应选项到增加到CONFIG变量。因此，对于Qt应用程序，增加opengl选项到QT和CONFIG变量不是必须的。

5、配置特性

qmake可以使用特性文件.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变量指定。

三、QMake命令行使用

当qmake有多个选项在命令行运行，qmake的行为可以被自定义。qmake选项可以微调构建过程，提供有用的诊断信息，并指定工程的目标平台。

1、语法

qmake的使用采用下列简单形式：
qmake [mode] [options] files
Qmake支持两种不同的操作模式：默认模式下，qmake会使用工程文件的信息生成MakeFile文件，但qmake也可以生成工程文件。如果要显示设置模式，必须在其它所有选项前指定模式。模式有下列两个选项值：
-makefile：qmake生成MakeFile
-project：qmake生成工程文件，生成的过程文件可能需要编辑。

2、通用选项参数

为了自定义构建过程和覆写平台的默认设置，qmake可以在命令行指定一系列参数选项。下列基本选项提供有用的信息，指定qmake输出的文件的位置，控制输出到控制台调试信息的水平。
-help：qmake会回顾特性，给出有用帮助信息
-o file：qmake的输出会被重定向到file 文件。如果本选项不指定，qmake会根据运行的模式为输出选择一个合适的文件名。如果指定了“-”，输出定向到stdout。
-d：qmake会输出调试信息
对于每个目标平台都需要不同构建的有多个子目录的工程，qmake可以使用下列选项在每个工程文件中设置相应特定平台的变量。
-unix：qmake运行在unix模式，会使用unix的文件和路径命名规范，增加对unix的测试会成功，是所有的类unix平台的默认模式。
-macx：qmake运行在Mac OS X模式，会使用unix的文件和路径命名规范，增加对macx的测试会成功，是Mac OS X平台的默认模式。
-win32：qmake运行在win32模式，会使用Windows的文件和路径命名规范，增加对win32的测试会成功，是Windows平台的默认模式。
工程使用的模板通常在工程文件中使用TEMPLATE变量设置，可以使用下列选项覆写或修改：
-t tmpl：qamke会使用tmpl设置TEMPLATE变量，但仅在.pro文件被处理后。
-t prefix：增加前缀prefix到TEMPLATE变量
调整警告信息的水平可以帮助找到工程文件中的问题。
-Wall：qmake会报告已知的所有警告信息
-Wnone：不生成任何警告信息
-Wparser：qmake只会生成解析警告信息，解析警告信息会在解析工程文件过程中提醒开发者常见的陷阱和潜在问题。
-Wlogic：qmake会警告工程文件中的常见陷阱和潜在问题。例如，如果一个文件是否被多次放到文件列表中，或是如果文件没有找到，qmake会警告。

3、MakeFile模式选项

qmake -makefile [options] files
在makefile模式，qmake会生成用于构建工程的makefile文件。此外，下列选项可以被用于makefile模式中：
-after：qmake会在指定文件后的命令行上处理给定赋值
-nocache：qmake会忽略.qmake.cache文件
-nodepend：qmake不会生成任何依赖信息
-cache file：qmake会使用file作为缓存文件，其它的.qmake.cache文件会被忽略。
-spec spec：qmake会使用spec作为平台和编译器信息的路径，QMAKESPEC变量的值会被忽略。
可以在命令行上进行qmake赋值，赋值会在指定的所有文件处理。例如：
qmake -makefile -unix -o Makefile "CONFIG+=test" test.pro
上述代码会从使用unix路径名的test.pro文件生成一个Makefile。但指定选项的很多是默认的，不是必须的。因此，在Unix平台，上述代码可以简化如下：
qmake "CONFIG+=test" test.pro
如果确定变量在指定文件后被处理，可以使用-after选项。当-after选项指定，在-after后的所有命令行的赋值会被延迟到指定文件被解析后进行。

4、工程模式选项

qmake -project [options] files
在project模式下，qmake会生成一个工程文件。可以在project模式下使用下列选项：
-r：qmake会递归处理给定的目录
-nopwd：qmake不会查找当前源码的工作路径，只使用指定文件。
在project模式下，files参数是文件或目录列表。如果指定一个目录，会被包含到DEPENDPATH变量，相关代码会包含到生成的工程文