Skip to content

Commit 151f77b

Browse files
flexiondotorgflexiondotorg
committed
docs: update path from vendor/ to third_party/ for submodules
Change all references from vendor/ffmpeg-statigo to third_party/ffmpeg-statigo in documentation: - Update submodule integration instructions in README.md - Update development documentation paths - Update build commands to use `go build ./...` syntax - Update GitHub Actions examples with newer action versions - Add additional troubleshooting notes This change follows best practices of placing third-party dependencies in third_party/ directory rather than vendor/ to avoid Go module vendoring conflicts.
1 parent 9f9c17d commit 151f77b

5 files changed

Lines changed: 205 additions & 1091 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# ffmpeg-statigo Copilot Instructions
2+
3+
## Project Overview
4+
5+
Go bindings for FFmpeg 8.0 static libraries. Ships ~100MB platform-specific `libffmpeg.a` files that link directly into Go binaries—no system FFmpeg required.
6+
7+
## Critical Build Rules
8+
9+
**Always use `just build`**—never run `go build` directly. The justfile orchestrates:
10+
1. Building FFmpeg static library from source (`internal/builder/`)
11+
2. Regenerating Go bindings from headers (`internal/generator/`)
12+
3. Compiling Go code with correct CGO flags
13+
14+
## Code Generation
15+
16+
Files matching `*.gen.go` are **auto-generated**—never edit directly:
17+
- `constants.gen.go`, `enums.gen.go`, `structs.gen.go`, `functions.gen.go`, `callbacks.gen.go`
18+
19+
To regenerate after header changes: `just generate`
20+
21+
The generator (`internal/generator/`) parses FFmpeg headers in `include/` using libclang and outputs Go bindings.
22+
23+
## Architecture
24+
25+
| Component | Purpose |
26+
|-----------|---------|
27+
| `ffmpeg.go` | CGO directives, platform-specific linker flags, helper types (`CStr`, `AVError`) |
28+
| `*.gen.go` | Generated FFmpeg API bindings |
29+
| `include/` | FFmpeg C headers (libavcodec, libavformat, libavutil, etc.) |
30+
| `lib/<os>_<arch>/` | Platform-specific static libraries (gitignored) |
31+
| `internal/builder/` | Builds FFmpeg + 20 dependencies from source |
32+
| `internal/generator/` | Generates Go bindings from headers |
33+
| `cmd/download-lib/` | Downloads pre-built libraries from GitHub Releases |
34+
| `examples/` | Working examples: transcode, metadata, asciiplayer, introspect |
35+
36+
## Internal Builder
37+
38+
The builder (`internal/builder/`) compiles FFmpeg and dependencies from source. Key files:
39+
40+
- `libraries.go` — Library definitions (URLs, versions, build configs)
41+
- `buildsystems.go` — Autoconf, CMake, Meson, Cargo build implementations
42+
- `main.go` — CLI entry point with `--clean` and `--list` flags
43+
44+
Build commands:
45+
- `just build-static` — Build all libraries
46+
- `just build-static ffmpeg --clean` — Rebuild FFmpeg only
47+
- `go run ./internal/builder --list` — Show library versions
48+
49+
## Hardware Acceleration
50+
51+
Supports NVENC/NVDEC (Linux), QuickSync (Linux), VideoToolbox (macOS), and Vulkan Video. See `README.md` and `docs/CODECS.md` for codec and hardware details.
52+
53+
## Library Distribution
54+
55+
Static libraries distributed via GitHub Releases (`lib-8.0.0.x` tags), not git. Download with:
56+
```
57+
go run ./cmd/download-lib
58+
```
59+
60+
## Platform Support
61+
62+
Linux (amd64, arm64) and macOS (amd64, arm64). CGO required (`CGO_ENABLED=1`).
63+
64+
Platform-specific code uses build tags in CGO directives—see `ffmpeg.go` lines 11-17.
65+
66+
## Testing
67+
68+
```
69+
just test
70+
```
71+
72+
Tests require downloaded libraries. See `ffmpeg_test.go` for version validation pattern.
73+
74+
## Key Patterns
75+
76+
- All FFmpeg types prefixed with `AV*` (e.g., `AVCodecContext`, `AVFrame`)
77+
- Use `CStr` type for C string interop—call `.Free()` when done
78+
- Wrap FFmpeg return codes with `WrapErr()` to convert to Go errors
79+
- Check `AVErrorEOF` and `EAgain` for stream processing loops
80+
81+
## Environment
82+
- NixOS development shell via `flake.nix`
83+
- Fish shell for terminal commands
84+
- CGO required (`CGO_ENABLED=1` in build)
85+
86+
## Further Reading
87+
88+
- `docs/DEVELOPMENT.md` — Consumer integration, project layout, troubleshooting
89+
- `docs/CODECS.md` — Enabled codecs, muxers, parsers
90+
91+
## Reference Projects
92+
93+
See [jivedrop](https://github.com/linuxmatters/jivedrop) and [jivefire](https://github.com/linuxmatters/jivefire) for consumer integration patterns with justfiles and GitHub workflows.

‎README.md‎

Lines changed: 9 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -24,49 +24,19 @@ Build once, deploy anywhere. No hunting for system FFmpeg. No version mismatches
2424

2525
## Installation
2626

27-
ffmpeg-statigo includes large static libraries (~100MB per platform) that cannot be distributed via `go get`. This requires a simple manual setup:
27+
Static libraries (~100MB per platform) cannot be distributed via `go get`. Use as a git submodule with a replace directive:
2828

29-
### Using Git Submodules
29+
1. Add submodule: `git submodule add https://github.com/linuxmatters/ffmpeg-statigo third_party/ffmpeg-statigo`
30+
2. Add replace directive to `go.mod`: `replace github.com/linuxmatters/ffmpeg-statigo => ./third_party/ffmpeg-statigo`
31+
3. Download libraries: `cd third_party/ffmpeg-statigo && go run ./cmd/download-lib`
32+
4. Configure git for submodule-friendly pulls: `git config pull.ff only && git config submodule.recurse true`
33+
5. Build: `go build ./...`
3034

31-
For clean project integration, use ffmpeg-statigo as a git submodule:
35+
Step 4 prevents `git pull --rebase` from breaking submodule references. Fast-forward only pulls ensure submodule commits stay in sync with the parent repository.
3236

33-
1. Add ffmpeg-statigo as a submodule in your project
34-
```bash
35-
git submodule add https://github.com/linuxmatters/ffmpeg-statigo vendor/ffmpeg-statigo
36-
```
37+
Static libraries are gitignored—only the submodule reference is committed.
3738

38-
2. Add a replace directive pointing to the submodule
39-
```bash
40-
go mod edit -replace github.com/linuxmatters/ffmpeg-statigo=./vendor/ffmpeg-statigo
41-
```
42-
43-
3. Get the dependency
44-
```bash
45-
go get github.com/linuxmatters/ffmpeg-statigo
46-
```
47-
48-
4. Download the static libraries
49-
```bash
50-
cd vendor/ffmpeg-statigo
51-
go run ./cmd/download-lib
52-
cd ../..
53-
```
54-
55-
5. Build your project
56-
```bash
57-
go build
58-
```
59-
60-
6. Commit only the submodule reference
61-
62-
The static libraries (`lib/*/libffmpeg.a`) won't be committed - they're gitignored
63-
64-
```bash
65-
git add .gitmodules vendor/ffmpeg-statigo
66-
git commit -m "Add ffmpeg-statigo as submodule"
67-
```
68-
69-
**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for alternative installation methods, CI/CD integration, and troubleshooting.**
39+
**See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for CI/CD integration, cross-compilation, and troubleshooting.**
7040

7141
## Codec Inclusion Policy
7242

0 commit comments

Comments
 (0)