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.
Packages are primarily divided into four 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.
- **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.
```yaml
{pkg-name}:
type: {pkg-type}
...
```
## 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.
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.
Assuming `example-library-package` is a dependency library whose source archive is hosted at `https://example.com/example-library.tar.gz`, its Package and Artifact definitions would look like this:
```yaml
example-library-package:
type: library
artifact:
source:
type: url
url: 'https://example.com/example-library.tar.gz'
```
For more on Artifact definitions, see the [Artifact Model](./artifact-model) chapter.
## 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.
zend-extension: false # Optional, true indicates this is a Zend extension (e.g., opcache, xdebug)
build-shared: true # Optional, whether building as a shared extension (.so) is allowed, default true
build-static: true # Optional, whether inline static building (compiled into PHP) is allowed, default true
build-with-php: true # Optional, true means the extension is built together via the PHP source tree
# (used for built-in extensions)
# display-name affects the php --ri argument in smoke tests and the license export display name
# If not set, defaults to the extension name (the part after ext-); if set to empty string, skips --ri check
display-name: 'My Extension'
# os restricts the extension to be available only on specified platforms;
# platforms not in the list will be rejected for building
# Allowed values: Linux, Darwin, Windows
os: [Linux, Darwin]
```
## 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.
Taking openssl as an example:
```yaml
openssl:
type: library
artifact:
source:
type: ghrel
repo: openssl/openssl
match: openssl.+\.tar\.gz
prefer-stable: true
binary: hosted
metadata:
license-files: [LICENSE.txt]
license: OpenSSL
depends:
- zlib
depends@windows:
- zlib
- jom
headers:
- openssl
static-libs@unix:
- libssl.a
- libcrypto.a
static-libs@windows:
- libssl.lib
- libcrypto.lib
```
Allowed fields for `library`:
```yaml
{lib-name}:
type: library # library or target (target inherits all fields from library)
# ── Common Fields ─────────────────────────────────────────────────────────
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.
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:
- 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.
