osi-tools/Documentation/README.md

# osi-tools: Operating System Image Tools

<!--
Copyright (C) 2018  Luke Shumaker
Copyright (C) 2023-2024  Umorpha Systems
SPDX-License-Identifier: AGPL-3.0-or-later
-->

## Usage

	$ ./bin/osi-mk [FLAGS] SYS.img                               # to build an image
	$ ./bin/osi-shell SYS.img                                    # launch an interactive shell in an emulator
	$ sudo ./bin/osi-mount --{root|user} SYS.img MNT COMMAND     # run command with SYS.img mounted at MNT
	$ sudo ./bin/osi-extract SYS.img IMAGE_SRC_DIR HOST_DST_DIR  # to extract files from an image

## Dependencies

I believe the complete list of dependencies is (along with what I
believe is the newest feature that is depended on):

 - arch-install-scripts
 - btrfs-progs
 - GNU Bash 4.4 (needs `@Q`)
 - GNU coretutils 8.15 (needs `realpath`)
 - GNU gettext
 - QEMU (needs `qemu-system-x86_64`)
 - sed
 - sudo
 - util-linux-ng 2.18 or newer (needs automatic loop devices in `mount`)

This can be install on a Parabola Parabola GNU/Linux-libre system with
the following command:

	sudo pacman -S --needed arch-install-scripts btrfs-progs bash coreutils gettext qemu-system-x86 sed sudo util-linux

The tests require

 - BATS
 - bats-support
 - bats-assert
 - bats-file

## Developing

You can lint the code in this repository by running `make lint`, which
requires the `shellcheck` command.

The tests can run in parallel, obeying Make's `-j`/`--jobs` flag.
Some of the tests write several gigabytes to `$TMPDIR`; 3GB of space
on `$TMPDIR` is plenty when run serially, but is not enough when run
in parallel.