# azldev

Adopt this skill: https://proskills.md/skills/other/microsoft-azurelinux-agents-skills-azldev

Page: https://proskills.md/skills/other/microsoft-azurelinux-agents-skills-azldev
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents/skills/azldev/SKILL.md
size: 4400
sha: 261c9814f1c9ad11ec71e924f9e32210afa9b8ed
upstream: https://github.com/microsoft/azurelinux/blob/4.0/.agents/skills/azldev/SKILL.md

```text
---
name: azldev
description: "Read this before running azldev or editing azldev config, and whenever working in a repo that contains an azldev.toml file; do not guess azldev's commands or config. Explains how to use the azldev CLI to build a distro from TOML config, including the core concepts (components, overlays, distros, rendered specs, locks), running azldev (repo root or -C, plus the -q and -O json flags), the common commands, and where to go for each workflow. Triggers include azldev, comp build, comp render, comp update, build a component, add a component, distro config."
---

# Using azldev

azldev builds a Linux distribution from TOML configuration. It imports RPM specs
from an upstream distro and customizes them with an overlay system — no spec
forking. Components render to specs and sidecar build inputs, then build into RPMs;
images assemble RPMs into bootable artifacts.

## Orient yourself

- Run azldev from the repo root (where `azldev.toml` lives), or pass `-C <dir>`.
- Global, agent-friendly flags: **`-q`** (quiet) and **`-O json`** (machine-readable
  output). They work on every command.
- Config is a stitched TOML hierarchy: `azldev.toml` includes the distro and project
  config, which include the component files (`**/*.comp.toml`) into one namespace.

## Core concepts

- **Component** — a unit of packaging that renders to a spec and sidecar build inputs,
  then builds into one or more RPMs. Its spec source is upstream (default), a pinned
  upstream distro/version, or a local spec.
- **Overlay** — a semantic patch applied to a spec or source file at render time, so
  you customize upstream without forking it.
- **Distro** — a named build target (`*.distro.toml`) with upstream URIs, release
  versions, and build inputs.
- **Rendered spec** — the generated `.spec` after overlays; a build input, never
  hand-edited.
- **Lock** — a per-component file pinning the resolved upstream commit and an input
  fingerprint.

## Common commands

Top-level commands in this build:

- `azldev completion` — Generate the autocompletion script for the specified shell
- `azldev component` — Manage components
- `azldev config` — Manage tool configuration
- `azldev docs` — Documentation commands
- `azldev image` — Manage Azure Linux images
- `azldev package` — Manage binary package configuration
- `azldev project` — Manage Azure Linux projects
- `azldev repo` — Inspect and manage RPM repositories
- `azldev version` — Print the CLI version

Everyday tasks (add `-q -O json` when scripting):

| Task | Command |
| --- | --- |
| List components | `azldev comp list -a` |
| Inspect one component | `azldev comp list -p <name>` |
| Add a component | `azldev comp add` |
| Build a component | `azldev comp build -p <name>` |
| Render specs | `azldev comp render -p <name>` (or `-a`) |
| Refresh a lock | `azldev comp update -p <name>` |
| List / build images | `azldev image list` / `azldev image build` |

`comp` is an alias for `component`. Always confirm current syntax with
`azldev <command> --help`.

The hidden `advanced` group (`adv`) contains specialist integrations such as MCP and
mock helpers; it is intentionally omitted from normal help.

## Where to go next

- Add a new component — read the `azldev-add-component` skill.
- Edit or review a component's TOML — read the `azldev-comp-toml` skill.
- Add or change overlays — read the `azldev-overlays` skill.
- Annotate an overlay's intent (category, upstream status, provenance) — read the `azldev-overlay-metadata` skill.
- Build, iterate, and debug a component — read the `azldev-build-component` skill.
- Build, boot, and register images — read the `azldev-image` skill.
- Refresh a lock and finalize for a PR — read the `azldev-update-component` skill.
- Remove a component — read the `azldev-remove-component` skill.
- Test built RPMs in a chroot — read the `azldev-mock` skill.

## Golden rules

- **Never edit generated output** — rendered specs and the output/work/log dirs are
  produced by azldev. Change the source config and re-render.
- **Re-run `azldev comp update` before opening a PR** — the lock fingerprint covers
  the whole component config, and lock / rendered-spec CI checks run on committed state.
- **Every overlay needs a `description`** explaining why the change is needed.

Generated by `azldev docs agent`; do not hand-edit.
```

## File: README.md
upstream: https://github.com/microsoft/azurelinux/blob/4.0/README.md

````text
<h1>
  <img src="assets/azurelinux-logo-48.png" alt="Azure Linux logo" align="left" height="44" /> Azure Linux 4
</h1>

**An open-source Linux distribution built and optimized for [Azure](https://azure.microsoft.com/), with sources derived from [Fedora Linux](https://fedoraproject.org/).** Azure Linux provides a secured, reliable operating system for virtual machines, containers, and bare-metal platforms.

Azure Linux is built on a robust open-source foundation from the Fedora ecosystem and enhanced with Azure-specific innovations. This provides the familiarity of the RPM package ecosystem, while adding Azure-native security, compliance, and operational capabilities.

Key features of Azure Linux include: hardened security posture, an Azure-optimized kernel, supply chain security, native Azure integration, and a predictable lifecycle.

> **This branch holds the in-development sources for Azure Linux 4.** For Azure Linux 3, see the [`3.0` branch](https://github.com/microsoft/azurelinux/tree/3.0).

## Getting started

The links below will help you get started with Azure Linux:

| | |
|---|---|
| **Product documentation** | <https://aka.ms/azurelinux> |
| **Release information** | [GitHub Releases](https://github.com/microsoft/azurelinux/releases) |
| **File a bug / feedback** | [GitHub Issues](https://github.com/microsoft/azurelinux/issues) |
| **Ask a question / get help** | [SUPPORT.md](SUPPORT.md) |
| **Get started as a distro developer** | [DEVELOPING.md](DEVELOPING.md) |
| **Contribution guidelines** | [CONTRIBUTING.md](CONTRIBUTING.md) |
| **Report a security issue** | [SECURITY.md](SECURITY.md) |

## Using Azure Linux

*Note: Azure Linux 4 is still in development*

<details open>
<summary><b>🖥️ Azure VM</b></summary>

To try Azure Linux in an Azure VM, please visit [our Azure Linux 4.0 page](https://aka.ms/azure-linux-4-marketplace) on the Microsoft Marketplace.

</details>

<details open>
<summary><b>📦 Container</b></summary>

To try Azure Linux base container, please use the following image reference: `mcr.microsoft.com/azurelinux-beta/base/core:4.0`

</details>

<details>
<summary><b>💿 ISO Installer</b></summary>

To try Azure Linux in a local VM, please download the ISO Installer: [x86_64](https://aka.ms/azurelinux-4.0-x86_64.iso) / [ARM64](https://aka.ms/azurelinux-4.0-aarch64.iso)

Before using a downloaded ISO, [verify the checksum and signature of the ISO](./docs/verify-iso-signature-and-checksum.md).

After downloading and verifying the ISO, follow the [ISO installer instructions](./docs/iso-installer-in-local-vm.md) to install and use Azure Linux in a local VM (Hyper-V on Windows or QEMU/KVM on Linux). The ISO runs the [Anaconda](https://anaconda-installer.readthedocs.io/) installer.

_Note: Support for the ISO is community based. Before filing a new bug or feature request, please search the list of Github Issues. If you are unable to find a matching issue, please report new bugs by clicking [here](https://github.com/microsoft/azurelinux/issues). For additional information, refer to the [SUPPORT.md](./SUPPORT.md) file._

</details>

<details>
<summary><b>🐧 Windows Subsystem for Linux (WSL)</b></summary>

To try Azure Linux on the Windows Subsystem for Linux, install it from the WSL distribution list:

```powershell
wsl --install AzureLinux-4
```

`wsl --install` downloads the package for your architecture (x86_64 or ARM64) and checks it against the SHA-256 checksum in the WSL distribution manifest before installing it. `wsl --list --online` shows Azure Linux 4 among the available distributions.

To list all the installed distributions:

```powershell
wsl --list
```

To use the distro:

```powershell
wsl -d AzureLinux-4
```

To install from a downloaded `.wsl` package instead, download the package for your architecture:

- [x86_64](https://aka.ms/azurelinux-4.0-x86_64.wsl)
- [ARM64](https://aka.ms/azurelinux-4.0-aarch64.wsl)

Before installing a downloaded package, [verify the checksum and signature of the `.wsl` package](./docs/verify-wsl-signature-and-checksum.md). Then install it using `wsl`:

```powershell
wsl --install --from-file "C:\Path\To\AzureLinux-4.0-ARCH.wsl"
```

See [Systemd defaults in WSL images](./docs/wsl-systemd-policy.md) for the
networking, console, and temporary-file policies.

</details>

## What's in this branch?

Azure Linux 4 is an RPM-based distribution optimized for Azure and modern cloud workloads. It is defined by a set of TOML configuration files and targeted *overlays* applied to [Fedora Linux](https://fedoraproject.org/), its upstream base.

Deviations from upstream are declaratively defined and scoped to avoid unnecessary divergence or forking. This repository contains a mechanically rendered set of RPM package spec files derived from applying this layer to Fedora's upstream packaging sources.

For the implementations selected by the VM base images, see [VM base image userland implementations](base/images/README.md).

## How Azure Linux is defined

The distro is described almost entirely in TOML-based configuration files. Our open-source development tool, [`azldev`](https://github.com/microsoft/azure-linux-dev-tools), is used to apply this configuration to upstream Fedora spec files and packaging sources.

```text
azldev.toml        # Top-level entry point
├── distro/        # Distro-wide configs (e.g., sources, mock configs)
└── base/          # The "base" project: components, images, tests
    └── comps/     # Component definitions (one per source package)
    └── images/    # Base image definitions
```

### Concepts/terms

- **Components** (also known as source packages) are the unit of packaging.
  Most are imported in source form from Fedora's upstream dist-git repositories; each component produces one or more RPMs. Azure Linux builds all components from sources to produce a full set of installable RPM packages.
- **Overlays** are declarative modifications to upstream specs and sources
  (e.g., patches, additions/removals, build parameters). They live alongside the component definition and always carry a `description` explaining *why* the change is needed. Overlays let us avoid forking upstream specs and are more flexible than plain textual patches.
- **Rendered specs** are the final `.spec` files produced by applying overlays to upstream sources. They are mechanically generated by `azldev`, checked in for visibility and auditability, and live under [`specs/`](specs/). Treat them as derived output and not sources for editing. We use them as the input to standard RPM building services/tools (`mock` + `rpmbuild`, `koji`).

For a deeper tour of the tooling, the overlay system, and how to get started developing within this distro, please see
[DEVELOPING.md](DEVELOPING.md).

## Repository layout

| Path | What's there |
|---|---|
| [`azldev.toml`](azldev.toml) | Top-level config — includes `distro/` and `base/`. |
| [`distro/`](distro/) | Distro definitions (Azure Linux + upstream Fedora), shared `mock` configs. |
| [`base/`](base/) | The `base` project: components, images, tests. |
| [`base/comps/`](base/comps/) | **Component definitions** — the heart of the distro. |
| [`base/images/`](base/images/) | Image definitions (VM, container, etc.) built from the component set using [`KIWI NG`](https://osinside.github.io/kiwi/). |
| [`specs/`](specs/) | **Rendered specs** — generated `.spec` files after overlays are applied. Checked in for visibility; do not hand-edit. |
| [`locks/`](locks/) | Per-component lock files pinning upstream commits + input fingerprints; do not hand-edit. |
| [`external/schemas/`](external/schemas/) | Cached copy of the JSON Schema for TOML config files; mirrored from `azldev`. |
| [`.github/`](.github/) | CI workflows, plus Copilot prompts, skills, and agent instructions used by AI-assisted development. |

## Getting started as a distro developer

If you want to build or develop within the distro, start with **[DEVELOPING.md](DEVELOPING.md)**. Don't worry about this if you're pri
````
