refactor(backend): rename declaration generation methods and update header files

- Rename genFunctionDeclaration to genFunctionDeclarations
- Rename genExternGlobalVars to genDataDeclarations
- Update global variable declaration header from global_var_decl.h to data_decl.h
- Update documentation to reflect new internal build header files
- Modify source pipeline to use new method names and header naming convention

docs/AOT_BUILD_SPEED_RESEARCH.md

@@ -18,7 +18,7 @@
 1. `prepare()`：扫描文件、解析 AST、收集符号、排序依赖
 2. `convert()`：生成每个 PHP 文件对应的 `.cc`
 3. `genStubFile()`：生成 arginfo / class register 头文件
-4. `genFunctionDeclaration()` / `genExternGlobalVars()`：生成公共声明头
+4. `genFunctionDeclarations()` / `genDataDeclarations()`：生成构建期内部声明头
 5. `genExtension()`：生成单个 `extension-<target>.cc`
 6. `compile()`：把所有 `.cc/.c/...` 编译为 `.o`
 7. `build()`：链接为最终可执行文件或扩展
@@ -30,7 +30,7 @@
 当前所有翻译单元都会包含：
 
 - `php_<target>_func_decl.h`
-- `php_<target>_global_var_decl.h`
+- `php_<target>_data_decl.h`
 
 只要任何函数声明、默认参数 helper、全局符号声明发生变化，就会导致大量 `.cc` 重新编译。
 
@@ -101,7 +101,7 @@ clang-format -i <file>
 - `.cc`
 - arginfo `.h`
 - `php_<target>_func_decl.h`
-- `php_<target>_global_var_decl.h`
+- `php_<target>_data_decl.h`
 - `extension-<target>.cc`
 
 在写盘前先比较内容：
@@ -317,8 +317,8 @@ clang-format -i <file>
   - `compile()`
   - `compileSourceFile()`
   - `compileWithPcntl()`
-  - `genFunctionDeclaration()`
+  - `genFunctionDeclarations()`
-  - `genExternGlobalVars()`
+  - `genDataDeclarations()`
   - `genExtension()`
   - `genStubFile()`
 - `src/Php/Backend/*`
@@ -339,4 +339,3 @@ clang-format -i <file>
 - **增量**
 - **拆分**
 - **减少公共依赖面**
-

docs/MIXED_CPP_PHP.md

@@ -699,14 +699,25 @@ function vector_new(int $size, bool $init = false): mixed {}
 - 当其他 target 引用该 stub 时，函数按 `prime2` 库 ABI 导入，且链接阶段自动加入 `prime2` 库。
 - 注解只允许用于 `.stub.php` 文件；未声明时，stub 函数默认由当前 target 实现。
 
+`php_<target>_func_decl.h` 和 `php_<target>_data_decl.h` 都是 TypePHP 构建过程的内部生成文件，不是库的对外开发头文件。
+`func_decl.h` 在 `-m lib` 构建时还会被强制包含，用于给当前 target 的 `php_*` C++ ABI 函数添加平台导出标记；`data_decl.h` 仅在 target 内部声明全局变量、字面量、常量对象和运行时映射等数据。
+
+发布 TypePHP 库时，对外提供：
+
+- 描述 TypePHP 函数接口和所属库的 `.stub.php`；
+- Windows 平台的 `.dll` 和导入库 `.lib`；
+- Linux 等平台的 `.so`。
+
+如果库另外导出了自定义 C++ ABI 或 C ABI，库作者需要自行编写并随库发布对应的 `.h` 头文件。
+
 ✅ **正确**:
 ```php
 <?php
-function is_prime(int $n): bool {
+function is_prime(int $n): bool {}
-    // 空实现或简单返回
-}
 ```
 
+stub 仅保留空函数体，实现位于 C++ 或所属 TypePHP 库中。
+
 ❌ **错误**:
 ```php
 <?php

phpunit/src/CompilerBaseApiTest.php

@@ -844,7 +844,7 @@ YAML);
         $this->compiler->convertFile($testFile);
 
         $headerFile = $this->testDir . '/php_abi_defaults_func_decl.h';
-        $this->compiler->genFunctionDeclaration($headerFile);
+        $this->compiler->genFunctionDeclarations($headerFile);
         $header = file_get_contents($headerFile);
 
         $this->assertStringContainsString('#pragma once', $header);
@@ -867,14 +867,14 @@ YAML);
         $this->assertStringNotContainsString('php_func_map', $header);
         $this->assertStringNotContainsString('php_class_map', $header);
 
-        $globalHeaderFile = $this->testDir . '/php_abi_defaults_global_var_decl.h';
+        $dataHeaderFile = $this->testDir . '/php_abi_defaults_data_decl.h';
-        $this->compiler->genExternGlobalVars($globalHeaderFile);
+        $this->compiler->genDataDeclarations($dataHeaderFile);
-        $globalHeader = file_get_contents($globalHeaderFile);
+        $dataHeader = file_get_contents($dataHeaderFile);
-        $this->assertStringContainsString('extern php::Var _const_var_EXPORTED_ABI_INT;', $globalHeader);
+        $this->assertStringContainsString('extern php::Var _const_var_EXPORTED_ABI_INT;', $dataHeader);
-        $this->assertStringContainsString('extern php::Var _const_var_EXPORTED_ABI_STRING;', $globalHeader);
+        $this->assertStringContainsString('extern php::Var _const_var_EXPORTED_ABI_STRING;', $dataHeader);
-        $this->assertStringContainsString('extern php::Var _const_var_EXPORTED_ABI_ARRAY;', $globalHeader);
+        $this->assertStringContainsString('extern php::Var _const_var_EXPORTED_ABI_ARRAY;', $dataHeader);
-        $this->assertStringContainsString('extern php::Str _literal_strings[', $globalHeader);
+        $this->assertStringContainsString('extern php::Str _literal_strings[', $dataHeader);
-        $this->assertStringContainsString('extern THREAD_LOCAL zend_function *php_func_map[', $globalHeader);
+        $this->assertStringContainsString('extern THREAD_LOCAL zend_function *php_func_map[', $dataHeader);
 
         $extensionFile = $this->compiler->genExtension();
         $extension = file_get_contents($extensionFile);
@@ -896,7 +896,7 @@ YAML);
         $this->compiler->convertFile($testFile);
 
         $headerFile = $this->testDir . '/php_consumer_func_decl.h';
-        $this->compiler->genFunctionDeclaration($headerFile);
+        $this->compiler->genFunctionDeclarations($headerFile);
         $header = file_get_contents($headerFile);
 
         $this->assertStringContainsString('TYPEPHP_PRIME2_API __declspec(dllimport)', $header);

src/Build/SourcePipelineTrait.php

@@ -193,9 +193,9 @@ trait SourcePipelineTrait
             $this->stop('No valid source file found');
         }
 
-        // 生成头文件：函数声明、全局变量声明
+        // 生成构建期内部头文件：函数声明、运行时数据声明
-        $this->genFunctionDeclaration($this->getIncludeDir() . "/php_{$this->targetName}_func_decl.h");
+        $this->genFunctionDeclarations($this->getIncludeDir() . "/php_{$this->targetName}_func_decl.h");
-        $this->genExternGlobalVars($this->getIncludeDir() . "/php_{$this->targetName}_global_var_decl.h");
+        $this->genDataDeclarations($this->getIncludeDir() . "/php_{$this->targetName}_data_decl.h");
         // 生成扩展模块源文件
         $sourceFiles[] = $this->genExtension();
 

src/Translator.php

@@ -656,7 +656,7 @@ class Translator extends Preprocessor
         $argv = $processed;
     }
 
-    public function genExternGlobalVars(string $file): void
+    public function genDataDeclarations(string $file): void
     {
         $lines[] = '#include <phpx.h>';
         $lines[] = PHP_EOL;
@@ -1539,7 +1539,7 @@ CODE;
         return $this->climate->arguments->trailingArray() ?? [];
     }
 
-    public function genFunctionDeclaration(string $file): void
+    public function genFunctionDeclarations(string $file): void
     {
         $code = '#pragma once' . PHP_EOL . PHP_EOL;
         $code .= '#include <phpx.h>' . PHP_EOL;
@@ -1673,7 +1673,7 @@ CODE;
     {
         $headers = array_merge($this->globalHeaders, [
             "php_{$this->targetName}_func_decl.h",
-            "php_{$this->targetName}_global_var_decl.h",
+            "php_{$this->targetName}_data_decl.h",
         ], $this->localHeaders);
         $lines = [];
         foreach ($headers as $header) {