Skip to content

Commit a080a55

Browse files
waruqiwaruqi
committed
update docs
1 parent b271a1f commit a080a55

File tree

5 files changed

+450
-106
lines changed

5 files changed

+450
-106
lines changed

‎manual/project_target.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2885,6 +2885,107 @@ After `set_configvar("HAVE_SSE2", 1)` is enabled, it becomes `HAVE_SSE2 equ 1`.
28852885
28862886
For a detailed description of this, see: https://github.com/xmake-io/xmake/issues/320
28872887
2888+
##### Define export macros
2889+
2890+
A new feature added in v2.9.8 is that it can generate export macro definitions for dynamic libraries, which are usually used for symbol export and import of dll libraries under Windows.
2891+
2892+
Define in config.h.in:
2893+
2894+
```c
2895+
${define_export MYLIB}
2896+
```
2897+
2898+
It will generate
2899+
2900+
```c
2901+
#ifdef MYLIB_STATIC
2902+
# define MYLIB_EXPORT
2903+
#else
2904+
# if defined(_WIN32)
2905+
# define MYLIB_EXPORT __declspec(dllexport)
2906+
# elif defined(__GNUC__) && ((__GNUC__ >= 4) || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3))
2907+
# define MYLIB_EXPORT __attribute__((visibility("default")))
2908+
# else
2909+
# define MYLIB_EXPORT
2910+
# endif
2911+
#endif
2912+
```
2913+
2914+
When we define the dynamic library export symbol, we can use this macro to control the import and export.
2915+
2916+
```c
2917+
MYLIB_EXPORT void foo();
2918+
```
2919+
2920+
It is similar to CMake's [GenerateExportHeader](https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html).
2921+
2922+
However, it does not generate an independent export header file, but generates it directly in config.h.
2923+
2924+
For more details, see: [#6088](https://github.com/xmake-io/xmake/issues/6088)
2925+
2926+
##### Custom preprocessor
2927+
2928+
If the built-in build rules of xmake do not meet your needs, you can also customize the processor to rewrite the build rules, such as rewriting `${define_export XXX}`:
2929+
2930+
```lua
2931+
target("test")
2932+
set_kind("binary")
2933+
add_files("main.c")
2934+
add_configfiles("config.h.in", {
2935+
preprocessor = function (preprocessor_name, name, value, opt)
2936+
if preprocessor_name == "define_export" then
2937+
value = ([[#ifdef %s_STATIC
2938+
# define %s_EXPORT
2939+
#else
2940+
# if defined(_WIN32)
2941+
# define %s_EXPORT __declspec(dllexport)
2942+
# elif defined(__GNUC__) && ((__GNUC__ >= 4) || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3))
2943+
# define %s_EXPORT __attribute__((visibility("default")))
2944+
# else
2945+
# define %s_EXPORT
2946+
# endif
2947+
#endif
2948+
]]):format(name, name, name, name, name)
2949+
return value
2950+
end
2951+
end})
2952+
```
2953+
2954+
We can also override the generation of `${define XXX}` and `${default XXX}`, or even customize and extend other preprocessor configurations.
2955+
2956+
For example:
2957+
2958+
```lua
2959+
target("test")
2960+
set_kind("binary")
2961+
add_files("main.c")
2962+
set_configvar("FOO", "foo")
2963+
add_configfiles("config.h")
2964+
add_configfiles("config.h.in", {
2965+
preprocessor = function (preprocessor_name, name, value, opt)
2966+
local argv = opt.argv
2967+
if preprocessor_name == "define_custom" then
2968+
return string.format("#define CUSTOM_%s %s", name, value)
2969+
end
2970+
end})
2971+
```
2972+
2973+
Then we configure in config.h.in:
2974+
2975+
```c
2976+
${define_custom FOO arg1 arg2}
2977+
```
2978+
2979+
Where, `define_custom` is the custom preprocessor name, FOO is the variable name, and the variable value can be obtained from `set_configvar`.
2980+
2981+
arg1 and arg2 are optional preprocessing parameter lists. Whether they are needed depends on actual needs. If you want to use parameters, you can get them through `opt.argv`, which is a parameter list table.
2982+
2983+
After running `xmake config`, the following configuration will be automatically generated in config.h:
2984+
2985+
```c
2986+
#define CUSTOM_FOO foo
2987+
```
2988+
28882989
### target:set_policy
28892990

28902991
#### Set build policy

‎mirror/manual/project_target.html

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2406,6 +2406,77 @@ <h5 id="macrodefinition">Macro definition</h5>
24062406
<pre><code>HAVE_SSE2 equ ${default VAR_HAVE_SSE2 0}
24072407
</code></pre><p>After <code>set_configvar("HAVE_SSE2", 1)</code> is enabled, it becomes <code>HAVE_SSE2 equ 1</code>. If no variable is set, the default value is used: <code>HAVE_SSE2 equ 0</code></p>
24082408
<p>For a detailed description of this, see: <a href="https://github.com/xmake-io/xmake/issues/320">https://github.com/xmake-io/xmake/issues/320</a></p>
2409+
<h5 id="defineexportmacros">Define export macros</h5>
2410+
<p>A new feature added in v2.9.8 is that it can generate export macro definitions for dynamic libraries, which are usually used for symbol export and import of dll libraries under Windows.</p>
2411+
<p>Define in config.h.in:</p>
2412+
<pre><code class="lang-c">${define_export MYLIB}
2413+
</code></pre>
2414+
<p>It will generate</p>
2415+
<pre><code class="lang-c">#ifdef MYLIB_STATIC
2416+
# define MYLIB_EXPORT
2417+
#else
2418+
# if defined(_WIN32)
2419+
# define MYLIB_EXPORT __declspec(dllexport)
2420+
# elif defined(__GNUC__) &amp;&amp; ((__GNUC__ >= 4) || (__GNUC__ == 3 &amp;&amp; __GNUC_MINOR__ >= 3))
2421+
# define MYLIB_EXPORT __attribute__((visibility("default")))
2422+
# else
2423+
# define MYLIB_EXPORT
2424+
# endif
2425+
#endif
2426+
</code></pre>
2427+
<p>When we define the dynamic library export symbol, we can use this macro to control the import and export.</p>
2428+
<pre><code class="lang-c">MYLIB_EXPORT void foo();
2429+
</code></pre>
2430+
<p>It is similar to CMake&#39;s <a href="https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html">GenerateExportHeader</a>.</p>
2431+
<p>However, it does not generate an independent export header file, but generates it directly in config.h.</p>
2432+
<p>For more details, see: <a href="https://github.com/xmake-io/xmake/issues/6088">#6088</a></p>
2433+
<h5 id="custompreprocessor">Custom preprocessor</h5>
2434+
<p>If the built-in build rules of xmake do not meet your needs, you can also customize the processor to rewrite the build rules, such as rewriting <code>${define_export XXX}</code>:</p>
2435+
<pre><code class="lang-lua">target("test")
2436+
set_kind("binary")
2437+
add_files("main.c")
2438+
add_configfiles("config.h.in", {
2439+
preprocessor = function (preprocessor_name, name, value, opt)
2440+
if preprocessor_name == "define_export" then
2441+
value = ([[#ifdef %s_STATIC
2442+
# define %s_EXPORT
2443+
#else
2444+
# if defined(_WIN32)
2445+
# define %s_EXPORT __declspec(dllexport)
2446+
# elif defined(__GNUC__) &amp;&amp; ((__GNUC__ >= 4) || (__GNUC__ == 3 &amp;&amp; __GNUC_MINOR__ >= 3))
2447+
# define %s_EXPORT __attribute__((visibility("default")))
2448+
# else
2449+
# define %s_EXPORT
2450+
# endif
2451+
#endif
2452+
]]):format(name, name, name, name, name)
2453+
return value
2454+
end
2455+
end})
2456+
</code></pre>
2457+
<p>We can also override the generation of <code>${define XXX}</code> and <code>${default XXX}</code>, or even customize and extend other preprocessor configurations.</p>
2458+
<p>For example:</p>
2459+
<pre><code class="lang-lua">target("test")
2460+
set_kind("binary")
2461+
add_files("main.c")
2462+
set_configvar("FOO", "foo")
2463+
add_configfiles("config.h")
2464+
add_configfiles("config.h.in", {
2465+
preprocessor = function (preprocessor_name, name, value, opt)
2466+
local argv = opt.argv
2467+
if preprocessor_name == "define_custom" then
2468+
return string.format("#define CUSTOM_%s %s", name, value)
2469+
end
2470+
end})
2471+
</code></pre>
2472+
<p>Then we configure in config.h.in:</p>
2473+
<pre><code class="lang-c">${define_custom FOO arg1 arg2}
2474+
</code></pre>
2475+
<p>Where, <code>define_custom</code> is the custom preprocessor name, FOO is the variable name, and the variable value can be obtained from <code>set_configvar</code>.</p>
2476+
<p>arg1 and arg2 are optional preprocessing parameter lists. Whether they are needed depends on actual needs. If you want to use parameters, you can get them through <code>opt.argv</code>, which is a parameter list table.</p>
2477+
<p>After running <code>xmake config</code>, the following configuration will be automatically generated in config.h:</p>
2478+
<pre><code class="lang-c">#define CUSTOM_FOO foo
2479+
</code></pre>
24092480
<h3 id="targetset_policy">target:set_policy</h3>
24102481
<h4 id="setbuildpolicy">Set build policy</h4>
24112482
<p>Xmake has many default behaviors, such as: automatic detection and mapping of flags, cross-target parallel construction, etc. Although it provides a certain amount of intelligent processing, it is difficult to adjust and may not meet all users&#39; habits and needs.</p>

‎mirror/zh-cn/manual/project_target.html

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2378,6 +2378,77 @@ <h5 id="">宏定义</h5>
23782378
<pre><code>HAVE_SSE2 equ ${default VAR_HAVE_SSE2 0}
23792379
</code></pre><p>通过<code>set_configvar("HAVE_SSE2", 1)</code>启用变量后，变为<code>HAVE_SSE2 equ 1</code>，如果没有设置变量，则使用默认值：<code>HAVE_SSE2 equ 0</code></p>
23802380
<p>关于这个的详细说明，见：<a href="https://github.com/xmake-io/xmake/issues/320">https://github.com/xmake-io/xmake/issues/320</a></p>
2381+
<h5 id="">定义导出宏</h5>
2382+
<p>v2.9.8 新增的特性，可以生成动态库的导出宏定义，通常用于 windows 下 dll 库的符号导出和导入。</p>
2383+
<p>在 config.h.in 中定义：</p>
2384+
<pre><code class="lang-c">${define_export MYLIB}
2385+
</code></pre>
2386+
<p>就会生成</p>
2387+
<pre><code class="lang-c">#ifdef MYLIB_STATIC
2388+
# define MYLIB_EXPORT
2389+
#else
2390+
# if defined(_WIN32)
2391+
# define MYLIB_EXPORT __declspec(dllexport)
2392+
# elif defined(__GNUC__) &amp;&amp; ((__GNUC__ >= 4) || (__GNUC__ == 3 &amp;&amp; __GNUC_MINOR__ >= 3))
2393+
# define MYLIB_EXPORT __attribute__((visibility("default")))
2394+
# else
2395+
# define MYLIB_EXPORT
2396+
# endif
2397+
#endif
2398+
</code></pre>
2399+
<p>我们在定义动态库导出符号时，可以通过这个宏来控制导入导出。</p>
2400+
<pre><code class="lang-c">MYLIB_EXPORT void foo();
2401+
</code></pre>
2402+
<p>它跟 CMake 的 <a href="https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html">GenerateExportHeader</a> 的功能类似。</p>
2403+
<p>不过，它不会额外生成一个独立的导出头文件，而是直接在 config.h 中去生成它。</p>
2404+
<p>更多详情见：<a href="https://github.com/xmake-io/xmake/issues/6088">#6088</a></p>
2405+
<h5 id="">自定义预处理器</h5>
2406+
<p>如果 xmake 内置的生成规则不满足需求，也可以自定义处理器去重写生成规则，例如重写 <code>${define_export XXX}</code>：</p>
2407+
<pre><code class="lang-lua">target("test")
2408+
set_kind("binary")
2409+
add_files("main.c")
2410+
add_configfiles("config.h.in", {
2411+
preprocessor = function (preprocessor_name, name, value, opt)
2412+
if preprocessor_name == "define_export" then
2413+
value = ([[#ifdef %s_STATIC
2414+
# define %s_EXPORT
2415+
#else
2416+
# if defined(_WIN32)
2417+
# define %s_EXPORT __declspec(dllexport)
2418+
# elif defined(__GNUC__) &amp;&amp; ((__GNUC__ >= 4) || (__GNUC__ == 3 &amp;&amp; __GNUC_MINOR__ >= 3))
2419+
# define %s_EXPORT __attribute__((visibility("default")))
2420+
# else
2421+
# define %s_EXPORT
2422+
# endif
2423+
#endif
2424+
]]):format(name, name, name, name, name)
2425+
return value
2426+
end
2427+
end})
2428+
</code></pre>
2429+
<p>我们也可以重写对 <code>${define XXX}</code> 和 <code>${default XXX}</code> 的生成，甚至自定义扩展其他预处理配置。</p>
2430+
<p>例如：</p>
2431+
<pre><code class="lang-lua">target("test")
2432+
set_kind("binary")
2433+
add_files("main.c")
2434+
set_configvar("FOO", "foo")
2435+
add_configfiles("config.h")
2436+
add_configfiles("config.h.in", {
2437+
preprocessor = function (preprocessor_name, name, value, opt)
2438+
local argv = opt.argv
2439+
if preprocessor_name == "define_custom" then
2440+
return string.format("#define CUSTOM_%s %s", name, value)
2441+
end
2442+
end})
2443+
</code></pre>
2444+
<p>然后我们在 config.h.in 中配置：</p>
2445+
<pre><code class="lang-c">${define_custom FOO arg1 arg2}
2446+
</code></pre>
2447+
<p>其中，<code>define_custom</code> 是自定义的预处理器名，FOO 是变量名，可以从 <code>set_configvar</code> 中获取变量值。</p>
2448+
<p>而 arg1, arg2 是可选的预处理参数列表，根据实际的需求来判断是否需要使用，如果想要使用参数，可以通过 <code>opt.argv</code> 来获取，它是一个参数列表 table。</p>
2449+
<p>在运行 <code>xmake config</code> 后，就会在 config.h 中自动生成如下配置：</p>
2450+
<pre><code class="lang-c">#define CUSTOM_FOO foo
2451+
</code></pre>
23812452
<h3 id="targetset_policy">target:set_policy</h3>
23822453
<h4 id="">设置构建行为策略</h4>
23832454
<p>xmake有很多的默认行为，比如：自动检测和映射flags、跨target并行构建等，虽然提供了一定的智能化处理，但重口难调，不一定满足所有的用户的使用习惯和需求。</p>

0 commit comments

Comments
 (0)