From a50ea9f95295127c98be170b36f6710abf0cc7d3 Mon Sep 17 00:00:00 2001 From: ruki Date: Fri, 30 Nov 2018 22:39:11 +0800 Subject: update docs for v2.2.3 --- README.md | 6 +++ manual.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++------ zh/README.md | 6 +++ zh/manual.md | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++++------ 4 files changed, 227 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 32282d93..da933456 100644 --- a/README.md +++ b/README.md @@ -1179,6 +1179,12 @@ We can add the repository with the following command: $ xmake repo --add myrepo git@github.com:myrepo/xmake-repo.git ``` +Starting with v2.2.3, support for adding repos for specified branches, for example: + +```console +$ xmake repo --add myrepo git@github.com:myrepo/xmake-repo.git dev +``` + Or we write directly in xmake.lua: ```lua diff --git a/manual.md b/manual.md index d7511505..4867bebf 100644 --- a/manual.md +++ b/manual.md @@ -28,17 +28,18 @@ It's according to the following rules: Conditions are generally used to handle some special compilation platforms. -| Interfaces | Description | Support version | -| ------------------------- | ---------------------------------------- | --------------------------- | -| [is_os](#is_os) | Is the current compilation target system? | >= 2.0.1 | -| [is_arch](#is_arch) | Is the current compilation architecture? | >= 2.0.1 | -| [is_plat](#is_plat) | Is the current compilation platform? | >= 2.0.1 | -| [is_host](#is_host) | Is the current compilation host system? | >= 2.1.4 | -| [is_mode](#is_mode) | Is the current compilation mode? | >= 2.0.1 | -| [is_kind](#is_kind) | Is the current target kind? | >= 2.0.1 | -| [is_option](#is_option) | Is the given options enabled? | >= 2.0.1 < 2.2.2 deprecated | -| [is_config](#is_config) | Is the given config values? | >= 2.2.2 | -| [has_config](#has_config) | Is the given configs enabled? | >= 2.2.2 | +| Interfaces | Description | Support version | +| ------------------------- | ---------------------------------------- | --------------------------- | +| [is_os](#is_os) | Is the current compilation target system? | >= 2.0.1 | +| [is_arch](#is_arch) | Is the current compilation architecture? | >= 2.0.1 | +| [is_plat](#is_plat) | Is the current compilation platform? | >= 2.0.1 | +| [is_host](#is_host) | Is the current compilation host system? | >= 2.1.4 | +| [is_mode](#is_mode) | Is the current compilation mode? | >= 2.0.1 | +| [is_kind](#is_kind) | Is the current target kind? | >= 2.0.1 | +| [is_option](#is_option) | Is the given options enabled? | >= 2.0.1 < 2.2.2 deprecated | +| [is_config](#is_config) | Is the given config values? | >= 2.2.2 | +| [has_config](#has_config) | Is the given configs enabled? | >= 2.2.2 | +| [has_package](#has_package) | Is the given dependent package enabled? | >= 2.2.3 | ##### is_os @@ -314,6 +315,34 @@ This interface can determine not only the built-in global and local configs, but also the custom options defined through the [option](#option).

+##### has_package + +###### Is the given dependent package enabled? + +This interface is introduced from version 2.2.3 to detect whether a dependent package exists or is enabled. + +It is usually used to [ add_requires](#add_requires). + +```lua +add_requires("tbox", {optional = true}) + +target("test") + set_kind("binary") + add_files("src/*.c") + add_packages("tbox") + + if has_package("tbox") then + add_defines("HAVE_TBOX") + end +``` + +If the remote dependencies are added via the optional add-on package added by `add_requires`, or the current platform does not support the actual installation, then `has_package` will return false. +Indicates that it does not exist, and then does some special processing for other flags definitions and even source file compilation controls. + +

+The difference between this interface and [has_config](#has_config) is that [has_config](#has_config) is used for [option](#option) and it is used for [add_requires](#add_requires). +

+ #### Global Interfaces The global interface affects the whole project description scope and all sub-project files. @@ -624,6 +653,46 @@ add_requires("tbox", {config = {small=true}}) ``` Pass `--small=true` to the tbox package so that compiling the installed tbox package is enabled. +After v2.2.3, you can control whether you need to add a dependency package in your own definition configuration option parameter by [option](#option) and [has_config](#has_config): + +```lua +option("luajit") +    set_default(false) +    set_showmenu(true) +    set_category("option") +    set_description("Enable the luajit runtime engine.") +option_end() + +if has_config("luajit") then +    add_requires("luajit") +else +    add_requires("lua") +end +``` + +We can switch dependencies by `$xmake f --luajit=y`. + +And we also added the group parameter to group the dependencies, all the dependencies under the same group, only one can be enabled, the order of the order depends on the order added by `add_requires`: + +```lua +add_requires("openssl", {group = "ssl", optional = true}) +add_requires("mbedtls", {group = "ssl", optional = true}) + +target("test") +    add_packages("openssl", "mbedtls") +``` + +For example, above, so relying on two ssl packages at the same time, in fact only will enable the ssl package that is valid for the actual installation, and will not link two dependent packages at the same time. + +We also added the `on_load` parameter, which will be called after the dependency package is loaded successfully, providing the user with a chance to set some other flags, for example: + +```lua +add_requires("tbox", {on_load = function (package) +    package:add("defines_h", "PACKAGE_HAVE_TBOX") +end}) +``` + +After the dependent package tbox is loaded, add the `PACKAGE_HAVE_TBOX` macro to `config.h`. ##### add_repositories @@ -2550,6 +2619,33 @@ target("test") 而在v2.2.2版本之后，此接口也同时支持远程依赖包管理中[add_requires](#add_requires)定义的包。 +```lua +add_requires("zlib", "polarssl") +target("test") + add_packages("zlib", "polarssl") +``` + +v2.2.3之后，还支持覆写内置的links，控制实际链接的库： + + +```lua +-- 默认会有 ncurses, panel, form等links +add_requires("ncurses") + +target("test") + + -- 显示指定，只使用ncurses一个链接库 + add_packages("ncurses", {links = "ncurses"}) +``` + +或者干脆禁用links，只使用头文件： + +```lua +add_requires("lua") +target("test") + add_packages("lua", {links = {}}) +``` + ##### target:add_languages ###### Add language standards diff --git a/zh/README.md b/zh/README.md index e0fb7a3d..a7b4a882 100644 --- a/zh/README.md +++ b/zh/README.md @@ -1405,6 +1405,12 @@ $ xmake require --list $ 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 diff --git a/zh/manual.md b/zh/manual.md index f1477f41..90d4365b 100644 --- a/zh/manual.md +++ b/zh/manual.md @@ -28,17 +28,18 @@ search: zh 条件判断的api，一般用于必须要处理特定平台的编译逻辑的场合。。通常跟lua的if语句配合使用。 -| 接口 | 描述 | 支持版本 | -| ------------------------- | ----------------------------- | ----------------------- | -| [is_os](#is_os) | 判断当前构建目标的操作系统 | >= 2.0.1 | -| [is_arch](#is_arch) | 判断当前编译架构 | >= 2.0.1 | -| [is_plat](#is_plat) | 判断当前编译平台 | >= 2.0.1 | -| [is_host](#is_host) | 判断当前主机环境操作系统 | >= 2.1.4 | -| [is_mode](#is_mode) | 判断当前编译模式 | >= 2.0.1 | -| [is_kind](#is_kind) | 判断当前编译类型 | >= 2.0.1 | -| [is_option](#is_option) | 判断选项是否启用 | >= 2.0.1 < 2.2.2 已废弃 | -| [is_config](#is_config) | 判断指定配置是否为给定的值 | >= 2.2.2 | -| [has_config](#has_config) | 判断配置是否启用或者存在 | >= 2.2.2 | +| 接口 | 描述 | 支持版本 | +| ------------------------- | ----------------------------- | ----------------------- | +| [is_os](#is_os) | 判断当前构建目标的操作系统 | >= 2.0.1 | +| [is_arch](#is_arch) | 判断当前编译架构 | >= 2.0.1 | +| [is_plat](#is_plat) | 判断当前编译平台 | >= 2.0.1 | +| [is_host](#is_host) | 判断当前主机环境操作系统 | >= 2.1.4 | +| [is_mode](#is_mode) | 判断当前编译模式 | >= 2.0.1 | +| [is_kind](#is_kind) | 判断当前编译类型 | >= 2.0.1 | +| [is_option](#is_option) | 判断选项是否启用 | >= 2.0.1 < 2.2.2 已废弃 | +| [is_config](#is_config) | 判断指定配置是否为给定的值 | >= 2.2.2 | +| [has_config](#has_config) | 判断配置是否启用或者存在 | >= 2.2.2 | +| [has_package](#has_package) | 判断依赖包是否被启用或者存在 | >= 2.2.3 | ##### is_os @@ -335,6 +336,34 @@ $ xmake f --test1=false

+##### has_package + +###### 判断依赖包是否启用或者存在 + +此接口从2.2.3版本开始引入，用于检测远程依赖包是否存在或启用，可用于描述域。 + +一般配合[add_requires](#add_requires)一起使用，例如： + +```lua +add_requires("tbox", {optional = true}) + +target("test") + set_kind("binary") + add_files("src/*.c") + add_packages("tbox") + + if has_package("tbox") then + add_defines("HAVE_TBOX") + end +``` + +如果通过`add_requires`添加的可选依赖包，远程下载安装失败，或者当前平台不支持导致实际上没有被正常安装上，那么`has_package`就会返回false， +表示不存在，然后对其他flags定义甚至源文件编译控制做一些特殊处理。 + +

+此接口跟[has_config](#has_config)的区别在于，[has_config](#has_config)用于[option](#option)，而它用于[add_requires](#add_requires)。 +

+ #### 全局接口 全局接口影响整个工程描述，被调用后，后面被包含进来的所有子`xmake.lua`都会受影响。 @@ -649,6 +678,47 @@ add_requires("tbox", {config = {small=true}}) 传递`--small=true`给tbox包，使得编译安装的tbox包是启用此选项的。 +v2.2.3之后，可以通过[option](#option)和[has_config](#has_config)配合，在自己定义配置选项参数中控制是否需要添加某个依赖包： + +```lua +option("luajit") + set_default(false) + set_showmenu(true) + set_category("option") + set_description("Enable the luajit runtime engine.") +option_end() + +if has_config("luajit") then + add_requires("luajit") +else + add_requires("lua") +end +``` + +我们可以通过`$xmake f --luajit=y`去切换依赖包。 + +并且我们也新增了group参数，来分组依赖包，同一个组下的所有依赖包，只能有一个生效启用，启用顺序依赖`add_requires`添加的顺序: + +```lua +add_requires("openssl", {group = "ssl", optional = true}) +add_requires("mbedtls", {group = "ssl", optional = true}) + +target("test") + add_packages("openssl", "mbedtls") +``` + +例如上面，所以同时依赖两个ssl包，实际上只会启用生效实际安装成功的那一个ssl包，并不会同时链接两个依赖包。 + +我们还新增了`on_load`参数，在依赖包加载成功后，会被调用，提供用户一个机会去设置一些其他的flags，例如： + +```lua +add_requires("tbox", {on_load = function (package) + package:add("defines_h", "PACKAGE_HAVE_TBOX") +end}) +``` + +当依赖包tbox生效加载后，添加`PACKAGE_HAVE_TBOX`宏到`config.h`中去。 + ##### add_repositories ###### 添加依赖包仓库 @@ -2570,6 +2640,33 @@ target("test") 而在v2.2.2版本之后，此接口也同时支持远程依赖包管理中[add_requires](#add_requires)定义的包。 +```lua +add_requires("zlib", "polarssl") +target("test") + add_packages("zlib", "polarssl") +``` + +v2.2.3之后，还支持覆写内置的links，控制实际链接的库： + + +```lua +-- 默认会有 ncurses, panel, form等links +add_requires("ncurses") + +target("test") + + -- 显示指定，只使用ncurses一个链接库 + add_packages("ncurses", {links = "ncurses"}) +``` + +或者干脆禁用links，只使用头文件： + +```lua +add_requires("lua") +target("test") + add_packages("lua", {links = {}}) +``` + ##### target:add_languages ###### 添加语言标准 -- cgit v1.2.3