update docs

manual/extension_modules.md

@@ -1848,3 +1848,53 @@ If you don’t want to automatically generate def from dll.a, but want to borrow
 `{dllname = xxx, arch = "xxx"}` These are optional, according to your needs.
 
 You can also directly xmake l utils.platform.gnu2mslib xxx.lib xxx.dll.a quick test verification
+
+### cli
+
+#### cli.amalgamate
+
+- Merge into single source file
+
+This is a small utility module for quickly merging all c/c++ and header sources inside a given target into a single source file.
+
+The merge expands all the internal includes headers and generates a DAG, which is introduced by topological sorting.
+
+By default it will handle the merge of all targets, for example:
+
+```bash
+$ xmake l cli.amalgamate
+build/tbox.c generated!
+build/tbox.h generated!
+```
+
+We can also specify the targets we need for the merge:
+
+```bash
+$ xmake l cli.amalgamate tbox
+build/tbox.c generated!
+build/tbox.h generated!
+```
+
+You can also handle symbol conflicts by specifying a custom unique ID macro definition for each source file you merge.
+
+```bash
+$ xmake l cli.amalgamate -u MY_UNIQUEU_ID
+build/tbox.c generated!
+build/tbox.h generated!
+```
+
+If there are renamed symbols in multiple source files, you can determine if the `MY_UNIQUEU_ID` macro is defined, and if it is, then it is in a single file, so you can handle the renamed symbols yourself in the source code.
+
+```c
+#ifdef MY_UNIQUEU_ID
+    // do some thing
+#endif
+```
+
+We can also specify the output location:
+
+```bash
+$ xmake l cli.amalgamate -o /xxx
+/xxx/tbox.c generated!
+/xxx/tbox.h generated!
+```

zh-cn/manual/extension_modules.md

@@ -1627,3 +1627,54 @@ gnu2mslib("xxx.lib", "xxx.dll.a", {dllname = "xxx.dll", arch = "x64"})
 `{dllname = xxx, arch = "xxx"}` 这些是可选的，根据自己的需求而定。。
 
 也可以直接 xmake l utils.platform.gnu2mslib xxx.lib xxx.dll.a 快速测试验证
+
+### cli
+
+#### cli.amalgamate
+
+- 合并成单源码文件
+
+这是一个小工具模块，主要用于快速合并指定 target 里面的所有 c/c++ 和 头文件源码到单个源文件。
+
+合并会将内部 includes 头文件全部展开，并生成 DAG，通过拓扑排序引入。
+
+默认它会处理所有 target 的合并，例如：
+
+```bash
+$ xmake l cli.amalgamate
+build/tbox.c generated!
+build/tbox.h generated!
+```
+
+我们也可以指定合并需要的目标：
+
+```bash
+$ xmake l cli.amalgamate tbox
+build/tbox.c generated!
+build/tbox.h generated!
+```
+
+也可以在合并每个源文件时候，指定一个自定义的 unique ID 的宏定义，来处理符号冲突问题。
+
+```bash
+$ xmake l cli.amalgamate -u MY_UNIQUEU_ID
+build/tbox.c generated!
+build/tbox.h generated!
+```
+
+如果多个源文件内部有重名符号，就可以判断这个 `MY_UNIQUEU_ID` 宏是否被定义，如果定义了，说明是在单文件中，就自己在源码中处理下重名符号。
+
+```c
+#ifdef MY_UNIQUEU_ID
+    // do some thing
+#endif
+```
+
+
+我们也可以指定输出位置：
+
+```bash
+$ xmake l cli.amalgamate -o /xxx
+/xxx/tbox.c generated!
+/xxx/tbox.h generated!
+```