feat(docs): update package model documentation to include new package types and clarify definitions

2026-07-16 21:35:36 +08:00 · 2026-07-14 23:03:15 +08:00
parent abc6e3695f
commit 01a0b26a2a
2 changed files with 116 additions and 39 deletions
--- a/docs/en/develop/package-model.md
+++ b/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.