add add_embeddirs

Author: waruqi

docs/api/description/builtin-rules.md

@@ -612,6 +612,10 @@ cat build/.gens/test/macosx/x86_64/release/rules/c++/bin2c/image.png.h
   0x68, 0x65, 0x6C, 0x6C, 0x6F, 0x20, 0x78, 0x6D, 0x61, 0x6B, 0x65, 0x21, 0x0A, 0x00
 ```
 
+:::tip TIP
+If you are using a compiler that supports the C23 `#embed` feature (such as clang or gcc), you can also use the `#embed` directive directly to embed binary files. You need to set the C23 language standard first via `set_languages("c23")`, and then use [add_embeddirs](project-target.md#add_embeddirs) to set the search path. This approach is more aligned with the C23 standard and does not require generating additional header files.
+:::
+
 ## utils.glsl2spv
 
 This rule can be used in v2.6.1 and above. Import glsl shader files such as `*.vert/*.frag` into the project, and then realize automatic compilation to generate `*.spv` files.

docs/api/description/project-target.md

@@ -3271,6 +3271,70 @@ In the case of the msvc compiler, it will be:
 In addition, the dependency package introduced with `add_requires()` will also use `-isystem` as the external system header file by default.
 :::
 
+## add_embeddirs
+
+### Add #embed search directory
+
+#### Function Prototype
+
+::: tip API
+```lua
+add_embeddirs(embeddirs: <string|array>, ..., {
+    public|interface|private = <boolean>
+})
+```
+:::
+
+
+#### Parameter Description
+
+| Parameter | Description |
+|-----------|-------------|
+| embeddirs | #embed search directory string or array, supports wildcard matching patterns |
+| ... | Variable parameters, can pass multiple #embed search directory strings |
+| public\|interface\|private | Visibility setting, see [Visibility Settings](#visibility) for details |
+
+#### Usage
+
+Set the search directory for the C23 `#embed` preprocessor directive, similar to how `add_includedirs` works. This interface is used to configure the directory paths that the compiler searches when looking for files referenced by `#embed` directives.
+
+Both clang and gcc support the C23 `#embed` feature and provide the `--embed-dir=` argument to set the search path.
+
+```lua
+target("test")
+    set_kind("binary")
+    set_languages("c23")
+    add_embeddirs("./my_dir")
+    add_files("src/*.c")
+```
+
+You can also set different search paths based on platform or configuration conditions:
+
+```lua
+target("test")
+    set_kind("binary")
+    set_languages("c23")
+    add_embeddirs("./my_dir")
+    on_config("linux", function(target)
+        target:add("embeddirs", "./linux/embeds")
+    end)
+    add_files("src/*.c")
+```
+
+The generated compilation options are as follows:
+
+```sh
+--embed-dir=./my_dir --embed-dir=./linux/embeds
+```
+
+:::tip NOTE
+Using the `#embed` feature requires setting the C23 language standard, which can be enabled via `set_languages("c23")`. If you don't want it to be fixed in the project, you can also set it through `cxflags`/`cxxflags`, but you need to provide different argument formats for different compilers. Using `add_embeddirs` can automatically adapt to different compilers.
+:::
+
+:::tip TIP
+For embedding binary files using `#embed`, you can also refer to the [utils.bin2c](builtin-rules.md#utilsbin2c) rule, which provides another way to embed binary files into code.
+:::
+
 ## add_defines
 
 ### Add macro definition

docs/zh/api/description/builtin-rules.md

@@ -601,6 +601,10 @@ cat build/.gens/test/macosx/x86_64/release/rules/c++/bin2c/image.png.h
   0x68, 0x65, 0x6C, 0x6C, 0x6F, 0x20, 0x78, 0x6D, 0x61, 0x6B, 0x65, 0x21, 0x0A, 0x00
 ```
 
+:::tip 提示
+如果你使用支持 C23 `#embed` 特性的编译器（如 clang 或 gcc），也可以直接使用 `#embed` 指令来嵌入二进制文件。需要先通过 `set_languages("c23")` 设置 C23 语言标准，然后使用 [add_embeddirs](project-target.md#add_embeddirs) 来设置搜索路径。这种方式更符合 C23 标准，无需生成额外的头文件。
+:::
+
 ## utils.glsl2spv
 
 v2.6.1 以上版本可以使用此规则，在项目中引入 `*.vert/*.frag` 等 glsl shader 文件，然后实现自动编译生成 `*.spv` 文件。

docs/zh/api/description/project-target.md

@@ -3335,6 +3335,70 @@ target("test")
 另外，使用 `add_requires()` 引入的依赖包，默认也会使用 `-isystem` 作为外部系统头文件。
 :::
 
+## add_embeddirs
+
+### 添加 #embed 搜索目录
+
+#### 函数原型
+
+::: tip API
+```lua
+add_embeddirs(embeddirs: <string|array>, ..., {
+    public|interface|private = <boolean>
+})
+```
+:::
+
+
+#### 参数说明
+
+| 参数 | 描述 |
+|------|------|
+| embeddirs | #embed 搜索目录字符串或数组，支持通配符匹配模式 |
+| ... | 可变参数，可传入多个 #embed 搜索目录字符串 |
+| public\|interface\|private | 可见性设置，详见[可见性设置](#visibility) |
+
+#### 用法说明
+
+设置 C23 `#embed` 预处理器的搜索目录，类似于 `add_includedirs` 的工作方式。此接口用于配置编译器在查找 `#embed` 指令引用的文件时搜索的目录路径。
+
+clang 和 gcc 都支持 C23 `#embed` 特性，并且都提供了 `--embed-dir=` 参数来设置搜索路径。
+
+```lua
+target("test")
+    set_kind("binary")
+    set_languages("c23")
+    add_embeddirs("./my_dir")
+    add_files("src/*.c")
+```
+
+也可以根据平台或配置条件设置不同的搜索路径：
+
+```lua
+target("test")
+    set_kind("binary")
+    set_languages("c23")
+    add_embeddirs("./my_dir")
+    on_config("linux", function(target)
+        target:add("embeddirs", "./linux/embeds")
+    end)
+    add_files("src/*.c")
+```
+
+生成的编译选项如下：
+
+```sh
+--embed-dir=./my_dir --embed-dir=./linux/embeds
+```
+
+:::tip 注意
+使用 `#embed` 特性需要设置 C23 语言标准，通过 `set_languages("c23")` 来启用。如果不想在工程中写死，也可以通过 `cxflags`/`cxxflags` 来设置，但需要根据不同编译器提供不同的参数格式，使用 `add_embeddirs` 可以自动适配不同编译器。
+:::
+
+:::tip 提示
+关于使用 `#embed` 嵌入二进制文件，也可以参考 [utils.bin2c](builtin-rules.md#utilsbin2c) 规则，它提供了另一种将二进制文件嵌入到代码中的方式。
+:::
+
 ## add_defines
 
 ### 添加宏定义