azldev-mock

---
name: azldev-mock
description: "Read this before testing or inspecting a built RPM; do not drive mock by hand from memory. Explains how to test and inspect built packages in a mock chroot with 'azldev adv mock shell', covering non-interactive (heredoc) and interactive chroot workflows, the -p/--add-package flag, and resetting stale chroot state. Triggers include test package, mock shell, inspect rpm, smoke test, chroot, verify build output."
---

# Test and inspect packages in a mock chroot

> **Never install built RPMs on the host.** They target the distro you are
> building, not your dev machine. Use a mock chroot instead.

azldev tests and inspects packages inside `mock` build roots via `mock shell`,
which lives under the hidden `advanced` group (`azldev adv` is an alias for
`azldev advanced`; it does not appear in `azldev --help`).

## Non-interactive chroot (preferred for agents)

Pipe commands in via a heredoc — fully autonomous, no user interaction needed:

```sh
azldev adv mock shell --add-package /path/to/package.rpm <<'CMDS'
<command> --version
echo "exit code: $?"
exit
CMDS
```

Use this for automated checks: running binaries, querying installed packages,
inspecting paths.

## Inspect an RPM without installing it

When `--add-package` fails to install, or you just want to look at an RPM's
contents, get the file inside the chroot and inspect it there rather than
installing on the host. If the RPM is not already reachable inside the build
root, copy it in first with `mock --copyin <rpm> /tmp/` (using the project's
distro mock config), then:

```sh
azldev adv mock shell <<'CMDS'
rpm -qip /tmp/<name>*.rpm    # package info
rpm -qlp /tmp/<name>*.rpm    # file list
rpm -qRp /tmp/<name>*.rpm    # dependencies
dnf install /tmp/<name>*.rpm # retry the install to see the error details
exit
CMDS
```

This gives you the full distro environment for debugging dependency issues, file
conflicts, and failed installs, without touching the host.

## Interactive chroot

Use when you need to explore interactively or react to output between commands:

```sh
azldev adv mock shell --add-package /path/to/package.rpm --enable-network
```

When driving an interactive shell as an agent:

1. Run a simple command (e.g. `echo ready`) in a foreground terminal to establish a shared shell.
2. Ask the user to run the `azldev adv mock shell` command in that same terminal.
3. Wait for confirmation that they are inside the mock shell.
4. Run diagnostic commands in the same foreground terminal — they execute inside the chroot.
5. Run `exit` to leave the chroot.

Prefer the non-interactive heredoc approach; use interactive only when you must
react to output between commands.

## Key flags

| Flag | Purpose |
| --- | --- |
| `-p`, `--add-package <path>` | Install a package into the chroot before entering. Accepts an RPM file path or a package name. May be repeated. |
| `--enable-network` | Allow network access (dependency resolution, downloads). |

> **`-p` means `--add-package`, not a component name.** Unlike `azldev comp build -p <name>`,
> `mock shell` has no component selector. `-p <name>` installs a package *by name* from the
> configured repos — it does not set up a chroot with that component's build dependencies.

## Gotchas

- **Don't mix `-p <name>` with `--add-package /path/to/<name>.rpm` for the same package** — that
  installs both the repo build and your local build, which conflict. Use one or the other.
- **The mock chroot is persistent** across `azldev adv mock shell` sessions — installed packages and
  created files survive. Handy (install once, re-enter later), but stale state can confuse. azldev
  has no built-in reset; clear it with `mock` directly (`--scrub=chroot`, or `--scrub=all` to also
  drop the bootstrap), pointing at the project's distro mock config.
- **One mock session per terminal.** Running `azldev adv mock shell` while a terminal is already
  inside a mock shell fails — run `exit` first.

Generated by `azldev docs agent`; do not hand-edit. Generated for azldev version `v0.4.0`.