This is a mirror page, please see the original page:

https://xmake.io/#/zh-cn/manual/builtin_modules

在自定义脚本、插件脚本、任务脚本、平台扩展、模板扩展等脚本代码中使用,也就是在类似下面的代码块中,可以使用这些模块接口:

on_run(function (target)
    print("hello xmake!")
end)


为了保证外层的描述域尽可能简洁、安全,一般不建议在这个域使用接口和模块操作api,因此大部分模块接口只能脚本域使用,来实现复杂功能。

当然少部分只读的内置接口还是可以在描述域使用的,具体见下表:

接口 描述 可使用域 支持版本
val 获取内置变量的值 脚本域 >= 2.1.5
import 导入扩展摸块 脚本域 >= 2.0.1
inherit 导入并继承基类模块 脚本域 >= 2.0.1
try-catch-finally 异常捕获 脚本域 >= 2.0.1
pairs 用于遍历字典 描述域、脚本域 >= 2.0.1
ipairs 用于遍历数组 描述域、脚本域 >= 2.0.1
print 换行打印终端日志 描述域、脚本域 >= 2.0.1
printf 无换行打印终端日志 脚本域 >= 2.0.1
cprint 换行彩色打印终端日志 脚本域 >= 2.0.1
cprintf 无换行彩色打印终端日志 脚本域 >= 2.0.1
format 格式化字符串 描述域、脚本域 >= 2.0.1
vformat 格式化字符串,支持内置变量转义 脚本域 >= 2.0.1
raise 抛出异常中断程序 脚本域 >= 2.0.1
os 系统操作模块 部分只读操作描述域、脚本域 >= 2.0.1
io 文件操作模块 脚本域 >= 2.0.1
path 路径操作模块 描述域、脚本域 >= 2.0.1
table 数组和字典操作模块 描述域、脚本域 >= 2.0.1
string 字符串操作模块 描述域、脚本域 >= 2.0.1
process 进程操作模块 脚本域 >= 2.0.1
coroutine 协程操作模块 脚本域 >= 2.0.1
find_packages 查找依赖包 脚本域 >= 2.2.5

在描述域使用接口调用的实例如下,一般仅用于条件控制:

-- 扫描当前xmake.lua目录下的所有子目录,以每个目录的名字定义一个task任务
for _, taskname in ipairs(os.dirs("*"), path.basename) do
    task(taskname)
        on_run(function ()
        end)
end

上面所说的脚本域、描述域主要是指:

-- 描述域
target("test")

    -- 描述域
    set_kind("static")
    add_files("src/*.c")

    on_run(function (target)
        -- 脚本域
    end)

-- 描述域

val

获取内置变量的值

内置变量可以通过此接口直接获取,而不需要再加$()的包裹,使用更加简单,例如:

print(val("host"))
print(val("env PATH"))
local s = val("shell echo hello")

而用vformat就比较繁琐了:

local s = vformat("$(shell echo hello)")

不过vformat支持字符串参数格式化,更加强大, 所以应用场景不同。

import

导入扩展摸块

import的主要用于导入xmake的扩展类库以及一些自定义的类库模块,一般用于:

导入机制如下:

  1. 优先从当前脚本目录下导入
  2. 再从扩展类库中导入

导入的语法规则:

基于.的类库路径规则,例如:

import("core.base.option")
import("core.base.task")

function main()

    -- 获取参数选项
    print(option.get("version"))

    -- 运行任务和插件
    task.run("hello")
end

导入当前目录下的自定义模块:

目录结构:

plugin
  - xmake.lua
  - main.lua
  - modules
    - hello1.lua
    - hello2.lua

在main.lua中导入modules

import("modules.hello1")
import("modules.hello2")

导入后就可以直接使用里面的所有公有接口,私有接口用_前缀标示,表明不会被导出,不会被外部调用到。。

除了当前目录,我们还可以导入其他指定目录里面的类库,例如:

import("hello3", {rootdir = "/home/xxx/modules"})

为了防止命名冲突,导入后还可以指定的别名:

import("core.platform.platform", {alias = "p"})

function main()

    -- 这样我们就可以使用p来调用platform模块的plats接口,获取所有xmake支持的平台列表了
    utils.dump(p.plats())
end

import不仅可以导入类库,还支持导入的同时作为继承导入,实现模块间的继承关系

import("xxx.xxx", {inherit = true})

这样导入的不是这个模块的引用,而是导入的这个模块的所有公有接口本身,这样就会跟当前模块的接口进行合并,实现模块间的继承。

2.1.5版本新增两个新属性:import("xxx.xxx", {try = true, anonymous = true})

try为true,则导入的模块不存在的话,仅仅返回nil,并不会抛异常后中断xmake.
anonymous为true,则导入的模块不会引入当前作用域,仅仅在import接口返回导入的对象引用。

inherit

导入并继承基类模块

这个等价于import接口的inherit模式,也就是:

import("xxx.xxx", {inherit = true})

inherit接口的话,会更简洁些:

inherit("xxx.xxx")

使用实例,可以参看xmake的tools目录下的脚本:clang.lua

这个就是clang工具模块继承了gcc的部分实现。

try-catch-finally

异常捕获

lua原生并没有提供try-catch的语法来捕获异常处理,但是提供了pcall/xpcall等接口,可在保护模式下执行lua函数。

因此,可以通过封装这两个接口,来实现try-catch块的捕获机制。

我们可以先来看下,封装后的try-catch使用方式:

try
{
    -- try 代码块
    function ()
        error("error message")
    end,

    -- catch 代码块
    catch 
    {
        -- 发生异常后,被执行
        function (errors)
            print(errors)
        end
    }
}

上面的代码中,在try块内部认为引发了一个异常,并且抛出错误消息,在catch中进行了捕获,并且将错误消息进行输出显示。

而finally的处理,这个的作用是对于try{}代码块,不管是否执行成功,都会执行到finally块中

也就说,其实上面的实现,完整的支持语法是:try-catch-finally模式,其中catch和finally都是可选的,根据自己的实际需求提供

例如:

try
{
    -- try 代码块
    function ()
        error("error message")
    end,

    -- catch 代码块
    catch 
    {
        -- 发生异常后,被执行
        function (errors)
            print(errors)
        end
    },

    -- finally 代码块
    finally 
    {
        -- 最后都会执行到这里
        function (ok, errors)
            -- 如果try{}中存在异常,ok为true,errors为错误信息,否则为false,errors为try中的返回值
        end
    }
}

或者只有finally块:

try
{
    -- try 代码块
    function ()
        return "info"
    end,

    -- finally 代码块
    finally 
    {
        -- 由于此try代码没发生异常,因此ok为true,errors为返回值: "info"
        function (ok, errors)
        end
    }
}

处理可以在finally中获取try里面的正常返回值,其实在仅有try的情况下,也是可以获取返回值的:

-- 如果没发生异常,result 为返回值:"xxxx",否则为nil
local result = try
{
    function ()
        return "xxxx"
    end
}

在xmake的自定义脚本、插件开发中,也是完全基于此异常捕获机制

这样使得扩展脚本的开发非常的精简可读,省去了繁琐的if err ~= nil then返回值判断,在发生错误时,xmake会直接抛出异常进行中断,然后高亮提示详细的错误信息。

例如:

target("test")
    set_kind("binary")
    add_files("src/*.c")

    -- 在编译完ios程序后,对目标程序进行ldid签名
    after_build(function (target))
        os.run("ldid -S %s", target:targetfile())
    end

只需要一行os.run就行了,也不需要返回值判断是否运行成功,因为运行失败后,xmake会自动抛异常,中断程序并且提示错误

如果你想在运行失败后,不直接中断xmake,继续往下运行,可以自己加个try快就行了:

target("test")
    set_kind("binary")
    add_files("src/*.c")

    after_build(function (target))
        try
        {
            function ()
                os.run("ldid -S %s", target:targetfile())
            end
        }
    end

如果还想捕获出错信息,可以再加个catch:

target("test")
    set_kind("binary")
    add_files("src/*.c")

    after_build(function (target))
        try
        {
            function ()
                os.run("ldid -S %s", target:targetfile())
            end,
            catch 
            {
                function (errors)
                    print(errors)
                end
            }
        }
    end

不过一般情况下,在xmake中写自定义脚本,是不需要手动加try-catch的,直接调用各种api,出错后让xmake默认的处理程序接管,直接中断就行了。。

pairs

用于遍历字典

这个是lua原生的内置api,在xmake中,在原有的行为上对其进行了一些扩展,来简化一些日常的lua遍历代码。

先看下默认的原生写法:

local t = {a = "a", b = "b", c = "c", d = "d", e = "e", f = "f"}

for key, val in pairs(t) do
    print("%s: %s", key, val)
end

这对于通常的遍历操作就足够了,但是如果我们相对其中每个遍历出来的元素,获取其大写,我们可以这么写:

for key, val in pairs(t, function (v) return v:upper() end) do
     print("%s: %s", key, val)
end

甚至传入一些参数到第二个function中,例如:

for key, val in pairs(t, function (v, a, b) return v:upper() .. a .. b end, "a", "b") do
     print("%s: %s", key, val)
end

ipairs

用于遍历数组

这个是lua原生的内置api,在xmake中,在原有的行为上对其进行了一些扩展,来简化一些日常的lua遍历代码。

先看下默认的原生写法:

for idx, val in ipairs({"a", "b", "c", "d", "e", "f"}) do
     print("%d %s", idx, val)
end

扩展写法类似pairs接口,例如:

for idx, val in ipairs({"a", "b", "c", "d", "e", "f"}, function (v) return v:upper() end) do
     print("%d %s", idx, val)
end

for idx, val in ipairs({"a", "b", "c", "d", "e", "f"}, function (v, a, b) return v:upper() .. a .. b end, "a", "b") do
     print("%d %s", idx, val)
end

这样可以简化for块代码的逻辑,例如我要遍历指定目录,获取其中的文件名,但不包括路径,就可以通过这种扩展方式,简化写法:

for _, filename in ipairs(os.dirs("*"), path.filename) do
    -- ...
end

print

换行打印终端日志

此接口也是lua的原生接口,xmake在原有行为不变的基础上也进行了扩展,同时支持:格式化输出、多变量输出。

先看下原生支持的方式:

print("hello xmake!")
print("hello", "xmake!", 123)

并且同时还支持扩展的格式化写法:

print("hello %s!", "xmake")
print("hello xmake! %d", 123)

xmake会同时支持这两种写法,内部会去自动智能检测,选择输出行为。

printf

无换行打印终端日志

类似print接口,唯一的区别就是不换行。

cprint

换行彩色打印终端日志

行为类似print,区别就是此接口还支持彩色终端输出,并且支持emoji字符输出。

例如:

    cprint('${bright}hello xmake')
    cprint('${red}hello xmake')
    cprint('${bright green}hello ${clear}xmake')
    cprint('${blue onyellow underline}hello xmake${clear}')
    cprint('${red}hello ${magenta}xmake')
    cprint('${cyan}hello ${dim yellow}xmake')

显示结果如下:

cprint_colors

跟颜色相关的描述,都放置在 ${ } 里面,可以同时设置多个不同的属性,例如:

    ${bright red underline onyellow}

表示:高亮红色,背景黄色,并且带下滑线

所有这些描述,都会影响后面一整行字符,如果只想显示部分颜色的文字,可以在结束位置,插入${clear}清楚前面颜色描述

例如:

    ${red}hello ${clear}xmake

这样的话,仅仅hello是显示红色,其他还是正常默认黑色显示。

其他颜色属于,我这里就不一一介绍,直接贴上xmake代码里面的属性列表吧:

    colors.keys = 
    {
        -- 属性
        reset       = 0 -- 重置属性
    ,   clear       = 0 -- 清楚属性
    ,   default     = 0 -- 默认属性
    ,   bright      = 1 -- 高亮
    ,   dim         = 2 -- 暗色
    ,   underline   = 4 -- 下划线
    ,   blink       = 5 -- 闪烁
    ,   reverse     = 7 -- 反转颜色
    ,   hidden      = 8 -- 隐藏文字

        -- 前景色 
    ,   black       = 30
    ,   red         = 31
    ,   green       = 32
    ,   yellow      = 33
    ,   blue        = 34
    ,   magenta     = 35 
    ,   cyan        = 36
    ,   white       = 37

        -- 背景色 
    ,   onblack     = 40
    ,   onred       = 41
    ,   ongreen     = 42
    ,   onyellow    = 43
    ,   onblue      = 44
    ,   onmagenta   = 45
    ,   oncyan      = 46
    ,   onwhite     = 47

除了可以色彩高亮显示外,如果你的终端是在macosx下,lion以上的系统,xmake还可以支持emoji表情的显示哦,对于不支持系统,会
忽略显示,例如:

    cprint("hello xmake${beer}")
    cprint("hello${ok_hand} xmake")

上面两行代码,我打印了一个homebrew里面经典的啤酒符号,下面那行打印了一个ok的手势符号,是不是很炫哈。。

cprint_emoji

所有的emoji表情,以及xmake里面对应的key,都可以通过emoji符号里面找到。。

2.1.7版本支持24位真彩色输出,如果终端支持的话:

import("core.base.colors")
if colors.truecolor() then
    cprint("${255;0;0}hello")
    cprint("${on;255;0;0}hello${clear} xmake")
    cprint("${bright 255;0;0 underline}hello")
    cprint("${bright on;255;0;0 0;255;0}hello${clear} xmake")
end

xmake对于truecolor的检测支持,是通过$COLORTERM环境变量来实现的,如果你的终端支持truecolor,可以手动设置此环境变量,来告诉xmake启用truecolor支持。

可以通过下面的命令来启用和测试:

$ export COLORTERM=truecolor
$ xmake --version

2.1.7版本可通过COLORTERM=nocolor来禁用色彩输出。

cprintf

无换行彩色打印终端日志

此接口类似cprint,区别就是不换行输出。

format

格式化字符串

如果只是想格式化字符串,不进行输出,可以使用这个接口,此接口跟string.format接口等价,只是个接口名简化版。

local s = format("hello %s", xmake)

vformat

格式化字符串,支持内置变量转义

此接口跟format接口类似,只是增加对内置变量的获取和转义支持。

local s = vformat("hello %s $(mode) $(arch) $(env PATH)", xmake)

raise

抛出异常中断程序

如果想在自定义脚本、插件任务中中断xmake运行,可以使用这个接口抛出异常,如果上层没有显示调用try-catch捕获的话,xmake就会中断执行,并且显示出错信息。

if (errors) raise(errors)

如果在try块中抛出异常,就会在catch和finally中进行errors信息捕获,具体见:try-catch

find_packages

查找依赖包

此接口是对lib.detect.find_package接口的封装,提供多个依赖包的查找支持,例如:

target("test")
    set_kind("binary")
    add_files("src/*.c")
    on_load(function (target)
        target:add(find_packages("openssl", "zlib"))
    end)

os

系统操作模块,属于内置模块,无需使用import导入,可直接脚本域调用其接口。

此模块也是lua的原生模块,xmake在其基础上进行了扩展,提供更多实用的接口。


os模块里面只有部分readonly接口(例如:os.getenv, os.arch)是可以在描述域中使用,其他接口只能在脚本域中使用,例如:os.cp, os.rm

接口 描述 支持版本
os.cp 复制文件或目录 >= 2.0.1
os.mv 移动重命名文件或目录 >= 2.0.1
os.rm 删除文件或目录树 >= 2.0.1
os.trycp 尝试复制文件或目录 >= 2.1.6
os.trymv 尝试移动重命名文件或目录 >= 2.1.6
os.tryrm 尝试删除文件或目录树 >= 2.1.6
os.cd 进入指定目录 >= 2.0.1
os.rmdir 删除目录树 >= 2.0.1
os.mkdir 创建指定目录 >= 2.0.1
os.isdir 判断目录是否存在 >= 2.0.1
os.isfile 判断文件是否存在 >= 2.0.1
os.exists 判断文件或目录是否存在 >= 2.0.1
os.dirs 遍历获取指定目录下的所有目录 >= 2.0.1
os.files 遍历获取指定目录下的所有文件 >= 2.0.1
os.filedirs 遍历获取指定目录下的所有文件或目录 >= 2.0.1
os.run 安静运行程序 >= 2.0.1
os.runv 安静运行程序,带参数列表 >= 2.1.5
os.exec 回显运行程序 >= 2.0.1
os.execv 回显运行程序,带参数列表 >= 2.1.5
os.iorun 运行并获取程序输出内容 >= 2.0.1
os.iorunv 运行并获取程序输出内容,带参数列表 >= 2.1.5
os.getenv 获取环境变量 >= 2.0.1
os.setenv 设置环境变量 >= 2.0.1
os.tmpdir 获取临时目录路径 >= 2.0.1
os.tmpfile 获取临时文件路径 >= 2.0.1
os.curdir 获取当前目录路径 >= 2.0.1
os.filesize 获取文件大小 >= 2.1.9
os.scriptdir 获取脚本目录路径 >= 2.0.1
os.programdir 获取xmake安装主程序脚本目录 >= 2.1.5
os.projectdir 获取工程主目录 >= 2.1.5
os.arch 获取当前系统架构 >= 2.0.1
os.host 获取当前主机系统 >= 2.0.1

os.cp

行为和shell中的cp命令类似,支持路径通配符匹配(使用的是lua模式匹配),支持多文件复制,以及内置变量支持。

例如:

os.cp("$(scriptdir)/*.h", "$(buildir)/inc")
os.cp("$(projectdir)/src/test/**.h", "$(buildir)/inc")

上面的代码将:当前xmake.lua目录下的所有头文件、工程源码test目录下的头文件全部复制到$(buildir)输出目录中。

其中$(scriptdir), $(projectdir) 这些变量是xmake的内置变量,具体详情见:内置变量的相关文档。

*.h**.h中的匹配模式,跟add_files中的类似,前者是单级目录匹配,后者是递归多级目录匹配。

此接口同时支持目录的递归复制,例如:

-- 递归复制当前目录到临时目录
os.cp("$(curdir)/test/", "$(tmpdir)/test")

上面的复制,会把所有文件全部展开复制到指定目录,丢失源目录层级,如果要按保持原有的目录结构复制,可以设置rootdir参数:

os.cp("src/**.h", "/tmp/", {rootdir = "src"})

上面的脚本可以按src根目录,将src下的所有子文件保持目录结构复制过去。


尽量使用os.cp接口,而不是os.run("cp .."),这样更能保证平台一致性,实现跨平台构建描述。

os.mv

os.cp的使用类似,同样支持多文件移动操作和模式匹配,例如:

-- 移动文件到临时目录
os.mv("$(buildir)/test1", "$(tmpdir)")

-- 文件移动不支持批量操作,也就是文件重命名
os.mv("$(buildir)/libtest.a", "$(buildir)/libdemo.a")

os.rm

支持递归删除目录,批量删除操作,以及模式匹配和内置变量,例如:

os.rm("$(buildir)/inc/**.h", "$(buildir)/lib/")

os.trycp

os.cp类似,唯一的区别就是,此接口操作失败不会抛出异常中断xmake,而是通过返回值标示是否执行成功。

if os.trycp("file", "dest/file") then
end

os.trymv

os.mv类似,唯一的区别就是,此接口操作失败不会抛出异常中断xmake,而是通过返回值标示是否执行成功。

if os.trymv("file", "dest/file") then
end

os.tryrm

os.rm类似,唯一的区别就是,此接口操作失败不会抛出异常中断xmake,而是通过返回值标示是否执行成功。

if os.tryrm("file") then
end

os.cd

这个操作用于目录切换,同样也支持内置变量,但是不支持模式匹配和多目录处理,例如:

-- 进入临时目录
os.cd("$(tmpdir)")

如果要离开进入之前的目录,有多种方式:

-- 进入上级目录
os.cd("..")

-- 进入先前的目录,相当于:cd -
os.cd("-")

-- 进入目录前保存之前的目录,用于之后跨级直接切回
local oldir = os.cd("./src")
...
os.cd(oldir)

os.rmdir

如果不是目录就无法删除。

os.mkdir

支持批量创建和内置变量,例如:

os.mkdir("$(tmpdir)/test", "$(buildir)/inc")

os.isdir

如果目录不存在,则返回false

if os.isdir("src") then
    -- ...
end

os.isfile

如果文件不存在,则返回false

if os.isfile("$(buildir)/libxxx.a") then
    -- ...
end

os.exists

如果文件或目录不存在,则返回false

-- 判断目录存在
if os.exists("$(buildir)") then
    -- ...
end

-- 判断文件存在
if os.exists("$(buildir)/libxxx.a") then
    -- ...
end

os.dirs

支持add_files中的模式匹配,支持递归和非递归模式遍历,返回的结果是一个table数组,如果获取不到,返回空数组,例如:

-- 递归遍历获取所有子目录
for _, dir in ipairs(os.dirs("$(buildir)/inc/**")) do
    print(dir)
end

os.files

支持add_files中的模式匹配,支持递归和非递归模式遍历,返回的结果是一个table数组,如果获取不到,返回空数组,例如:

-- 非递归遍历获取所有子文件
for _, filepath in ipairs(os.files("$(buildir)/inc/*.h")) do
    print(filepath)
end

os.filedirs

支持add_files中的模式匹配,支持递归和非递归模式遍历,返回的结果是一个table数组,如果获取不到,返回空数组,例如:

-- 递归遍历获取所有子文件和目录
for _, filedir in ipairs(os.filedirs("$(buildir)/**")) do
    print(filedir)
end

os.run

用于执行第三方的shell命令,但不会回显输出,仅仅在出错后,高亮输出错误信息。

此接口支持参数格式化、内置变量,例如:

-- 格式化参数传入
os.run("echo hello %s!", "xmake")

-- 列举构建目录文件
os.run("ls -l $(buildir)")


使用此接口执行shell命令,容易使构建跨平台性降低,对于os.run("cp ..")这种尽量使用os.cp代替。

如果必须使用此接口运行shell程序,请自行使用config.plat接口判断平台支持。

更加高级的进程运行和控制,见process模块接口。

os.runv

os.run类似,只是传递参数的方式是通过参数列表传递,而不是字符串命令,例如:

os.runv("echo", {"hello", "xmake!"})

另外,此接口也支持envs参数设置:

os.runv("echo", {"hello", "xmake!"}, {envs = {PATH = "xxx;xx", CFLAGS = "xx"}}

os.exec

os.run接口类似,唯一的不同是,此接口执行shell程序时,是带回显输出的,一般调试的时候用的比较多

os.execv

os.exec类似,只是传递参数的方式是通过参数列表传递,而不是字符串命令,例如:

os.execv("echo", {"hello", "xmake!"})

另外,此接口还支持一个可选的参数,用于传递设置:重定向输出,执行环境变量设置,例如:

os.execv("echo", {"hello", "xmake!"}, {stdout = outfile, stderr = errfile, envs = {PATH = "xxx;xx", CFLAGS = "xx"}}

其中,stdout和stderr参数用于传递重定向输出和错误输出,可以直接传入文件路径,也可以传入io.open打开的文件对象。

另外,如果想在这次执行中临时设置和改写一些环境变量,可以传递envs参数,里面的环境变量设置会替换已有的设置,但是不影响外层的执行环境,只影响当前命令。

我们也可以通过os.getenvs()接口获取当前所有的环境变量,然后改写部分后传入envs参数。

os.iorun

os.run接口类似,唯一的不同是,此接口执行shell程序后,会获取shell程序的执行结果,相当于重定向输出。

可同时获取stdout, stderr中的内容,例如:

local outdata, errdata = os.iorun("echo hello xmake!")

os.iorunv

os.iorun类似,只是传递参数的方式是通过参数列表传递,而不是字符串命令,例如:

local outdata, errdata = os.iorunv("echo", {"hello", "xmake!"})

另外,此接口也支持envs参数设置:

local outdata, errdata = os.iorunv("echo", {"hello", "xmake!"}, {envs = {PATH = "xxx;xx", CFLAGS = "xx"}}

os.getenv

print(os.getenv("PATH"))

os.setenv

os.setenv("HOME", "/tmp/")

os.tmpdir

$(tmpdir)结果一致,只不过是直接获取返回一个变量,可以用后续字符串维护。

print(path.join(os.tmpdir(), "file.txt"))

等价于:

print("$(tmpdir)/file.txt")

os.tmpfile

用于获取生成一个临时文件路径,仅仅是个路径,文件需要自己创建。

os.curdir

$(curdir)结果一致,只不过是直接获取返回一个变量,可以用后续字符串维护。

用法参考:os.tmpdir

os.filesize

print(os.filesize("/tmp/a"))

os.scriptdir

$(scriptdir)结果一致,只不过是直接获取返回一个变量,可以用后续字符串维护。

用法参考:os.tmpdir

os.programdir

$(programdir)结果一致,只不过是直接获取返回一个变量,可以用后续字符串维护。

os.projectdir

$(projectdir)结果一致,只不过是直接获取返回一个变量,可以用后续字符串维护。

os.arch

也就是当前主机系统的默认架构,例如我在linux x86_64上执行xmake进行构建,那么返回值是:x86_64

os.host

$(host)结果一致,例如我在linux x86_64上执行xmake进行构建,那么返回值是:linux

io

io操作模块,扩展了lua内置的io模块,提供更多易用的接口。

接口 描述 支持版本
io.open 打开文件用于读写 >= 2.0.1
io.load 从指定路径文件反序列化加载所有table内容 >= 2.0.1
io.save 序列化保存所有table内容到指定路径文件 >= 2.0.1
io.readfile 从指定路径文件读取所有内容 >= 2.1.3
io.writefile 写入所有内容到指定路径文件 >= 2.1.3
io.gsub 全文替换指定路径文件的内容 >= 2.0.1
io.tail 读取和显示文件的尾部内容 >= 2.0.1
io.cat 读取和显示文件的所有内容 >= 2.0.1
io.print 带换行格式化输出内容到文件 >= 2.0.1
io.printf 无换行格式化输出内容到文件 >= 2.0.1

io.open

这个是属于lua的原生接口,详细使用可以参看lua的官方文档:The Complete I/O Model

如果要读取文件所有内容,可以这么写:

local file = io.open("$(tmpdir)/file.txt", "r")
if file then
    local data = file:read("*all")
    file:close()
end

或者可以使用io.readfile更加快速地读取。

如果要写文件,可以这么操作:

-- 打开文件:w 为写模式, a 为追加写模式
local file = io.open("xxx.txt", "w")
if file then

    -- 用原生的lua接口写入数据到文件,不支持格式化,无换行,不支持内置变量
    file:write("hello xmake\n")

    -- 用xmake扩展的接口写入数据到文件,支持格式化,无换行,不支持内置变量
    file:writef("hello %s\n", "xmake")

    -- 使用xmake扩展的格式化传参写入一行,带换行符,并且支持内置变量
    file:print("hello %s and $(buildir)", "xmake")

    -- 使用xmake扩展的格式化传参写入一行,无换行符,并且支持内置变量
    file:printf("hello %s and $(buildir) \n", "xmake")

    -- 关闭文件
    file:close()
end

io.load

可以从文件中加载序列化好的table内容,一般与io.save配合使用,例如:

-- 加载序列化文件的内容到table
local data = io.load("xxx.txt")
if data then

    -- 在终端中dump打印整个table中内容,格式化输出
    utils.dump(data)
end

io.save

可以序列化存储table内容到指定文件,一般与io.load配合使用,例如:

io.save("xxx.txt", {a = "a", b = "b", c = "c"})

存储结果为:

{
    ["b"] = "b"
,   ["a"] = "a"
,   ["c"] = "c"
}

io.readfile

可在不打开文件的情况下,直接读取整个文件的内容,更加的方便,例如:

local data = io.readfile("xxx.txt")

io.writefile

可在不打开文件的情况下,直接写入整个文件的内容,更加的方便,例如:

io.writefile("xxx.txt", "all data")

io.gsub

类似string.gsub接口,全文模式匹配替换内容,不过这里是直接操作文件,例如:

-- 移除文件所有的空白字符
io.gsub("xxx.txt", "%s+", "")

io.tail

读取文件尾部指定行数的数据,并显示,类似cat xxx.txt | tail -n 10命令,例如:

-- 显示文件最后10行内容
io.tail("xxx.txt", 10)

io.cat

读取文件的所有内容并显示,类似cat xxx.txt命令,例如:

io.cat("xxx.txt")

io.print

直接格式化传参输出一行字符串到文件,并且带换行,例如:

io.print("xxx.txt", "hello %s!", "xmake")

io.printf

直接格式化传参输出一行字符串到文件,不带换行,例如:

io.printf("xxx.txt", "hello %s!\n", "xmake")

path

路径操作模块,实现跨平台的路径操作,这是xmake的一个自定义的模块。

接口 描述 支持版本
path.join 拼接路径 >= 2.0.1
path.translate 转换路径到当前平台的路径风格 >= 2.0.1
path.basename 获取路径最后不带后缀的文件名 >= 2.0.1
path.filename 获取路径最后带后缀的文件名 >= 2.0.1
path.extension 获取路径的后缀名 >= 2.0.1
path.directory 获取路径最后的目录名 >= 2.0.1
path.relative 转换成相对路径 >= 2.0.1
path.absolute 转换成绝对路径 >= 2.0.1
path.is_absolute 判断是否为绝对路径 >= 2.0.1
path.splitenv 分割环境变量中的路径 >= 2.2.7

path.join

将多个路径项进行追加拼接,由于windows/unix风格的路径差异,使用api来追加路径更加跨平台,例如:

print(path.join("$(tmpdir)", "dir1", "dir2", "file.txt"))

上述拼接在unix上相当于:$(tmpdir)/dir1/dir2/file.txt,而在windows上相当于:$(tmpdir)\\dir1\\dir2\\file.txt

如果觉得这样很繁琐,不够清晰简洁,可以使用:path.translate方式,格式化转换路径字符串到当前平台支持的格式。

path.translate

格式化转化指定路径字符串到当前平台支持的路径风格,同时支持windows/unix格式的路径字符串参数传入,甚至混合传入,例如:

print(path.translate("$(tmpdir)/dir/file.txt"))
print(path.translate("$(tmpdir)\\dir\\file.txt"))
print(path.translate("$(tmpdir)\\dir/dir2//file.txt"))

上面这三种不同格式的路径字符串,经过translate规范化后,就会变成当前平台支持的格式,并且会去掉冗余的路径分隔符。

path.basename

print(path.basename("$(tmpdir)/dir/file.txt"))

显示结果为:file

path.filename

print(path.filename("$(tmpdir)/dir/file.txt"))

显示结果为:file.txt

path.extension

print(path.extensione("$(tmpdir)/dir/file.txt"))

显示结果为:.txt

path.directory

print(path.directory("$(tmpdir)/dir/file.txt"))

显示结果为:dir

path.relative

print(path.relative("$(tmpdir)/dir/file.txt", "$(tmpdir)"))

显示结果为:dir/file.txt

第二个参数是指定相对的根目录,如果不指定,则默认相对当前目录:

os.cd("$(tmpdir)")
print(path.relative("$(tmpdir)/dir/file.txt"))

这样结果是一样的。

path.absolute

print(path.absolute("dir/file.txt", "$(tmpdir)"))

显示结果为:$(tmpdir)/dir/file.txt

第二个参数是指定相对的根目录,如果不指定,则默认相对当前目录:

os.cd("$(tmpdir)")
print(path.absolute("dir/file.txt"))

这样结果是一样的。

path.is_absolute

if path.is_absolute("/tmp/file.txt") then
    -- 如果是绝对路径
end

path.splitenv

local pathes = path.splitenv(vformat("$(env PATH)"))

-- for windows 
local pathes = path.splitenv("C:\\Windows;C:\\Windows\\System32")
-- got { "C:\\Windows", "C:\\Windows\\System32" }

-- for *nix 
local pathes = path.splitenv("/usr/bin:/usr/local/bin")
-- got { "/usr/bin", "/usr/local/bin" }

结果为一个包含了输入字符串中路径的数组。

table

table属于lua原生提供的模块,对于原生接口使用可以参考:lua官方文档

xmake中对其进行了扩展,增加了一些扩展接口:

接口 描述 支持版本
table.join 合并多个table并返回 >= 2.0.1
table.join2 合并多个table到第一个table >= 2.0.1
table.unique 对table中的内容进行去重 >= 2.0.1
table.slice 获取table的切片 >= 2.0.1

table.join

可以将多个table里面的元素进行合并后,返回到一个新的table中,例如:

local newtable = table.join({1, 2, 3}, {4, 5, 6}, {7, 8, 9})

结果为:{1, 2, 3, 4, 5, 6, 7, 8, 9}

并且它也支持字典的合并:

local newtable = table.join({a = "a", b = "b"}, {c = "c"}, {d = "d"})

结果为:{a = "a", b = "b", c = "c", d = "d"}

table.join2

类似table.join,唯一的区别是,合并的结果放置在第一个参数中,例如:

local t = {0, 9}
table.join2(t, {1, 2, 3})

结果为:t = {0, 9, 1, 2, 3}

table.unique

去重table的元素,一般用于数组table,例如:

local newtable = table.unique({1, 1, 2, 3, 4, 4, 5})

结果为:{1, 2, 3, 4, 5}

table.slice

用于提取数组table的部分元素,例如:

-- 提取第4个元素后面的所有元素,结果:{4, 5, 6, 7, 8, 9}
table.slice({1, 2, 3, 4, 5, 6, 7, 8, 9}, 4)

-- 提取第4-8个元素,结果:{4, 5, 6, 7, 8}
table.slice({1, 2, 3, 4, 5, 6, 7, 8, 9}, 4, 8)

-- 提取第4-8个元素,间隔步长为2,结果:{4, 6, 8}
table.slice({1, 2, 3, 4, 5, 6, 7, 8, 9}, 4, 8, 2)

string

字符串模块为lua原生自带的模块,具体使用见:lua官方手册

xmake中对其进行了扩展,增加了一些扩展接口:

接口 描述 支持版本
string.startswith 判断字符串开头是否匹配 >= 1.0.1
string.endswith 判断字符串结尾是否匹配 >= 1.0.1
string.split 分割字符串 >= 1.0.1
string.trim 去掉字符串左右空白字符 >= 1.0.1
string.ltrim 去掉字符串左边空白字符 >= 1.0.1
string.rtrim 去掉字符串右边空白字符 >= 1.0.1

string.startswith

local s = "hello xmake"
if s:startswith("hello") then
    print("match")
end

string.endswith

local s = "hello xmake"
if s:endswith("xmake") then
    print("match")
end

string.split

v2.2.7版本对这个接口做了改进,以下是对2.2.7之后版本的使用说明。

按模式匹配分割字符串,忽略空串,例如:

("1\n\n2\n3"):split('\n') => 1, 2, 3
("abc123123xyz123abc"):split('123') => abc, xyz, abc
("abc123123xyz123abc"):split('[123]+') => abc, xyz, abc

按纯文本匹配分割字符串,忽略空串(省去了模式匹配,会提升稍许性能),例如:

("1\n\n2\n3"):split('\n', {plain = true}) => 1, 2, 3
("abc123123xyz123abc"):split('123', {plain = true}) => abc, xyz, abc

按模式匹配分割字符串,严格匹配,不忽略空串,例如:

("1\n\n2\n3"):split('\n', {strict = true}) => 1, , 2, 3
("abc123123xyz123abc"):split('123', {strict = true}) => abc, , xyz, abc
("abc123123xyz123abc"):split('[123]+', {strict = true}) => abc, xyz, abc

按纯文本匹配分割字符串,严格匹配,不忽略空串(省去了模式匹配,会提升稍许性能),例如:

("1\n\n2\n3"):split('\n', {plain = true, strict = true}) => 1, , 2, 3
("abc123123xyz123abc"):split('123', {plain = true, strict = true}) => abc, , xyz, abc

限制分割块数

("1\n\n2\n3"):split('\n', {limit = 2}) => 1, 2\n3
("1.2.3.4.5"):split('%.', {limit = 3}) => 1, 2, 3.4.5

string.trim

string.trim("    hello xmake!    ")

结果为:"hello xmake!"

string.ltrim

string.ltrim("    hello xmake!    ")

结果为:"hello xmake! "

string.rtrim

string.rtrim("    hello xmake!    ")

结果为:" hello xmake!"

process

这个是xmake扩展的进程控制模块,用于更加灵活的控制进程,比起:os.run系列灵活性更高,也更底层。

接口 描述 支持版本
process.open 打开进程 >= 2.0.1
process.openv 打开进程,传递参数列表 >= 2.0.1
process.waitlist 同时等待多个进程 >= 2.0.1

process.open

通过路径创建运行一个指定程序,并且返回对应的进程对象:

-- 打开进程,后面两个参数指定需要捕获的stdout, stderr文件路径
local proc = process.open("echo hello xmake!", {outpath = "/tmp/out", errpath = "/tmp/err", envs = {"PATH=xxx", "XXX=yyy"}}) 
if proc then

    -- 等待进程执行完成
    --
    -- 参数一为等待超时,-1为永久等待,0为尝试获取进程状态
    -- 返回值waitok为等待状态:1为等待进程正常结束,0为进程还在运行中,-1位等待失败
    -- 返回值status为,等待进程结束后,进程返回的状态码
    local waitok, status = proc:wait(-1)

    -- 释放进程对象
    proc:close()
end

上面的open参数中,outpath, errpath参数指定需要捕获的stdout, stderr文件路径。

另外,如果想在这次执行中临时设置和改写一些环境变量,可以传递envs参数,里面的环境变量设置会替换已有的设置,但是不影响外层的执行环境,只影响当前命令。

我们也可以通过os.getenvs()接口获取当前所有的环境变量,然后改写部分后传入envs参数。

process.openv

此接口和process.open用法基本相似,唯一的不同是,这里传递一个带参数列表的命令来执行,而不是传递命令字符串,这样会省去不必要的转义,传入的参数更加可靠,兼容性和效率也更好。

local proc = process.openv("echo", {"hello", "xmake!"})

process.waitlist

-- 第二个参数是等待超时,返回进程状态列表
for _, procinfo in ipairs(process.waitlist(procs, -1)) do

    -- 每个进程的:进程对象、进程pid、进程结束状态码
    local proc      = procinfo[1]
    local procid    = procinfo[2]
    local status    = procinfo[3]

end

coroutine

协程模块是lua原生自带的模块,具使用见:lua官方手册