static-php-cli/docs/en/develop/structure.md

Project Structure

Concepts

StaticPHP is a CLI application built on symfony/console, with core code located in the src/StaticPHP directory. It is organized into several modules:

• Registry: Manages registry data. Each registry contains multiple packages (Package), and the StaticPHP project ships with a built-in core registry that includes PHP and related extensions, dependencies, and more.
• Package: Represents a single package. There are four package types: php-extension (PHP extension), library (library), target (build target), and virtual-target (virtual build target). Each package contains build information, dependencies, and more.
• Installer/Builder: Handles installation and build logic for packages — executing build commands, extracting build artifacts, processing build results, etc.
• Doctor: Provides system environment checking, responsible for installing and verifying system-level dependencies such as make, cmake, autoconf, and more.
• Runtime/Executor: Contains runtime-related utility classes, such as shell command execution and CMake build execution.
• Toolchain: Provides toolchain abstraction interfaces for different operating systems and environments, handling system-level differences during the build process.
• Utils: General-purpose utility classes, such as file system operations, logging, and OS-specific helper methods.
• DependencyResolver: Resolves dependencies between packages and generates build order.

Directory Layout

static-php-cli/
├── bin/                        # Executable entry scripts (spc, spc.ps1, setup-runtime, etc.)
├── config/
│   ├── env.ini                 # Default environment variable configuration
│   ├── env.custom.ini          # User-defined environment variables (overrides env.ini)
│   ├── artifact/               # Build artifact configuration (toolchain downloads, pre-built binaries, etc.)
│   └── pkg/                    # Package configuration files (YAML)
│       ├── ext/                # PHP extension package config (ext-*.yml, builtin-extensions.yml)
│       ├── lib/                # Library package config (*.yml)
│       └── target/             # Build target config (php.yml, curl.yml, etc.)
├── src/
│   ├── bootstrap.php           # Application bootstrap (auto-loading, DI container, etc.)
│   ├── globals/                # Global helper functions
│   ├── Package/                # Build logic implementations for each package (PHP classes)
│   │   ├── Artifact/           # Custom download/extract logic for build artifacts
│   │   ├── Command/            # Package-level custom commands
│   │   ├── Extension/          # PHP extension build classes (ext-*.php)
│   │   ├── Library/            # Library build classes (*.php)
│   │   └── Target/             # Build target classes (php.php, curl.php, etc.)
│   └── StaticPHP/              # Framework core code
│       ├── ConsoleApplication.php  # Symfony Console application entry
│       ├── Artifact/           # Build artifact download and extraction (Downloader, Extractor, etc.)
│       ├── Attribute/          # PHP attribute definitions
│       │   ├── Artifact/       # Artifact-related attributes (CustomSource, BinaryExtract, etc.)
│       │   ├── Doctor/         # Doctor-related attributes (CheckItem, FixItem, etc.)
│       │   └── Package/        # Package build-related attributes (BuildFor, BeforeStage, AfterStage,
│       │                       #   CustomPhpConfigureArg, PatchBeforeBuild, etc.)
│       ├── Command/            # CLI command implementations (build-libs, build-target, doctor, etc.)
│       ├── Config/             # Configuration loading and validation (PackageConfig, ArtifactConfig, etc.)
│       ├── DI/                 # Dependency injection container (ApplicationContext, CallbackInvoker, etc.)
│       ├── Doctor/             # System environment checking and fixing (Doctor, CheckResult)
│       ├── Exception/          # Custom exception classes
│       ├── Package/            # Core package models and build scheduling
│       │   ├── Package.php             # Base package class
│       │   ├── LibraryPackage.php      # Library package type
│       │   ├── PhpExtensionPackage.php # PHP extension package type
│       │   ├── TargetPackage.php       # Build target package type
│       │   ├── PackageInstaller.php    # Package installer (download, extract source)
│       │   └── PackageBuilder.php      # Package builder (execute build pipeline)
│       ├── Registry/           # Registry management (Registry, PackageLoader, ArtifactLoader)
│       ├── Runtime/            # Runtime utilities
│       │   ├── Executor/       # Command executors (UnixAutoconfExecutor, UnixCMakeExecutor,
│       │   │                   #   WindowsCMakeExecutor, Executor base class)
│       │   ├── Shell/          # Shell abstraction (UnixShell, WindowsCmd, etc.)
│       │   └── SystemTarget.php # System target information
│       ├── Toolchain/          # Toolchain abstraction (GccNative, Musl, MSVC, Zig, ClangBrew, etc.)
│       └── Util/               # General utility classes
│           ├── System/         # OS platform utilities (LinuxUtil, MacOSUtil, WindowsUtil, etc.)
│           ├── BuildRootTracker.php  # buildroot file tracking
│           ├── DependencyResolver.php # Dependency resolution and build order
│           ├── FileSystem.php        # File system operations
│           ├── GlobalEnvManager.php  # Global environment variable management
│           ├── InteractiveTerm.php   # Interactive terminal output
│           ├── LicenseDumper.php     # License export
│           ├── PkgConfigUtil.php     # pkg-config utility wrapper
│           ├── SourcePatcher.php     # Source code patching utility
│           └── SPCConfigUtil.php     # SPC configuration reader
├── tests/                      # Unit tests and integration tests
├── downloads/                  # Download cache directory (source packages, pre-built binaries)
├── source/                     # Extracted source code directory
├── buildroot/                  # Build output directory (headers, static libraries, etc.)
├── pkgroot/                    # Platform-archived build artifacts
└── spc.registry.yml            # core registry definition file

Note that the classes in src/Package are responsible for implementing the build logic of specific packages, while the classes in src/StaticPHP provide the core functionality of the build framework, such as command scheduling, environment checking, and toolchain abstraction. The two are decoupled: src/Package corresponds to the packages in the core registry (including PHP, extensions, libraries, and build targets), while src/StaticPHP is the infrastructure that supports build needs across different registries and packages.