> ## Documentation Index
> Fetch the complete documentation index at: https://buildcharts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> Inputs, validation rules, generated files, and Bake outputs in the BuildCharts flow.

## File layout

BuildCharts uses separate files for separate concerns.

* `build.yml` defines repository-local build intent: targets, types, variables, and optional plugins.
* `charts/buildcharts/Chart.yaml` maps those target types to versioned OCI-hosted chart implementations.
* `charts/buildcharts/Chart.lock` optionally pins the resolved chart digests for repeatability and drift detection.

This separation is deliberate. Repositories declare what should be built. Shared charts define how it is implemented. Docker Buildx Bake remains the execution layer.

### `build.yml`

This file defines variables, plugins, targets, and optional type matrices. Each target declares a `type`, but BuildCharts does not implement that type directly. Instead, it uses the type as an alias lookup into `charts/buildcharts/Chart.yaml`.

Example:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
version: v1beta

variables:
  VERSION: "1.0.0-local"
  COMMIT: "local"

targets:
  buildcharts.sln:
    type: build
    with:
      contexts:
        base: docker-image://mcr.microsoft.com/dotnet/sdk:10.0

  src/App/App.csproj:
    type: docker
    with:
      contexts:
        base: docker-image://mcr.microsoft.com/dotnet/runtime:10.0
      tags: ["docker.io/example/app:${VERSION}-${COMMIT}"]
```

These rules matter on every run:

* Exactly one `build` target must be defined.
* Every target `type` must match an alias declared in `charts/buildcharts/Chart.yaml`.
* Target contexts are declared under `with.contexts`.
* Plugins run during generation, not during Bake execution.

### `charts/buildcharts/Chart.yaml`

This file maps each target alias to a versioned OCI chart. The alias is the contract between repo-local intent and shared implementation.

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
dependencies:
  - name: dotnet-build
    alias: build
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts
```

Running `buildcharts update` resolves those dependencies and can record the resolved digests in `Chart.lock`.

### `charts/buildcharts/Chart.lock`

This file is optional. When it exists, `buildcharts generate` validates it against `Chart.yaml` and the registry digest unless `--ignore-lock` is used. This keeps chart version selection flexible in `Chart.yaml` while still pinning the exact artifact used during generation.

Example:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
dependencies:
  - name: dotnet-build
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts/dotnet-build
    digest: sha256:...
lockVersion: 1
```

## Generation flow

During `buildcharts generate`, BuildCharts acts as a generator:

1. It removes the previous `.buildcharts` output.
2. It reads `build.yml`, `Chart.yaml`, and `Chart.lock` if it exists.
3. It validates the build target count, target aliases, and lock file state.
4. It pulls or reuses the OCI chart artifacts referenced by `Chart.yaml`.
5. It materializes chart contents under `.buildcharts`.
6. It runs each configured plugin.
7. It writes `.buildcharts/docker-bake.hcl`.

The important boundary is that BuildCharts stops after generation. The generated HCL and Dockerfiles are the handoff to Docker tooling.

<Tip>
  With `--use-inline-dockerfiles`, the generated HCL embeds chart Dockerfiles instead of referencing files under `.buildcharts/<chart-name>/Dockerfile`. That can make the generated plan easier to move around as a single artifact.
</Tip>

## Execution flow

After generation, execution flows through Docker Buildx Bake and BuildKit:

* BuildCharts writes the generated HCL.
* Docker Buildx Bake reads the generated Bake file.
* BuildKit executes the selected targets.

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
# Run default group target
docker buildx bake --file .buildcharts/docker-bake.hcl

# Run specific target
docker buildx bake --file .buildcharts/docker-bake.hcl test
```

From there, [Docker builds](/core-features/docker-builds) covers execution options, [Exporting build artifacts](/charts/using-outputs) covers output behavior by target type, and [Examples](/examples) shows complete workflows.