import{_ as i,c as a,o as e,aj as t}from"./chunks/framework.C2AwuPrQ.js";const c=JSON.parse('{"title":"Artifact Model","description":"","frontmatter":{"outline":"deep"},"headers":[],"relativePath":"en/develop/artifact-model.md","filePath":"en/develop/artifact-model.md"}'),l={name:"en/develop/artifact-model.md"};function n(h,s,r,p,o,d){return e(),a("div",null,[...s[0]||(s[0]=[t(`

Artifact Model ​

An Artifact is a core concept in the StaticPHP build system. It represents a source archive or pre-built binary required to build a package. Each artifact describes where to download the file, how to extract it, and the resulting path layout. Packages reference one or more artifacts via the artifact field to obtain the source code or binaries they need.

Defining an Artifact ​

Here is a minimal artifact object that points to a source archive (curl's source code):

yaml
&:
  source:
    type: ghrel
    repo: curl/curl
    match: curl.+\\.tar\\.xz
    prefer-stable: true

There are two ways to define an artifact and associate it with a package: inline (defined directly inside the package file) or standalone (defined in a separate file and referenced by name):

yaml
# This is a package declaration
curl:
  type: target
  artifact:
    source:
      type: ghrel
      repo: curl/curl
      match: curl.+\\.tar\\.xz
      prefer-stable: true
yaml
# This is a standalone artifact declaration, typically placed under config/artifact/
curl-src:
  source:
    type: ghrel
    repo: curl/curl
    match: curl.+\\.tar\\.xz
    prefer-stable: true
yaml
# This is a package declaration
curl:
  type: target
  artifact: curl-src

Structure ​

An artifact has three top-level sections: source, binary, and metadata.

Both source and binary accept either an inline source object or a reference to a standalone artifact by name (as shown above).

Full artifact object format:

yaml
&:
  source: {source-object} # (optional)
  binary:
    windows-x86_64: {source-object} # (optional)
    linux-x86_64: {source-object} # (optional)
    linux-aarch64: {source-object} # (optional)
    macos-x86_64: {source-object} # (optional)
    macos-aarch64: {source-object} # (optional)
  metadata: # (optional)
    license: "" # (optional) SPDX identifier
    license-files: ["LICENSE"] # License files from the source directory
    source-root: "subdir" # (optional) Use if the actual source root is inside a subdirectory

The basic format of a source-object:

yaml
&:
  type: "url" # Download type
  # ...: Additional keys depend on the type; see below
  extract: "path/to/dir" # (optional) Override extract path; default: SOURCE_PATH/{artifact-name}

Metadata ​

The metadata field provides supplementary information about an artifact. It supports three subfields:

license ​

yaml
metadata:
  license: MIT

license-files ​

The following built-in license files are currently available: bzip2.txt, gmp.txt, icu.txt, postgresql.txt, sqlite.txt, zlib.txt.

yaml
# Common case: read from the source directory
metadata:
  license-files: [LICENSE]

# Multiple license files
metadata:
  license-files: [LICENSE, COPYING.LESSER]

# License file inside a subdirectory
metadata:
  license-files: [gettext-runtime/intl/COPYING.LIB]

# Use a built-in license file when the source package does not include one
metadata:
  license-files: ['@/bzip2.txt']

source-root ​

yaml
# krb5's actual source root is in the src/ subdirectory after extraction
metadata:
  source-root: src

Download Types ​

Artifacts support a variety of download types. Choose the one that best fits where the package is hosted.

TypeDescription
urlDownload from a fixed URL. Supports filename (custom local filename) and version (manually set version).
gitClone from a Git repository. Supports rev (branch/tag/commit), submodules (fetch submodules), and extract.
ghrelDownload from GitHub Release Assets by regex match. Requires repo (owner/repo) and match (filename regex). Supports prefer-stable.
ghtarDownload the source tarball from a GitHub Release (/releases API), matching by release name with match. Supports prefer-stable.
ghtagtarDownload the source tarball from a GitHub Tag (/tags API), matching by tag name with match. Supports prefer-stable.
filelistScrape an HTML page for a file listing, extract the filename and version via regex, then download the matched file. Suitable for official download index pages (e.g. ftp.gnu.org, openssl.org).
peclDownload a PHP extension from PECL by name. Supports prefer-stable.
pieDownload a PHP extension from Packagist via the PIE spec. Requires repo (vendor/package).
php-releaseDownload official PHP source from php.net. The version is controlled by the --with-php build argument.
bitbuckettagDownload source tarball from the latest Bitbucket tag. Requires repo (workspace/repo).
localUse a pre-existing local directory as the source. Requires dirname. Useful for offline or development scenarios.
customFully custom download logic implemented in a PHP class under src/Package/Artifact/. Optionally calls a specific method via func.

Type Reference ​

url ​

Downloads a file from a fixed URL and extracts it automatically.

yaml
# sqlite downloaded from a fixed URL
artifact:
  source:
    type: url
    url: 'https://www.sqlite.org/2024/sqlite-autoconf-3450200.tar.gz'

TIP

Inside an artifact, a bare string starting with http:// or https:// is automatically expanded into a type: url object, so you can often just write the URL directly:

yaml
artifact:
  source: 'https://www.sqlite.org/2024/sqlite-autoconf-3450200.tar.gz'

git ​

Clones a Git repository as the source. Supports two modes: clone a specific branch/tag/commit (rev), or use a regex to match the highest-versioned branch from all remote refs (regex).

yaml
# php-glfw cloned from the master branch
artifact:
  source:
    type: git
    url: 'https://github.com/mario-deluna/php-glfw'
    rev: master

ghrel ​

Downloads a file from GitHub Release Assets using a regex to match the asset filename. Best suited for repositories that upload pre-compiled packages or source archives as release assets.

yaml
# openssl downloaded from GitHub Release Assets
artifact:
  source:
    type: ghrel
    repo: openssl/openssl
    match: openssl.+\\.tar\\.gz
    prefer-stable: true

ghtar ​

Downloads the source tarball automatically generated by a GitHub Release (the "Source code" archive on the Release page). Unlike ghrel which downloads uploaded assets, ghtar uses the auto-generated tarball from the /releases API.

yaml
# librdkafka downloaded via GitHub Release tarball
artifact:
  source:
    type: ghtar
    repo: confluentinc/librdkafka

ghtagtar ​

Downloads a source tarball from a GitHub Tag via the /tags API. Functionally identical to ghtar, but targets the tags endpoint instead of releases — useful for repositories that tag releases without creating a formal GitHub Release.

yaml
# brotli: only match v1.x tags
artifact:
  source:
    type: ghtagtar
    repo: google/brotli
    match: 'v1\\.\\d.*'

# libpng: match v1.6.x tags, with pagination
artifact:
  source:
    type: ghtagtar
    repo: pnggroup/libpng
    match: v1\\.6\\.\\d+
    query: '?per_page=150'

filelist ​

Fetches an HTML page (typically an official download index), extracts filenames and version numbers from the page content using a regex, then automatically selects and downloads the highest stable version. Pre-release versions (those containing keywords like alpha, beta, rc, dev, nightly, or snapshot) are automatically skipped.

Best for: projects without GitHub that publish versioned archives on their own FTP or web index, such as https://ftp.gnu.org/pub/gnu/ncurses/.

yaml
# ncurses: scrape latest version from the GNU FTP index
artifact:
  source:
    type: filelist
    url: 'https://ftp.gnu.org/pub/gnu/ncurses/'
    regex: '/href="(?<file>ncurses-(?<version>[^"]+)\\.tar\\.gz)"/'

# openssl: mirror source using filelist
artifact:
  source-mirror:
    type: filelist
    url: 'https://www.openssl.org/source/'
    regex: '/href="(?<file>openssl-(?<version>[^"]+)\\.tar\\.gz)"/'

pecl ​

Downloads a PHP extension source package from PECL using the PECL REST API. The latest stable version is selected automatically.

yaml
# APCu downloaded from PECL
artifact:
  source:
    type: pecl
    name: APCu

pie ​

Downloads a PHP extension from Packagist following the PIE specification. Package metadata is fetched via the Packagist p2/ API, and the source archive is downloaded from the dist field.

yaml
# xdebug downloaded from Packagist
artifact:
  source:
    type: pie
    repo: xdebug/xdebug

# php-spx with a custom extraction path
artifact:
  source:
    type: pie
    repo: noisebynorthwest/php-spx
    extract: php-src/ext/spx

php-release ​

Downloads the official PHP source from php.net. The version is determined at build time by the --with-php argument. SHA256 integrity is verified automatically. Passing git as the version will clone the master branch of php/php-src directly.

yaml
# php-src with primary and mirror sources
artifact:
  source:
    type: php-release
    domain: 'https://www.php.net'
  source-mirror:
    type: php-release
    domain: 'https://phpmirror.static-php.dev'

bitbuckettag ​

Downloads a source tarball from the latest tag of a Bitbucket repository via the Bitbucket REST API.

yaml
artifact:
  source:
    type: bitbuckettag
    repo: snappy-m-o/php-snappy

local ​

Uses a pre-existing local directory as the source without performing any download. Useful for offline environments or local development where the source has already been placed on disk.

yaml
artifact:
  source:
    type: local
    dirname: /path/to/local/source

custom ​

Delegates download logic entirely to a PHP class under src/Package/Artifact/. If func is not specified, the class's default download method is called.

yaml
artifact:
  source:
    type: custom
`,92)])])}const g=i(l,[["render",n]]);export{c as __pageData,g as default};