213 lines
6.2 KiB
Markdown
Executable File
213 lines
6.2 KiB
Markdown
Executable File
# 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
|