mirror of
https://github.com/crazywhalecc/static-php-cli.git
synced 2026-07-07 08:45:40 +08:00
feat(docs): add agent guide, build class patterns, log triage, and AI instructions
This commit is contained in:
crazywhalecc
56
.github/skills/staticphp-build-troubleshooting/SKILL.md
vendored
Normal file
56
.github/skills/staticphp-build-troubleshooting/SKILL.md
vendored
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: staticphp-build-troubleshooting
|
||||
description: 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.
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
1. Capture the exact command, OS, architecture, PHP version, extensions/libs/targets, and whether the run used `-v`, `-vv`, or `-vvv`.
|
||||
2. 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.
|
||||
3. 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`.
|
||||
4. Read `references/log-triage.md` for 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`, and `Failed stage`.
|
||||
- Use `config.log` and CMake logs for configure detection failures; use `spc.shell.log` for the actual command and env.
|
||||
- Be careful with rebuild suggestions. `spc reset --with-download --yes` is destructive to caches; ask before clearing caches unless the user explicitly asked.
|
||||
|
||||
## Repro Commands
|
||||
|
||||
Use focused commands when reproducing:
|
||||
|
||||
```bash
|
||||
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 edit `config/pkg/*` or `config/artifact/*`.
|
||||
- Build command or patch issue: inspect the package class under `src/Package/*`.
|
||||
- Environment issue: check `doctor`, toolchain classes, and `config/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.
|
||||
4
.github/skills/staticphp-build-troubleshooting/agents/openai.yaml
vendored
Normal file
4
.github/skills/staticphp-build-troubleshooting/agents/openai.yaml
vendored
Normal file
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "StaticPHP Build Troubleshooting"
|
||||
short_description: "Diagnose StaticPHP build and log failures."
|
||||
default_prompt: "Use $staticphp-build-troubleshooting to investigate a StaticPHP build, download, doctor, or log failure."
|
||||
209
.github/skills/staticphp-build-troubleshooting/references/log-triage.md
vendored
Normal file
209
.github/skills/staticphp-build-troubleshooting/references/log-triage.md
vendored
Normal file
@@ -0,0 +1,209 @@
|
||||
# StaticPHP Log Triage
|
||||
|
||||
## Contents
|
||||
|
||||
- Log files
|
||||
- Terminal summary
|
||||
- Search strategy
|
||||
- Failure categories
|
||||
- Rebuild hygiene
|
||||
- Reporting checklist
|
||||
|
||||
## Log Files
|
||||
|
||||
Default log directory is `log/`, controlled by `SPC_LOGS_DIR`. The important files are:
|
||||
|
||||
- `spc.output.log`: StaticPHP console/logger output and exception summaries.
|
||||
- `spc.shell.log`: command execution log with command, caller, inline env, working directory, stdout, stderr, and exit code.
|
||||
- `php-src.config.log`: copied when PHP source configure fails.
|
||||
- `lib.<pkg>.console.log`: copied Autoconf `config.log` for a library when available.
|
||||
- `lib.<pkg>.cmake-configure.log`: copied CMake 3.26+ configure log.
|
||||
- `lib.<pkg>.cmake-error.log`: copied CMake error log.
|
||||
- `lib.<pkg>.cmake-output.log`: copied CMake output log.
|
||||
|
||||
Logs are created when `SPC_ENABLE_LOG_FILE` is true. Old `*.log` files are cleaned unless the preserve-log env is true. Note the current code checks `SPC_PRESERVE_LOG`, while `config/env.ini` and docs mention `SPC_PRESERVE_LOGS`; verify this mismatch when diagnosing log retention behavior.
|
||||
|
||||
## Terminal Summary
|
||||
|
||||
StaticPHP exceptions often print:
|
||||
|
||||
- Exception category: build, download, environment, execution, file system, patch, validation, wrong usage, registry, internal.
|
||||
- Failed module: package name, type, and sometimes class/file/line.
|
||||
- Failed stage: call chain such as `build` or `build -> configure`.
|
||||
- Failed command: the command that returned non-zero.
|
||||
- Command working directory and inline env.
|
||||
- Paths to `spc.output.log`, `spc.shell.log`, and extra logs.
|
||||
|
||||
Use this summary to choose the first files to read. If a package and stage are present, start with that package's YAML and class after reading the relevant log tail.
|
||||
|
||||
## Search Strategy
|
||||
|
||||
For long logs, search from the end first.
|
||||
|
||||
Useful patterns:
|
||||
|
||||
```text
|
||||
Failed module:
|
||||
Failed stage:
|
||||
Failed command:
|
||||
Command exited with non-zero code
|
||||
configure: error
|
||||
CMake Error
|
||||
undefined reference
|
||||
cannot find -l
|
||||
fatal error:
|
||||
No package
|
||||
Package .* not found
|
||||
Could NOT find
|
||||
is not a valid
|
||||
permission denied
|
||||
curl: (
|
||||
HTTP/2 403
|
||||
rate limit
|
||||
```
|
||||
|
||||
In `spc.shell.log`, each command block begins with `>>>>>>>>>>>>>>>>>>>>>>>>>>`, then prints the command, caller, env, and working dir. The last failed block is usually the highest-value evidence.
|
||||
|
||||
## Failure Categories
|
||||
|
||||
### Download Failure
|
||||
|
||||
Signs:
|
||||
|
||||
- `Download failed`
|
||||
- `curl: (56)`, `curl: (22)`, HTTP 403/404/429
|
||||
- GitHub API calls in verbose logs
|
||||
- Asset regex did not match a release asset
|
||||
|
||||
Likely checks:
|
||||
|
||||
- If GitHub rate limited, ask user to set `GITHUB_TOKEN`.
|
||||
- Verify artifact source type and regex in `config/pkg/*` or `config/artifact/*`.
|
||||
- Use `--dl-retry`, `--dl-parallel`, `--ignore-cache`, `--no-alt`, or custom source options only as repro aids.
|
||||
- Prefer fixing stale URLs/regexes over adding workarounds.
|
||||
|
||||
### Doctor or Environment Failure
|
||||
|
||||
Signs:
|
||||
|
||||
- `Environment check failed`
|
||||
- missing `make`, `cmake`, `autoconf`, `pkg-config`, compiler, Perl, Visual Studio, MSYS2, Zig, etc.
|
||||
- `Some check items can not be fixed`
|
||||
|
||||
Likely checks:
|
||||
|
||||
- Run `php bin/spc doctor -vvv`.
|
||||
- Inspect `src/StaticPHP/Doctor/Item/*` for the check and fix behavior.
|
||||
- Inspect `config/pkg/tool/*` for installable helper tools.
|
||||
- On Windows, some dependencies cannot be auto-installed.
|
||||
|
||||
### Configure Failure
|
||||
|
||||
Signs:
|
||||
|
||||
- `configure: error`
|
||||
- Autoconf failure before compilation
|
||||
- extra `config.log` listed
|
||||
|
||||
Likely checks:
|
||||
|
||||
- Read copied `php-src.config.log` or `lib.<pkg>.console.log`.
|
||||
- Look for the first compiler/linker probe that failed.
|
||||
- Check `headers`, `static-libs`, `pkg-configs`, dependency order, and `initializeEnv($pkg)` behavior.
|
||||
- For extensions, check `php-extension.arg-type` and `#[CustomPhpConfigureArg]`.
|
||||
|
||||
### CMake Failure
|
||||
|
||||
Signs:
|
||||
|
||||
- `CMake Error`
|
||||
- `Could NOT find`
|
||||
- missing target, package config, or static library
|
||||
|
||||
Likely checks:
|
||||
|
||||
- Read `lib.<pkg>.cmake-error.log` and `lib.<pkg>.cmake-configure.log`.
|
||||
- Inspect `UnixCMakeExecutor`/`WindowsCMakeExecutor` usage in the package class.
|
||||
- Check CMake options, toolchain root path, `pkg-configs`, and transitive dependency libraries.
|
||||
|
||||
### Compile Failure
|
||||
|
||||
Signs:
|
||||
|
||||
- compiler `fatal error: header.h: No such file or directory`
|
||||
- syntax/type errors from upstream source
|
||||
- incompatible PHP API or platform macros
|
||||
|
||||
Likely checks:
|
||||
|
||||
- Identify the source file and include path from `spc.shell.log`.
|
||||
- Verify dependency headers are installed in `buildroot/include`.
|
||||
- Check PHP version compatibility and existing patches in `src/globals/patch`.
|
||||
- Prefer targeted patches or compile flags in the package class over broad toolchain changes.
|
||||
|
||||
### Link Failure
|
||||
|
||||
Signs:
|
||||
|
||||
- `undefined reference`
|
||||
- `cannot find -lfoo`
|
||||
- duplicate symbols
|
||||
- Windows unresolved external symbol or missing `.lib`
|
||||
|
||||
Likely checks:
|
||||
|
||||
- Verify `static-libs`, dependency order, and `getStaticLibFiles()` usage.
|
||||
- Inspect `SPC_EXTRA_LIBS`, `Libs.private` in `.pc` files, and package-specific pkg-config patching.
|
||||
- On Windows, confirm `.lib` names and required system libraries.
|
||||
- For OpenSSL/curl-like packages, search existing linker flag hooks before adding a new one.
|
||||
|
||||
### Smoke Test or Validation Failure
|
||||
|
||||
Signs:
|
||||
|
||||
- `Validation failed`
|
||||
- `php --ri` failure
|
||||
- extension not loaded after build
|
||||
- micro/embed runtime smoke test fails
|
||||
|
||||
Likely checks:
|
||||
|
||||
- Check extension `display-name`; empty string skips `php --ri`.
|
||||
- Confirm static vs shared build settings.
|
||||
- Confirm the extension is included in the final SAPI target and not only built as a dependency.
|
||||
- Inspect `src/globals/ext-tests/*` and common tests for expected runtime behavior.
|
||||
|
||||
### Registry or Config Failure
|
||||
|
||||
Signs:
|
||||
|
||||
- `Registry error`
|
||||
- unknown package, invalid field, invalid platform suffix, type mismatch
|
||||
- package referenced by attribute but missing config
|
||||
|
||||
Likely checks:
|
||||
|
||||
- Run `php bin/spc dev:lint-config`.
|
||||
- Inspect `ConfigValidator` tests for accepted fields and error expectations.
|
||||
- Confirm attribute type matches YAML `type`.
|
||||
- Confirm hooks reference existing package names and stages for the current platform.
|
||||
|
||||
## Rebuild Hygiene
|
||||
|
||||
Use the smallest cleanup that can invalidate the suspected stale state:
|
||||
|
||||
- Redownload one artifact: `--ignore-cache="artifact-name"`.
|
||||
- Skip downloads to test local source/build logic: `--no-download`.
|
||||
- Prefer source when debugging build logic: `--dl-prefer-source`.
|
||||
- Clear build products only when necessary. `spc reset --with-download --yes` removes caches and should not be suggested casually.
|
||||
|
||||
## Reporting Checklist
|
||||
|
||||
When preparing an issue or PR explanation, include:
|
||||
|
||||
- Exact `php bin/spc ...` command.
|
||||
- OS, architecture, PHP version option, and relevant env vars.
|
||||
- Failed package and stage.
|
||||
- Last failed command and exit code.
|
||||
- Tail of `spc.output.log`, relevant command block from `spc.shell.log`, and any extra config/CMake log.
|
||||
- Whether the failure reproduces after a focused clean or cache refresh.
|
||||
Reference in New Issue
Block a user