diff options
| -rw-r--r-- | manual/global_interfaces.md | 71 | ||||
| -rw-r--r-- | manual/project_target.md | 142 | ||||
| -rw-r--r-- | zh-cn/manual/global_interfaces.md | 69 | ||||
| -rw-r--r-- | zh-cn/manual/project_target.md | 142 |
4 files changed, 118 insertions, 306 deletions
diff --git a/manual/global_interfaces.md b/manual/global_interfaces.md index 94f7c427..f47762f2 100644 --- a/manual/global_interfaces.md +++ b/manual/global_interfaces.md @@ -28,6 +28,62 @@ In addition, in 2.2.5 and later, this interface provides some built-in helper fu For a more complete description of this, see: [https://github.com/xmake-io/xmake/issues/342](https://github.com/xmake-io/xmake/issues/342 ) +Examples: + +Check links, ctype, includes and features and write macro definitions to the config.h file. + +```lua +includes("check_links.lua") +includes("check_ctypes.lua") +includes("check_cfuncs.lua") +includes("check_features.lua") +includes("check_csnippets.lua") +includes("check_cincludes.lua") + +target("test") + set_kind("binary") + add_files("*.c") + add_configfiles("config.h.in") + + configvar_check_ctypes("HAS_WCHAR", "wchar_t") + configvar_check_cincludes("HAS_STRING_H", "string.h") + configvar_check_cincludes("HAS_STRING_AND_STDIO_H", {"string.h", "stdio.h"}) + configvar_check_ctypes("HAS_WCHAR_AND_FLOAT", {"wchar_t", "float"}) + configvar_check_links("HAS_PTHREAD", {"pthread", "m", "dl"}) + configvar_check_csnippets("HAS_STATIC_ASSERT", "_Static_assert(1, \"\");") + configvar_check_cfuncs("HAS_SETJMP", "setjmp", {includes = {"signal.h", "setjmp.h"}}) + configvar_check_features("HAS_CONSTEXPR", "cxx_constexpr") + configvar_check_features("HAS_CONSEXPR_AND_STATIC_ASSERT", {"cxx_constexpr", "c_static_assert"}, {languages = "c++11"}) +``` + +config.h.in + +```c +${define HAS_STRING_H} +${define HAS_STRING_AND_STDIO_H} +${define HAS_WCHAR} +${define HAS_WCHAR_AND_FLOAT} +${define HAS_PTHREAD} +${define HAS_STATIC_ASSERT} +${define HAS_SETJMP} +${define HAS_CONSTEXPR} +${define HAS_CONSEXPR_AND_STATIC_ASSERT} +``` + +config.h + +```c +/* #undef HAS_STRING_H */ +#define HAS_STRING_AND_STDIO_H 1 +/* #undef HAS_WCHAR */ +/* #undef HAS_WCHAR_AND_FLOAT */ +#define HAS_PTHREAD 1 +#define HAS_STATIC_ASSERT 1 +#define HAS_SETJMP 1 +/* #undef HAS_CONSTEXPR */ +#define HAS_CONSEXPR_AND_STATIC_ASSERT 1 +``` + ### set_modes #### Set project compilation modes @@ -78,25 +134,14 @@ Set the whole project version, we can set it at the beginning of `xmake.lua`. set_version("1.5.1") ``` -It will add project version info to this file automatically if we call [set_config_header](#targetset_config_header) to set `config.h`.` - -For example: - -```c -// version -#define TB_CONFIG_VERSION "1.5.1" -#define TB_CONFIG_VERSION_MAJOR 1 -#define TB_CONFIG_VERSION_MINOR 5 -#define TB_CONFIG_VERSION_ALTER 1 -#define TB_CONFIG_VERSION_BUILD 201510220917 -``` - We can set build version in v2.1.7 version: ```lua set_version("1.5.1", {build = "%Y%m%d%H%M"}) ``` +We can also add version to the config header files, @see [add_configfiles](/manual/project_target?id=add-template-configuration-files) + ### set_xmakever #### Set minimal xmake version diff --git a/manual/project_target.md b/manual/project_target.md index 04840411..59d4863a 100644 --- a/manual/project_target.md +++ b/manual/project_target.md @@ -105,10 +105,6 @@ target("test2") | [add_ldflags](#targetadd_ldflags) | Add static library link flags | >= 1.0.1 | | [add_arflags](#targetadd_arflags) | Add archive library flags | >= 1.0.1 | | [add_shflags](#targetadd_shflags) | Add dynamic library link flags | >= 1.0.1 | -| [add_cfunc](#targetadd_cfunc) | Add single c function for checking | >= 2.0.1 | -| [add_cxxfunc](#targetadd_cxxfunc) | Add single c++ function for checking | >= 2.0.1 | -| [add_cfuncs](#targetadd_cfuncs) | Add c functions for checking | >= 2.0.1 | -| [add_cxxfuncs](#targetadd_cxxfuncs) | Add c++ functions for checking | >= 2.0.1 | | [add_packages](#targetadd_packages) | Add package dependencies | >= 2.0.1 | | [add_options](#targetadd_options) | Add options dependencies | >= 2.0.1 | | [add_languages](#targetadd_languages) | Add language standards | >= 1.0.1 | @@ -374,7 +370,7 @@ if this time, the build configuration is: `xmake f -m debug -a armv7`, then the If you want to further customize the directory name of the target file, refer to: [set_targetdir](#targetset_targetdir). -Or implement more advanced logic by writing custom scripts, see: [after_build](#targetafter_build) and [os.mv](#os-mv). +Or implement more advanced logic by writing custom scripts, see: [after_build](#targetafter_build) and [os.mv](/manual/builtin_modules?id=osmv). ### target:set_filename @@ -1817,142 +1813,6 @@ Affect the generation of dynamic libraries add_shflags("xxx") ``` -### target:add_cfunc - -#### Add single c function for checking - -Similar to [add_cfuncs](#targetadd_cfuncs), only a single function interface is set and only valid for the `target` domain. This interface does not exist in `option`. - -The purpose of this interface is primarily to create a more highly customized macro switch in `config.h`, for example: - -```lua -target("demo") - - -- Set and enable config.h - set_config_header("$(buildir)/config.h", {prefix = "TEST"}) - - -- Set module name prefix only by parameter one - add_cfunc("libc", nil, nil, {"sys/select.h"}, "select") - - -- Set the simultaneous detection of the link library via parameter three: libpthread.a - add_cfunc("pthread", nil, "pthread", "pthread.h", "pthread_create") - - -- Set interface alias by parameter two - add_cfunc(nil, "PTHREAD", nil, "pthread.h", "pthread_create") -``` - -The resulting results are as follows: - -```c -#ifndef TEST_H -#define TEST_H - -// Macro naming convention: $(prefix) prefix _ module name (if non-nil) _ HAVE _ interface name or alias (uppercase) -#define TEST_LIBC_HAVE_SELECT 1 -#define TEST_PTHREAD_HAVE_PTHREAD_CREATE 1 -#define TEST_HAVE_PTHREAD 1 - -#endif -``` - -For more flexible function detection, you can do this in a custom script with [lib.detect.has_cfuncs](#detect-has_cfuncs). - -### target:add_cxxfunc - -#### Add single c++ function for checking - -Similar to [add_cfunc](#targetadd_cfunc), only the function interface detected is a c++ function. - -### target:add_cfuncs - -#### Add c functions for checking - -<p class="warn"> -This interface is the interface shared by `target` and `option`, but the interface behavior is slightly different. -</p> - -| Interface Field | Description | Examples | -| ------ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| target | header files, link libraries, and function interfaces are also specified | `add_cfuncs("libc", nil, {"signal.h", "setjmp.h"}, "signal", "setjmp", "sigsetjmp{sigjmp_buf buf ; sigsetjmp(buf, 0);}", "kill")` | -Option | only specifies the function interface, the header file depends on [add_cincludes](#targetadd_cincludes) and other independent interfaces | `add_cincludes("setjmp.h")` `add_cfuncs("sigsetjmp")` | - -For `option`, this interface is very simple to use, similar to [add_cincludes](#targetadd_cincludes), for example: - -```lua -option("setjmp") - set_default(false) - add_cincludes("setjmp.h") - add_cfuncs("sigsetjmp", "setjmp") - add_defines("HAVE_SETJMP") - -target("test") - add_options("setjmp") -``` - -This option detects if there are some interfaces of `setjmp`. If the test passes, then the `test` target program will add the macro definition of `HAVE_SETJMP`. - -<p class="warn"> -Note that using this interface to detect dependencies in `option` requires adding a separate [add_cincludes](#targetadd_cincludes) header file search path and specifying [add_links](#targetadd_links) link library (optional). Otherwise the specified function is not detected. -<br><br> -And some header file interfaces are defined by macro switches, so it is best to pass the dependent macro switch with [add_defines](#targetadd_defines) when detecting. -</p> - -For `target`, this interface can be set at the same time: dependent header files, dependent link modules, dependent function interfaces, to ensure the integrity of the detection environment, for example: - -```lua -target("test") - - -- Add libc library interface related detection - -- First parameter: module name for the final macro definition prefix generation - -- The second parameter: the link library - -- The third parameter: header file - -- after the list of function interfaces - add_cfuncs("libc", nil, {"signal.h", "setjmp.h"}, "signal", "setjmp", "sigsetjmp{sigjmp_buf buf; sigsetjmp(buf, 0);}", "kill") - - -- Add the pthread library interface related detection, and specify whether you need to detect the existence of the `libpthread.a` link library. - add_cfuncs("posix", "pthread", "pthread.h", "pthread_mutex_init", - "pthread_create", - "pthread_setspecific", - "pthread_getspecific", - "pthread_key_create", - "pthread_key_delete") -``` - -Set the `test` target, rely on these interfaces, pre-detect them when building, and automatically generate header files if set via the [set_config_h](#targetset_config_h) interface: `config.h` - -Then, the test result will be automatically added to the corresponding `config.h`, which is also the function that `option` does not have, for example: - -```c -#define TB_CONFIG_LIBC_HAVE_SIGNAL 1 -#define TB_CONFIG_LIBC_HAVE_SETJMP 1 -#define TB_CONFIG_LIBC_HAVE_SIGSETJMP 1 -#define TB_CONFIG_LIBC_HAVE_KILL 1 - -#define TB_CONFIG_POSIX_HAVE_PTHREAD_MUTEX_INIT 1 -#define TB_CONFIG_POSIX_HAVE_PTHREAD_CREATE 1 -#define TB_CONFIG_POSIX_HAVE_PTHREAD_SETSPECIFIC 1 -#define TB_CONFIG_POSIX_HAVE_PTHREAD_GETSPECIFIC 1 -#define TB_CONFIG_POSIX_HAVE_PTHREAD_KEY_CREATE 1 -#define TB_CONFIG_POSIX_HAVE_PTHREAD_KEY_DELETE 1 -``` - -Because, in different header files, functions are defined in different ways, such as macro functions, static inline functions, extern functions, and so on. - -To fully test the success, the grammar requires a certain degree of flexibility. Here are some grammar rules: - -| Detection Syntax | Examples | -| ------------- | ----------------------------------------------- | -| pure function name | `sigsetjmp` | -| Single line call | `sigsetjmp((void*)0, 0)` | -| Function Block Call | `sigsetjmp{sigsetjmp((void*)0, 0);}` | -| Function Block + Variable | `sigsetjmp{int a = 0; sigsetjmp((void*)a, a);}` | - -### target:add_cxxfuncs - -#### Add c++ functions for checking - -Similar to [add_cfuncs](#targetadd_cfuncs), only the function interface detected is a c++ function. - ### target:add_options #### Add option dependencies diff --git a/zh-cn/manual/global_interfaces.md b/zh-cn/manual/global_interfaces.md index 91765207..7b8e752b 100644 --- a/zh-cn/manual/global_interfaces.md +++ b/zh-cn/manual/global_interfaces.md @@ -28,6 +28,62 @@ 关于这块的更加完整的说明，可以看下：[https://github.com/xmake-io/xmake/issues/342](https://github.com/xmake-io/xmake/issues/342) +例子： + +检测links, c/c++ type, includes和编译器特性，并且写入宏定义到config.h + +```lua +includes("check_links.lua") +includes("check_ctypes.lua") +includes("check_cfuncs.lua") +includes("check_features.lua") +includes("check_csnippets.lua") +includes("check_cincludes.lua") + +target("test") + set_kind("binary") + add_files("*.c") + add_configfiles("config.h.in") + + configvar_check_ctypes("HAS_WCHAR", "wchar_t") + configvar_check_cincludes("HAS_STRING_H", "string.h") + configvar_check_cincludes("HAS_STRING_AND_STDIO_H", {"string.h", "stdio.h"}) + configvar_check_ctypes("HAS_WCHAR_AND_FLOAT", {"wchar_t", "float"}) + configvar_check_links("HAS_PTHREAD", {"pthread", "m", "dl"}) + configvar_check_csnippets("HAS_STATIC_ASSERT", "_Static_assert(1, \"\");") + configvar_check_cfuncs("HAS_SETJMP", "setjmp", {includes = {"signal.h", "setjmp.h"}}) + configvar_check_features("HAS_CONSTEXPR", "cxx_constexpr") + configvar_check_features("HAS_CONSEXPR_AND_STATIC_ASSERT", {"cxx_constexpr", "c_static_assert"}, {languages = "c++11"}) +``` + +config.h.in + +```c +${define HAS_STRING_H} +${define HAS_STRING_AND_STDIO_H} +${define HAS_WCHAR} +${define HAS_WCHAR_AND_FLOAT} +${define HAS_PTHREAD} +${define HAS_STATIC_ASSERT} +${define HAS_SETJMP} +${define HAS_CONSTEXPR} +${define HAS_CONSEXPR_AND_STATIC_ASSERT} +``` + +config.h + +```c +/* #undef HAS_STRING_H */ +#define HAS_STRING_AND_STDIO_H 1 +/* #undef HAS_WCHAR */ +/* #undef HAS_WCHAR_AND_FLOAT */ +#define HAS_PTHREAD 1 +#define HAS_STATIC_ASSERT 1 +#define HAS_SETJMP 1 +/* #undef HAS_CONSTEXPR */ +#define HAS_CONSEXPR_AND_STATIC_ASSERT 1 +``` + ### set_modes #### 设置支持的编译模式 @@ -76,23 +132,14 @@ set_version("1.5.1") set_version("1.5.1") ``` -以tbox为例，如果调用[set_config_header](#targetset_config_header)设置了`config.h`，那么会自动生成如下宏： - -```c -// version -#define TB_CONFIG_VERSION "1.5.1" -#define TB_CONFIG_VERSION_MAJOR 1 -#define TB_CONFIG_VERSION_MINOR 5 -#define TB_CONFIG_VERSION_ALTER 1 -#define TB_CONFIG_VERSION_BUILD 201510220917 -``` - 2.1.7版本支持buildversion的配置： ```lua set_version("1.5.1", {build = "%Y%m%d%H%M"}) ``` +我们也能够添加版本宏定义到头文件，请参考：[add_configfiles](/manual/project_target?id=add-template-configuration-files) + ### set_xmakever #### 设置最小xmake版本 diff --git a/zh-cn/manual/project_target.md b/zh-cn/manual/project_target.md index a592eb69..43708ffe 100644 --- a/zh-cn/manual/project_target.md +++ b/zh-cn/manual/project_target.md @@ -106,10 +106,6 @@ target("test2") | [add_ldflags](#targetadd_ldflags) | 添加链接选项 | >= 1.0.1 | | [add_arflags](#targetadd_arflags) | 添加静态库归档选项 | >= 1.0.1 | | [add_shflags](#targetadd_shflags) | 添加动态库链接选项 | >= 1.0.1 | -| [add_cfunc](#targetadd_cfunc) | 添加单个c库函数检测 | >= 2.0.1 | -| [add_cxxfunc](#targetadd_cxxfunc) | 添加单个c++库函数检测 | >= 2.0.1 | -| [add_cfuncs](#targetadd_cfuncs) | 添加c库函数检测 | >= 2.0.1 | -| [add_cxxfuncs](#targetadd_cxxfuncs) | 添加c++库函数接口 | >= 2.0.1 | | [add_packages](#targetadd_packages) | 添加包依赖 | >= 2.0.1 | | [add_options](#targetadd_options) | 添加关联选项 | >= 2.0.1 | | [add_languages](#targetadd_languages) | 添加语言标准 | >= 1.0.1 | @@ -372,7 +368,7 @@ target("xxx") 如果还想进一步定制目标文件的目录名，可参考：[set_targetdir](#targetset_targetdir)。 -或者通过编写自定义脚本，实现更高级的逻辑，具体见：[after_build](#targetafter_build)和[os.mv](#os-mv)。 +或者通过编写自定义脚本，实现更高级的逻辑，具体见：[after_build](#targetafter_build)和[os.mv](/zh-cn/manual/builtin_modules?id=osmv)。 ### target:set_filename @@ -1811,142 +1807,6 @@ add_arflags("xxx") add_shflags("xxx") ``` -### target:add_cfunc - -#### 添加单个c库函数检测 - -与[add_cfuncs](#targetadd_cfuncs)类似，只是仅对单个函数接口进行设置，并且仅对`target`域生效，`option`中不存在此接口。 - -此接口的目的主要是为了在`config.h`中更加高度定制化的生成宏开关，例如： - -```lua -target("demo") - - -- 设置和启用config.h - set_config_header("$(buildir)/config.h", {prefix = "TEST"}) - - -- 仅通过参数一设置模块名前缀 - add_cfunc("libc", nil, nil, {"sys/select.h"}, "select") - - -- 通过参数三，设置同时检测链接库：libpthread.a - add_cfunc("pthread", nil, "pthread", "pthread.h", "pthread_create") - - -- 通过参数二设置接口别名 - add_cfunc(nil, "PTHREAD", nil, "pthread.h", "pthread_create") -``` - -生成的结果如下： - -```c -#ifndef TEST_H -#define TEST_H - -// 宏命名规则：$(prefix)前缀 _ 模块名（如果非nil）_ HAVE _ 接口名或者别名 （大写） -#define TEST_LIBC_HAVE_SELECT 1 -#define TEST_PTHREAD_HAVE_PTHREAD_CREATE 1 -#define TEST_HAVE_PTHREAD 1 - -#endif -``` - -如果要更加灵活的函数检测，可以通过[lib.detect.has_cfuncs](#detect-has_cfuncs)在自定义脚本中实现。 - -### target:add_cxxfunc - -#### 添加单个c++库函数检测 - -与[add_cfunc](#targetadd_cfunc)类似，只是检测的函数接口是c++函数。 - -### target:add_cfuncs - -#### 添加c库函数检测 - -<p class="warn"> -此接口是`target`和`option`共用的接口，但是接口行为稍有不同。 -</p> - -| 接口域 | 描述 | 例子 | -| ------ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| target | 头文件、链接库和函数接口同时指定 | `add_cfuncs("libc", nil, {"signal.h", "setjmp.h"}, "signal", "setjmp", "sigsetjmp{sigjmp_buf buf; sigsetjmp(buf, 0);}", "kill")` | -| option | 仅指定函数接口，头文件依赖[add_cincludes](#targetadd_cincludes)等独立接口 | `add_cincludes("setjmp.h")` `add_cfuncs("sigsetjmp")` | - -对于`option`，这个接口的使用很简单，跟[add_cincludes](#targetadd_cincludes)类似，例如： - -```lua -option("setjmp") - set_default(false) - add_cincludes("setjmp.h") - add_cfuncs("sigsetjmp", "setjmp") - add_defines("HAVE_SETJMP") - -target("test") - add_options("setjmp") -``` - -此选项检测是否存在`setjmp`的一些接口，如果检测通过那么`test`目标程序将会加上`HAVE_SETJMP`的宏定义。 - -<p class="warn"> -需要注意的是，在`option`中使用此接口检测依赖函数，需要同时使用独立的[add_cincludes](#targetadd_cincludes)增加头文件搜索路径，指定[add_links](#targetadd_links)链接库（可选），否则检测不到指定函数。 -<br><br> -并且某些头文件接口是通过宏开关分别定义的，那么检测的时候最好通过[add_defines](#targetadd_defines)带上依赖的宏开关。 -</p> - -对于`target`，此接口可以同时设置：依赖的头文件、依赖的链接模块、依赖的函数接口，保证检测环境的完整性，例如： - -```lua -target("test") - - -- 添加libc库接口相关检测 - -- 第一个参数：模块名，用于最后的宏定义前缀生成 - -- 第二个参数：链接库 - -- 第三个参数：头文件 - -- 之后的都是函数接口列表 - add_cfuncs("libc", nil, {"signal.h", "setjmp.h"}, "signal", "setjmp", "sigsetjmp{sigjmp_buf buf; sigsetjmp(buf, 0);}", "kill") - - -- 添加pthread库接口相关检测，同时指定需要检测`libpthread.a`链接库是否存在 - add_cfuncs("posix", "pthread", "pthread.h", "pthread_mutex_init", - "pthread_create", - "pthread_setspecific", - "pthread_getspecific", - "pthread_key_create", - "pthread_key_delete") -``` - -设置`test`目标，依赖这些接口，构建时会预先检测他们，并且如果通过[set_config_h](#targetset_config_h)接口设置的自动生成头文件：`config.h` - -那么，检测结果会自动加到对应的`config.h`上去，这也是`option`没有的功能，例如： - -```c -#define TB_CONFIG_LIBC_HAVE_SIGNAL 1 -#define TB_CONFIG_LIBC_HAVE_SETJMP 1 -#define TB_CONFIG_LIBC_HAVE_SIGSETJMP 1 -#define TB_CONFIG_LIBC_HAVE_KILL 1 - -#define TB_CONFIG_POSIX_HAVE_PTHREAD_MUTEX_INIT 1 -#define TB_CONFIG_POSIX_HAVE_PTHREAD_CREATE 1 -#define TB_CONFIG_POSIX_HAVE_PTHREAD_SETSPECIFIC 1 -#define TB_CONFIG_POSIX_HAVE_PTHREAD_GETSPECIFIC 1 -#define TB_CONFIG_POSIX_HAVE_PTHREAD_KEY_CREATE 1 -#define TB_CONFIG_POSIX_HAVE_PTHREAD_KEY_DELETE 1 -``` - -由于，不同头文件中，函数的定义方式不完全相同，例如：宏函数、静态内联函数、extern函数等。 - -要想完全检测成功，检测语法上需要一定程度的灵活性，下面是一些语法规则： - -| 检测语法 | 例子 | -| ------------- | ----------------------------------------------- | -| 纯函数名 | `sigsetjmp` | -| 单行调用 | `sigsetjmp((void*)0, 0)` | -| 函数块调用 | `sigsetjmp{sigsetjmp((void*)0, 0);}` | -| 函数块 + 变量 | `sigsetjmp{int a = 0; sigsetjmp((void*)a, a);}` | - -### target:add_cxxfuncs - -#### 添加c++库函数检测 - -与[add_cfuncs](#targetadd_cfuncs)类似，只是检测的函数接口是c++函数。 - ### target:add_options #### 添加关联选项 |