Staticphp Build Troubleshooting
Testing & Qualitystaticphp-build-troubleshootingStaticphp Build Troubleshooting is an Agent Skill for testing & quality published in the crazywhalecc/static-php-cli repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Diagnose StaticPHP v3 failures. Use when investigating build, compile, linker, download, doctor, environment, CI, smoke-test, terminal output, spc.output.log, spc.shell.log, config.log, CMake logs, or user-provided error snippets from StaticPHP commands.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/crazywhalecc/static-php-cli/blob/HEAD/.github/skills/staticphp-build-troubleshooting/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/staticphp-build-troubleshooting, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
StaticPHP Build Troubleshooting
Overview
Use this skill to triage StaticPHP failures from the outside in: command and environment first, SPC module/stage metadata next, shell/config logs last. The goal is to isolate the failing package, stage, command, and root cause before editing code.
First Pass
- Capture the exact command, OS, architecture, PHP version, extensions/libs/targets, and whether the run used
-v,-vv, or-vvv. - Read the final terminal error first. StaticPHP prints module error info, failed package, failed stage, failed command, log paths, and extra log files when available.
- If log files exist, inspect them in this order:
log/spc.output.log: user-facing SPC messages and exception summary.log/spc.shell.log: executed commands, working directories, env, stdout/stderr.- Extra logs named in the exception output:
php-src.config.log,lib.<pkg>.console.log,lib.<pkg>.cmake-error.log,lib.<pkg>.cmake-configure.log,lib.<pkg>.cmake-output.log.
- Read
references/log-triage.mdfor pattern matching, likely causes, and next checks.
Diagnosis Rules
- Do not start by changing shared core code. Most failures are package metadata, environment, upstream source, dependency order, or platform flags.
- Prefer evidence from the last failing command over earlier warnings.
- When logs are long, search backward for
Command exited,error:,undefined reference,not found,No package,CMake Error,configure: error,fatal error,Failed module, andFailed stage. - Use
config.logand CMake logs for configure detection failures; usespc.shell.logfor the actual command and env. - Be careful with rebuild suggestions.
spc reset --with-download --yesis destructive to caches; ask before clearing caches unless the user explicitly asked.
Repro Commands
Use focused commands when reproducing:
php bin/spc doctor -vvv
php bin/spc download --for-extensions="curl,openssl" --with-php=8.5 --parallel=4 --retry=3 -vvv
php bin/spc build:libs "openssl" -vvv
php bin/spc build:php "bcmath,openssl,curl" --build-cli -vvv
php bin/spc dev:lint-config
Choose the smallest command that still reaches the failing package.
Fix Direction
After finding the failing package/stage:
- Package YAML issue: use
$staticphp-package-maintenance, then editconfig/pkg/*orconfig/artifact/*. - Build command or patch issue: inspect the package class under
src/Package/*. - Environment issue: check
doctor, toolchain classes, andconfig/pkg/tool/*. - Upstream download issue: check artifact type, regex, GitHub rate limiting, mirror behavior, and
GITHUB_TOKEN. - Core exception/logging issue: inspect
src/StaticPHP/Exception,src/StaticPHP/Runtime/Shell, or executor classes only after package-level causes are ruled out.
Resources
references/log-triage.md: log files, failure categories, search patterns, and likely fixes.