插件和任务
Xmake 支持自定义任务和插件，它们都基于 task 任务系统实现。任务可以用于自动化构建流程、代码生成、文件处理等各种项目需求。
基础概念
- 任务 (Task): 自定义的构建步骤或工具，可以在项目中调用
- 插件 (Plugin): 特殊的任务，通常提供更复杂的功能，通过
set_category("plugin")分类 - 菜单: 通过
set_menu()设置，让任务可以通过命令行直接调用
创建简单任务
基本语法
lua
task("taskname") on_run(function () -- 任务执行逻辑 print("任务执行中...") end)示例：Hello 任务
lua
task("hello") on_run(function () print("hello xmake!") end)这个任务只能在 xmake.lua 中通过 task.run() 调用：
lua
target("test") after_build(function (target) import("core.project.task") task.run("hello") end)创建命令行任务
设置菜单
通过 set_menu() 可以让任务通过命令行直接调用：
lua
task("echo") on_run(function () import("core.base.option") -- 获取参数内容并显示 local contents = option.get("contents") or {} local color = option.get("color") or "black" cprint("${%s}%s", color, table.concat(contents, " ")) end) set_menu { usage = "xmake echo [options]", description = "显示指定信息", options = { {'c', "color", "kv", "black", "设置输出颜色"}, {nil, "contents", "vs", nil, "要显示的内容"} } }现在可以通过命令行调用：
sh
$ xmake echo -c red hello xmake!任务分类
设置任务分类
lua
task("myplugin") set_category("plugin") -- 分类为插件 on_run(function () print("这是一个插件") end)分类说明：
- plugin: 显示在 "Plugins" 分组中
- action: 内置任务默认分类
- 自定义: 可以设置任意分类名称
任务参数处理
参数类型
lua
task("example") on_run(function () import("core.base.option") -- 获取不同类型的参数 local verbose = option.get("verbose") -- 布尔值 local color = option.get("color") -- 键值对 local files = option.get("files") -- 多值参数 local args = {...} -- 可变参数 end) set_menu { options = { {'v', "verbose", "k", nil, "启用详细输出"}, -- 布尔选项 {'c', "color", "kv", "red", "设置颜色"}, -- 键值选项 {'f', "files", "vs", nil, "文件列表"}, -- 多值选项 {nil, "args", "vs", nil, "其他参数"} -- 可变参数 } }参数类型说明
- k: key-only，布尔值参数
- kv: key-value，键值对参数
- v: value，单值参数
- vs: values，多值参数
在项目中使用任务
构建后执行任务
lua
target("test") set_kind("binary") add_files("src/*.cpp") after_build(function (target) import("core.project.task") -- 构建完成后运行代码生成任务 task.run("generate-code") -- 运行测试任务 task.run("run-tests") end)自定义构建任务
lua
-- 代码生成任务 task("generate-code") on_run(function () print("生成代码...") -- 执行代码生成逻辑 os.exec("protoc --cpp_out=src proto/*.proto") end) -- 测试任务 task("run-tests") on_run(function () print("运行测试...") os.exec("xmake run test") end)文件处理任务
lua
task("process-assets") on_run(function () import("core.base.option") local input_dir = option.get("input") or "assets" local output_dir = option.get("output") or "build/assets" -- 处理资源文件 os.mkdir(output_dir) os.cp(path.join(input_dir, "*.png"), output_dir) os.cp(path.join(input_dir, "*.json"), output_dir) print("资源文件处理完成") end) set_menu { usage = "xmake process-assets [options]", description = "处理项目资源文件", options = { {'i', "input", "kv", "assets", "输入目录"}, {'o', "output", "kv", "build/assets", "输出目录"} } }复杂任务示例
示例 1：代码格式化任务
lua
task("format") on_run(function () import("core.base.option") import("lib.detect.find_tool") local tool = find_tool("clang-format") if not tool then raise("clang-format not found!") end local files = option.get("files") or {"src/**/*.cpp", "src/**/*.h"} for _, pattern in ipairs(files) do local filelist = os.files(pattern) for _, file in ipairs(filelist) do os.execv(tool.program, {"-i", file}) print("格式化文件:", file) end end end) set_menu { usage = "xmake format [options]", description = "格式化代码文件", options = { {'f', "files", "vs", nil, "要格式化的文件模式"} } }示例 2：项目清理任务
lua
task("clean-all") on_run(function () local patterns = { "build/**", "*.log", "*.tmp", "*.o", "*.a", "*.so", "*.dylib", "*.exe" } for _, pattern in ipairs(patterns) do os.tryrm(pattern) end print("项目清理完成") end) set_menu { usage = "xmake clean-all", description = "清理所有构建文件和临时文件" }任务调用方式
1. 命令行调用
sh
$ xmake taskname [options] [args...]2. 脚本中调用
lua
import("core.project.task") -- 调用任务 task.run("taskname") -- 传递参数 task.run("taskname", {option1 = "value1"}, "arg1", "arg2")3. 在构建流程中调用
lua
target("test") before_build(function (target) task.run("prepare") end) after_build(function (target) task.run("post-process") end)最佳实践
- 错误处理: 使用
pcall包装任务逻辑 - 进度显示: 使用
progress.show()显示执行进度 - 参数验证: 检查必要参数是否存在
- 模块化: 复杂任务使用独立模块文件
- 文档化: 为任务添加清晰的描述和用法说明