static-php-cli/assets/zh_develop_package-model.md.DYRZ8aaf.js

import{_ as i,c as a,o as n,aj as l}from"./chunks/framework.C2AwuPrQ.js";const g=JSON.parse('{"title":"Package 模型","description":"","frontmatter":{},"headers":[],"relativePath":"zh/develop/package-model.md","filePath":"zh/develop/package-model.md"}'),p={name:"zh/develop/package-model.md"};function h(t,s,k,e,d,r){return n(),a("div",null,[...s[0]||(s[0]=[l(`<h1 id="package-模型" tabindex="-1">Package 模型 <a class="header-anchor" href="#package-模型" aria-label="Permalink to “Package 模型”">​</a></h1><h2 id="package-定义" tabindex="-1">Package 定义 <a class="header-anchor" href="#package-定义" aria-label="Permalink to “Package 定义”">​</a></h2><p>Package 是 StaticPHP 构建系统中的核心概念，代表一个可构建/可安装的单元，如 PHP 扩展、库、构建目标等。</p><p>每个 Package 包含构建信息、依赖关系、构建逻辑等，构成了 StaticPHP 的构建模型。Package 的定义主要通过 YAML/JSON 配置文件来实现。<code>core</code> 注册表的包配置文件位于 <code>config/pkg/</code> 目录下，对应的构建类位于 <code>src/Package/</code> 目录下。</p><p>Package 主要分为四种类型：</p><ul><li><strong>php-extension</strong>：PHP 扩展包，包含 PHP 扩展的构建信息和构建逻辑。</li><li><strong>library</strong>：库包，包含构建工具链、依赖库等的构建信息和构建逻辑。</li><li><strong>target</strong>：构建目标包，代表最终的构建产物，如 PHP 二进制、curl 二进制等，继承自 <code>library</code> 包类型。</li><li><strong>virtual-target</strong>：虚构建目标包，代表一个抽象的构建目标，不直接对应构建产物，主要用于依赖管理和构建调度。</li></ul><div class="language-yaml"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pkg-name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pkg-type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  ...</span></span></code></pre></div><h2 id="artifact-定义" tabindex="-1">Artifact 定义 <a class="header-anchor" href="#artifact-定义" aria-label="Permalink to “Artifact 定义”">​</a></h2><p>Artifact 是独立于 Package 的定义，它包含构建包的源码归档文件或预构建的二进制文件。每个 Artifact 定义了下载 URL、解压方式、构建产物的文件路径等信息。Package 可以通过 <code>artifact</code> 字段引用一个或多个 Artifact 来获取构建所需的源码或二进制文件。</p><p>简单来说，默认情况下，一个 Package 对应一个 Artifact；如果多个 Package 共用一份源码时，可以定义一个 Artifact 供多个 Package 引用。Artifact 的定义位于 <code>config/artifact/</code> 目录下，对应的自定义下载/解压逻辑类位于 <code>src/Package/Artifact/</code> 目录下；对于虚拟目标、PHP 内置扩展等特殊包类型，Package 也可以不设置 Artifact 字段。</p><p>我们假设 <code>example-library-package</code> 是一个依赖库，它的源码归档文件托管在 <code>https://example.com/example-library.tar.gz</code>，则它的 Package 定义和 Artifact 定义可以如下所示：</p><div class="language-yaml"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">example-library-package</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">library</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  artifact</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">url</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      url</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;https://example.com/example-library.tar.gz&#39;</span></span></code></pre></div><p>更多有关 Artifact 定义的内容，请参阅 <a href="./artifact-model.html">Artifact 模型</a> 章节。</p><h2 id="php-extension-包类型" tabindex="-1">php-extension 包类型 <a class="header-anchor" href="#php-extension-包类型" aria-label="Permalink to “php-extension 包类型”">​</a></h2><p>php-extension 一个包代表一个 PHP 扩展，它的配置文件位于 <code>config/pkg/ext/</code> 目录下，构建类继承自 <code>PhpExtensionPackage</code>，位于 <code>src/Package/Extension/</code> 目录下。PHP 扩展包的配置文件包含扩展名称、版本、依赖关系、构建选项等信息。</p><div class="language-yaml"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">ext-lz4</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">php-extension</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  artifact</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">git</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      url</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;https://github.com/kjdev/php-ext-lz4.git&#39;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      rev</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">master</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      extract</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">php-src/ext/lz4</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      license-files</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">LICENSE</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      license</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">MIT</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  depends</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">liblz4</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  php-extension</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    arg-type@unix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;--enable-lz4=@shared_suffix@ --with-lz4-includedir=@build_root_path@&#39;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    arg-type@windows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;--enable-lz4&#39;</span></span></code></pre></div><p><code>php-extension</code> 允许的定义字段：</p><div class="language-yaml"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">ext-{ext-name}</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:          </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 包名必须以 ext- 前缀开头</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">php-extension</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ── 通用字段 ─────────────────────────────────────────────────────────────</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;...&#39;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">     # 可选，人类可读的包描述</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  lang</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">c</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                # 可选，扩展的实现语言（c / c++ 等）</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  frameworks</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []         </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 可选，相关macOS框架依赖列表</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  artifact</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;{artifact-name}&#39;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 可选；字符串时引用同名 Artifact 定义，</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                               # 对象时为内联 Artifact（内置扩展无需此字段）</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # depends / suggests 支持 @windows / @unix / @linux / @macos 后缀</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  depends</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []            </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 可选，硬依赖列表（库名直接写，PHP 扩展需加 ext- 前缀）</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  depends@unix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []       </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 可选，仅 Unix 平台生效的硬依赖</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  depends@windows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []    </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 可选，仅 Windows 平台生效的硬依赖</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  suggests</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []           </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 可选，可选依赖列表（格式同 depends）</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  suggests@unix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ── php-extension 专属字段（嵌套在 php-extension: 对象中）─────────────────</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  php-extension</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # arg-type 决定传递给 ./configure 的参数形式，支持平台后缀</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # 支持的平台后缀：@unix（Linux + macOS）、@linux、@macos、@windows</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # 优先级（以 Linux 为例）：arg-type@linux &gt; arg-type@unix &gt; arg-type（无后缀）</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # 内置关键字：</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    #   enable      → --enable-{extname}（默认值，未配置时使用）</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    #   enable-path → --enable-{extname}={buildroot}</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    #   with        → --with-{extname}</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    #   with-path   → --with-{extname}={buildroot}</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    #   custom/none → 不传递任何参数（由 PHP 类的 #[CustomPhpConfigureArg] 方法处理）</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # 也可直接写完整参数字符串，支持以下占位符：</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    #   @build_root_path@   → BUILD_ROOT_PATH（buildroot 绝对路径）</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    #   @shared_suffix@     → 共享构建时展开为 =shared，静态构建时为空</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    #   @shared_path_suffix@ → 共享构建时展开为 =shared,{buildroot}，静态构建时为 ={buildroot}</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    arg-type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">enable</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    arg-type@unix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;--enable-{extname}=@shared_suffix@&#39;</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    arg-type@windows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">with-path</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    zend-extension</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 可选，true 表示这是 Zend 扩展（如 opcache、xdebug）</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    build-shared</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">     # 可选，是否允许构建为共享扩展（.so），默认 true</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    build-static</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">     # 可选，是否允许内联静态构建（编译进 PHP），默认 true</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    build-with-php</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # 可选，true 表示该扩展通过 PHP 源码树一同编译（内置扩展使用）</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # display-name 影响 smoke test 中 php --ri 的参数及许可证导出显示名称</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # 不填时默认使用扩展名（ext- 后缀部分）；填空字符串则跳过 --ri 检查</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    display-name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;My Extension&#39;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # os 限制该扩展仅在指定平台上可用，不在列表内的平台会拒绝构建</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # 可选值：Linux、Darwin、Windows</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    os</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Linux</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Darwin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span></code></pre></div><h2 id="library-包类型" tabindex="-1">library 包类型 <a class="header-anchor" href="#library-包类型" aria-label="Permalink to “library 包类型”">​</a></h2><p>library 包代表一个需要从源码编译的依赖库（如 openssl、zlib 等），其配置文件位于 <code>config/pkg/lib/</code> 目录下，构建类继承自 <code>LibraryPackage</code>，位于 <code>src/Package/Library/</code> 目录下。</p><p>以 openssl 为例：</p><div class="language-yaml"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">openssl</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">library</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  artifact</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ghrel</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      repo</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">openssl/openssl</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      match</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">openssl.+\\.tar\\.gz</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      prefer-stable</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    binary</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">hosted</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    metadata</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      license-files</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">LICENSE.txt</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">      license</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">OpenSSL</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  depends</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">zlib</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  depends@windows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">zlib</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">jom</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  headers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">openssl</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  static-libs@unix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">libssl.a</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">libcrypto.a</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  static-libs@windows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">libssl.lib</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">libcrypto.lib</span></span></code></pre></div><p><code>library</code> 允许的定义字段：</p><div class="language-yaml"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark" style="--shiki-light:#24292e;--shiki-dark:#e1e4e8;--shiki-light-bg:#fff;--shiki-dark-bg:#24292e;" tabindex="0" dir="ltr"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lib-name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">library</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">           # library 或 target（target 继承 library 的所有字段）</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ── 通用字段 ─────────────────────────────────────────────────────────────</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;...&#39;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">     # 可选，人类可读的包描述</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  license</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">MIT</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">           # 可选，SPDX 许可证标识符（用于许可证导出）</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  lang</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">c</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                # 可选，库的实现语言（c / c++ 等）</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  frameworks</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []         </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 可选，相关框架标签列表</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  artifact</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;{artifact-name}&#39;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 必填；字符串时引用同名 Artifact 定义，对象时为内联 Artifact</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # depends / suggests 支持 @windows / @unix / @linux / @macos 后缀</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  depends</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []            </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 可选，硬依赖列表（库名或 ext- 前缀的 PHP 扩展名）</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  depends@unix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  depends@windows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  suggests</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: []           </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># 可选，可选依赖列表（格式同 depends）</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # ── library / target 专属字段 ────────────────────────────────────────────</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 以下字段用于构建完成后验证产物是否已正确安装，支持 @unix / @windows / @linux / @macos 后缀</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 验证 buildroot/include/ 下是否存在指定头文件或目录</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 相对路径基于 buildroot/include/，绝对路径直接使用</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  headers</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">openssl</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">             # 对应 buildroot/include/openssl/</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">zlib.h</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">              # 对应 buildroot/include/zlib.h</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  headers@unix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ffi.h</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 验证 buildroot/lib/ 下是否存在指定静态库文件</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 相对路径基于 buildroot/lib/，绝对路径直接使用</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  static-libs@unix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">libssl.a</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  static-libs@windows</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">libssl.lib</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 验证 buildroot/lib/pkgconfig/ 下是否存在指定 .pc 文件</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 仅在非 Windows 平台检查（pkg-config 在 Windows 上不适用）</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  pkg-configs</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">openssl</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">             # 对应 buildroot/lib/pkgconfig/openssl.pc</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">libssl</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">              # 自动补全 .pc 后缀</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 验证 buildroot/bin/ 下是否存在指定可执行文件</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 相对路径基于 buildroot/bin/，绝对路径直接使用</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  static-bins</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">my-tool</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 包安装完成后注入到全局 PATH 的目录列表，支持路径占位符（见下方说明）</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  path</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;{pkg_root_path}/rust/bin&#39;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 包安装完成后设置的环境变量（覆盖已有值），支持路径占位符</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  env</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    MY_VAR</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;{build_root_path}/lib&#39;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # 包安装完成后追加到已有环境变量末尾的值，支持路径占位符</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">  append-env</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">    CFLAGS</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39; -I{build_root_path}/include&#39;</span></span></code></pre></div><p><code>path</code>、<code>env</code>、<code>append-env</code> 字段的字符串值中支持以下路径占位符：</p><table tabindex="0"><thead><tr><th>占位符</th><th>实际路径</th></tr></thead><tbody><tr><td><code>{build_root_path}</code></td><td>buildroot 目录（<code>buildroot/</code>）</td></tr><tr><td><code>{pkg_root_path}</code></td><td>pkgroot 目录（<code>pkgroot/</code>）</td></tr><tr><td><code>{working_dir}</code></td><td>工作目录（项目根目录）</td></tr><tr><td><code>{download_path}</code></td><td>下载缓存目录（<code>downloads/</code>）</td></tr><tr><td><code>{source_path}</code></td><td>解压源码目录（<code>source/</code>）</td></tr><tr><td><code>{php_sdk_path}</code></td><td>Windows PHP SDK 目录</td></tr></tbody></table><h2 id="target-包类型" tabindex="-1">target 包类型 <a class="header-anchor" href="#target-包类型" aria-label="Permalink to “target 包类型”">​</a></h2><p><code>target</code> 包代表一个最终的构建产物，它继承于 <code>library</code>，所以包含 <code>library</code> 的所有定义字段。<code>target</code> 包的配置文件位于 <code>config/pkg/target/</code> 目录下，构建类继承自 <code>TargetPackage</code>，位于 <code>src/Package/Target/</code> 目录下。</p><p>与 <code>library</code> 的唯一区别是，<code>target</code> 包可以注册成为构建目标，且自动注册构建命令 <code>spc build:{target-name}</code>。</p><h2 id="virtual-target-包类型" tabindex="-1">virtual-target 包类型 <a class="header-anchor" href="#virtual-target-包类型" aria-label="Permalink to “virtual-target 包类型”">​</a></h2><p>与 <code>target</code> 不同的是，<code>virtual-target</code> 可以不包含 <code>artifact</code>，即不直接对应一个可构建的实体，而是一个抽象的构建目标，主要用于依赖管理和构建调度。<code>virtual-target</code> 的配置文件位于 <code>config/pkg/target/</code> 目录下，构建类继承自 <code>TargetPackage</code>，位于 <code>src/Package/Target/</code> 目录下。它的定义与 <code>target</code> 基本相同，但 <code>artifact</code> 字段可选且通常不设置。<code>virtual-target</code> 主要用于以下场景：</p><ul><li>定义一个抽象的构建目标，供其他包依赖，但不直接对应一个可构建的实体。</li><li>作为多个 <code>target</code> 包的公共依赖，简化依赖关系管理。</li></ul><p>典型例子就是 PHP 包的 <code>php-cli</code>、<code>php-fpm</code> 等构建目标，他们没有独立的源码，依赖于 <code>php-src</code>，通过构建调度来决定最终构建成 CLI 还是 FPM 二进制。</p>`,33)])])}const c=i(p,[["render",h]]);export{g as __pageData,c as default};