xmake的工程描述文件xmake.lua虽然基于lua语法，但是为了使得更加方便简洁得编写项目构建逻辑，xmake对其进行了一层封装，使得编写xmake.lua不会像些makefile那样繁琐

基本上写个简单的工程构建描述，只需三行就能搞定，例如：

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

配置分离

xmake.lua采用二八原则实现了描述域、脚本域两层分离式配置。

什么是二八原则呢，简单来说，大部分项目的配置，80%的情况下，都是些基础的常规配置，比如：add_cxflags, add_links等，只有剩下不到20%的地方才需要额外做些复杂来满足一些特殊的配置需求。

而这剩余的20%的配置通常比较复杂，如果直接充斥在整个xmake.lua里面，会把整个项目的配置整个很混乱，非常不可读。

因此，xmake通过描述域、脚本域两种不同的配置方式，来隔离80%的简单配置以及20%的复杂配置，使得整个xmake.lua看起来非常的清晰直观，可读性和可维护性都达到最佳。

描述域

对于刚入门的新手用户，或者仅仅是维护一些简单的小项目，通过完全在描述配置就已经完全满足需求了，那什么是描述域呢？它长这样：

  1. target("test")
  2.     set_kind("binary")
  3.     add_files("src/*.c")
  4.     add_defines("DEBUG")
  5.     add_links("pthread", "m", "dl")

一眼望去，其实就是个 set_xxx/add_xxx的配置集，对于新手，完全可以不把它当做lua脚本，仅仅作为普通的，但有一些基础规则的配置文件就行了。

如果因为，看着有括号，还是像脚本语言的函数调用，那我们也可以这么写（是否带括号看个人喜好）：

  1. target "test"
  2.     set_kind    "binary"
  3.     add_files   "src/*.c"
  4.     add_defines "DEBUG"
  5.     add_links   "pthread", "m", "dl"

这是不是看着更像配置文件了？其实描述域就是配置文件，类似像json等key/values的配置而已，所以即使完全不会lua的新手，也是能很快上手的。

而且，对于通常的项目，仅通过set_xxx/add_xxx去配置各种项目设置，已经完全满足需求了。

这也就是开头说的：80%的情况下，可以用最简单的配置规则去简化项目的配置，提高可读性和可维护性，这样对用户和开发者都会非常的友好，也更加直观。

如果我们要针对不同平台，架构做一些条件判断怎么办？没关系，描述域除了基础配置，也是支持条件判断，以及for循环的：

  1. target("test")
  2.     set_kind("binary")
  3.     add_files("src/*.c")
  4.     add_defines("DEBUG")
  5.     if is_plat("linux", "macosx") then
  6.         add_links("pthread", "m", "dl")
  7.     end
  1. target("test")
  2.     set_kind("binary")
  3.     add_files("src/*.c")
  4.     add_defines("DEBUG")
  5.     for _, name in ipairs({"pthread", "m", "dl"}) do
  6.         add_links(name)
  7.     end

这是不是看着有点像lua了？虽说，平常可以把它当做普通配置问题，但是xmake毕竟基于lua，所以描述域还是支持lua的基础语言特性的。

!> 不过需要注意的是，描述域虽然支持lua的脚本语法，但在描述域尽量不要写太复杂的lua脚本，比如一些耗时的函数调用和for循环

并且在描述域，主要目的是为了设置配置项，因此xmake并没有完全开放所有的模块接口，很多接口在描述域是被禁止调用的，即使开放出来的一些可调用接口，也是完全只读的，不耗时的安全接口，比如：os.getenv()等读取一些常规的系统信息，用于配置逻辑的控制。

!> 另外需要注意一点，xmake.lua是会被多次解析的，用于在不同阶段解析不同的配置域：比如：option(), target()等域。

因此，不要想着在xmake.lua的描述域，写复杂的lua脚本，也不要在描述域调用print去显示信息，因为会被执行多遍，记住：会被执行多遍！！！

脚本域

限制描述域写复杂的lua，各种lua模块和接口都用不了？怎么办？这个时候就是脚本域出场的时候了。

如果用户已经完全熟悉了xmake的描述域配置，并且感觉有些满足不了项目上的一些特殊配置维护了，那么我们可以在脚本域做更加复杂的配置逻辑：

  1. target("test")
  2.     set_kind("binary")
  3.     add_files("src/*.c")
  4.     on_load(function (target)
  5.         if is_plat("linux", "macosx") then
  6.             target:add("links", "pthread", "m", "dl")
  7.         end
  8.     end)
  9.     after_build(function (target)
  10.         import("core.project.config")
  11.         local targetfile = target:targetfile()
  12.         os.cp(targetfile, path.join(config.buildir(), path.filename(targetfile)))
  13.         print("build %s", targetfile)
  14.     end)

只要是类似：on_xxx, after_xxx, before_xxx等字样的function body内部的脚本，都属于脚本域。

在脚本域中，用户可以干任何事，xmake提供了import接口可以导入xmake内置的各种lua模块，也可以导入用户提供的lua脚本。

我们可以在脚本域实现你想实现的任意功能，甚至写个独立项目出来都是可以的。

对于一些脚本片段，不是很臃肿的话，像上面这么内置写写就足够了，如果需要实现更加复杂的脚本，不想充斥在一个xmake.lua里面，可以把脚本分离到独立的lua文件中去维护。

例如：

  1. target("test")
  2.     set_kind("binary")
  3.     add_files("src/*.c")
  4.     on_load("modules.test.load")
  5.     on_install("modules.test.install")

我们可以吧自定义的脚本放置到xmake.lua对应目录下，modules/test/load.lua和modules/test/install.lua中独立维护。

这些独立的lua脚本里面，我们还可以通过import导入各种内置模块和自定义模块进来使用，就跟平常写lua, java没啥区别。

而对于脚本的域的不同阶段，on_load主要用于target加载时候，做一些动态化的配置，这里不像描述域，只会执行一遍哦!!!

其他阶段，还有很多，比如：on/after/before_build/install/package/run等，具体看下后面的target api手册部分吧，这里就不细说了。

配置类型

在描述域配置中，分配置域和配置项，配置域里面可以通过set_xxx/add_xxx的接口，配置各种配置项。

  1. target("test1")
  2.     set_kind("binary")
  3.     add_files("src/*.c")
  5. target("test2")
  6.     set_kind("binary")
  7.     add_files("src/*.c")

像上述配置中，target就属于配置域，它下面的所有set_xx/add_xxx接口配置都属于配置项，对这个target局部生效。

我们可以把它理解成局部作用域，类似c里面的block块：

  1. target("test1")
  2. {
  3.     set_kind("binary")
  4.     add_files("src/*.c")
  5. }
  6. target("test2")
  7. {
  8.     set_kind("binary")
  9.     add_files("src/*.c")
  10. }

不过，为了简化写法，xmake约定每个新定义的target域开始，上一个配置域就自动结束了，当然，如果这样用户觉得有困扰，也可以手动配置离开域：

  1. target("test1")
  2.     set_kind("binary")
  3.     add_files("src/*.c")
  4. target_end()
  6. target("test2")
  7.     set_kind("binary")
  8.     add_files("src/*.c")
  9. target_end()

配置域

目前提供的配置域有：target(), option(), task(), package()

每个域的详细说明，见：API手册

配置项

只要是带有set_xxx和add_xxx字样的配置，都属于配置项，一个配置域里面可以设置多个配置项。

关于配置项的规范说明，见：接口规范

作用域

xmake的描述语法是按作用域划分的，主要分为：

  • 外部作用域
  • 内部作用域
  • 接口作用域

那哪些属于外部，哪些又属于内部呢，看看下面的注释，就知道个大概了：

  1. -- 外部作用域
  2. target("test")
  4.     -- 外部作用域
  5.     set_kind("binary")
  6.     add_files("src/*.c")
  8.     on_run(function ()
  9.         -- 内部作用域
  10.         end)
  12.     after_package(function ()
  13.         -- 内部作用域
  14.         end)
  16. -- 外部作用域
  17. task("hello")
  19.     -- 外部作用域
  20.     on_run(function ()
  21.         -- 内部作用域
  22.         end)

简单的说，就是在自定义脚本function () end之内的都属于内部作用域，也就是脚本作用域，其他地方都是都属于于外部作用域。。

外部作用域

对于大部分工程来说，并不需要很复杂的工程描述，也不需要自定义脚本支持，只需要简单的 set_xxx 或者 add_xxx 就能满足需求了

那么根据二八定律，80%的情况下，我们只需要这么写：

  1. target("test")
  2.     set_kind("static")
  3.     add_files("src/test/*.c")
  5. target("demo")
  6.     add_deps("test")
  7.     set_kind("binary")
  8.     add_links("test")
  9.     add_files("src/demo/*.c")

不需要复杂的api调用，也不需要各种繁琐的变量定义，以及 if 判断 和 for 循环，要的就是简洁可读，一眼看过去，就算不懂lua语法也没关系

就当做简单的描述语法，看上去有点像函数调用而已，会点编程的基本一看就知道怎么配置。

为了做到简洁、安全，在这个作用域内，很多lua 内置api是不开放出来的，尤其是跟写文件、修改操作环境相关的，仅仅提供一些基本的只读接口，和逻辑操作

目前外部作用域开放的lua内置api有：

  • table
  • string
  • pairs
  • ipairs
  • print
  • os

当然虽然内置lua api提供不多，但xmake还提供了很多扩展api，像描述api就不多说，详细可参考：API手册

还有些辅助api，例如：

dirs：扫描获取当前指定路径中的所有目录files：扫描获取当前指定路径中的所有文件format: 格式化字符串，string.format的简写版本

还有变量定义、逻辑操作也是可以使用的，毕竟是基于lua的，该有的基础语法，还是要有的，我们可以通过if来切换编译文件：

  1. target("test")
  2.     set_kind("static")
  3.     if is_plat("iphoneos") then
  4.         add_files("src/test/ios/*.c")
  5.     else
  6.         add_files("src/test/*.c")
  7.     end

需要注意的是，变量定义分全局变量和局部变量，局部变量只对当前xmake.lua有效，不影响子xmake.lua

  1. -- 局部变量，只对当前xmake.lua有效
  2. local var1 = 0
  4. -- 全局变量，影响所有之后 includes() 包含的子 xmake.lua 
  5. var2 = 1
  7. includes("src")

内部作用域

也称插件、脚本作用域，提供更加复杂、灵活的脚本支持，一般用于编写一些自定义脚本、插件开发、自定义task任务、自定义模块等等

一般通过function () end包含，并且被传入到on_xxx, before_xxx和after_xxx接口内的，都属于自作用域。

例如：

  1. -- 自定义脚本
  2. target("hello")
  3.     after_build(function ()
  4.         -- 内部作用域
  5.         end)
  7. -- 自定义任务、插件
  8. task("hello")
  9.     on_run(function ()
  10.         -- 内部作用域
  11.         end)

在此作用域中，不仅可以使用大部分lua的api，还可以使用很多xmake提供的扩展模块，所有扩展模块，通过import来导入

具体可参考：import模块导入文档

这里我们给个简单的例子，在编译完成后，对ios目标程序进行ldid签名：

  1. target("iosdemo")
  2.     set_kind("binary")
  3.     add_files("*.m")
  4.     after_build(function (target) 
  6.         -- 执行签名，如果失败，自动中断，给出高亮错误信息
  7.         os.run("ldid -S$(projectdir)/entitlements.plist %s", target:targetfile())
  8.     end)

需要注意的是，在内部作用域中，所有的调用都是启用异常捕获机制的，如果运行出错，会自动中断xmake，并给出错误提示信息

因此，脚本写起来，不需要繁琐的if retval then判断，脚本逻辑更加一目了然

接口作用域

在外部作用域中的所有描述api设置，本身也是有作用域之分的，在不同地方调用，影响范围也不相同，例如：

  1. -- 全局根作用域，影响所有target，包括includes() 中的子工程target设置
  2. add_defines("DEBUG")
  4. -- 定义或者进入demo目标作用域（支持多次进入来追加设置）
  5. target("demo")
  6.     set_kind("shared")
  7.     add_files("src/*.c")
  8.     -- 当前target作用域，仅仅影响当前target
  9.     add_defines("DEBUG2")
  11. -- 选项设置，仅支持局部设置，不受全局api设置所影响
  12. option("test")
  13.     -- 当前选项的局部作用域
  14.     set_default(false)
  16. -- 其他target设置，-DDEBUG 也会被设置上
  17. target("demo2")
  18.     set_kind("binary")
  19.     add_files("src/*.c")
  21. -- 重新进入demo目标作用域
  22. target("demo")
  23.     -- 追加宏定义，只对当前demo目标有效
  24.     add_defines("DEBUG3")

通常情况下，进入另一个target/option域设置，会自动离开上个target/option域，但是有时候为了比较一些作用域污染情况，我们可以显示离开某个域，例如：

  1. option("test")
  2.     set_default(false)
  3. option_end()
  5. target("demo")
  6.     set_kind("binary")
  7.     add_files("src/*.c")
  8. target_end()

调用option_end(), target_end()即可显式的离开当前target/option域设置。

作用域缩进

xmake.lua里面缩进，只是个编写规范，用于更加清楚的区分，当前的设置 是针对 那个作用域的，虽然就算不缩进，也一样ok，但是可读性上 并不是很好。。

例如：

  1. target("xxxx")
  2.     set_kind("binary")
  3.     add_files("*.c")

和

  1. target("xxxx")
  2. set_kind("binary")
  3. add_files("*.c")

上述两种方式，效果上都是一样的，但是理解上，第一种更加直观，一看就知道add_files仅仅只是针对 target 设置的，并不是全局设置

因此，适当的进行缩进，有助于更好的维护xmake.lua

最后附上，tbox的xmake.lua描述，仅供参考。。

多级配置

在脚本域我们可以通过import导入各种丰富的扩展模块来使用，而在描述域我们可以通过includes接口，来引入项目子目录下的xmake.lua配置。

记住：xmake的includes是按照tree结构来处理配置关系的，子目录下的xmake.lua里面的target配置会继承父xmake.lua中的根域配置，例如：

目前有如下项目结构：

  1. projectdir
  2.     - xmake.lua
  3.     - src
  4.       - xmake.lua

projectdir/xmake.lua是项目的根xmake.lua配置，而src/xmake.lua是项目的子配置。

projectdir/xmake.lua内容：

  1. add_defines("ROOT")
  3. target("test1")
  4.     set_kind("binary")
  5.     add_files("src/*.c")
  6.     add_defines("TEST1")
  8. target("test2")
  9.     set_kind("binary")
  10.     add_files("src/*.c")
  11.     add_defines("TEST2")
  13. includes("src")

里面全局根域配置了add_defines("ROOT")，会影响下面的所有target配置，包括includes里面子xmake.lua中的所有target配置，所以这个是全局总配置。

而在test1/test2里面的add_defines("TEST1")和add_defines("TEST2")属于局部配置，只对当前target生效。

src/xmake.lua内容：

  1. add_defines("ROOT2")
  3. target("test3")
  4.     set_kind("binary")
  5.     add_files("src/*.c")
  6.     add_defines("TEST3")

在src/xmake.lua子配置中，也有个全局根域，配置了add_defines("ROOT2")，这个属于子配置根域，只对当前子xmake.lua里面所有target生效，也会对下级includes里面的子xmake.lua中target生效，因为之前说了，xmake是tree状结构的配置继承关系。

所以，这几个target的最终配置结果依次是：

  1. target("test1"): -DROOT -DTEST1
  2. target("test2"): -DROOT -DTEST2
  3. target("test3"): -DROOT -DROOT2 -DTEST3

语法简化

xmake.lua的配置域语法，非常灵活，可以在相关域做各种复杂灵活的配置，但是对于许多精简的小块配置，这个时候就稍显冗余了：

  1. option("test1")
  2.     set_default(true)
  3.     set_showmenu(true)
  4.     set_description("test1 option")
  6. option("test2")
  7.     set_default(true)
  8.     set_showmeu(true)
  10. option("test3")
  11.     set_default("hello")

xmake 2.2.6以上版本，对于上面的这些小块option域设置，我们可以简化下成单行描述：

  1. option("test1", {default = true, showmenu = true, description = "test1 option"})
  2. option("test2", {default = true, showmenu = true})
  3. option("test3", {default = "hello"})

除了option域，对于其他域也是支持这种简化写法的，例如：

  1. target("demo")
  2.     set_kind("binary")
  3.     add_files("src/*.c")

简化为：

  1. target("demo", {kind = "binary", files = "src/*.c"})

当然，如果配置需求比较复杂的，还是原有的多行设置方式更加方便，这个就看自己的需求来评估到底使用哪种方式了。