Apply suggestion

This reverts commit 977ea4a8f8.

.github/copilot-instructions.md

@@ -10,6 +10,7 @@ Use the repository skills when the task matches them:
 
 - `.github/skills/staticphp-package-maintenance`: add, modify, review, or validate package, artifact, extension, library, target, or tool definitions.
 - `.github/skills/staticphp-build-troubleshooting`: diagnose build, download, doctor, shell, terminal, CI, smoke-test, or log failures.
+- `.github/skills/staticphp-documentation-sync`: synchronize bilingual documentation (`docs/en/` and `docs/zh/`) when features, commands, configuration, APIs, or behavior change.
 
 ## Quick Reference
 

.github/skills/staticphp-documentation-sync/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: staticphp-documentation-sync
+description: Synchronize bilingual documentation when StaticPHP v3 user-facing or developer-facing documentation must change. Use when adding, modifying, deprecating, or removing documented features, CLI commands/options, environment variables, configuration formats, public APIs/extension points, workflows, installation requirements, migration guidance, or user-visible behavior. Do not use solely for internal implementation changes, package/library additions, or build bug fixes unless they change documented behavior or require updating existing docs.
+---
+
+# StaticPHP Documentation Sync
+
+## Overview
+
+StaticPHP maintains bilingual documentation under `docs/en/` (English) and `docs/zh/` (Chinese). User-facing or developer-facing documentation changes must be reflected in both languages. Use this skill to identify affected docs, update them in sync, and validate sidebar/config consistency.
+
+## When to Use This Skill
+
+Invoke this skill when the change involves:
+
+- New or modified CLI commands, options, or arguments
+- New or changed environment variables
+- Package (extension/library/target/tool) additions, removals, or behavioral changes that affect documented support, dependencies, commands, or workflows
+- Configuration format changes (YAML fields, artifact definitions, registry)
+- Build lifecycle, doctor, or toolchain changes
+- API or extension point changes (attributes, hooks, DI, custom artifacts)
+- Workflow changes (installation, first build, migration)
+- Deprecation or removal of any documented feature
+
+Do not update docs just because code changed. Internal refactors, new libraries used only as dependencies, package build fixes, CI-only changes, and bug fixes that preserve documented behavior usually do not need documentation changes. If existing docs mention the changed behavior, command, package support, dependency, caveat, or workaround, update them.
+
+## Documentation Map
+
+```
+docs/
+├── en/                          # English docs (canonical source)
+│   ├── index.md                 # Home page hero/features
+│   ├── guide/                   # User-facing guides
+│   │   ├── index.md             # Overview
+│   │   ├── installation.md      # Installation instructions
+│   │   ├── first-build.md       # First build walkthrough
+│   │   ├── sapi-reference.md    # PHP SAPI options
+│   │   ├── cli-reference.md     # CLI commands and options
+│   │   ├── cli-generator.md     # Build command generator
+│   │   ├── migrate-from-v2.md   # v2 → v3 migration
+│   │   ├── extensions.md        # Supported extensions list
+│   │   ├── extension-notes.md   # Per-extension notes
+│   │   ├── env-vars.md          # Environment variables
+│   │   ├── deps-map.md          # Dependency map
+│   │   └── troubleshooting.md   # Troubleshooting guide
+│   ├── develop/                 # Developer docs
+│   │   ├── index.md             # Dev overview
+│   │   ├── structure.md         # Project structure
+│   │   ├── registry.md          # Registry model
+│   │   ├── package-model.md     # Package YAML model
+│   │   ├── artifact-model.md    # Artifact YAML model
+│   │   ├── craft-yml.md         # craft.yml reference
+│   │   ├── build-lifecycle.md   # Build stages/lifecycle
+│   │   ├── system-build-tools.md # System tool requirements
+│   │   ├── doctor-module.md     # Doctor module
+│   │   ├── php-src-changes.md   # PHP source patches
+│   │   └── extending/           # Extension authoring
+│   │       ├── index.md
+│   │       ├── package-classes.md
+│   │       ├── annotations.md
+│   │       ├── lifecycle-hooks.md
+│   │       ├── dependency-injection.md
+│   │       └── custom-artifact.md
+│   ├── contributing/
+│   │   └── index.md
+│   └── faq/
+│       └── index.md
+├── zh/                          # Chinese docs (mirrors en/ structure)
+│   └── (same structure as en/)
+├── .vitepress/
+│   ├── sidebar.en.ts            # English sidebar config
+│   ├── sidebar.zh.ts            # Chinese sidebar config
+│   └── config.ts                # VitePress site config
+└── deps-craft-yml.md            # Shared craft.yml include used by both languages
+```
+
+Other documentation files outside this tree may also matter, especially root-level `ext-support.md`.
+
+**Key rule**: `docs/en/` and `docs/zh/` have identical file trees. Every `.md` file under `en/` must have a corresponding file under `zh/`.
+
+## Workflow
+
+### Step 1: Identify Impact Scope
+
+Map the change to affected documentation:
+
+| Change Type | Likely Affected Docs |
+|---|---|
+| New/removed CLI command | `guide/cli-reference.md`, `guide/cli-generator.md` |
+| New/removed CLI option | `guide/cli-reference.md`, `guide/first-build.md` |
+| New env var | `guide/env-vars.md` |
+| New/removed documented extension package | `guide/extensions.md`, `guide/extension-notes.md`, `guide/deps-map.md`, root `ext-support.md` |
+| Package config field change | `develop/package-model.md`, `develop/artifact-model.md` |
+| Build lifecycle change | `develop/build-lifecycle.md` |
+| Doctor change | `develop/doctor-module.md`, `develop/system-build-tools.md` |
+| New attribute/hook/DI | `develop/extending/annotations.md`, `develop/extending/lifecycle-hooks.md`, `develop/extending/dependency-injection.md` |
+| PHP source patch | `develop/php-src-changes.md` |
+| Registry change | `develop/registry.md` |
+| Install/setup change | `guide/installation.md`, `guide/first-build.md` |
+| Deprecation/removal | All docs referencing the feature |
+| New doc page | `sidebar.en.ts`, `sidebar.zh.ts` |
+
+### Step 2: Read Current Docs
+
+Before editing, read BOTH the English and Chinese versions of each affected file to understand the current content and existing translation patterns.
+
+```bash
+# Example: check both language versions of the CLI reference
+cat docs/en/guide/cli-reference.md
+cat docs/zh/guide/cli-reference.md
+```
+
+### Step 3: Update English Docs First
+
+1. Update `docs/en/` files with accurate, complete English content.
+2. Follow existing formatting conventions (headings, code blocks, tables, admonitions).
+3. If adding a new page:
+   - Create the file under `docs/en/<category>/<name>.md`
+   - Add the corresponding entry in `docs/.vitepress/sidebar.en.ts`
+   - Ensure the file has proper VitePress frontmatter if needed
+
+### Step 4: Sync Chinese Docs
+
+1. Update `docs/zh/` files to match the English changes.
+2. Translate all changed or added prose. Do not leave placeholder text or untranslated English in Chinese docs.
+3. Match the structure and formatting of the English version exactly.
+4. If a new page was added in English, create the corresponding `docs/zh/` file and update `docs/.vitepress/sidebar.zh.ts`.
+5. Treat `docs/deps-craft-yml.md` as a special shared include for both languages. If it needs prose changes, either keep the shared content acceptable for both languages or split the included content before adding language-specific prose.
+
+### Step 5: Validate
+
+Run these checks before considering the task complete:
+
+```bash
+# Check that en/ and zh/ have matching file trees
+diff <(find docs/en -name '*.md' | sed 's|docs/en/||' | sort) \
+     <(find docs/zh -name '*.md' | sed 's|docs/zh/||' | sort)
+
+# Check that all sidebar links point to existing files
+# (manual check: every 'link' in sidebar.*.ts must resolve to an actual .md file)
+
+# Build docs when Node dependencies are available; this catches many broken links/config issues
+npm run docs:build
+```
+
+## Translation Guidelines
+
+- **Chinese docs must be complete**: Every section, paragraph, and table in the English docs must have a Chinese equivalent. Never skip sections.
+- **Code blocks and command examples**: Keep executable code and commands identical in both languages. Translate surrounding prose; translate comments inside examples only when they are explanatory docs rather than copy-pasteable source/config.
+- **Technical terms**: Use consistent translations. Refer to existing Chinese docs for established term translations. When in doubt, prefer the term used elsewhere in `docs/zh/`.
+- **Links**: Internal links in Chinese docs should point to `/zh/...` paths (not `/en/...`).
+- **YAML frontmatter**: Keep frontmatter identical between languages (layout, etc.) unless the title/tagline field is translated.
+
+## Common Pitfalls
+
+- **Don't update only one language**: This is the most common mistake. Always update both `en/` and `zh/` in the same change.
+- **Don't forget sidebar configs**: When adding, renaming, or removing doc pages, update both `sidebar.en.ts` and `sidebar.zh.ts`.
+- **Don't forget shared/root docs**: root `ext-support.md` and `docs/deps-craft-yml.md` are also documentation. Update them if relevant.
+- **Don't leave TODO markers**: Do not commit TODO translation placeholders unless the user explicitly allows it or the task is blocked; if that happens, call it out in the final response.
+- **Don't translate file paths or URLs**: Only translate human-readable content, not paths, URLs, command names, or code identifiers.

.github/workflows/vitepress-deploy.yml

@@ -27,9 +27,14 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - uses: actions/setup-node@v3
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: yarn
 
-      - run: npm install
+      - name: Install documentation dependencies
+        run: yarn install --frozen-lockfile
 
       - name: "Install PHP for official runners"
         uses: shivammathur/setup-php@v2
@@ -57,7 +62,7 @@ jobs:
         run: "composer install --no-interaction --no-progress"
 
       - name: Build
-        run: npm run docs:build
+        run: yarn docs:build
 
       # Deploy to GitHub Pages only when the workflow is triggered by a push to the v3 branch
       - name: Deploy to GitHub Pages

.gitignore

@@ -52,6 +52,7 @@ packlib_files.txt
 /node_modules/
 /docs/.vitepress/dist/
 /docs/.vitepress/cache/
+/docs/.vitepress/.temp/
 /docs/.vitepress/ext-data.json
 /docs/.vitepress/deps-data.json
 package-lock.json

AGENTS.md

@@ -10,6 +10,7 @@ Detailed task workflows live in `.github/skills`. Use them when the task matches
 
 - `.github/skills/staticphp-package-maintenance`: add, modify, review, or validate package, artifact, extension, library, target, or tool definitions.
 - `.github/skills/staticphp-build-troubleshooting`: diagnose build, download, doctor, shell, terminal, CI, smoke-test, or log failures.
+- `.github/skills/staticphp-documentation-sync`: synchronize bilingual documentation (`docs/en/` and `docs/zh/`) when features, commands, configuration, APIs, or behavior change.
 
 If your agent does not automatically discover skills from `.github/skills`, read the matching `SKILL.md` manually before working on that task.
 

config/env.ini

@@ -102,7 +102,7 @@ CXX=${SPC_DEFAULT_CXX}
 AR=${SPC_DEFAULT_AR}
 LD=${SPC_DEFAULT_LD}
 ; default compiler flags, used in CMake toolchain file, openssl and pkg-config build
-SPC_DEFAULT_CFLAGS="-fPIC -O3 -pipe -fno-plt -fno-semantic-interposition -fstack-clash-protection -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -ffunction-sections -fdata-sections"
+SPC_DEFAULT_CFLAGS="-fPIC -O3 -pipe -fno-plt -fno-semantic-interposition -fstack-clash-protection -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -ffunction-sections -fdata-sections -Wno-unused-command-line-argument"
 SPC_DEFAULT_CXXFLAGS="${SPC_DEFAULT_CFLAGS}"
 SPC_DEFAULT_LDFLAGS="-Wl,-z,relro -Wl,--as-needed -Wl,-z,now -Wl,-z,noexecstack -Wl,--gc-sections"
 ; upx executable path
@@ -125,6 +125,8 @@ SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS="-g -fstack-protector-strong -fno-ident -fPIE
 SPC_CMD_VAR_PHP_MAKE_EXTRA_CXXFLAGS="-g -fstack-protector-strong -fno-ident -fPIE -fvisibility=hidden -fvisibility-inlines-hidden ${SPC_DEFAULT_CXXFLAGS}"
 ; EXTRA_LDFLAGS for `make` php, can use -release to set a soname for libphp.so
 SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS=""
+; EXTRA_LDFLAGS_PROGRAM for `make` php; appended only to SAPI executable links (cli/fpm/cgi/micro/embed). Used by PGO to inject -fprofile-use= without polluting libphp.{a,so}.
+SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS_PROGRAM=""
 
 ; optional, path to openssl conf. This affects where openssl will look for the default CA.
 ; default on Debian/Alpine: /etc/ssl, default on RHEL: /etc/pki/tls
@@ -163,5 +165,7 @@ SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS="-g -fstack-protector-strong -fpic -fpie -fvis
 SPC_CMD_VAR_PHP_MAKE_EXTRA_CXXFLAGS="-g -fstack-protector-strong -fno-ident -fpie -fvisibility=hidden -fvisibility-inlines-hidden -Werror=unknown-warning-option ${SPC_DEFAULT_CXXFLAGS}"
 ; EXTRA_LDFLAGS for `make` php, can use -release to set a soname for libphp.dylib
 SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS=""
+; EXTRA_LDFLAGS_PROGRAM for `make` php; appended only to SAPI executable links (cli/fpm/cgi/micro/embed). Used by PGO to inject -fprofile-use= without polluting libphp.{a,dylib}.
+SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS_PROGRAM=""
 ; minimum compatible macOS version (LLVM vars, availability not guaranteed)
 MACOSX_DEPLOYMENT_TARGET=12.0

config/pkg/ext/ext-brotli.yml

@@ -2,12 +2,13 @@ ext-brotli:
   type: php-extension
   artifact:
     source:
-      type: git
+      type: ghtagtar
+      repo: kjdev/php-ext-brotli
       extract: php-src/ext/brotli
-      rev: master
-      url: 'https://github.com/kjdev/php-ext-brotli'
     metadata:
       license-files: [LICENSE]
       license: MIT
   depends:
     - brotli
+  php-extension:
+    arg-type: '--enable-brotli@shared_suffix@ --with-libbrotli'

config/pkg/ext/ext-zstd.yml

@@ -2,9 +2,8 @@ ext-zstd:
   type: php-extension
   artifact:
     source:
-      type: git
-      url: 'https://github.com/kjdev/php-ext-zstd'
-      rev: master
+      type: ghtar
+      repo: kjdev/php-ext-zstd
       extract: php-src/ext/zstd
     metadata:
       license-files: [LICENSE]

config/pkg/lib/gmssl.yml

@@ -2,8 +2,9 @@ gmssl:
   type: library
   artifact:
     source:
-      type: ghtar
-      repo: guanzhi/GmSSL
+      type: git
+      url: 'https://github.com/guanzhi/GmSSL.git'
+      rev: master
     metadata:
       license-files: [LICENSE]
       license: Apache-2.0

docs/.vitepress/components/CliGenerator.vue

@@ -45,7 +45,7 @@
         <label :for="'build_' + item">{{ item }}</label>
       </div>
     </div>
-    <div v-if="selectedSystem === 'windows' && (checkedTargets.includes('fpm') || checkedTargets.includes('embed') || checkedTargets.includes('frankenphp'))" class="warning custom-block">
+    <div v-if="selectedSystem === 'windows' && checkedTargets.includes('fpm')" class="warning custom-block">
       <p class="custom-block-title">WARNING</p>
       <p>{{ I18N[lang].windowsSAPIUnavailable }}</p>
     </div>
@@ -157,7 +157,7 @@
         <div class="warning custom-block">
           <p class="custom-block-title">WARNING</p>
           <p>{{ I18N[lang].windowsDownSPCWarning }}</p>
-          <a href="https://dl.static-php.dev/v3/spc-bin/latest/spc-windows-x86_64.exe" target="_blank">https://dl.static-php.dev/v3/spc-bin/latest/spc-windows-x86_64.exe</a>
+          <a href="https://dl.static-php.dev/v3/spc-bin/nightly/spc-windows-x86_64.exe" target="_blank">https://dl.static-php.dev/v3/spc-bin/nightly/spc-windows-x86_64.exe</a>
         </div>
       </div>
     </div>
@@ -278,7 +278,7 @@ const spcCommand = computed(() => {
 const spcDownloadCommand = computed(() => {
   const os = selectedSystem.value === 'macos' ? 'macos' : 'linux';
   const arch = selectedArch.value;
-  return `curl -#fSL https://dl.static-php.dev/v3/spc-bin/latest/spc-${os}-${arch} -o spc && chmod +x spc`;
+  return `curl -#fSL https://dl.static-php.dev/v3/spc-bin/nightly/spc-${os}-${arch} -o spc && chmod +x spc`;
 });
 
 const doctorCommandString = computed(() => `${spcCommand.value} doctor --auto-fix`);
@@ -425,7 +425,7 @@ const I18N: Record<string, Record<string, string>> = {
     downloadPhpVersion: '下载 PHP 版本',
     downloadSPCBinaryCommand: '下载 spc 二进制命令',
     selectedSystem: '选择操作系统',
-    windowsSAPIUnavailable: 'Windows 目前不支持 fpm、embed、frankenphp 构建！',
+    windowsSAPIUnavailable: 'Windows 目前不支持 fpm 构建！',
     useUPX: '是否开启 UPX 压缩（减小二进制体积）',
     windowsDownSPCWarning: 'Windows 下请手动下载 spc.exe 二进制文件！',
     usePreBuilt: '如果可能，使用预编译的依赖库（减少编译时间）',
@@ -459,7 +459,7 @@ const I18N: Record<string, Record<string, string>> = {
     downloadPhpVersion: 'PHP version',
     downloadSPCBinaryCommand: 'Download spc binary',
     selectedSystem: 'Select OS',
-    windowsSAPIUnavailable: 'Windows does not support fpm, embed and frankenphp build!',
+    windowsSAPIUnavailable: 'Windows does not support fpm build!',
     useUPX: 'Enable UPX compression (reduce binary size)',
     windowsDownSPCWarning: 'Please download the spc.exe binary manually on Windows!',
     usePreBuilt: 'Use pre-built dependencies where available (reduce compile time)',

docs/en/develop/package-model.md

@@ -4,14 +4,15 @@
 
 A Package is the core concept in StaticPHP's build system, representing a buildable/installable unit such as a PHP extension, library, or build target.
 
-Each Package contains build information, dependencies, and build logic, forming StaticPHP's build model. Package definitions are primarily implemented through YAML/JSON configuration files. The package configuration files for the `core` registry are located in the `config/pkg/` directory, and the corresponding build classes are in the `src/Package/` directory.
+Each Package contains build information, dependencies, and build logic, forming StaticPHP's build model. Package definitions are primarily implemented through YAML/JSON configuration files. The package configuration files for the `core` registry are located in the `config/pkg/` directory, and optional recipe classes are in the corresponding subdirectories of `src/Package/`.
 
-Packages are primarily divided into four types:
+Packages are divided into five types:
 
 - **php-extension**: A PHP extension package containing build information and logic for a PHP extension.
-- **library**: A library package containing build information and logic for build tools, dependency libraries, etc.
+- **library**: A dependency library package, usually installed into `buildroot/` for other packages to compile and link against.
 - **target**: A build target package representing the final build artifact, such as a PHP binary or curl binary. Inherits from the `library` package type.
 - **virtual-target**: A virtual build target package representing an abstract build target that doesn't directly correspond to a build artifact, primarily used for dependency management and build scheduling.
+- **tool**: A host-side build tool package, installed separately under `pkgroot/` and not treated as a link-time library dependency.
 
 ```yaml
 {pkg-name}:
@@ -21,7 +22,7 @@ Packages are primarily divided into four types:
 
 ## Artifact Definition
 
-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 `artifact` field to obtain the source or binaries needed for building.
+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. A Package can reference one Artifact via the `artifact` field to obtain the source or binary needed for building.
 
 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 `config/artifact/` directory, and the corresponding custom download/extract logic classes are in the `src/Package/Artifact/` directory. For special package types like virtual targets and PHP built-in extensions, a Package may also omit the Artifact field entirely.
 
@@ -40,7 +41,7 @@ For more on Artifact definitions, see the [Artifact Model](./artifact-model) cha
 
 ## php-extension Package Type
 
-A php-extension package represents a PHP extension. Its configuration file is located in the `config/pkg/ext/` directory, and its build class inherits from `PhpExtensionPackage` in the `src/Package/Extension/` directory. PHP extension package configurations include extension name, version, dependencies, build options, and more.
+A php-extension package represents a PHP extension. Its configuration file is located in the `config/pkg/ext/` directory. Optional recipe classes are normally placed in `src/Package/Extension/`, registered with `#[Extension]`, and receive the corresponding `PhpExtensionPackage` through callback context. Inheriting from `PhpExtensionPackage` is supported but is not required by the current core recipes.
 
 ```yaml
 ext-lz4:
@@ -57,7 +58,7 @@ ext-lz4:
   depends:
     - liblz4
   php-extension:
-    arg-type@unix: '--enable-lz4=@shared_suffix@ --with-lz4-includedir=@build_root_path@'
+    arg-type@unix: '--enable-lz4@shared_suffix@ --with-lz4-includedir=@build_root_path@'
     arg-type@windows: '--enable-lz4'
 ```
 
@@ -72,16 +73,18 @@ ext-{ext-name}:          # Package name must start with ext- prefix
   lang: c                 # Optional, implementation language of the extension (c / c++ etc.)
   frameworks: []          # Optional, list of related macOS framework dependencies
 
-  artifact: '{artifact-name}'  # Optional; when a string, references an Artifact definition
-                               # with the same name; when an object, is an inline Artifact
+  artifact: '{artifact-name}'  # Optional; when a string, references the named Artifact definition;
+                               # when an object, it is an inline Artifact
                                # (built-in extensions don't need this field)
 
-  # depends / suggests support @windows / @unix / @linux / @macos suffixes
+  # depends / suggests / tools support @windows / @unix / @linux / @macos suffixes
   depends: []             # Optional, hard dependency list (library names as-is, PHP extensions need ext- prefix)
   depends@unix: []        # Optional, hard dependencies only effective on Unix platforms
   depends@windows: []     # Optional, hard dependencies only effective on Windows platforms
   suggests: []            # Optional, optional dependency list (same format as depends)
   suggests@unix: []
+  tools: []               # Optional, host-side build tool dependencies; resolved separately
+  tools@windows: []       # Optional, platform-specific tool dependencies
 
   # ── php-extension Specific Fields (nested under php-extension: object) ────
   php-extension:
@@ -100,7 +103,7 @@ ext-{ext-name}:          # Package name must start with ext- prefix
     #   @shared_path_suffix@   → Expands to =shared,{buildroot} in shared builds,
     #                            expands to ={buildroot} in static builds
     arg-type: enable
-    arg-type@unix: '--enable-{extname}=@shared_suffix@'
+    arg-type@unix: '--enable-my-extension@shared_suffix@'
     arg-type@windows: with-path
 
     zend-extension: false   # Optional, true indicates this is a Zend extension (e.g., opcache, xdebug)
@@ -121,7 +124,7 @@ ext-{ext-name}:          # Package name must start with ext- prefix
 
 ## library Package Type
 
-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 `config/pkg/lib/` directory, and its build class inherits from `LibraryPackage` in the `src/Package/Library/` directory.
+A library package represents a dependency library, such as openssl or zlib, installed from source or a pre-built binary. Its configuration file is located in the `config/pkg/lib/` directory. Optional recipe classes are normally placed in `src/Package/Library/`, registered with `#[Library]`, and receive a `LibraryPackage` through callback context; they do not need to inherit from it.
 
 Taking openssl as an example:
 
@@ -161,22 +164,27 @@ Allowed fields for `library`:
 
   # ── Common Fields ─────────────────────────────────────────────────────────
   description: '..'       # Optional, human-readable package description
-  license: MIT            # Optional, SPDX license identifier (for license export)
+  license:                # Optional, license material copied after a source build
+    type: file            # type is file or text; a list of entries is also accepted
+    path: LICENSE
   lang: c                 # Optional, implementation language of the library (c / c++ etc.)
   frameworks: []          # Optional, list of related framework tags
 
-  artifact: '{artifact-name}'  # Required; when a string, references an Artifact definition
-                               # with the same name; when an object, is an inline Artifact
+  artifact: '{artifact-name}'  # Required; when a string, references the named Artifact definition;
+                               # when an object, it is an inline Artifact
 
-  # depends / suggests support @windows / @unix / @linux / @macos suffixes
+  # depends / suggests / tools support @windows / @unix / @linux / @macos suffixes
   depends: []             # Optional, hard dependency list (library names or PHP extension names with ext- prefix)
   depends@unix: []
   depends@windows: []
   suggests: []            # Optional, optional dependency list (same format as depends)
+  tools: []               # Optional, ToolPackage names required only while building
+  tools@windows: []
 
   # ── library / target Specific Fields ───────────────────────────────────────
   # The following fields are used to verify that artifacts have been correctly
-  # installed after the build. They support @unix / @windows / @linux / @macos suffixes.
+  # installed after the build. headers, static-libs, and static-bins support
+  # @unix / @windows / @linux / @macos suffixes.
 
   # Verify that specified header files or directories exist under buildroot/include/
   # Relative paths are based on buildroot/include/, absolute paths are used directly
@@ -231,17 +239,49 @@ The following path placeholders are supported in string values of the `path`, `e
 | `{source_path}` | Extracted source directory (`source/`) |
 | `{spc_msys2_path}` | MSYS2 root directory (`msys64/`) — Windows only |
 
+## tool Package Type
+
+A `tool` package represents an executable needed while building another package, rather than a library linked into the final target. Tool packages may use a pre-built binary or build from source, and install under `pkgroot/` by default, using either a shared `bin/` directory or a configured subdirectory. Packages request them through the top-level `tools` field; this dependency set is resolved independently of `depends` and `suggests`.
+
+```yaml
+nasm:
+  type: tool
+  artifact:
+    binary:
+      windows-x86_64:
+        type: url
+        url: 'https://example.com/nasm-win64.zip'
+        extract:
+          nasm.exe: '{pkg_root_path}/bin/nasm.exe'
+          ndisasm.exe: '{pkg_root_path}/bin/ndisasm.exe'
+  tool:
+    provides: [nasm.exe, ndisasm.exe]
+    binary-subdir: bin
+    min-version: '2.16'
+```
+
+The nested `tool` object supports:
+
+| Field | Required | Meaning |
+|---|---|---|
+| `provides` | Yes | Executable filenames used to decide whether the tool is installed |
+| `binary-subdir` | No | Directory below `install-root` containing the executables; defaults to the install root |
+| `install-root` | No | Installation root; defaults to `PKG_ROOT_PATH` and supports path placeholders |
+| `min-version` | No | Declared minimum version metadata exposed by `ToolPackage`; the installer does not currently enforce it |
+
+Fields inside `tool` may use `@windows`, `@unix`, `@linux`, and `@macos` suffixes. For example, `provides@windows` can list `.exe` names while `provides@unix` lists Unix names.
+
 ## target Package Type
 
-A `target` package represents a final build artifact. It inherits from `library`, so it includes all definition fields of `library`. The configuration file for `target` packages is located in the `config/pkg/target/` directory, and its build class inherits from `TargetPackage` in the `src/Package/Target/` directory.
+A `target` package represents a final build artifact. It inherits from `library`, so it includes all definition fields of `library`. Its configuration file is located in `config/pkg/target/`. Optional recipe classes are normally placed in `src/Package/Target/`, registered with `#[Target]`, and receive a `TargetPackage`; inheriting from `TargetPackage` is optional.
 
 The only difference from `library` is that a `target` package can be registered as a build target and automatically registers the build command `spc build:{target-name}`.
 
 ## virtual-target Package Type
 
-Unlike `target`, a `virtual-target` may not include an `artifact`, 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 `virtual-target` is located in the `config/pkg/target/` directory, and its build class inherits from `TargetPackage` in the `src/Package/Target/` directory. Its definition is essentially the same as `target`, but the `artifact` field is optional and typically not set. `virtual-target` is primarily used in the following scenarios:
+Unlike `target`, a `virtual-target` may omit `artifact`, 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. Its configuration and optional recipe classes use the same directories and `#[Target]` registration mechanism as `target`. Its definition is otherwise essentially the same, but the `artifact` field is optional and typically not set. `virtual-target` is primarily used in the following scenarios:
 
 - Defining an abstract build target for other packages to depend on, without directly corresponding to a buildable entity.
 - Serving as a common dependency for multiple `target` packages, simplifying dependency management.
 
-A typical example is the `php-cli`, `php-fpm` build targets for PHP. They have no independent source code and depend on `php-src`, with the final build outcome (CLI or FPM binary) determined through build scheduling.
+Typical examples are the `php-cli` and `php-fpm` build targets. They have no independent source and depend on the `php` target, whose Artifact is `php-src`; build scheduling determines whether the CLI or FPM binary is produced.

docs/zh/develop/package-model.md

@@ -1,20 +1,18 @@
 # Package 模型
 
-<!-- TODO: 统一 Package 模型说明：library / php-extension / target 类型。
-  config/pkg/ 下 per-package YAML 格式、depends 字段、平台覆盖（@windows / @unix 写法）。
-  artifact.source 和 artifact.binary 字段。附注释的 library 和 extension YAML 示例。 -->
 ## Package 定义
 
 Package 是 StaticPHP 构建系统中的核心概念，代表一个可构建/可安装的单元，如 PHP 扩展、库、构建目标等。
 
-每个 Package 包含构建信息、依赖关系、构建逻辑等，构成了 StaticPHP 的构建模型。Package 的定义主要通过 YAML/JSON 配置文件来实现。`core` 注册表的包配置文件位于 `config/pkg/` 目录下，对应的构建类位于 `src/Package/` 目录下。
+每个 Package 包含构建信息、依赖关系、构建逻辑等，构成了 StaticPHP 的构建模型。Package 的定义主要通过 YAML/JSON 配置文件来实现。`core` Registry 的 Package 配置位于 `config/pkg/` 目录下，可选 recipe class 位于 `src/Package/` 对应的子目录中。
 
-Package 主要分为四种类型：
+Package 分为五种类型：
 
 - **php-extension**：PHP 扩展包，包含 PHP 扩展的构建信息和构建逻辑。
-- **library**：库包，包含构建工具链、依赖库等的构建信息和构建逻辑。
+- **library**：依赖库 Package，通常安装到 `buildroot/`，供其他 Package 编译和链接。
 - **target**：构建目标包，代表最终的构建产物，如 PHP 二进制、curl 二进制等，继承自 `library` 包类型。
 - **virtual-target**：虚构建目标包，代表一个抽象的构建目标，不直接对应构建产物，主要用于依赖管理和构建调度。
+- **tool**：宿主机侧构建工具 Package，单独安装在 `pkgroot/` 下，不作为链接期库依赖处理。
 
 ```yaml
 {pkg-name}:
@@ -24,7 +22,7 @@ Package 主要分为四种类型：
 
 ## Artifact 定义
 
-Artifact 是独立于 Package 的定义，它包含构建包的源码归档文件或预构建的二进制文件。每个 Artifact 定义了下载 URL、解压方式、构建产物的文件路径等信息。Package 可以通过 `artifact` 字段引用一个或多个 Artifact 来获取构建所需的源码或二进制文件。
+Artifact 是独立于 Package 的定义，它包含构建包的源码归档文件或预构建的二进制文件。每个 Artifact 定义了下载 URL、解压方式、构建产物的文件路径等信息。一个 Package 可以通过 `artifact` 字段引用一个 Artifact，以获取构建所需的源码或二进制文件。
 
 简单来说，默认情况下，一个 Package 对应一个 Artifact；如果多个 Package 共用一份源码时，可以定义一个 Artifact 供多个 Package 引用。Artifact 的定义位于 `config/artifact/` 目录下，对应的自定义下载/解压逻辑类位于 `src/Package/Artifact/` 目录下；对于虚拟目标、PHP 内置扩展等特殊包类型，Package 也可以不设置 Artifact 字段。
 
@@ -43,7 +41,7 @@ example-library-package:
 
 ## php-extension 包类型
 
-php-extension 一个包代表一个 PHP 扩展，它的配置文件位于 `config/pkg/ext/` 目录下，构建类继承自 `PhpExtensionPackage`，位于 `src/Package/Extension/` 目录下。PHP 扩展包的配置文件包含扩展名称、版本、依赖关系、构建选项等信息。
+php-extension Package 代表一个 PHP 扩展，它的配置文件位于 `config/pkg/ext/` 目录下。可选的 recipe class 通常放在 `src/Package/Extension/`，通过 `#[Extension]` 注册，并从 callback context 接收对应的 `PhpExtensionPackage`。当前 core recipe 支持继承 `PhpExtensionPackage`，但并不要求继承。
 
 ```yaml
 ext-lz4:
@@ -60,7 +58,7 @@ ext-lz4:
   depends:
     - liblz4
   php-extension:
-    arg-type@unix: '--enable-lz4=@shared_suffix@ --with-lz4-includedir=@build_root_path@'
+    arg-type@unix: '--enable-lz4@shared_suffix@ --with-lz4-includedir=@build_root_path@'
     arg-type@windows: '--enable-lz4'
 ```
 
@@ -75,15 +73,17 @@ ext-{ext-name}:          # 包名必须以 ext- 前缀开头
   lang: c                # 可选，扩展的实现语言（c / c++ 等）
   frameworks: []         # 可选，相关macOS框架依赖列表
 
-  artifact: '{artifact-name}'  # 可选；字符串时引用同名 Artifact 定义，
+  artifact: '{artifact-name}'  # 可选；字符串时引用指定名称的 Artifact 定义，
                                # 对象时为内联 Artifact（内置扩展无需此字段）
 
-  # depends / suggests 支持 @windows / @unix / @linux / @macos 后缀
+  # depends / suggests / tools 支持 @windows / @unix / @linux / @macos 后缀
   depends: []            # 可选，硬依赖列表（库名直接写，PHP 扩展需加 ext- 前缀）
   depends@unix: []       # 可选，仅 Unix 平台生效的硬依赖
   depends@windows: []    # 可选，仅 Windows 平台生效的硬依赖
   suggests: []           # 可选，可选依赖列表（格式同 depends）
   suggests@unix: []
+  tools: []              # 可选，宿主机侧构建工具依赖，单独解析
+  tools@windows: []      # 可选，特定平台的工具依赖
 
   # ── php-extension 专属字段（嵌套在 php-extension: 对象中）─────────────────
   php-extension:
@@ -101,7 +101,7 @@ ext-{ext-name}:          # 包名必须以 ext- 前缀开头
     #   @shared_suffix@     → 共享构建时展开为 =shared，静态构建时为空
     #   @shared_path_suffix@ → 共享构建时展开为 =shared,{buildroot}，静态构建时为 ={buildroot}
     arg-type: enable
-    arg-type@unix: '--enable-{extname}=@shared_suffix@'
+    arg-type@unix: '--enable-my-extension@shared_suffix@'
     arg-type@windows: with-path
 
     zend-extension: false  # 可选，true 表示这是 Zend 扩展（如 opcache、xdebug）
@@ -120,7 +120,7 @@ ext-{ext-name}:          # 包名必须以 ext- 前缀开头
 
 ## library 包类型
 
-library 包代表一个需要从源码编译的依赖库（如 openssl、zlib 等），其配置文件位于 `config/pkg/lib/` 目录下，构建类继承自 `LibraryPackage`，位于 `src/Package/Library/` 目录下。
+library Package 代表 openssl、zlib 等依赖库，可以从源码或预构建二进制安装。其配置文件位于 `config/pkg/lib/` 目录下。可选的 recipe class 通常放在 `src/Package/Library/`，通过 `#[Library]` 注册，并从 callback context 接收 `LibraryPackage`；不要求继承该类。
 
 以 openssl 为例：
 
@@ -160,20 +160,25 @@ openssl:
 
   # ── 通用字段 ─────────────────────────────────────────────────────────────
   description: '...'     # 可选，人类可读的包描述
-  license: MIT           # 可选，SPDX 许可证标识符（用于许可证导出）
+  license:               # 可选，从源码构建后复制的许可证内容
+    type: file           # type 可为 file 或 text，也可填写多个条目的列表
+    path: LICENSE
   lang: c                # 可选，库的实现语言（c / c++ 等）
   frameworks: []         # 可选，相关框架标签列表
 
-  artifact: '{artifact-name}'  # 必填；字符串时引用同名 Artifact 定义，对象时为内联 Artifact
+  artifact: '{artifact-name}'  # 必填；字符串时引用指定名称的 Artifact 定义，对象时为内联 Artifact
 
-  # depends / suggests 支持 @windows / @unix / @linux / @macos 后缀
+  # depends / suggests / tools 支持 @windows / @unix / @linux / @macos 后缀
   depends: []            # 可选，硬依赖列表（库名或 ext- 前缀的 PHP 扩展名）
   depends@unix: []
   depends@windows: []
   suggests: []           # 可选，可选依赖列表（格式同 depends）
+  tools: []              # 可选，仅构建时需要的 ToolPackage 名称
+  tools@windows: []
 
   # ── library / target 专属字段 ────────────────────────────────────────────
-  # 以下字段用于构建完成后验证产物是否已正确安装，支持 @unix / @windows / @linux / @macos 后缀
+  # 以下字段用于构建完成后验证产物是否已正确安装；headers、static-libs、static-bins
+  # 支持 @unix / @windows / @linux / @macos 后缀
 
   # 验证 buildroot/include/ 下是否存在指定头文件或目录
   # 相对路径基于 buildroot/include/，绝对路径直接使用
@@ -225,17 +230,49 @@ openssl:
 | `{source_path}` | 解压源码目录（`source/`） |
 | `{spc_msys2_path}` | MSYS2 根目录（`msys64/`）——仅 Windows |
 
+## tool 包类型
+
+`tool` Package 表示构建其他 Package 时需要的可执行工具，而不是链接进最终 target 的库。Tool Package 可以使用预构建二进制，也可以从源码构建，默认安装在 `pkgroot/` 下的共享 `bin/` 或配置的子目录。其他 Package 通过顶层 `tools` 字段请求这些工具；该依赖集合与 `depends`、`suggests` 分开解析。
+
+```yaml
+nasm:
+  type: tool
+  artifact:
+    binary:
+      windows-x86_64:
+        type: url
+        url: 'https://example.com/nasm-win64.zip'
+        extract:
+          nasm.exe: '{pkg_root_path}/bin/nasm.exe'
+          ndisasm.exe: '{pkg_root_path}/bin/ndisasm.exe'
+  tool:
+    provides: [nasm.exe, ndisasm.exe]
+    binary-subdir: bin
+    min-version: '2.16'
+```
+
+嵌套的 `tool` 对象支持：
+
+| 字段 | 是否必填 | 含义 |
+|---|---|---|
+| `provides` | 是 | 用于判断工具是否已经安装的可执行文件名 |
+| `binary-subdir` | 否 | `install-root` 下存放可执行文件的目录；默认就是安装根目录 |
+| `install-root` | 否 | 安装根目录；默认为 `PKG_ROOT_PATH`，支持路径占位符 |
+| `min-version` | 否 | 由 `ToolPackage` 暴露的最低版本元数据；installer 当前不会强制校验 |
+
+`tool` 内的字段可以使用 `@windows`、`@unix`、`@linux` 和 `@macos` 后缀。例如，`provides@windows` 可以列出 `.exe` 名称，`provides@unix` 列出 Unix 名称。
+
 ## target 包类型
 
-`target` 包代表一个最终的构建产物，它继承于 `library`，所以包含 `library` 的所有定义字段。`target` 包的配置文件位于 `config/pkg/target/` 目录下，构建类继承自 `TargetPackage`，位于 `src/Package/Target/` 目录下。
+`target` Package 代表一个最终的构建产物，它继承于 `library`，所以包含 `library` 的所有定义字段。其配置文件位于 `config/pkg/target/`。可选的 recipe class 通常放在 `src/Package/Target/`，通过 `#[Target]` 注册，并接收 `TargetPackage`；是否继承 `TargetPackage` 是可选的。
 
 与 `library` 的唯一区别是，`target` 包可以注册成为构建目标，且自动注册构建命令 `spc build:{target-name}`。
 
 ## virtual-target 包类型
 
-与 `target` 不同的是，`virtual-target` 可以不包含 `artifact`，即不直接对应一个可构建的实体，而是一个抽象的构建目标，主要用于依赖管理和构建调度。`virtual-target` 的配置文件位于 `config/pkg/target/` 目录下，构建类继承自 `TargetPackage`，位于 `src/Package/Target/` 目录下。它的定义与 `target` 基本相同，但 `artifact` 字段可选且通常不设置。`virtual-target` 主要用于以下场景：
+与 `target` 不同，`virtual-target` 可以省略 `artifact`，即不直接对应一个可构建的实体，而是用于依赖管理和构建调度的抽象构建目标。它与 `target` 使用相同的配置目录、可选 recipe class 目录和 `#[Target]` 注册方式。其余定义基本相同，但 `artifact` 字段可选且通常不设置。`virtual-target` 主要用于以下场景：
 
 - 定义一个抽象的构建目标，供其他包依赖，但不直接对应一个可构建的实体。
 - 作为多个 `target` 包的公共依赖，简化依赖关系管理。
 
-典型例子就是 PHP 包的 `php-cli`、`php-fpm` 等构建目标，他们没有独立的源码，依赖于 `php-src`，通过构建调度来决定最终构建成 CLI 还是 FPM 二进制。
+典型例子是 `php-cli` 和 `php-fpm` 构建目标。它们没有独立源码，依赖 Artifact 为 `php-src` 的 `php` target；构建调度会决定最终生成 CLI 还是 FPM 二进制。

package.json

@@ -2,12 +2,12 @@
   "scripts": {
     "docs:dev": "node docs/.vitepress/gen-meta.js && vitepress dev docs",
     "docs:gen-meta": "node docs/.vitepress/gen-meta.js",
-    "docs:build": "npm run docs:gen-meta && vitepress build docs",
+    "docs:build": "node docs/.vitepress/gen-meta.js && vitepress build docs",
     "docs:preview": "vitepress preview docs"
   },
   "devDependencies": {
     "mermaid": "^11.0.0",
-    "vitepress": "^2.0.0-alpha.5",
+    "vitepress": "2.0.0-alpha.18",
     "vue": "^3.2.47"
   }
 }

src/Package/Artifact/gmssl.php

@@ -17,4 +17,11 @@ class gmssl
         FileSystem::replaceFileStr($target_path . '/src/hex.c', 'unsigned char *OPENSSL_hexstr2buf(const char *str, size_t *len)', 'unsigned char *GMSSL_hexstr2buf(const char *str, size_t *len)');
         FileSystem::replaceFileStr($target_path . '/src/hex.c', 'OPENSSL_hexchar2int', 'GMSSL_hexchar2int');
     }
+
+    #[AfterSourceExtract('ext-gmssl')]
+    #[PatchDescription('Rename pbkdf2_hmac_sm3_genkey() to sm3_pbkdf2() (renamed upstream in GmSSL 3.2+; identical signature)')]
+    public function patchExt(string $target_path): void
+    {
+        FileSystem::replaceFileStr($target_path . '/gmssl.c', 'pbkdf2_hmac_sm3_genkey(', 'sm3_pbkdf2(');
+    }
 }

src/Package/Artifact/go_xcaddy.php

@@ -25,7 +25,6 @@ class go_xcaddy
     ])]
     public function downBinary(ArtifactDownloader $downloader): DownloadResult
     {
-        $pkgroot = PKG_ROOT_PATH;
         $name = SystemTarget::getCurrentPlatformString();
         $arch = match (explode('-', $name)[1]) {
             'x86_64' => 'amd64',
@@ -64,7 +63,7 @@ class go_xcaddy
         if ($file_hash !== $hash) {
             throw new DownloaderException("Hash mismatch for downloaded go-xcaddy binary. Expected {$hash}, got {$file_hash}");
         }
-        return DownloadResult::archive(basename($path), ['url' => $url, 'version' => $version], extract: "{$pkgroot}/go-xcaddy", verified: true, version: $version);
+        return DownloadResult::archive(basename($path), ['url' => $url, 'version' => $version], extract: '{pkg_root_path}/go-xcaddy', verified: true, version: $version);
     }
 
     #[CustomBinaryCheckUpdate('go-xcaddy', [
@@ -109,7 +108,7 @@ class go_xcaddy
             'GOROOT' => "{$target_path}",
             'GOBIN' => "{$target_path}/bin",
             'GOPATH' => "{$target_path}/go",
-        ])->exec('CC=cc go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest');
+        ])->exec('CGO_ENABLED=0 go install github.com/caddyserver/xcaddy/cmd/xcaddy@master');
         GlobalEnvManager::addPathIfNotExists("{$target_path}/bin");
     }
 }

src/Package/Library/bzip2.php

@@ -17,7 +17,9 @@ class bzip2
     #[PatchBeforeBuild]
     public function patchBeforeBuild(LibraryPackage $lib): void
     {
-        FileSystem::replaceFileStr($lib->getSourceDir() . '/Makefile', 'CFLAGS=-Wall', 'CFLAGS=-fPIC -Wall');
+        // Inject SPC_DEFAULT_CFLAGS into the Makefile
+        $extra = deduplicate_flags(trim((string) getenv('SPC_DEFAULT_CFLAGS')) . ' -Wall');
+        FileSystem::replaceFileStr($lib->getSourceDir() . '/Makefile', 'CFLAGS=-Wall', "CFLAGS={$extra}");
     }
 
     #[BuildFor('Windows')]

src/Package/Library/fastlz.php

@@ -18,9 +18,11 @@ class fastlz
     {
         $cc = getenv('CC') ?: 'cc';
         $ar = getenv('AR') ?: 'ar';
+        $extra = trim((string) getenv('SPC_DEFAULT_CFLAGS'));
+        $extra = $extra !== '' ? $extra . ' -fPIC' : '-O3 -fPIC';
 
         shell()->cd($lib->getSourceDir())->initializeEnv($lib)
-            ->exec("{$cc} -c -O3 -fPIC fastlz.c -o fastlz.o")
+            ->exec("{$cc} -c {$extra} fastlz.c -o fastlz.o")
             ->exec("{$ar} rcs libfastlz.a fastlz.o");
 
         // Copy header file

src/Package/Library/icu.php

@@ -24,9 +24,12 @@ class icu
     #[BuildFor('Linux')]
     public function buildLinux(LibraryPackage $lib, ToolchainInterface $toolchain, PackageBuilder $builder): void
     {
+        // runConfigureICU bakes CXXFLAGS/LDFLAGS, apply user flags too
+        $userCxxFlags = trim((string) getenv('SPC_DEFAULT_CXXFLAGS'));
+        $userLdFlags = trim((string) getenv('SPC_DEFAULT_LDFLAGS'));
         $cppflags = 'CPPFLAGS="-DU_CHARSET_IS_UTF8=1  -DU_USING_ICU_NAMESPACE=1 -DU_STATIC_IMPLEMENTATION=1 -DPIC -fPIC"';
-        $cxxflags = 'CXXFLAGS="-std=c++17 -DPIC -fPIC -fno-ident"';
-        $ldflags = $toolchain->isStatic() ? 'LDFLAGS="-static"' : '';
+        $cxxflags = "CXXFLAGS=\"-std=c++17 -DPIC -fPIC -fno-ident {$userCxxFlags}\"";
+        $ldflags = $toolchain->isStatic() ? "LDFLAGS=\"-static {$userLdFlags}\"" : "LDFLAGS=\"{$userLdFlags}\"";
         shell()->cd($lib->getSourceDir() . '/source')->initializeEnv($lib)
             ->exec(
                 "{$cppflags} {$cxxflags} {$ldflags} " .

src/Package/Library/jbig.php

@@ -17,7 +17,9 @@ class jbig
     #[PatchBeforeBuild]
     public function patchBeforeBuild(LibraryPackage $lib): void
     {
-        FileSystem::replaceFileStr($lib->getSourceDir() . '/Makefile', 'CFLAGS = -O2 -W -Wno-unused-result', 'CFLAGS = -O2 -W -Wno-unused-result -fPIC');
+        $extra = trim((string) getenv('SPC_DEFAULT_CFLAGS'));
+        $cflags = ($extra !== '' ? $extra : '-O2') . ' -W -Wno-unused-result -fPIC';
+        FileSystem::replaceFileStr($lib->getSourceDir() . '/Makefile', 'CFLAGS = -O2 -W -Wno-unused-result', "CFLAGS = {$cflags}");
     }
 
     #[BuildFor('Darwin')]

src/Package/Library/libaom.php

@@ -9,8 +9,10 @@ use StaticPHP\Attribute\Package\Library;
 use StaticPHP\Package\LibraryPackage;
 use StaticPHP\Runtime\Executor\UnixCMakeExecutor;
 use StaticPHP\Runtime\Executor\WindowsCMakeExecutor;
+use StaticPHP\Runtime\SystemTarget;
 use StaticPHP\Toolchain\Interface\ToolchainInterface;
 use StaticPHP\Toolchain\ZigToolchain;
+use StaticPHP\Util\System\UnixUtil;
 
 #[Library('libaom')]
 class libaom extends LibraryPackage
@@ -39,9 +41,27 @@ class libaom extends LibraryPackage
             $new = trim($extra . ' -D_GNU_SOURCE');
             f_putenv("SPC_COMPILER_EXTRA={$new}");
         }
+        $targetCpu = SystemTarget::getTargetArch();
+        if (str_starts_with($targetCpu, 'aarch')) {
+            $targetCpu = str_replace('aarch', 'arm', $targetCpu);
+        }
+        if (
+            in_array($targetCpu, ['x86', 'x86_64'], true)
+            && !UnixUtil::findCommand('nasm')
+            && !UnixUtil::findCommand('yasm')
+        ) {
+            $targetCpu = 'generic';
+        }
         UnixCMakeExecutor::create($this)
             ->setBuildDir("{$this->getSourceDir()}/builddir")
-            ->addConfigureArgs('-DAOM_TARGET_CPU=generic')
+            ->addConfigureArgs(
+                "-DAOM_TARGET_CPU={$targetCpu}",
+                '-DCONFIG_RUNTIME_CPU_DETECT=1',
+                '-DENABLE_EXAMPLES=OFF',
+                '-DENABLE_TESTS=OFF',
+                '-DENABLE_TOOLS=OFF',
+                '-DENABLE_DOCS=OFF',
+            )
             ->build();
         f_putenv("SPC_COMPILER_EXTRA={$extra}");
         $this->patchPkgconfPrefix(['aom.pc']);

src/Package/Library/libffi.php

@@ -8,6 +8,7 @@ use StaticPHP\Attribute\Package\BuildFor;
 use StaticPHP\Attribute\Package\Library;
 use StaticPHP\Package\LibraryPackage;
 use StaticPHP\Runtime\Executor\UnixAutoconfExecutor;
+use StaticPHP\Runtime\SystemTarget;
 
 #[Library('libffi')]
 class libffi extends LibraryPackage
@@ -28,7 +29,7 @@ class libffi extends LibraryPackage
     #[BuildFor('Darwin')]
     public function buildDarwin(): void
     {
-        $arch = getenv('SPC_ARCH');
+        $arch = SystemTarget::getTargetArch();
         UnixAutoconfExecutor::create($this)
             ->configure(
                 "--host={$arch}-apple-darwin",

src/Package/Library/libheif.php

@@ -24,6 +24,17 @@ class libheif
                 'list(APPEND REQUIRES_PRIVATE "libbrotlidec")' . "\n" . '        list(APPEND REQUIRES_PRIVATE "libbrotlienc")'
             );
         }
+        // libheif 1.22+ ships a C-incompatible header: `struct heif_bad_pixel`
+        $heif_properties = $lib->getSourceDir() . '/libheif/api/libheif/heif_properties.h';
+        if (file_exists($heif_properties)
+            && str_contains(file_get_contents($heif_properties), 'struct heif_bad_pixel { uint32_t row; uint32_t column; };')
+        ) {
+            FileSystem::replaceFileStr(
+                $heif_properties,
+                'struct heif_bad_pixel { uint32_t row; uint32_t column; };',
+                'typedef struct heif_bad_pixel { uint32_t row; uint32_t column; } heif_bad_pixel;'
+            );
+        }
     }
 
     #[BuildFor('Darwin')]

src/Package/Library/ncurses.php

@@ -6,6 +6,8 @@ namespace Package\Library;
 
 use StaticPHP\Attribute\Package\BuildFor;
 use StaticPHP\Attribute\Package\Library;
+use StaticPHP\Attribute\Package\PatchBeforeBuild;
+use StaticPHP\Attribute\PatchDescription;
 use StaticPHP\Package\LibraryPackage;
 use StaticPHP\Runtime\Executor\UnixAutoconfExecutor;
 use StaticPHP\Toolchain\Interface\ToolchainInterface;
@@ -16,6 +18,24 @@ use StaticPHP\Util\FileSystem;
 #[Library('ncursesw')]
 class ncurses
 {
+    #[PatchBeforeBuild]
+    #[PatchDescription('Filter clang/zig "N warning(s) generated." line out of MKlib_gen.sh preprocessor pipe')]
+    public function patchBeforeBuild(LibraryPackage $lib): void
+    {
+        // MKlib_gen.sh feeds the C preprocessor's stdout through a sed/awk
+        // pipeline into lib_gen.c. zig-cc/clang emits "N warning(s) generated."
+        // on stdout (not stderr), and that line ends up as invalid C in the
+        // generated source. Filter it out of the pipe before sed sees it.
+        $mklibGen = $lib->getSourceDir() . '/ncurses/base/MKlib_gen.sh';
+        if (is_file($mklibGen) && !str_contains((string) file_get_contents($mklibGen), "| grep -v ' generated")) {
+            FileSystem::replaceFileStr(
+                $mklibGen,
+                '$preprocessor $TMP 2>/dev/null \\',
+                "\$preprocessor \$TMP 2>/dev/null \\\n| grep -v ' generated\\.\$' \\",
+            );
+        }
+    }
+
     #[BuildFor('Darwin')]
     #[BuildFor('Linux')]
     public function build(LibraryPackage $package, ToolchainInterface $toolchain): void
@@ -45,6 +65,7 @@ class ncurses
             '--without-tests',
             '--without-dlsym',
             '--without-debug',
+            '--disable-stripping',
             '--enable-symlinks',
             "--with-terminfo-dirs={$terminfo_dirs}",
             "--bindir={$package->getBinDir()}",

src/Package/Library/openssl.php

@@ -11,6 +11,7 @@ use StaticPHP\Package\LibraryPackage;
 use StaticPHP\Package\PackageBuilder;
 use StaticPHP\Package\ToolPackage;
 use StaticPHP\Registry\PackageLoader;
+use StaticPHP\Runtime\SystemTarget;
 use StaticPHP\Util\FileSystem;
 use StaticPHP\Util\System\LinuxUtil;
 
@@ -57,7 +58,11 @@ class openssl
     public function buildForDarwin(LibraryPackage $pkg): void
     {
         $zlib_libs = $pkg->getInstaller()->getLibraryPackage('zlib')->getStaticLibFiles();
-        $arch = getenv('SPC_ARCH');
+        $targetArch = SystemTarget::getTargetArch();
+        $arch = match ($targetArch) {
+            'aarch64' => 'arm64',
+            default => $targetArch,
+        };
 
         shell()->cd($pkg->getSourceDir())->initializeEnv($pkg)
             ->exec(
@@ -76,12 +81,7 @@ class openssl
     #[BuildFor('Linux')]
     public function build(LibraryPackage $lib): void
     {
-        $arch = getenv('SPC_ARCH');
-
-        $env = "CC='" . getenv('CC') . ' -idirafter ' . BUILD_INCLUDE_PATH .
-            ' -idirafter /usr/include/ ' .
-            ' -idirafter /usr/include/' . getenv('SPC_ARCH') . '-linux-gnu/ ' .
-            "' ";
+        $arch = SystemTarget::getTargetArch();
 
         $ex_lib = trim($lib->getInstaller()->getLibraryPackage('zlib')->getStaticLibFiles()) . ' -ldl -pthread';
         $zlib_extra =
@@ -92,9 +92,15 @@ class openssl
         $openssl_dir ??= LinuxUtil::getOSRelease()['dist'] === 'redhat' ? '/etc/pki/tls' : '/etc/ssl';
         $ex_lib = trim($ex_lib);
 
+        // anything we want included (PGO -fprofile-*, LTO, custom hardening)
+        // has to be appended on the command line *after* the target name.
+        $userCFlags = trim((string) getenv('SPC_DEFAULT_CFLAGS'));
+        $userLdFlags = trim((string) getenv('SPC_DEFAULT_LDFLAGS'));
+        $userExtra = trim($userCFlags . ' ' . $userLdFlags);
+
         shell()->cd($lib->getSourceDir())->initializeEnv($lib)
             ->exec(
-                "{$env} ./Configure no-shared zlib " .
+                './Configure no-shared zlib ' .
                 "--prefix={$lib->getBuildRootPath()} " .
                 "--libdir={$lib->getLibDir()} " .
                 "--openssldir={$openssl_dir} " .
@@ -102,7 +108,8 @@ class openssl
                 'enable-pie ' .
                 'no-legacy ' .
                 'no-tests ' .
-                "linux-{$arch}"
+                "linux-{$arch} " .
+                $userExtra
             )
             ->exec('make clean')
             ->exec("make -j{$lib->getBuilder()->concurrency} CNF_EX_LIBS=\"{$ex_lib}\"")

src/StaticPHP/Artifact/Downloader/Type/GitHubTokenSetupTrait.php

@@ -14,17 +14,18 @@ trait GitHubTokenSetupTrait
     public static function getGitHubTokenHeadersStatic(): array
     {
         // GITHUB_TOKEN support
-        if (($token = getenv('GITHUB_TOKEN')) !== false && ($user = getenv('GITHUB_USER')) !== false) {
+        $token = getenv('GITHUB_TOKEN');
+        if ($token === false || $token === '') {
+            return [];
+        }
+        if (($user = getenv('GITHUB_USER')) !== false && $user !== '') {
             logger()->debug("Using 'GITHUB_TOKEN' with user {$user} for authentication");
             $encoded = base64_encode("{$user}:{$token}");
             spc_add_log_filter([$user, $token, $encoded]);
             return ["Authorization: Basic {$encoded}"];
         }
-        if (($token = getenv('GITHUB_TOKEN')) !== false) {
-            logger()->debug("Using 'GITHUB_TOKEN' for authentication");
-            spc_add_log_filter($token);
-            return ["Authorization: Bearer {$token}"];
-        }
-        return [];
+        logger()->debug("Using 'GITHUB_TOKEN' for authentication");
+        spc_add_log_filter($token);
+        return ["Authorization: Bearer {$token}"];
     }
 }

src/StaticPHP/Doctor/Item/LinuxMuslCheck.php

@@ -1,115 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace StaticPHP\Doctor\Item;
-
-use StaticPHP\Artifact\ArtifactCache;
-use StaticPHP\Artifact\ArtifactDownloader;
-use StaticPHP\Artifact\ArtifactExtractor;
-use StaticPHP\Attribute\Doctor\CheckItem;
-use StaticPHP\Attribute\Doctor\FixItem;
-use StaticPHP\Attribute\Doctor\OptionalCheck;
-use StaticPHP\DI\ApplicationContext;
-use StaticPHP\Doctor\CheckResult;
-use StaticPHP\Runtime\Shell\Shell;
-use StaticPHP\Toolchain\Interface\ToolchainInterface;
-use StaticPHP\Toolchain\MuslToolchain;
-use StaticPHP\Toolchain\ZigToolchain;
-use StaticPHP\Util\FileSystem;
-use StaticPHP\Util\InteractiveTerm;
-use StaticPHP\Util\SourcePatcher;
-use StaticPHP\Util\System\LinuxUtil;
-
-#[OptionalCheck([self::class, 'optionalCheck'])]
-class LinuxMuslCheck
-{
-    public static function optionalCheck(): bool
-    {
-        $toolchain = ApplicationContext::get(ToolchainInterface::class);
-        return $toolchain instanceof MuslToolchain || $toolchain instanceof ZigToolchain && !LinuxUtil::isMuslDist() && !str_contains(getenv('SPC_TARGET') ?: '', 'gnu');
-    }
-
-    /** @noinspection PhpUnused */
-    #[CheckItem('if musl-wrapper is installed', limit_os: 'Linux', level: 800)]
-    public function checkMusl(): ?CheckResult
-    {
-        $musl_wrapper_lib = sprintf('/lib/ld-musl-%s.so.1', php_uname('m'));
-        if (file_exists($musl_wrapper_lib) && (file_exists('/usr/local/musl/lib/libc.a') || getenv('SPC_TOOLCHAIN') === ZigToolchain::class)) {
-            return null;
-        }
-        return CheckResult::fail('musl-wrapper is not installed on your system', 'fix-musl-wrapper');
-    }
-
-    #[CheckItem('if musl-cross-make is installed', limit_os: 'Linux', level: 799)]
-    public function checkMuslCrossMake(): ?CheckResult
-    {
-        if (getenv('SPC_TOOLCHAIN') === ZigToolchain::class && !LinuxUtil::isMuslDist()) {
-            return null;
-        }
-        $arch = arch2gnu(php_uname('m'));
-        $cross_compile_lib = "/usr/local/musl/{$arch}-linux-musl/lib/libc.a";
-        $cross_compile_gcc = "/usr/local/musl/bin/{$arch}-linux-musl-gcc";
-        if (file_exists($cross_compile_lib) && file_exists($cross_compile_gcc)) {
-            return CheckResult::ok();
-        }
-        return CheckResult::fail('musl-cross-make is not installed on your system', 'fix-musl-cross-make');
-    }
-
-    #[FixItem('fix-musl-wrapper')]
-    public function fixMusl(): bool
-    {
-        $downloader = new ArtifactDownloader(interactive: false);
-        $downloader->add('musl-wrapper')->download();
-        $extractor = new ArtifactExtractor(ApplicationContext::get(ArtifactCache::class));
-        $extractor->extract('musl-wrapper');
-
-        // Apply CVE-2025-26519 patch and install musl wrapper
-        SourcePatcher::patchFile('musl-1.2.5_CVE-2025-26519_0001.patch', SOURCE_PATH . '/musl-wrapper');
-        SourcePatcher::patchFile('musl-1.2.5_CVE-2025-26519_0002.patch', SOURCE_PATH . '/musl-wrapper');
-
-        $prefix = '';
-        if (get_current_user() !== 'root') {
-            $prefix = 'sudo ';
-            logger()->warning('Current user is not root, using sudo for running command');
-        }
-        $sysEnv = ['CC' => 'gcc', 'CXX' => 'g++', 'AR' => 'ar', 'LD' => 'ld', 'RANLIB' => 'ranlib'];
-        $envFlags = '';
-        foreach ($sysEnv as $k => $v) {
-            $envFlags .= "{$k}={$v} ";
-        }
-        $envFlags = rtrim($envFlags);
-        $shell = shell()->cd(SOURCE_PATH . '/musl-wrapper')
-            ->setEnv($sysEnv)
-            ->exec('./configure --disable-gcc-wrapper')
-            ->exec('make -j');
-        if ($prefix !== '') {
-            f_passthru('cd ' . SOURCE_PATH . "/musl-wrapper && {$envFlags} {$prefix}make install");
-        } else {
-            $shell->exec("{$prefix}make install");
-        }
-        return true;
-    }
-
-    #[FixItem('fix-musl-cross-make')]
-    public function fixMuslCrossMake(): bool
-    {
-        // sudo
-        $prefix = '';
-        if (get_current_user() !== 'root') {
-            $prefix = 'sudo ';
-            logger()->warning('Current user is not root, using sudo for running command');
-        }
-        Shell::passthruCallback(function () {
-            InteractiveTerm::advance();
-        });
-        $downloader = new ArtifactDownloader(interactive: false);
-        $extractor = new ArtifactExtractor(ApplicationContext::get(ArtifactCache::class));
-        $downloader->add('musl-toolchain')->download();
-        $extractor->extract('musl-toolchain');
-        $pkg_root = PKG_ROOT_PATH . '/musl-toolchain';
-        f_passthru("{$prefix}cp -rf {$pkg_root}/* /usr/local/musl");
-        FileSystem::removeDir($pkg_root);
-        return true;
-    }
-}

src/StaticPHP/Util/SourcePatcher.php

@@ -173,6 +173,9 @@ class SourcePatcher
      */
     public static function patchMicroPhar(int $version_id): void
     {
+        if (file_exists(SOURCE_PATH . '/php-src/ext/phar/phar.c.bak')) {
+            return;
+        }
         FileSystem::backupFile(SOURCE_PATH . '/php-src/ext/phar/phar.c');
         FileSystem::replaceFileStr(
             SOURCE_PATH . '/php-src/ext/phar/phar.c',
@@ -198,6 +201,12 @@ class SourcePatcher
 
     public static function unpatchMicroPhar(): void
     {
+        // Tolerate a missing .bak: both drivers call this, and the first restore
+        // consumes the backup. Without this guard the second call throws
+        // "Cannot find bak file". No .bak means the source is already pristine.
+        if (!file_exists(SOURCE_PATH . '/php-src/ext/phar/phar.c.bak')) {
+            return;
+        }
         FileSystem::restoreBackupFile(SOURCE_PATH . '/php-src/ext/phar/phar.c');
     }