How buildpacks/libcnb works
Project Type and Purpose
• This is a Go language binding (a library) for the Cloud Native Buildpacks (CNB) API.
• It exposes a non-opinionated Go API to:
• Detect whether a buildpack applies (“detect”)
• Execute buildpack logic and produce layers (“build”)
• Generate project artifacts (“generate”)
• It is consumed by tools like pack or any Go program that wants to orchestrate CNB buildpacks.
High-Level Architecture
• External Consumer (e.g., the pack CLI or another Go program)
→ imports github.com/buildpacks/libcnb
→ calls top-level functions: Detect(), Build(), Generate()
• Public API Layer (root package)
• main.go → entrypoint for CLI or Go programs
• detect.go, build.go, generate.go → core workflows
• config.go, environment.go, extension.go, process.go, store.go, layer.go, platform.go → domain constructs
• Internal Utility Layer (internal/)
• config_map.go, directory_contents.go → inspect file system
• toml_writer.go, execd_writer.go, environment_writer.go → write CNB metadata (TOML, exec.d scripts, env files)
• exit_handler.go, formatter.go → handle process exit codes & logging format
• match_toml.go → parse and match buildpack.toml
• Logging Subsystem (log/)
• logger.go → structured logger interface
• formatter.go → log formatting
• Supporting Artifacts
• examples/ → usage examples
• mocks/ & log/mocks/ → test doubles for unit tests
• tools/ → small helper binaries
• testdata/ → sample JSON, TOML for tests
Relationships and Data Flow
• Consumer invokes Detect()
→ Detect() uses MatchTOML → ConfigMap → DirectoryContents → returns a Plan
• Consumer invokes Build()
→ Build() reads Platform API, Environment, Layer definitions
→ uses ExecDWriter, EnvWriter, TOMLWriter to produce output artifacts
• Consumer invokes Generate()
→ Generate() orchestrates metadata output for builders, extensions
• All components emit logs via the Logger interface
Architectural Patterns & Principles
• Package encapsulation: only root package is public; everything under internal/ is private.
• Separation of concerns:
• Public API deals in CNB concepts (buildpacks, layers, plans)
• Internal packages deal with on-disk representation and formatting
• Dependency Injection via interfaces (e.g., logger, file-writers) for testability
• Clear distinction between domain constructs and I/O