write some os module api docs

1 files changed, 130 insertions, 16 deletions

diff --git a/docs/zh/manual.md b/docs/zh/manual.md
index 468ec86b6..951d0efe8 100755
--- a/docs/zh/manual.md
+++ b/docs/zh/manual.md
@@ -2882,21 +2882,60 @@ on_run(function (target)
 end)
 ```
 
-| 接口                                            | 描述                                         | 支持版本 |
-| ----------------------------------------------- | -------------------------------------------- | -------- |
-| [import](#import)                               | 导入扩展摸块                                 | >= 2.0.1 |
-| [inherit](#inherit)                             | 导入并继承基类模块                           | >= 2.0.1 |
-| [ifelse](#ifelse)                               | 类似三元条件判断                             | >= 2.0.1 |
-| [try-catch-finally](#try-catch-finally)         | 异常捕获                                     | >= 2.0.1 |
-| [pairs](#pairs)                                 | 用于遍历字典                                 | >= 2.0.1 |
-| [ipairs](#ipairs)                               | 用于遍历数组                                 | >= 2.0.1 |
-| [print](#print)                                 | 换行打印终端日志                             | >= 2.0.1 |
-| [printf](#printf)                               | 无换行打印终端日志                           | >= 2.0.1 |
-| [cprint](#cprint)                               | 换行彩色打印终端日志                         | >= 2.0.1 |
-| [cprintf](#cprintf)                             | 无换行彩色打印终端日志                       | >= 2.0.1 |
-| [format](#format)                               | 格式化字符串                                 | >= 2.0.1 |
-| [raise](#raise)                                 | 抛出异常中断程序                             | >= 2.0.1 |
+<p class="warning">
+为了保证外层的描述域尽可能简洁、安全，一般不建议在这个域使用接口和模块操作api，因此大部分模块接口只能再脚本域使用，来实现复杂功能。</br>
+当然少部分只读的内置接口还是可以在描述域使用的，具体见下表：
+</p>
+
+| 接口                                            | 描述                                         | 可使用域                   | 支持版本 |
+| ----------------------------------------------- | -------------------------------------------- | -------------------------- | -------- |
+| [import](#import)                               | 导入扩展摸块                                 | 脚本域                     | >= 2.0.1 |
+| [inherit](#inherit)                             | 导入并继承基类模块                           | 脚本域                     | >= 2.0.1 |
+| [ifelse](#ifelse)                               | 类似三元条件判断                             | 描述域、脚本域             | >= 2.0.1 |
+| [try-catch-finally](#try-catch-finally)         | 异常捕获                                     | 脚本域                     | >= 2.0.1 |
+| [pairs](#pairs)                                 | 用于遍历字典                                 | 描述域、脚本域             | >= 2.0.1 |
+| [ipairs](#ipairs)                               | 用于遍历数组                                 | 描述域、脚本域             | >= 2.0.1 |
+| [print](#print)                                 | 换行打印终端日志                             | 描述域、脚本域             | >= 2.0.1 |
+| [printf](#printf)                               | 无换行打印终端日志                           | 脚本域                     | >= 2.0.1 |
+| [cprint](#cprint)                               | 换行彩色打印终端日志                         | 脚本域                     | >= 2.0.1 |
+| [cprintf](#cprintf)                             | 无换行彩色打印终端日志                       | 脚本域                     | >= 2.0.1 |
+| [format](#format)                               | 格式化字符串                                 | 描述域、脚本域             | >= 2.0.1 |
+| [raise](#raise)                                 | 抛出异常中断程序                             | 脚本域                     | >= 2.0.1 |
+| [os](#os)                                       | 系统操作模块                                 | 部分只读操作描述域、脚本域 | >= 2.0.1 |
+| [io](#io)                                       | 文件操作模块                                 | 脚本域                     | >= 2.0.1 |
+| [path](#path)                                   | 路径操作模块                                 | 描述域、脚本域             | >= 2.0.1 |
+| [table](#table)                                 | 数组和字典操作模块                           | 描述域、脚本域             | >= 2.0.1 |
+| [string](#string)                               | 字符串操作模块                               | 描述域、脚本域             | >= 2.0.1 |
+| [process](#process)                             | 进程操作模块                                 | 脚本域                     | >= 2.0.1 |
+| [coroutine](#coroutine)                         | 协程操作模块                                 | 脚本域                     | >= 2.0.1 |
+
+在描述域使用接口调用的实例如下，一般仅用于条件控制：
+
+```lua
+-- 扫描当前xmake.lua目录下的所有子目录，以每个目录的名字定义一个task任务
+for _, taskname in ipairs(os.dirs("*"), path.basename) do
+    task(taskname)
+        on_run(function ()
+        end)
+end
+```
+
+上面所说的脚本域、描述域主要是指：
+
+```lua
+-- 描述域
+target("test")
+    
+    -- 描述域
+    set_kind("static")
+    add_files("src/*.c")
+
+    on_run(function (target)
+        -- 脚本域
+    end)
 
+-- 描述域
+```
 
 ##### import
 
@@ -3437,8 +3476,8 @@ if (errors) raise(errors)
 
 | 接口                                            | 描述                                         | 支持版本 |
 | ----------------------------------------------- | -------------------------------------------- | -------- |
-| [os.cp](#os-cp)                                 | 复制文件                                     | >= 2.0.1 |
-| [os.mv](#os-mv)                                 | 移动，重命名文件                             | >= 2.0.1 |
+| [os.cp](#os-cp)                                 | 复制文件或目录                               | >= 2.0.1 |
+| [os.mv](#os-mv)                                 | 移动重命名文件或目录                         | >= 2.0.1 |
 | [os.rm](#os-rm)                                 | 删除文件或目录树                             | >= 2.0.1 |
 | [os.cd](#os-cd)                                 | 进入指定目录                                 | >= 2.0.1 |
 | [os.rmdir](#os-rmdir)                           | 删除目录树                                   | >= 2.0.1 |
@@ -3462,9 +3501,84 @@ if (errors) raise(errors)
 | [os.host](#os-host)                             | 获取当前主机系统                             | >= 2.0.1 |
 
 ###### os.cp
+
+####### 复制文件或目录
+
+行为和shell中的`cp`命令类似，支持路径通配符匹配（使用的是lua模式匹配），支持多文件复制，以及内置变量支持。
+
+例如：
+
+```lua
+os.cp("$(scriptdir)/*.h", "$(projectdir)/src/test/**.h", "$(buildir)/inc")
+```
+
+上面的代码将：当前`xmake.lua`目录下的所有头文件、工程源码test目录下的头文件全部复制到`$(buildir)`输出目录中。
+
+其中`$(scriptdir)`, `$(projectdir)` 这些变量是xmake的内置变量，具体详情见：[内置变量](#内置变量)的相关文档。
+
+而`*.h`和`**.h`中的匹配模式，跟[add_files](#targetadd_files)中的类似，前者是单级目录匹配，后者是递归多级目录匹配。
+
+此接口同时支持目录的`递归复制`，例如：
+
+```lua
+-- 递归复制当前目录到临时目录
+os.cp("$(curdir)/test/", "$(tmpdir)/test")
+```
+
+<p class="tip">
+尽量使用`os.cp`接口，而不是`os.run("cp ..")`，这样更能保证平台一致性，实现跨平台构建描述。
+</p>
+
 ###### os.mv
+
+####### 移动重命名文件或目录
+
+跟[os.cp](#os-cp)的使用类似，同样支持多文件移动操作和模式匹配，例如：
+
+```lua
+-- 移动多个文件到临时目录
+os.mv("$(buildir)/test1", "$(buildir)/test2", "$(tmpdir)")
+
+-- 文件移动不支持批量操作，也就是文件重命名
+os.mv("$(buildir)/libtest.a", "$(buildir)/libdemo.a")
+```
+
 ###### os.rm
+
+####### 删除文件或目录树
+
+支持递归删除目录，批量删除操作，以及模式匹配和内置变量，例如：
+
+```lua
+os.rm("$(buildir)/inc/**.h", "$(buildir)/lib/")
+```
+
 ###### os.cd
+
+####### 进入指定目录
+
+这个操作用于目录切换，同样也支持内置变量，但是不支持模式匹配和多目录处理，例如：
+
+```lua
+-- 进入临时目录
+os.cd("$(tmpdir)")
+```
+
+如果要离开进入之前的目录，有多种方式：
+
+```lua
+-- 进入上级目录
+os.cd("..")
+
+-- 进入先前的目录，相当于：cd -
+os.cd("-")
+
+-- 进入目录前保存之前的目录，用于之后跨级直接切回
+local oldir = os.cd("./src")
+...
+os.cd(oldir)
+```
+
 ###### os.rmdir
 ###### os.mkdir
 ###### os.isdir