meta-qcom AGENTS.md

Agent Guide for meta-qcom

This file guides automation agents to run builds / checks the same way CI does:

• use kas-container (isolated from host),
• keep DL_DIR and SSTATE_DIR outside the repo so caches are shared,
• run yocto-patchreview and oe-selftest routinely, and run yocto-check-layer before opening/updating a PR, via the CI helper scripts.

Project Overview

meta-qcom is an OpenEmbedded / Yocto Project hardware enablement layer for Qualcomm based platforms.

1) Prerequisites

1. kas-container available on PATH, or set KAS_CONTAINER=/abs/path/to/kas-container (from kas-container).
2. Container runtime access (Docker/Podman backend used by kas-container).
3. Work directories outside the repository for build outputs and shared caches.

Container runtime smoke test (required order)

Run Docker first:

docker run --rm hello-world

Then check Podman:

if command -v podman >/dev/null 2>&1; then
  podman run --rm hello-world
else
  echo "podman not installed; continue with Docker backend"
fi

Notes:

• Do not use sudo unless the host setup explicitly requires it.
• Do not create or modify user groups as part of this workflow.
• If Podman is unavailable, Docker-only operation is acceptable.

2) Recommended environment

If KAS_WORK_DIR, DL_DIR, and SSTATE_DIR are already set in the environment, use them directly — do not override them. Only set defaults when they are absent:

export REPO_DIR="$(pwd)"                               # meta-qcom checkout
export KAS_WORK_DIR="${KAS_WORK_DIR:-/path/to/kas-work}"      # outside repo to avoid polling the checkout
export DL_DIR="${DL_DIR:-/path/to/shared-cache/downloads}"
export SSTATE_DIR="${SSTATE_DIR:-/path/to/shared-cache/sstate-cache}"
mkdir -p "${DL_DIR}" "${SSTATE_DIR}" "${KAS_WORK_DIR}"

3) Build with kas-container (CI style)

CI build composition pattern: :ci/<machine>.yml[:distro.yml][:kernel.yml]