diff options
Diffstat (limited to 'zh-cn/package/remote_package.md')
| -rw-r--r-- | zh-cn/package/remote_package.md | 395 |
1 files changed, 395 insertions, 0 deletions
diff --git a/zh-cn/package/remote_package.md b/zh-cn/package/remote_package.md new file mode 100644 index 00000000..1d736c25 --- /dev/null +++ b/zh-cn/package/remote_package.md @@ -0,0 +1,395 @@ + +这个在2.2.2版本后已经初步支持，用法上更加的简单，只需要设置对应的依赖包就行了，例如： + +```lua +add_requires("tbox 1.6.*", "libpng ~1.16", "zlib") + +target("test") + set_kind("binary") + add_files("src/*.c") + add_packages("tbox", "libpng", "zlib") +``` + +上面的`add_requires`用于描述当前项目需要的依赖包，而`add_packages`用于应用依赖包到test目标，只有设置这个才会自动追加links, linkdirs, includedirs等设置。 + +然后直接执行编译即可： + +```console +$ xmake +``` + +xmake会去远程拉取相关源码包，然后自动编译安装，最后编译项目，进行依赖包的链接，具体效果见下图： + +<img src="/assets/img/index/package_manage.png" width="80%" /> + +关于包依赖管理的更多相关信息和进展见相关issues：[Remote package management](https://github.com/xmake-io/xmake/issues/69) + +## 目前支持的特性 + +* 语义版本支持，例如：">= 1.1.0 < 1.2", "~1.6", "1.2.x", "1.*" +* 提供官方包仓库、自建私有仓库、项目内置仓库等多仓库管理支持 +* 跨平台包编译集成支持（不同平台、不同架构的包可同时安装，快速切换使用） +* debug依赖包支持，实现源码调试 + +## 依赖包处理机制 + +这里我们简单介绍下整个依赖包的处理机制： + +<img src="/assets/img/index/package_arch.png" width="80%" /> + +1. 优先检测当前系统目录、第三方包管理下有没有存在指定的包，如果有匹配的包，那么就不需要下载安装了 （当然也可以设置不使用系统包） +2. 检索匹配对应版本的包，然后下载、编译、安装（注：安装在特定xmake目录，不会干扰系统库环境） +3. 编译项目，最后自动链接启用的依赖包 + +## 快速上手 + +新建一个依赖tbox库的空工程： + +```console +$ xmake create -t console_tbox test +$ cd test +``` + +执行编译即可，如果当前没有安装tbox库，则会自动下载安装后使用： + +```console +$ xmake +``` + +切换到iphoneos平台进行编译，将会重新安装iphoneos版本的tbox库进行链接使用： + +```console +$ xmake f -p iphoneos +$ xmake +``` + +切换到android平台arm64-v8a架构编译： + +```console +$ xmake f -p android [--ndk=~/android-ndk-r16b] +$ xmake +``` + +## 语义版本设置 + +xmake的依赖包管理是完全支持语义版本选择的，例如："~1.6.1"，对于语义版本的具体描述见：[https://semver.org/](https://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", {configs = {small=true}}) +``` + +传递`--small=true`给tbox包，使得编译安装的tbox包是启用此选项的。 + +## 第三方依赖包安装 + +2.2.5版本之后，xmake支持对对第三方包管理器里面的依赖库安装支持，例如：conan，brew, vcpkg等 + +### 添加homebrew的依赖包 + +```lua +add_requires("brew::zlib", {alias = "zlib"}}) +add_requires("brew::pcre2/libpcre2-8", {alias = "pcre2"}}) + +target("test") + set_kind("binary") + add_files("src/*.c") + add_packages("pcre2", "zlib") +``` + +### 添加vcpkg的依赖包 + +```lua +add_requires("vcpkg::zlib", "vcpkg::pcre2") + +target("test") + set_kind("binary") + add_files("src/*.c") + add_packages("vcpkg::zlib", "vcpkg::pcre2") +``` + +### 添加conan的依赖包 + +```lua +add_requires("CONAN::zlib/1.2.11@conan/stable", {alias = "zlib", debug = true}) +add_requires("CONAN::OpenSSL/1.0.2n@conan/stable", {alias = "openssl", + configs = {options = "OpenSSL:shared=True"}}) + +target("test") + set_kind("binary") + add_files("src/*.c") + add_packages("openssl", "zlib") +``` + +执行xmake进行编译后： + +```console +ruki:test_package ruki$ xmake +checking for the architecture ... x86_64 +checking for the Xcode directory ... /Applications/Xcode.app +checking for the SDK version of Xcode ... 10.14 +note: try installing these packages (pass -y to skip confirm)? + -> CONAN::zlib/1.2.11@conan/stable (debug) + -> CONAN::OpenSSL/1.0.2n@conan/stable +please input: y (y/n) + + => installing CONAN::zlib/1.2.11@conan/stable .. ok + => installing CONAN::OpenSSL/1.0.2n@conan/stable .. ok + +[ 0%]: ccache compiling.release src/main.c +[100%]: linking.release test +``` + +### 添加clib的依赖包 + +clib是一款基于源码的依赖包管理器，拉取的依赖包是直接下载对应的库源码，集成到项目中编译，而不是二进制库依赖。 + +其在xmake中集成也很方便，唯一需要注意的是，还需要自己添加上对应库的源码到xmake.lua，例如： + +```lua +add_requires("clib::clibs/bytes@0.0.4", {alias = "bytes"}) + +target("test") + set_kind("binary") + add_files("clib/bytes/*.c") + add_files("src/*.c") + add_packages("bytes") +``` + +## 使用自建私有包仓库 + +如果需要的包不在官方仓库[xmake-repo](https://github.com/xmake-io/xmake-repo)中，我们可以提交贡献代码到仓库进行支持。 +但如果有些包仅用于个人或者私有项目，我们可以建立一个私有仓库repo，仓库组织结构可参考：[xmake-repo](https://github.com/xmake-io/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 +``` + +这会完全卸载删除包文件。 + +### 查看包详细信息 + +```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 +``` + +v2.2.3开始，支持添加指定分支的repo，例如： + +```console +$ xmake repo --add myrepo git@github.com:myrepo/xmake-repo.git dev +``` + +我们也可以移除已安装的某个仓库： + +```console +$ xmake repo --remove myrepo +``` + +或者查看所有已添加的仓库： + +```console +$ xmake repo --list +``` + +如果远程仓库有更新，可以手动执行仓库更新，来获取更多、最新的包： + +```console +$ xmake repo -u +``` + +## 提交包到官方仓库 + +目前这个特性刚完成不久，目前官方仓库的包还不是很多，有些包也许还不支持部分平台，不过这并不是太大问题，后期迭代几个版本后，我会不断扩充完善包仓库。 + +如果你需要的包，当前的官方仓库还没有收录，可以提交issues或者自己可以在本地调通后，贡献提交到官方仓库：[xmake-repo](https://github.com/xmake-io/xmake-repo) + +详细的贡献说明，见：[CONTRIBUTING.md](https://github.com/xmake-io/xmake-repo/blob/master/CONTRIBUTING.md) + |