add docs

docs/api/scripts/extension-modules/async/jobgraph.md

@@ -0,0 +1,107 @@
+# async.jobgraph
+
+This module provides a job graph (DAG) for advanced asynchronous job scheduling and dependency management in xmake Lua scripts.
+
+## jobgraph.new
+
+Create a new job graph instance.
+
+```lua
+import("async.jobgraph")
+local jobs = jobgraph.new()
+```
+
+> All following examples assume `async.jobgraph` has been imported.
+
+## jobgraph:add
+
+- Add a job node to the job graph.
+
+```lua
+local jobs = jobgraph.new()
+jobs:add("job/root", function() print("root job") end)
+jobs:add("job/child", function() print("child job") end)
+```
+
+You can also assign a job to a group or multiple groups using the `groups` option:
+
+```lua
+local jobs = jobgraph.new()
+
+-- Add a job to a single group
+jobs:add("foo/buildfiles", function(index, total, opt)
+    -- build logic
+end, {groups = "foo/buildfiles"})
+
+-- Add a job to multiple groups
+jobs:add("xxx", function(index, total, opt)
+    -- ...
+end, {groups = {"group1", "group2"}})
+```
+
+::: tip NOTE
+For batch group operations, it is generally more recommended and convenient to use `jobgraph:group`.
+
+See: [jobgraph:group](#jobgraph-group)
+:::
+
+A typical use case in a rule:
+
+```lua
+rule("foo")
+    on_build_files(function (target, jobgraph, sourcebatch, opt)
+        local group_name = target:name() .. "/buildfiles"
+        for _, sourcefile in ipairs(sourcebatch.sourcefiles) do
+            local job_name = target:name() .. "/" .. sourcefile
+            jobgraph:add(job_name, function(index, total, opt)
+                -- TODO: build file
+            end, {groups = group_name})
+        end
+        -- add job orders, other target jobs -> this build group
+        jobgraph:add_orders(other_target:name() .. "/buildfiles", group_name)
+    end, {jobgraph = true})
+```
+
+## jobgraph:add_orders
+
+- Add dependency edges (jobname depends on ...).
+
+```lua
+local jobs = jobgraph.new()
+jobs:add("job/root", function() print("root job") end)
+jobs:add("job/child", function() print("child job") end)
+jobs:add_orders("job/child", "job/root")
+```
+
+## jobgraph:group
+
+- Group jobs for batch dependency management. You can use a callback to add jobs to a group.
+
+```lua
+local jobs = jobgraph.new()
+
+jobs:add("job", function(index, total, opt)
+    -- ...
+end)
+
+jobs:group("group1", function()
+    for i = 0, N do
+        jobs:add("group1/job" .. i, function(index, total, opt)
+            -- TODO
+        end)
+    end
+end)
+
+jobs:group("group2", function()
+    for i = 0, N do
+        jobs:add("group2/job" .. i, function(index, total, opt)
+            -- TODO
+        end)
+    end
+end)
+
+-- sort job orders after adding all these jobs
+jobs:add_orders("job", "group1", "group2")
+```
+
+See also: [async.runjobs](/api/scripts/extension-modules/async/runjobs) 

docs/api/scripts/extension-modules/async/runjobs.md

@@ -0,0 +1,43 @@
+# async.runjobs
+
+This module runs all jobs in a job graph concurrently, respecting dependencies.
+
+## runjobs
+
+Run all jobs in the job graph concurrently.
+
+- `comax`: Maximum number of concurrent jobs.
+- `timeout`: Timeout for each job (ms).
+- `timer`: Timer callback for monitoring running jobs.
+
+```lua
+import("core.base.scheduler")
+import("async.jobgraph")
+import("async.runjobs")
+
+function jobfunc(index, total, opt)
+    print("%s: run job (%d/%d)", scheduler.co_running(), index, total)
+    os.sleep(1000)
+    print("%s: run job (%d/%d) end, progress: %s", scheduler.co_running(), index, total, opt.progress)
+end
+
+local jobs = jobgraph.new()
+jobs:add("job/root", jobfunc)
+for i = 1, 3 do
+    jobs:add("job/" .. i, jobfunc)
+    for j = 1, 5 do
+        jobs:add("job/" .. i .. "/" .. j, jobfunc)
+        jobs:add_orders("job/" .. i .. "/" .. j, "job/" .. i, "job/root")
+    end
+end
+
+runjobs("test", jobs, {
+    comax = 4,
+    timeout = 1000,
+    timer = function (running_jobs_indices)
+        print("timeout, running: %s", table.concat(running_jobs_indices, ","))
+    end
+})
+```
+
+See also: [async.jobgraph](/api/scripts/extension-modules/async/jobgraph) 

docs/sidebar.ts

@@ -29,6 +29,7 @@ export function builtinModulesApiSidebarItems(): DefaultTheme.SidebarItem[] {
 
 export function extensionModulesApiSidebarItems(): DefaultTheme.SidebarItem[] {
   return [
+    asyncModulesApiSidebar(),
     cliModulesApiSidebar(),
     coreModulesApiSidebar(),
     develModulesApiSidebar(),
@@ -138,6 +139,17 @@ function netModulesApiSidebar(): DefaultTheme.SidebarItem {
   }
 }
 
+function asyncModulesApiSidebar(): DefaultTheme.SidebarItem {
+  return {
+    text: 'async',
+    collapsed: true,
+    items: [
+      { text: 'jobgraph', link: 'extension-modules/async/jobgraph' },
+      { text: 'runjobs', link: 'extension-modules/async/runjobs' },
+    ]
+  }
+}
+
 function privilegeModulesApiSidebar(): DefaultTheme.SidebarItem {
   return {
     text: 'privilege',

docs/zh/api/scripts/extension-modules/async/jobgraph.md

@@ -0,0 +1,107 @@
+# async.jobgraph
+
+此模块为 xmake 的 Lua 脚本提供任务图（DAG），用于高级异步任务调度与依赖管理。
+
+## jobgraph.new
+
+创建新的任务图实例。
+
+```lua
+import("async.jobgraph")
+local jobs = jobgraph.new()
+```
+
+> 下方所有示例均假定已 import("async.jobgraph")。
+
+## jobgraph:add
+
+- 向任务图添加一个任务节点。
+
+```lua
+local jobs = jobgraph.new()
+jobs:add("job/root", function() print("root job") end)
+jobs:add("job/child", function() print("child job") end)
+```
+
+如需将任务加入分组，可通过 `groups` 选项实现：
+
+```lua
+local jobs = jobgraph.new()
+
+-- 添加到单个分组
+jobs:add("foo/buildfiles", function(index, total, opt)
+    -- 构建逻辑
+end, {groups = "foo/buildfiles"})
+
+-- 添加到多个分组
+jobs:add("xxx", function(index, total, opt)
+    -- ...
+end, {groups = {"group1", "group2"}})
+```
+
+::: tip 提示
+对于批量分组场景，更推荐使用 `jobgraph:group`，更为方便。
+
+详见：[jobgraph:group](#jobgraph-group)
+:::
+
+典型用法（如 rule 中）：
+
+```lua
+rule("foo")
+    on_build_files(function (target, jobgraph, sourcebatch, opt)
+        local group_name = target:name() .. "/buildfiles"
+        for _, sourcefile in ipairs(sourcebatch.sourcefiles) do
+            local job_name = target:name() .. "/" .. sourcefile
+            jobgraph:add(job_name, function(index, total, opt)
+                -- TODO: 构建文件
+            end, {groups = group_name})
+        end
+        -- 添加依赖关系，其他 target 的 job -> 当前 build group
+        jobgraph:add_orders(other_target:name() .. "/buildfiles", group_name)
+    end, {jobgraph = true})
+```
+
+## jobgraph:add_orders
+
+- 添加依赖边（jobname 依赖 ...）。
+
+```lua
+local jobs = jobgraph.new()
+jobs:add("job/root", function() print("root job") end)
+jobs:add("job/child", function() print("child job") end)
+jobs:add_orders("job/child", "job/root")
+```
+
+## jobgraph:group
+
+- 分组批量管理任务依赖。可通过回调批量添加分组任务。
+
+```lua
+local jobs = jobgraph.new()
+
+jobs:add("job", function(index, total, opt)
+    -- ...
+end)
+
+jobs:group("group1", function()
+    for i = 0, N do
+        jobs:add("group1/job" .. i, function(index, total, opt)
+            -- TODO
+        end)
+    end
+end)
+
+jobs:group("group2", function()
+    for i = 0, N do
+        jobs:add("group2/job" .. i, function(index, total, opt)
+            -- TODO
+        end)
+    end
+end)
+
+-- 添加所有分组后统一排序依赖
+jobs:add_orders("job", "group1", "group2")
+```
+
+相关链接：[async.runjobs](/zh/api/scripts/extension-modules/async/runjobs) 

docs/zh/api/scripts/extension-modules/async/runjobs.md

@@ -0,0 +1,43 @@
+# async.runjobs
+
+此模块用于并发执行任务图中的所有任务，自动处理依赖关系。
+
+## runjobs
+
+并发执行任务图中的所有任务。
+
+- `comax`: 最大并发任务数
+- `timeout`: 单个任务超时时间（毫秒）
+- `timer`: 定时回调，可用于监控当前运行中的任务
+
+```lua
+import("core.base.scheduler")
+import("async.jobgraph")
+import("async.runjobs")
+
+function jobfunc(index, total, opt)
+    print("%s: run job (%d/%d)", scheduler.co_running(), index, total)
+    os.sleep(1000)
+    print("%s: run job (%d/%d) end, progress: %s", scheduler.co_running(), index, total, opt.progress)
+end
+
+local jobs = jobgraph.new()
+jobs:add("job/root", jobfunc)
+for i = 1, 3 do
+    jobs:add("job/" .. i, jobfunc)
+    for j = 1, 5 do
+        jobs:add("job/" .. i .. "/" .. j, jobfunc)
+        jobs:add_orders("job/" .. i .. "/" .. j, "job/" .. i, "job/root")
+    end
+end
+
+runjobs("test", jobs, {
+    comax = 4,
+    timeout = 1000,
+    timer = function (running_jobs_indices)
+        print("timeout, running: %s", table.concat(running_jobs_indices, ","))
+    end
+})
+```
+
+相关链接：[async.jobgraph](/zh/api/scripts/extension-modules/async/jobgraph) 

docs/zh/sidebar.ts

@@ -0,0 +1,23 @@
+function extensionModulesApiSidebarItems(): DefaultTheme.SidebarItem[] {
+  return [
+    asyncModulesApiSidebar(),
+    cliModulesApiSidebar(),
+    coreModulesApiSidebar(),
+    develModulesApiSidebar(),
+    libModulesApiSidebar(),
+    netModulesApiSidebar(),
+    privilegeModulesApiSidebar(),
+    utilsModulesApiSidebar(),
+  ]
+}
+
+function asyncModulesApiSidebar(): DefaultTheme.SidebarItem {
+  return {
+    text: 'async',
+    collapsed: true,
+    items: [
+      { text: 'jobgraph', link: 'extension-modules/async/jobgraph' },
+      { text: 'runjobs', link: 'extension-modules/async/runjobs' },
+    ]
+  }
+}