<spanclass="line"><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> ...</span></span></code></pre></div><h2id="artifact-definition"tabindex="-1">Artifact Definition <aclass="header-anchor"href="#artifact-definition"aria-label="Permalink to “Artifact Definition”"></a></h2><p>An Artifact is a definition independent of Packages. It contains the source archive file or pre-built binary for building packages. Each Artifact defines download URLs, extraction methods, and build artifact file paths. Packages can reference one or more Artifacts via the <code>artifact</code> field to obtain the source or binaries needed for building.</p><p>In simple terms, by default one Package corresponds to one Artifact; if multiple Packages share the same source, you can define a single Artifact for multiple Packages to reference. Artifact definitions are located in the <code>config/artifact/</code> directory, and the corresponding custom download/extract logic classes are in the <code>src/Package/Artifact/</code> directory. For special package types like virtual targets and PHP built-in extensions, a Package may also omit the Artifact field entirely.</p><p>Assuming <code>example-library-package</code> is a dependency library whose source archive is hosted at <code>https://example.com/example-library.tar.gz</code>, its Package and Artifact definitions would look like this:</p><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;">example-library-package</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> url</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'https://example.com/example-library.tar.gz'</span></span></code></pre></div><p>For more on Artifact definitions, see the <ahref="./artifact-model.html">Artifact Model</a> chapter.</p><h2id="php-extension-package-type"tabindex="-1">php-extension Package Type <aclass="header-anchor"href="#php-extension-package-type"aria-label="Permalink to “php-extension Package Type”"></a></h2><p>A php-extension package represents a PHP extension. Its configuration file is located in the <code>config/pkg/ext/</code> directory, and its build class inherits from <code>PhpExtensionPackage</code> in the <code>src/Package/Extension/</code> directory. PHP extension package configurations include extension name, version, dependencies, build options, and more.</p><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;">ext-lz4</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> arg-type@windows</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'--enable-lz4'</span></span></code></pre></div><p>Allowed fields for <code>php-extension</code>:</p><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;">ext-{ext-name}</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Package name must start with ext- prefix</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> lang</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">c</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Optional, implementation language of the extension (c / c++ etc.)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> frameworks</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] </span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Optional, list of related macOS framework dependencies</span></span>
<spanclass="line"></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> artifact</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'{artifact-name}'</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Optional; when a string, references an Artifact definition</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # with the same name; when an object, is an inline Artifact</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # (built-in extensions don't need this field)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> depends</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] </span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Optional, hard dependency list (library names as-is, PHP extensions need ext- prefix)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> depends@unix</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] </span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Optional, hard dependencies only effective on Unix platforms</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> depends@windows</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] </span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Optional, hard dependencies only effective on Windows platforms</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> suggests</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] </span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Optional, optional dependency list (same format as depends)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # arg-type determines the form of arguments passed to ./configure, supports platform suffixes</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Priority (using Linux as example): arg-type@linux > arg-type@unix > arg-type (no suffix)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # enable → --enable-{extname} (default value, used when not configured)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # custom/none → Pass no arguments (handled by the #[CustomPhpConfigureArg] method in the PHP class)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # You can also write the full argument string directly, supporting the following placeholders:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # @build_root_path@ → BUILD_ROOT_PATH (absolute path of buildroot)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # @shared_suffix@ → Expands to =shared in shared builds, empty in static builds</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # @shared_path_suffix@ → Expands to =shared,{buildroot} in shared builds,</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # expands to ={buildroot} in static builds</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> zend-extension</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Optional, true indicates this is a Zend extension (e.g., opcache, xdebug)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> build-shared</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Optional, whether building as a shared extension (.so) is allowed, default true</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> build-static</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Optional, whether inline static building (compiled into PHP) is allowed, default true</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> build-with-php</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Optional, true means the extension is built together via the PHP source tree</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # (used for built-in extensions)</span></span>
<spanclass="line"></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # display-name affects the php --ri argument in smoke tests and the license export display name</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # If not set, defaults to the extension name (the part after ext-); if set to empty string, skips --ri check</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # os restricts the extension to be available only on specified platforms;</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # platforms not in the list will be rejected for building</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> os</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Linux</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Darwin</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span></code></pre></div><h2id="library-package-type"tabindex="-1">library Package Type <aclass="header-anchor"href="#library-package-type"aria-label="Permalink to “library Package Type”"></a></h2><p>A library package represents a dependency library that needs to be compiled from source (such as openssl, zlib, etc.). Its configuration file is located in the <code>config/pkg/lib/</code> directory, and its build class inherits from <code>LibraryPackage</code> in the <code>src/Package/Library/</code> directory.</p><p>Taking openssl as an example:</p><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;">openssl</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">libcrypto.lib</span></span></code></pre></div><p>Allowed fields for <code>library</code>:</p><divclass="language-yaml"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">yaml</span><preclass="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><spanclass="line"><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">lib-name</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> type</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">library</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # library or target (target inherits all fields from library)</span></span>
<spanclass="line"></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # ── Common Fields ─────────────────────────────────────────────────────────</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> lang</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">c</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Optional, implementation language of the library (c / c++ etc.)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> frameworks</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] </span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Optional, list of related framework tags</span></span>
<spanclass="line"></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> artifact</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'{artifact-name}'</span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Required; when a string, references an Artifact definition</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # with the same name; when an object, is an inline Artifact</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> depends</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] </span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Optional, hard dependency list (library names or PHP extension names with ext- prefix)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> suggests</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [] </span><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Optional, optional dependency list (same format as depends)</span></span>
<spanclass="line"></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # ── library / target Specific Fields ───────────────────────────────────────</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # The following fields are used to verify that artifacts have been correctly</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # installed after the build. They support @unix / @windows / @linux / @macos suffixes.</span></span>
<spanclass="line"></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Verify that specified header files or directories exist under buildroot/include/</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Relative paths are based on buildroot/include/, absolute paths are used directly</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Verify that specified static library files exist under buildroot/lib/</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Relative paths are based on buildroot/lib/, absolute paths are used directly</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Verify that specified .pc files exist under buildroot/lib/pkgconfig/</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Only checked on non-Windows platforms (pkg-config is not applicable on Windows)</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Verify that specified executable files exist under buildroot/bin/</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Relative paths are based on buildroot/bin/, absolute paths are used directly</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # List of directories injected into the global PATH after the package is installed.</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Path placeholders are supported (see below for details).</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Environment variables set after the package is installed (overwrites existing values).</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Path placeholders are supported.</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Values appended to the end of existing environment variables after the package is installed.</span></span>
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # Path placeholders are supported.</span></span>
<spanclass="line"><spanstyle="--shiki-light:#22863A;--shiki-dark:#85E89D;"> CFLAGS</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><spanstyle="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">' -I{build_root_path}/include'</span></span></code></pre></div><p>The following path placeholders are supported in string values of the <code>path</code>, <code>env</code>, and <code>append-env</code> fields:</p><tabletabindex="0"><thead><tr><th>Placeholder</th><th>Actual Path</th></tr></thead><tbody><tr><td><code>{build_root_path}</code></td><td>buildroot directory (<code>buildroot/</code>)</td></tr><tr><td><code>{pkg_root_path}</code></td><td>pkgroot directory (<code>pkgroot/</code>)</td></tr><tr><td><code>{working_dir}</code></td><td>Working directory (project root)</td></tr><tr><td><code>{download_path}</code></td><td>Download cache directory (<code>downloads/</code>)</td></tr><tr><td><code>{source_path}</code></td><td>Extracted source directory (<code>source/</code>)</td></tr><tr><td><code>{php_sdk_path}</code></td><td>Windows PHP SDK directory</td></tr></tbody></table><h2id="target-package-type"tabindex="-1">target Package Type <aclass="header-anchor"href="#target-package-type"aria-label="Permalink to “target Package Type”"></a></h2><p>A <code>target</code> package represents a final build artifact. It inherits from <code>library</code>, so it includes all definition fields of <code>library</code>. The configuration file for <code>target</code> packages is located in the <code>config/pkg/target/</code> directory, and its build class inherits from <code>TargetPackage</code> in the <code>src/Package/Target/</code> directory.</p><p>The only difference from <code>library</code> is that a <code>target</code> package can be registered as a build target and automatically registers the build command <code>spc build:{target-name}</code>.</p><h2id="virtual-target-package-type"tabindex="-1">virtual-target Package Type <aclass="header-anchor"href="#virtual-target-package-type"aria-label="Permalink to “virtual-target Package Type”"></a></h2><p>Unlike <code>target</code>, a <code>virtual-target</code> may not include an <code>artifact</code>, meaning it doesn't directly correspond to a buildable entity but is instead an abstract build target, primarily used for dependency management and build scheduling. The configuration file for <code>virtual-target</code> is located in the <code>config/pkg/target/</code> directory, and its build class inherits from <code>TargetPackage</code> in the <code>src/Package/Target/</code> directory. Its definition is essentially the same as <code>target</code>, but the <code>artifact</code> field is optional and typically not set. <code>virtual-target</code> is primarily used in the following scenarios:</p><ul><li>Defining an abstract build target for other packages to depend on, without directly corresponding to a buildable entity.</li><li>Serving as a common dependency for multiple <code>target</code> packages, simplifying dependency management.</li></ul><p>A typical example is the <code>php-cli</code>, <code>php-fpm</code> build targets for PHP. They have no independent source code and depend on <code>php-src</code>, with the final build outcome (CLI or FPM binary) determined through build scheduling.</p></div></div></main><footerclass="VPDocFooter"data-v-7011f0d8data-v-e257564d><!--[--><!--]--><!----><navclass="prev-next"aria-labelledby="doc-footer-aria-label"data-v-e257564d><spanclass="visually-hidden"id="doc-footer-aria-label"data-v-e257564d>Pager</span><divclass="pager"data-v-e257564d><aclass="VPLink link pager-link prev"href="/en/develop/registry.html"data-v-e257564d><!--[--><spanclass="desc"data-v-e257564d>Previous page</span><spanclass="title"data-v-e257564d>Registry</span><!--]--></a></div><divclass="pager"data-v-e257564d><aclass="VPLink link pager-link next"href="/en/develop/artifact-model.html"data-v-e257564d><!--[--><spanclass="desc"data-v-e257564d>Next page</span><spanclass="title"data-v-e257564d>Artifact M
