update repo and package docs

1 files changed, 276 insertions, 9 deletions

diff --git a/zh/README.md b/zh/README.md
index 3b74a808..9a6e35c6 100644
--- a/zh/README.md
+++ b/zh/README.md
@@ -1085,31 +1085,298 @@ $ xmake g --vcpkg=f:\vcpkg
 
 #### 远程依赖模式
 
-这个是xmake包管理的最终目标，目前还在开发内测中，不是很成熟，不过对于xmake的项目包，支持上基本没啥大问题了。
-
-如果用户想要体验下的话，可以参考下下面的`xmake.lua`例子:
+这个在2.2.2版本后已经初步支持，用法上更加的简单，只需要设置对应的依赖包就行了，例如：
 
 ```lua
-add_requires("tboox.tbox ~1.6.0")
-add_requires("zlib >=1.2.11")
+add_requires("tbox 1.6.*", "libpng ~1.16", "zlib")
 
 target("test")
     set_kind("binary")
     add_files("src/*.c") 
-    add_packages("tboox.tbox", "zlib")
+    add_packages("tbox", "libpng", "zlib")
 ```
 
+上面的`add_requires`用于描述当前项目需要的依赖包，而`add_packages`用于应用依赖包到test目标，只有设置这个才会自动追加links, linkdirs, includedirs等设置。
+
 然后直接执行编译即可：
 
 ```console
 $ xmake 
 ```
 
-xmake会去远程拉取相关源码包，然后自动编译安装，最后编译项目，进行依赖包的链接。
+xmake会去远程拉取相关源码包，然后自动编译安装，最后编译项目，进行依赖包的链接，具体效果见下图：
+
+<img src="/assets/img/index/package_manage.png" width="80%" />
+
+关于包依赖管理的更多相关信息和进展见相关issues：[Remote package management](https://github.com/tboox/xmake/issues/69) 
+
+##### 目前支持的特性
+
+* 语义版本支持，例如：">= 1.1.0 < 1.2", "~1.6", "1.2.x", "1.*"
+* 系统库自动检测支持
+* 源码下载编译和自动链接支持
+* 二进制包下载直接安装支持
+* 级联依赖包支持
+* 提供官方包仓库、自建私有仓库、项目内置仓库等多仓库管理支持
+* 可以自定义包描述规则，添加自己的包
+* 跨平台包编译集成支持（不同平台、不同架构的包可同时安装，快速切换使用）
+* 内置release/debug依赖包支持，可指定使用debug包实现源码调试
+
+##### 依赖包处理机制
+
+这里我们简单介绍下整个依赖包的处理机制：
+
+1. 优先检测当前系统目录、第三方包管理下有没有存在指定的包，如果有匹配的包，那么就不需要下载安装了 （当然也可以设置不使用系统包）
+2. 检索匹配对应版本的包，然后下载、编译、安装（注：安装在特定xmake目录，不会干扰系统库环境）
+3. 编译项目，最后自动链接启用的依赖包
+
+##### 语义版本设置
+
+xmake的依赖包管理是完全支持语义版本选择的，例如："~1.6.1"，对于语义版本的具体描述见：[http://semver.org/](http://semver.org/)
+
+一些语义版本写法：
+
+```lua
+add_requires("tbox 1.6.*", "pcre 1.3.x", "libpng ^1.18")
+add_requires("libpng ~1.16", "zlib 1.1.2 || >=1.2.11 <1.3.0")
+```
+
+目前xmake使用的语义版本解析器是[uael](https://github.com/uael)贡献的[sv](https://github.com/uael/sv)库，里面也有对版本描述写法的详细说明，可以参考下：[版本描述说明](https://github.com/uael/sv#versions)
+
+当然，如果我们对当前的依赖包的版本没有特殊要求，那么可以直接这么写：
+
+```lua
+add_requires("tbox", "libpng", "zlib")
+```
+
+这会使用已知的最新版本包，或者是master分支的源码编译的包，如果当前包有git repo地址，我们也能指定特定分支版本：
+
+```lua
+add_requires("tbox master")
+add_requires("tbox dev")
+```
+
+##### 额外的包信息设置
+
+###### 可选包设置
+
+如果指定的依赖包当前平台不支持，或者编译安装失败了，那么xmake会编译报错，这对于有些必须要依赖某些包才能工作的项目，这是合理的。
+但是如果有些包是可选的依赖，即使没有也可以正常编译使用的话，可以设置为可选包：
+
+```lua
+add_requires("tbox", {optional = true})
+```
+
+###### 禁用系统库
+
+默认的设置，xmake会去优先检测系统库是否存在（如果没设置版本要求），如果用户完全不想使用系统库以及第三方包管理提供的库，那么可以设置：
+
+```lua
+add_requires("tbox", {system = false})
+```
+
+###### 使用调试版本的包
+
+如果我们想同时源码调试依赖包，那么可以设置为使用debug版本的包（当然前提是这个包支持debug编译）：
+
+```lua
+add_requires("tbox", {debug = true})
+```
+
+如果当前包还不支持debug编译，可在仓库中提交修改编译规则，对debug进行支持，例如：
+
+```lua
+package("openssl")
+    on_install("linux", "macosx", function (package)
+        os.vrun("./config %s --prefix=\"%s\"", package:debug() and "--debug" or "", package:installdir())
+        os.vrun("make -j4")
+        os.vrun("make install")
+    end)
+```
+
+###### 传递额外的编译信息到包
+
+某些包在编译时候有各种编译选项，我们也可以传递进来，当然包本身得支持：
+
+```lua
+add_requires("tbox", {config = {small=true}})
+```
+
+传递`--small=true`给tbox包，使得编译安装的tbox包是启用此选项的。
+
+##### 使用自建私有包仓库
+
+如果需要的包不在官方仓库[xmake-repo](https://github.com/tboox/xmake-repo)中，我们可以提交贡献代码到仓库进行支持。
+但如果有些包仅用于个人或者私有项目，我们可以建立一个私有仓库repo，仓库组织结构可参考：[xmake-repo](https://github.com/tboox/xmake-repo)
+
+比如，现在我们有一个一个私有仓库repo：`git@github.com:myrepo/xmake-repo.git`
+
+我们可以通过下面的命令进行仓库添加：
+
+```console
+$ xmake repo --add myrepo git@github.com:myrepo/xmake-repo.git
+```
+
+或者我们直接写在xmake.lua中：
+
+```lua
+add_repositories("my-repo git@github.com:myrepo/xmake-repo.git")
+```
+
+如果我们只是想添加一两个私有包，这个时候特定去建立一个git repo太小题大做了，我们可以直接把包仓库放置项目里面，例如：
+
+```
+projectdir
+  - myrepo
+    - packages
+      - t/tbox/xmake.lua
+      - z/zlib/xmake.lua
+  - src
+    - main.c
+  - xmake.lua
+```
+
+上面myrepo目录就是自己的私有包仓库，内置在自己的项目里面，然后在xmake.lua里面添加一下这个仓库位置：
+
+```lua
+add_repositories("my-repo myrepo")
+```
+
+这个可以参考[benchbox](https://github.com/tboox/benchbox)项目，里面就内置了一个私有仓库。
+
+我们甚至可以连仓库也不用建，直接定义包描述到项目xmake.lua中，这对依赖一两个包的情况还是很有用的，例如：
+
+```lua
+package("libjpeg")
+
+    set_urls("http://www.ijg.org/files/jpegsrc.$(version).tar.gz")
+
+    add_versions("v9c", "650250979303a649e21f87b5ccd02672af1ea6954b911342ea491f351ceb7122")
+
+    on_install("windows", function (package)
+        os.mv("jconfig.vc", "jconfig.h")
+        os.vrun("nmake -f makefile.vc")
+        os.cp("*.h", package:installdir("include"))
+        os.cp("libjpeg.lib", package:installdir("lib"))
+    end)
+
+    on_install("macosx", "linux", function (package)
+        import("package.tools.autoconf").install(package)
+    end)
+
+package_end()
+
+add_requires("libjpeg")
+
+target("test")
+    set_kind("binary")
+    add_files("src/*.c") 
+    add_packages("libjpeg")
+```
+
+##### 包管理命令使用
+
+包管理命令`$ xmake require` 可用于手动显示的下载编译安装、卸载、检索、查看包信息。
+
+###### 安装指定包
+
+```console
+$ xmake require tbox
+```
+
+安装指定版本包：
+
+```console
+$ xmake require tbox "~1.6"
+```
+
+强制重新下载安装，并且显示详细安装信息：
+
+```console
+$ xmake require -f -v tbox "1.5.x"
+```
+
+传递额外的设置信息：
+
+```console
+$ xmake require --extra="debug=true,config={small=true}" tbox
+```
+
+安装debug包，并且传递`small=true`的编译配置信息到包中去。
+
+###### 卸载指定包
+
+```console
+$ xmake require --uninstall tbox
+```
+
+这会完全卸载删除包文件。
+
+###### 移除指定包
+
+仅仅unlink指定包，不被当前项目检测到，但是包在本地还是存在的，如果重新安装的话，会很快完成。
+
+```console
+$ xmake require --unlink tbox
+```
+
+###### 查看包详细信息
+
+```console
+$ xmake require --info tbox
+```
+
+###### 在当前仓库中搜索包
+
+```console
+$ xmake require --search tbox
+```
+
+这个是支持模糊搜素以及lua模式匹配搜索的：
+
+```console
+$ xmake require --search pcr
+```
+
+会同时搜索到pcre, pcre2等包。
+
+###### 列举当前已安装的包
+
+```console
+$ xmake require --list
+```
+
+##### 仓库管理命令使用
+
+上文已经简单讲过，添加私有仓库可以用（支持本地路径添加）：
+
+```console
+$ xmake repo --add myrepo git@github.com:myrepo/xmake-repo.git
+```
+
+我们也可以移除已安装的某个仓库：
+
+```console
+$ xmake repo --remove myrepo
+```
+
+或者查看所有已添加的仓库：
+
+```console
+$ xmake repo --list
+```
+
+如果远程仓库有更新，可以手动执行仓库更新，来获取更多、最新的包：
+
+```console
+$ xmake repo -u
+```
+
+##### 提交包到官方仓库
 
-我们可以看个演示视频，直观感受下：[远程依赖包使用视频](https://asciinema.org/a/140336)
+如果你需要的包，当前的官方仓库不支持，那么可以在本地调通后，贡献提交到官方仓库：[xmake-repo](https://github.com/tboox/xmake-repo)
 
-由于这个特性，还是开发中，暂不完全开放，因此文档就不详细描述了，有兴趣的同学可以关注下相关issues：[Remote package management](https://github.com/tboox/xmake/issues/69) 来持续跟进开发进展。
+详细的贡献说明，见：[CONTRIBUTING.md](https://github.com/tboox/xmake-repo/blob/master/CONTRIBUTING.md)
 
 ## 问答