qmake 手册 013 替换函数
qmake手册013替换函数
qmake 提供了在配置过程中处理变量内容的函数。这些函数称为替换函数。通常，它们返回可以分配给其他变量的值。可以通过在函数前面加上 $$ 操作符来获得这些值。替换函数可以分为内置函数和函数库。
也可参阅 Test Functions
1. 内置的替换函数
基本替换函数被实现为内置函数。
1.1. absolute_path(path[, base])
返回 path 的绝对路径。
如果没有指定 base，则使用当前目录作为起始目录。如果是相对路径，则在使用前相对于当前目录进行解析。
例如，下面的调用返回字符串 "/home/toby/myproject/readme.txt":
message($$absolute_path("readme.txt", "/home/toby/myproject"))
这个函数是在 Qt 5.0 中引入的。
也可参阅 clean_path() 和 relative_path() 。
1.2. basename(variablename)
返回在 variablename 中指定的文件的基本名称。
例如：
FILE = /etc/passwd
FILENAME = $$basename(FILE) #passwd
1.3. cat(filename[, mode])
返回 filename 的内容。我们可以为 mode 指定以下选项:
| 选项 | 说明 |
|---|---|
| blob | 以一个值的形式返回文件的全部内容 |
| lines | 作为单独的值返回每一行(没有行结束) |
| true | (默认值)和 false 返回文件内容作为单独的值，根据 qmake 值列表分割规则进行分割(如变量分配)。如果 mode 是 false，则将只包含换行字符的值插入到列表中，以指示换行符在文件中的位置。 |
1.4. clean_path(path)
返回目录分隔符规范化(转换为"/")、删除冗余分隔符并且"."和".."都被(尽可能地)处理了的 path。这个函数是对 QDir::cleanPath 的封装。
这个函数是在 Qt 5.0 中引入的。
也可参阅 absolute_path(), relative_path(), shell_path(), system_path()
1.5. dirname(file)
返回指定 file 的目录名部分。例如:
FILE = /etc/X11R6/XF86Config
DIRNAME = $$dirname(FILE) #/etc/X11R6
1.6. enumerate_vars
返回所有已定义变量名的列表。
这个函数是在 Qt 5.0 中引入的。
1.7. escape_expand(arg1 [, arg2 ..., argn])
接受任意数量的参数。它为每个参数展开转义序列 \n、\r、\t，并以列表的形式返回参数。
注意:如果按字面意思指定要展开的字符串，则需要对反斜杠进行转义，如下面的代码片段所示:
message("First line$$escape_expand(\\n)Second line")
1.8. find(variablename, substr)
返回 variablename 中与正则表达式 substr 匹配的所有值。
MY_VAR = one two three four
MY_VAR2 = $$join(MY_VAR, " -L", -L) -Lfive
MY_VAR3 = $$member(MY_VAR, 3) $$find(MY_VAR, t.*)
message($$MY_VAR2)
message($$MY_VAR3)
上面示例的输出：
Project MESSAGE: -Lone -Ltwo -Lthree -Lfour -Lfive
Project MESSAGE: four two three
1.9. files(pattern[, recursive=false])
展开指定的通配符模式并返回文件名列表。如果 recursive 为 true，则此函数递归执行子目录。
1.10. first(variablename)
返回 variablename 的第一个值。
例如，以下调用返回 firstname:
CONTACT = firstname middlename surname phone
message($$first(CONTACT))
也可参阅 take_first(), last().
1.11. format_number(number[, options...])
以 options 指定的格式返回 number。我们可以指定以下选项:
| 选项 | 说明 |
|---|---|
| ibase=n | 设置输入的基数为 n |
| obase=n | 将输出的基数设置为 n |
| width=n | 设置输出的最小宽度为 n。如果输出小于 width，则用空格填充 |
| zeropad | 用零代替空格填充输出 |
| padsign | 在输出的正值前加一个空格 |
| alwayssign | 在输出的正值前加上一个加号 |
| leftalign | 将padding放在输出值的右侧 |
目前不支持浮点数。
例如，下面的调用将十六进制数字 BAD 转换为 002989:
message($$format_number(BAD, ibase=16 width=6 zeropad))
这个函数是在 Qt 5.0 中引入的。
1.12. fromfile(filename, variablename)
将 filename 当做一个 qmake 项目文件，并返回分配给 variablename 的值。
也可参阅 infile()
1.13. getenv(variablename)
返回环境变量 variablename 的值。这基本上等同于 $$(variablename) 语法。但是，getenv 函数支持名称中带有圆括号的环境变量。
这个函数是在 Qt 5.0 中引入的。
1.14. join(variablename, glue, before, after)
将 variablename 和 glue 的值连接起来。如果这个值不是空的，这个函数会在这个值前面加上 before 和在后面加上 after。variablename 是唯一必须的字段，其他字段默认为空字符串。如果需要在 glue、before 或 after 中对空格进行编码，则必须引用它们。
1.15. last(variablename)
返回 variablename 的最后一个值。
例如，以下调用返回 phone:
CONTACT = firstname middlename surname phone
message($$last(CONTACT))
1.16. list(arg1 [, arg2 ..., argn])
接受任意数量的参数。它创建一个唯一命名的变量，该变量包含参数列表，并返回该变量的名称。可以使用该变量编写循环，如下面的代码片段所示：
for(var, $$list(foo bar baz)) {
...
}
替换:
values = foo bar baz
for(var, values) {
...
}
1.17. lower(arg1 [, arg2 ..., argn])
接受任意数量的参数并将它们转换为小写。
也可参阅 upper()
1.18. member(variablename [, start [, end]])
返回 variablename 列表中的值，可以使用 start 指定零开始的元素索引，使用 end 指定结束元素的索引（该函数会包含 start 和 end 元素）。
如果 start 未指定，则使用其默认值 0，此时该函数的功能相当于 $$first(variablename) 。
如果 end 未指定，则其默认值 将与 start 相等，此用法表示简单的数组索引，因为将只返回一个元素。
也可以在单个参数中指定开始和结束，数字由两个句点分隔。
负数表示从列表末尾开始的索引，而 -1 是最后一个元素。
如果任一索引范围越界，则返回空列表。
如果 end 小于 start，则按相反顺序返回元素。
注意：结束（end）索引是包含的和无序的，这意味着只有当索引无效时(即输入变量为空时)才会返回一个空列表。
也可参阅 str_member()
1.19. num_add(arg1 [, arg2 ..., argn])
接受任意数量的数值参数并将它们相加，返回和。
可以隐式支持减法，因为可以简单地在数值前加一个减号来对其进行取负值 :
sum = $$num_add($$first, -$$second)
如果操作数可能已经是负数，则需要执行另一个额外的步骤来规范化数字:
second_neg = -$$second
second_neg ~= s/^--//
sum = $$num_add($$first, $$second_neg)
这个函数是在 Qt 5.8 中引入的。
1.20. prompt(question [, decorate])
显示指定的 question，并返回从 stdin 读取的值。
如果 decorate 为true(缺省值)，question 将获得一个通用的前缀和后缀，将其标识为提示符。
1.21. quote(string)
将整个 string 转换为单个实体并返回结果。这只是将字符串括在双引号中的一种特殊方式。
1.22. re_escape(string)
用反斜杠转义的每个特殊正则表达式字符返回 string。这个函数是 QRegExp::escape的包装器。
1.23. read_registry(tree, key[, flag])
返回目录树 tree 中的注册表项 key 的值。
仅支持目录 HKEY_CURRENT_USER (HKCU) 和 HKEY_LOCAL_MACHINE (HKLM)
flag 的值可以是 WOW64_32KEY (32) 或 WOW64_64KEY (64)
注意:此功能仅在 Windows 主机上可用。
这个函数是在 Qt 5.12.1 中引入的。
1.24. relative_path(filePath[, base])
返回 filePath 相对于 base 的路径。
如果未指定 base，则为当前项目目录。如果是相对的，则在使用前相对于当前项目目录进行解析。
如果 filePath 是相对的，它首先根据基本目录解析；在这种情况下，此函数实际上充当 $$clean_path() 。
这个函数是在 Qt 5.0 中引入的。
也可参见 absolute_path(), clean_path()
1.25. replace(string, old_string, new_string)
用 string 提供的变量内容中的 new_string 替换 old_string 的每个实例。例如，代码：
MESSAGE = This is a tent.
message($$replace(MESSAGE, tent, test))
输出：
This is a test.
1.26. resolve_depends(variablename, prefix)
这是一个我们通常不需要的内部功能。
这个函数是在 Qt 5.0 中引入的。
1.27. reverse(variablename)
以相反顺序返回 variablename 的值。
这个函数是在 Qt 5.0 中引入的。
1.28. section(variablename, separator, begin, end)
返回值 variablename 的一部分。这个函数是 QString::section 的包装器。
例如，下面的调用输出 surname:
CONTACT = firstname:middlename:surname:phone
message($$section(CONTACT, :, 2, 2))
1.29. shadowed(path)
将项目源目录的路径映射到构建目录。对于源代码内构建，该函数返回 path 。如果 path 指向源树之外，则返回一个空字符串。
这个函数是在 Qt 5.0 中引入的。
1.30. shell_path(path)
将 path 中的所有目录分隔符转换为与构建项目时使用的 shell(即由 make 工具调用的 shell)兼容的分隔符。例如，当使用 Windows shell 时，斜杠将转换为反斜杠。
这个函数是在 Qt 5.0 中引入的。
也可参阅 system_path()
1.31. shell_quote(arg)
为构建项目时使用的 shell 引用 arg 。
这个函数是在 Qt 5.0 中引入的。
也可参阅 system_quote()
1.32. size(variablename)
返回 variablename 的值的数目。
也可参阅 str_size()
1.33. sort_depends(variablename, prefix)
这是一个我们通常不需要的内部功能。
这个函数是在 Qt 5.0 中引入的。
1.34. sorted(variablename)
返回 variablename 中的值列表，其中项按 ASCII 升序排序。
在 format_number() 函数的帮助下，可以通过将值零填充到固定长度来完成数字排序。
这个函数是在 Qt 5.8 中引入的。
1.35. split(variablename, separator)
将 variablename 的值分割为单独的值，并以列表的形式返回它们。这个函数是 QString::split 的包装器。
例如:
CONTACT = firstname:middlename:surname:phone
message($$split(CONTACT, :))
1.36. sprintf(string, arguments...)
函数用 arguments 以逗号分隔的列表中的参数替换 string 中的%1-%9，并返回处理过的字符串。
1.37. str_member(arg [, start [, end]])
这个函数与 member() 相同，只是它操作的是字符串值而不是列表变量，因此索引引用字符位置。
这个函数可以用来实现许多常见的字符串切片操作:
# $$left(VAR, len)
left = $$str_member(VAR, 0, $$num_add($$len, -1))
# $$right(VAR, len)
right = $$str_member(VAR, -$$num, -1)
# $$mid(VAR, off, len)
mid = $$str_member(VAR, $$off, $$num_add($$off, $$len, -1))
# $$mid(VAR, off)
mid = $$str_member(VAR, $$off, -1)
# $$reverse(VAR)
reverse = $$str_member(VAR, -1, 0)
注意: 在这些实现中，len 为 0 的参数需要单独处理。
这个函数是在 Qt 5.8 中引入的。
1.38. str_size(arg)
返回参数中的字符数。
也可参阅 size().
这个函数是在 Qt 5.8 中引入的。
1.39. system(command[, mode[, stsvar]])
我们可以使用 system 函数的这个变体从命令中获取 stdout，并将其分配给一个变量。
例如:
UNAME = $$system(uname -s)
contains( UNAME, [lL]inux ):message( This looks like Linux ($$UNAME) to me )
与 $$cat() 类似，mode 参数将 blob、lines、true 和 false 作为值。但是，传统的分词规则 (如empty 和 true 或 false) 略有不同。
如果传递 stsvar，命令的退出状态将存储在该变量中。如果命令崩溃，状态将为 -1，否则为该命令选择的非负退出代码。通常，将状态与零(成功)进行比较就足够了。
请参阅 system() 的测试变体。
1.40. system_path(path)
将 path 中的所有目录分隔符转换为与 system() 函数用于调用命令的 shell 兼容的分隔符。例如，在 Windows shell 中将斜杠转换为反斜杠。
这个函数是在 Qt 5.0 中引入的。
也可参阅 shell_path()
1.41. system_quote(arg)
为 system() 函数使用的 shell 引用 arg。
这个函数是在 Qt 5.0 中引入的。
也可参阅 shell_quote()
1.42. take_first(variablename)
返回 variablename 的第一个值，并将其从源变量中删除。
例如，这为实现队列提供了便利。
这个函数是在 Qt 5.8 中引入的。
1.43. take_last(variablename)
返回 variablename 的最后一个值，并将其从源变量中删除。
例如，这为实现堆栈提供了便利。
这个函数是在 Qt 5.8 中引入的。
也可参阅 take_first(), last().
1.44. unique(variablename)
返回 variablename 中删除重复条目的值列表。例如:
ARGS = 1 2 3 2 5 1
ARGS = $$unique(ARGS) #1 2 3 5
1.45. upper(arg1 [, arg2 ..., argn])
接受任意数量的参数并将它们转换为大写。
也可参阅 lower()
1.46. val_escape(variablename)
转义 variablename 的值，使其能够解析为 qmake 代码。
这个函数是在 Qt 5.0 中引入的。
