diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b3c0e31 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,60 @@ +# AGENTS.md — layer-nvidia + +Standalone candy repo for the `nvidia` layer — NVIDIA GPU runtime support. The +candy lives in `charly.yml` at the repo root: multi-distro package arms, the +`LD_LIBRARY_PATH` environment, the Vulkan ICD wiring and signature-verification +`plan:` steps, and the embedded `skill:` entity projected into the marketplace +corpus as `/charly-distros:nvidia`. + +Canonical files: + +- `charly.yml` — the `nvidia:` candy entity and the `nvidia-skill:` skill entity. +- `CHANGELOG/` — per-CalVer release history; read it before changing baked checks. +- `.github/workflows/deploy.yml` — the manifest gate. +- `.github/workflows/tag-on-merge.yml` — CalVer tag + `CHANGELOG/` on merge. +- `README.md` — user overview only; never agent guidance. + +## Load these skills first (R0) + +- `/charly-distros:nvidia` — the owning skill. GPU runtime, CDI device + generation, the distro package arms, and verification. Load before editing or + troubleshooting the layer. +- `/charly-image:layer` — the candy authoring reference (`charly.yml` schema, + `plan:` step verbs incl. `check:`, per-distro `distro:` arms, package/repo + sections, and service declarations). Load before editing any entity field or + plan step. + +## Build / validate / test + +- `charly box validate` at the repo root — the same structural gate CI runs: the + manifest must parse and validate at the pinned charly. The CI pin lives in + `.github/workflows/deploy.yml`; keep the `version:` schema stamp within the + pinned charly's supported range (do not migrate the stamp past the pin). +- `.github/workflows/deploy.yml` — builds the pinned charly from a CI-time + checkout and runs `charly box validate`. This is the merge gate. +- The candy's `plan:` `check:` steps are the functional evidence; they must stay + valid on every distro arm they run on. Where a check only applies to one + distro family (e.g. a Fedora-only DNF path), scope it in the command itself — + the check runner does not honour runner-level `exclude-distro` fields. + +## Modify this repo + +- Edit the `nvidia:` candy entity AND the `nvidia-skill:` skill entity in + `charly.yml` together. The skill is the projected usage source, so a package, + distro-arm, or behaviour change that is not mirrored in the skill leaves the + corpus stale. +- Package changes go in the top-level `package:` or a `distro:` arm; repository + and signing policy go in the matching `distro:` arm's `repo:` block. +- New behaviour claims belong in the `plan:` as an observable `check:` step, and + in the skill body. Keep the Fedora signature-verification check intact. + +## Landing + +- PR-only. Every change lands through a pull request; the org-required + `charly/pr-validator` validates the diff and body and arms native auto-merge + on PASS. Direct pushes to `main` are blocked. +- History lives in `CHANGELOG/` (written by `tag-on-merge` at merge time); the + PR body IS the changelog. +- The authoritative rulebook is the umbrella `AGENTS.md` in + `opencharly/opencharly` and `charly/AGENTS.md` in the charly repo. Do not + restate its rules here. diff --git a/README.md b/README.md index da0ec63..98601c8 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,75 @@ -# layer-nvidia +# nvidia -The `layer-nvidia` candy of the [opencharly/charly](https://github.com/opencharly/charly) -candy library, as a standalone repo (the candy de-submodule cutover). +NVIDIA GPU runtime layer for OpenCharly images. -The candy manifest lives at the repo root (`charly.yml`); the charly resolver -fetches this repo at the pinned tag (`@github.com/opencharly/layer-nvidia:v`). +The `nvidia` candy prepares an image to use an NVIDIA GPU. It installs +`nvidia-container-toolkit` — the `nvidia-ctk` CLI that generates CDI device +specs — together with the per-distro driver libraries, exports +`LD_LIBRARY_PATH=/usr/lib64` so the driver libraries resolve, and prepares +`/etc/vulkan/icd.d` to hold the NVIDIA Vulkan ICD symlinks. It is the GPU +runtime base that GPU-accelerated boxes compose; the CUDA toolchain is a +separate `cuda` layer. -## Pins +## What it provides -- `charly` — the charly checkout this candy's manifest is validated against, - cloned into `.ci/charly` at CI time at the pinned tag (no committed - submodule). +| Property | Value | +|---|---| +| Layer / candy | `nvidia` | +| Package | `nvidia-container-toolkit` (all distros) | +| Binary | `/usr/bin/nvidia-ctk` | +| Environment | `LD_LIBRARY_PATH=/usr/lib64` | +| Directory | `/etc/vulkan/icd.d` (NVIDIA Vulkan ICD / layer symlinks) | +| Service / port | none | -## Gate +Per-distro driver packages: -`.github/workflows/deploy.yml` builds charly from the pinned checkout and runs -`charly box validate` on this repo's `charly.yml` — the manifest must parse and -validate at the pinned charly (the project schema version tracks the pin). +- `arch` / `omarchy` — `nvidia-utils` +- `fedora` — `libva-nvidia-driver` (from the negativo17 `fedora-multimedia` + repo) plus NVIDIA's own `nvidia-container-toolkit` repo, with package + signature verification enforced (`gpgcheck=1`, overriding NVIDIA's shipped + `gpgcheck=0`). + +## How to use it + +Compose the layer by pinning this repo in a box's `candy:` list: + +```yaml +my-box: + candy: + base: fedora # or cachyos / omarchy for the Arch driver layout + candy: + - '@github.com/opencharly/layer-nvidia:v2026.245.1541' +``` + +Once the image is built and the GPU is attached by the runtime: + +```bash +nvidia-smi # GPU information +nvidia-ctk --version # CDI toolkit +``` + +The layer bakes every artifact (package, `nvidia-ctk` binary, exported path, +Vulkan ICD directory) into the image, so it is verifiable without a physical +GPU. A GPU-accelerated box pairs it with `cuda` (CUDA toolkit, cuDNN) — for +example `python-ml`, `jupyter`, `ollama`, and `comfyui`. + +## Layout + +- `charly.yml` — the candy manifest: the multi-distro package arms, the + `LD_LIBRARY_PATH` environment, the Vulkan ICD wiring `plan:`, the `plan:` + checks, and the embedded `skill:` entity. +- `CHANGELOG/` — per-CalVer release notes. +- `.github/workflows/deploy.yml` — builds the pinned charly and runs + `charly box validate` on the manifest (the merge gate). +- `.github/workflows/tag-on-merge.yml` — CalVer tag + `CHANGELOG/` on merge. +- `README.md` — this user overview. + +## Related + +- Owning skill: `/charly-distros:nvidia` +- CUDA toolkit: `/charly-distros:cuda` +- Derived GPU boxes: `/charly-languages:python-ml`, `/charly-jupyter:jupyter`, + `/charly-ollama:ollama`, `/charly-comfyui:comfyui` +- Arch/CachyOS GPU base sibling: `cachyos.nvidia` in `opencharly/distro-cachyos` +- [`opencharly/charly`](https://github.com/opencharly/charly) — the charly CLI and image builder +- [`opencharly/opencharly`](https://github.com/opencharly/opencharly) — the umbrella