add xmake examples

docs/codes/examples/configuration/autogen/modules/modules/autogen/foo.lua

@@ -0,0 +1,10 @@
+function generate(sourcefile, sourcefile_cx)
+    local file = io.open(sourcefile_cx, "w")
+    if file then
+        file:write('#include <stdio.h>\n')
+        file:write('void generated_func() {\n')
+        file:write('    printf("hello xmake!\\n");\n')
+        file:write('}\n')
+        file:close()
+    end
+end

docs/codes/examples/configuration/autogen/modules/src/main.cpp

@@ -0,0 +1,5 @@
+extern void generated_func();
+int main() {
+    generated_func();
+    return 0;
+}

docs/codes/examples/configuration/autogen/modules/src/test.in

@@ -0,0 +1 @@
+dummy content

docs/codes/examples/configuration/autogen/modules/xmake.lua

@@ -0,0 +1,31 @@
+add_rules("mode.debug", "mode.release")
+
+add_moduledirs("modules")
+
+rule("autogen")
+    set_extensions(".in")
+    before_build_file(function (target, sourcefile, opt)
+        import("utils.progress")
+        import("core.project.depend")
+        import("core.tool.compiler")
+        import("autogen.foo", {always_build = true})
+
+        local sourcefile_cx = path.join(target:autogendir(), "rules", "autogen", path.basename(sourcefile) .. ".cpp")
+        local objectfile = target:objectfile(sourcefile_cx)
+        table.insert(target:objectfiles(), objectfile)
+
+        depend.on_changed(function ()
+            progress.show(opt.progress, "${color.build.object}compiling.autogen %s", sourcefile)
+            os.mkdir(path.directory(sourcefile_cx))
+            foo.generate(sourcefile, sourcefile_cx)
+            compiler.compile(sourcefile_cx, objectfile, {target = target})
+        end, {dependfile = target:dependfile(objectfile),
+              files = sourcefile,
+              changed = target:is_rebuilt()})
+    end)
+
+target("test")
+    set_kind("binary")
+    add_rules("autogen")
+    add_files("src/main.cpp")
+    add_files("src/*.in")

docs/codes/examples/configuration/custom_toolchain/unknown_toolchain/src/foo.cpp

@@ -0,0 +1 @@
+void foo() {}

docs/codes/examples/configuration/custom_toolchain/unknown_toolchain/src/test.cpp

@@ -0,0 +1 @@
+int main() { return 0; }

docs/codes/examples/configuration/custom_toolchain/unknown_toolchain/xmake.lua

@@ -0,0 +1,15 @@
+add_rules("mode.debug", "mode.release")
+
+add_moduledirs("xmake/modules")
+add_toolchaindirs("xmake/toolchains")
+
+set_toolchains("my-c6000")
+
+target("test")
+    set_kind("static")
+    add_files("src/foo.cpp")
+
+target("demo")
+    set_kind("binary")
+    add_deps("test")
+    add_files("src/test.cpp")

docs/codes/examples/configuration/custom_toolchain/unknown_toolchain/xmake/modules/core/tools/ar6x.lua

@@ -0,0 +1,5 @@
+inherit("core.tools.ar")
+
+function init(self)
+    self:set("arflags", "-r")
+end

docs/codes/examples/configuration/custom_toolchain/unknown_toolchain/xmake/modules/core/tools/cl6x.lua

@@ -0,0 +1,67 @@
+import("core.base.option")
+import("core.base.global")
+import("core.project.policy")
+import("core.language.language")
+import("utils.progress")
+
+function init(self)
+end
+
+function nf_symbol(self, level)
+    local kind = self:kind()
+    if language.sourcekinds()[kind] then
+        local maps = _g.symbol_maps
+        if not maps then
+            maps =
+            {
+                debug  = "-g"
+            }
+            _g.symbol_maps = maps
+        end
+        return maps[level .. '_' .. kind] or maps[level]
+    end
+end
+
+function nf_optimize(self, level)
+    local maps =
+    {
+        none       = "-O0"
+    ,   fast       = "-O1"
+    ,   faster     = "-O2"
+    ,   fastest    = "-O3"
+    ,   smallest   = "-m3"
+    ,   aggressive = "-O3"
+    }
+    return maps[level]
+end
+
+function nf_define(self, macro)
+    return "-D" .. macro
+end
+
+function nf_undefine(self, macro)
+    return "-U" .. macro
+end
+
+function nf_includedir(self, dir)
+    return {"-I" .. dir}
+end
+
+function nf_sysincludedir(self, dir)
+    return nf_includedir(self, dir)
+end
+
+function nf_link(self, lib)
+    if not lib:endswith(".a") and not lib:endswith(".so") then
+         lib = "lib" .. lib .. ".a"
+    end
+    return "-l" .. lib
+end
+
+function nf_syslink(self, lib)
+    return nf_link(self, lib)
+end
+
+function nf_linkdir(self, dir)
+    return {"-i" .. path.translate(dir)}
+end

docs/codes/examples/configuration/custom_toolchain/unknown_toolchain/xmake/modules/core/tools/cl6x/has_flags.lua

@@ -0,0 +1,73 @@
+import("core.cache.detectcache")
+import("core.language.language")
+
+function _islinker(flags, opt)
+    local toolkind = opt.toolkind or ""
+    return toolkind == "ld" or toolkind == "sh" or toolkind:endswith("ld") or toolkind:endswith("sh")
+end
+
+function _try_running(program, argv, opt)
+    local errors = nil
+    return try { function () os.runv(program, argv, opt); return true end, catch { function (errs) errors = (errs or ""):trim() end }}, errors
+end
+
+function _check_from_knownargs(flags, opt, islinker)
+    local flag = flags[1]
+    if not islinker then
+        if flag:startswith("-D") or
+           flag:startswith("-U") or
+           flag:startswith("-I") then
+            return true
+        end
+    end
+end
+
+function _check_from_arglist(flags, opt, islinker)
+    local key = "core.tools.cl6x." .. (islinker and "has_ldflags" or "has_cflags")
+    local flagskey = opt.program .. "_" .. (opt.programver or "")
+    local allflags = detectcache:get2(key, flagskey)
+    if not allflags then
+        allflags = {}
+        local arglist = try {function () return os.iorunv(opt.program, {"--help"}, {envs = opt.envs}) end}
+        if arglist then
+            for arg in arglist:gmatch("%s+(%-[%-%a%d]+)%s+") do
+                allflags[arg] = true
+            end
+        end
+        detectcache:set2(key, flagskey, allflags)
+    end
+    local flag = flags[1]
+    return allflags[flag]
+end
+
+function _get_extension(opt)
+    return (opt.program:endswith("++") or opt.flagkind == "cxxflags") and ".cpp" or (table.wrap(language.sourcekinds()[opt.toolkind or "cc"])[1] or ".c")
+end
+
+function _check_try_running(flags, opt, islinker)
+
+    local snippet = opt.snippet or "int main(int argc, char** argv)\n{return 0;}\n"
+    local sourcefile = os.tmpfile("cl6x_has_flags:" .. snippet) .. _get_extension(opt)
+    if not os.isfile(sourcefile) then
+        io.writefile(sourcefile, snippet)
+    end
+
+    local tmpfile = os.tmpfile()
+    if islinker then
+        return _try_running(opt.program, table.join(flags, "-z", "--output_file=" .. tmpfile, sourcefile), opt)
+    end
+
+    return _try_running(opt.program, table.join(flags, "-c", "--output_file=" .. tmpfile, sourcefile), opt)
+end
+
+function main(flags, opt)
+    opt = opt or {}
+    local islinker = _islinker(flags, opt)
+    if _check_from_knownargs(flags, opt, islinker) then
+        return true
+    end
+    if _check_from_arglist(flags, opt, islinker) then
+        return true
+    end
+    return _check_try_running(flags, opt, islinker)
+end

docs/codes/examples/configuration/custom_toolchain/unknown_toolchain/xmake/modules/core/tools/cl6x/parse_deps.lua

@@ -0,0 +1,36 @@
+import("core.project.config")
+import("core.project.project")
+import("core.base.hashset")
+
+function _normailize_dep(dep, projectdir)
+    if not is_host("windows") then
+        dep = dep:gsub("\\(.)", "%1")
+    end
+    if path.is_absolute(dep) then
+        dep = path.translate(dep)
+    else
+        dep = path.absolute(dep, projectdir)
+    end
+    if dep:startswith(projectdir) then
+        return path.relative(dep, projectdir)
+    else
+        return dep
+    end
+end
+
+function main(depsdata, opt)
+    local results = hashset.new()
+    local projectdir = os.projectdir()
+    local line = depsdata:rtrim()
+    local plain = {plain = true}
+    for _, includefile in ipairs(line:split('\n', plain)) do
+        includefile = includefile:split(": ", plain)[2]
+        if includefile and #includefile > 0 then
+            includefile = _normailize_dep(includefile, projectdir)
+            if includefile then
+                results:insert(includefile)
+            end
+        end
+    end
+    return results:to_array()
+end

docs/codes/examples/configuration/custom_toolchain/unknown_toolchain/xmake/modules/detect/tools/find_ar6x.lua

@@ -0,0 +1,14 @@
+import("lib.detect.find_program")
+import("lib.detect.find_programver")
+
+function main(opt)
+    opt = opt or {}
+    opt.check = "--help"
+    opt.command = "--help"
+    local program = find_program(opt.program or "ar6x", opt)
+    local version = nil
+    if program and opt.version then
+        version = find_programver(program, opt)
+    end
+    return program, version
+end

docs/codes/examples/configuration/custom_toolchain/unknown_toolchain/xmake/modules/detect/tools/find_cl6x.lua

@@ -0,0 +1,14 @@
+import("lib.detect.find_program")
+import("lib.detect.find_programver")
+
+function main(opt)
+    opt = opt or {}
+    opt.check = "--help"
+    opt.command = "--help"
+    local program = find_program(opt.program or "cl6x", opt)
+    local version = nil
+    if program and opt.version then
+        version = find_programver(program, opt)
+    end
+    return program, version
+end

docs/codes/examples/configuration/custom_toolchain/unknown_toolchain/xmake/toolchains/my-c6000/xmake.lua

@@ -0,0 +1,20 @@
+toolchain("my-c6000")
+    set_kind("standalone")
+    set_homepage("https://www.ti.com")
+    set_description("TI-CGT C6000 compiler")
+
+    set_toolset("cc", "cl6x")
+    set_toolset("cxx", "cl6x")
+    set_toolset("ld", "cl6x")
+    set_toolset("sh", "cl6x")
+    set_toolset("ar", "ar6x")
+    set_toolset("strip", "strip6x")
+    set_toolset("as", "cl6x")
+
+    on_check(function (toolchain)
+        return import("lib.detect.find_tool")("cl6x")
+    end)
+
+    on_load(function (toolchain)
+        toolchain:add("cxflags", "-Dxxx")
+    end)

docs/examples/configuration/autogen.md

@@ -34,39 +34,7 @@ Xmake introduces native module development, allowing code generation via native
 
 For details on native module development, see: [Native Module Development](/api/scripts/native-modules).
 
-```lua
-add_rules("mode.debug", "mode.release")
-
-add_moduledirs("modules")
-
-rule("autogen")
-    set_extensions(".in")
-    before_build_file(function (target, sourcefile, opt)
-        import("utils.progress")
-        import("core.project.depend")
-        import("core.tool.compiler")
-        import("autogen.foo", {always_build = true})
-
-        local sourcefile_cx = path.join(target:autogendir(), "rules", "autogen", path.basename(sourcefile) .. ".cpp")
-        local objectfile = target:objectfile(sourcefile_cx)
-        table.insert(target:objectfiles(), objectfile)
-
-        depend.on_changed(function ()
-            progress.show(opt.progress, "${color.build.object}compiling.autogen %s", sourcefile)
-            os.mkdir(path.directory(sourcefile_cx))
-            foo.generate(sourcefile, sourcefile_cx)
-            compiler.compile(sourcefile_cx, objectfile, {target = target})
-        end, {dependfile = target:dependfile(objectfile),
-              files = sourcefile,
-              changed = target:is_rebuilt()})
-    end)
-
-target("test")
-    set_kind("binary")
-    add_rules("autogen")
-    add_files("src/main.cpp")
-    add_files("src/*.in")
-```
+<FileExplorer rootFilesDir="examples/configuration/autogen/modules" />
 
 See the full example: [Native Module Autogen](https://github.com/xmake-io/xmake/blob/dev/tests/projects/other/autogen/autogen_shared_module/xmake.lua).
 

docs/examples/configuration/custom_toolchain.md

@@ -6,6 +6,8 @@ outline: deep
 
 We can use `toolchain()` to define custom toolchains to support special compilers or cross-compilation environments.
 
+For details on custom toolchain configuration, see: [Custom Toolchain API](/api/description/custom-toolchain).
+
 ## Basic Example
 
 <FileExplorer rootFilesDir="examples/configuration/custom_toolchain/basic" />
@@ -16,3 +18,10 @@ We can use `toolchain()` to define custom toolchains to support special compiler
 $ xmake
 $ xmake run
 ```
+
+## Unknown Toolchain
+
+If we need to support a completely unknown compiler toolchain, we need to implement the detection script of the toolchain, as well as the script configuration of all tool sets such as compilation, linking, archiving, etc.
+
+<FileExplorer rootFilesDir="examples/configuration/custom_toolchain/unknown_toolchain" />
+

docs/zh/examples/configuration/autogen.md

@@ -34,39 +34,7 @@ Xmake 新增了原生模块开发特性，即使不定义额外的 autogen 目
 
 关于原生模块开发，可参考文档：[Native 模块开发](/zh/api/scripts/native-modules)。
 
-```lua
-add_rules("mode.debug", "mode.release")
-
-add_moduledirs("modules")
-
-rule("autogen")
-    set_extensions(".in")
-    before_build_file(function (target, sourcefile, opt)
-        import("utils.progress")
-        import("core.project.depend")
-        import("core.tool.compiler")
-        import("autogen.foo", {always_build = true})
-
-        local sourcefile_cx = path.join(target:autogendir(), "rules", "autogen", path.basename(sourcefile) .. ".cpp")
-        local objectfile = target:objectfile(sourcefile_cx)
-        table.insert(target:objectfiles(), objectfile)
-
-        depend.on_changed(function ()
-            progress.show(opt.progress, "${color.build.object}compiling.autogen %s", sourcefile)
-            os.mkdir(path.directory(sourcefile_cx))
-            foo.generate(sourcefile, sourcefile_cx)
-            compiler.compile(sourcefile_cx, objectfile, {target = target})
-        end, {dependfile = target:dependfile(objectfile),
-              files = sourcefile,
-              changed = target:is_rebuilt()})
-    end)
-
-target("test")
-    set_kind("binary")
-    add_rules("autogen")
-    add_files("src/main.cpp")
-    add_files("src/*.in")
-```
+<FileExplorer rootFilesDir="examples/configuration/autogen/modules" />
 
 完整例子见：[Native 模块自动生成](https://github.com/xmake-io/xmake/blob/dev/tests/projects/other/autogen/autogen_shared_module/xmake.lua)。
 

docs/zh/examples/configuration/custom_toolchain.md

@@ -6,6 +6,8 @@ outline: deep
 
 我们可以使用 `toolchain()` 定义自定义工具链，以支持特殊的编译器或交叉编译环境。
 
+关于自定义工具链的更多详情，请参考：[自定义工具链 API](/zh/api/description/custom-toolchain)。
+
 ## 基础示例
 
 <FileExplorer rootFilesDir="examples/configuration/custom_toolchain/basic" />
@@ -16,3 +18,10 @@ outline: deep
 $ xmake
 $ xmake run
 ```
+
+## 未知工具链
+
+如果我们需要支持一个完全未知的编译器工具链，我们需要实现工具链的探测脚本，以及编译、链接、归档等所有工具集的脚本配置。
+
+<FileExplorer rootFilesDir="examples/configuration/custom_toolchain/unknown_toolchain" />
+