# Quick Start

Install and run ISO Scalpel in under five minutes.

> **Prerequisite:** Python 3.10+. Check with `python3 --version`.

## Install

```bash
tar xzf iso-scalpel-1.1.0.tar.gz
cd iso-scalpel-1.1.0

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt
```

> **On Arch / Fedora / Debian 12+ (PEP 668 distros):** do **not** run
> `pip install` against the system Python -- it will be refused with
> `externally-managed-environment`.  Always use a project venv as shown
> above, install the distro packages (`sudo pacman -S python-pyside6
> python-pycdlib`), or `pipx install iso-scalpel` once published.  If
> you launch `python main.py` without dependencies installed, ISO
> Scalpel will detect your distro and offer the right install command.

On minimal Linux, also install the Qt runtime libraries:

```bash
sudo apt install libegl1 libgl1 libglib2.0-0 libfontconfig1 \
                 libdbus-1-3 libxkbcommon0 libxcb-cursor0
```

## GUI

```bash
python main.py                     # empty window
python main.py my_image.iso        # open an image
python main.py --check-deps        # report any missing dependencies and exit
python main.py --no-install-deps   # never prompt to install missing deps
```

If a required Python package (`PySide6`, `pycdlib`) is missing when you
launch the GUI, ISO Scalpel will print a clear, copy-pasteable message
listing exactly what's missing and the right install command for your
distro (e.g. `pacman -S python-pycdlib` on Arch, `apt-get install
python3-pycdlib` on Debian/Ubuntu, `dnf install python3-pycdlib` on
Fedora).  When run from an interactive terminal it offers install
strategies in order of lowest privilege first:

1. **Project venv** (recommended on PEP 668 distros like Arch):
   `python -m venv .venv && .venv/bin/pip install ...` -- no sudo, no
   system mutation.  Afterwards run `./.venv/bin/python main.py`.
2. **Distro package manager** with `sudo` (e.g. `sudo pacman -S
   python-pycdlib`): shown with the exact command first, runs only after
   you type `y`.
3. **`pip install --user --break-system-packages`**: last-resort override
   for PEP 668, only with explicit consent.

> **Note on pipx:** `pipx install pycdlib` installs pycdlib into an
> isolated venv that exports only its CLI tools (`pycdlib-explorer`
> etc.) to your PATH.  The Python module is **not** importable from your
> system interpreter, so ISO Scalpel will still report it as missing.
> For libraries, use a project venv or the distro package instead.  For
> the ISO Scalpel application itself, you can `pipx install iso-scalpel`
> once it's published (see `pyproject.toml`).

Pass `--no-install-deps` to skip the prompts and just exit.

The window has two panes. By default the left pane is the filesystem and
the right pane is the ISO image. Each pane has breadcrumb navigation,
back/forward/up arrows, a filter box, and a tab bar. Press
`Ctrl+Shift+X` to swap the panes.

### Create an image

1. **Image → New…** (`Ctrl+N`).
2. Set the volume label.
3. Tick the extensions: Joliet, Rock Ridge, UDF.
4. Pick the ISO 9660 interchange level.
5. Click **OK**.

### Add files

Drag files from the filesystem pane onto a directory in the ISO pane.
Or select them and press `Insert`. Files are written into every enabled
naming convention; ISO 9660 names are mangled to valid 8.3 with
collision avoidance.

### Extract

Select entries in the ISO pane and press `Ctrl+E`.

### Make it bootable

**Tools → Boot Image…** (`Ctrl+B`). Pick a boot image, the platform ID
(x86 / EFI), and the media type. The boot file is added to the image
and the boot catalog is generated.

### Compare two images

**Tools → Compare Images…** (`Ctrl+D`). Pick image A and image B, click
**Compare**. The tree shows added (`+`), removed (`-`), modified (`M`),
and unchanged (`=`) entries. File contents are not compared — only the
filesystem structure.

## CLI

```bash
python cli.py --help
```

### Create an image

```bash
python cli.py new disc.iso -l MYDISC \
    --joliet 3 --rock-ridge 1.09 --udf 2.60 \
    --add readme.txt
```

### List contents

```bash
python cli.py list disc.iso
python cli.py list disc.iso / --view udf
python cli.py list disc.iso -r        # recursive
```

### Show metadata

```bash
python cli.py info disc.iso
```

### Add to an image

```bash
python cli.py add disc.iso ./file.txt /
python cli.py add disc.iso ./folder /sub
```

### Extract

```bash
python cli.py extract disc.iso /readme.txt ./out.txt
python cli.py extract disc.iso /sub ./out_dir
```

### Remove an entry

```bash
python cli.py rm disc.iso /old.txt
```

### Configure boot

```bash
python cli.py boot disc.iso --set boot.img --platform 0
python cli.py boot disc.iso --set efi.img --platform 0xEF
python cli.py boot disc.iso --clear
```

### Diff two images

```bash
python cli.py diff old.iso new.iso
python cli.py diff old.iso new.iso --all
```

## Scripting

The handler and diff engine are importable directly:

```python
from iso_scalpel.iso_handler import IsoHandler, NewIsoOptions
from iso_scalpel.diff import diff_images, format_diff_text

iso = IsoHandler()
iso.new(NewIsoOptions(volume_label="BACKUP", udf="2.60", joliet=3))
iso.add_file("readme.txt", "/", iso.default_name_type())
iso.save("backup.iso")
iso.close()

# compare two images
a = IsoHandler(); a.open("old.iso")
b = IsoHandler(); b.open("new.iso")
print(format_diff_text(diff_images(a, b)))
```

## Lint and tests

The project ships with a locked-in `ruff` configuration (PEP 8, SEI CERT,
MISRA-aligned immutability, POSIX shebang discipline). Run both before
pushing:

```bash
pip install -e '.[dev]'     # pytest + ruff
ruff check .                # must report "All checks passed!"
python -m pytest            # hermetic deps tests always run; GUI tests
                            # self-skip when PySide6 / pycdlib are absent
```

See [README.md · Coding standards](README.md#coding-standards) for the
full rule set and the rationale behind each.

## Where to go next

- [README.md](README.md) — full feature list and API reference
- [BLOG.md](BLOG.md) — what's new in this release
- `iso_scalpel/iso_handler.py` — the core engine (read the docstrings)
- `iso_scalpel/diff.py` — the diff engine
- `~/.config/iso-scalpel/settings.json` — application settings