pacwrap/docs/manual.md

# Pacwrap User Manual

This document was generated by the pacwrap binary with version 0.8.4-43de5c7-RELEASE (14/09/2024) of the program.

## NAME
pacwrap

## SYNOPSIS
pacwrap [**OPERATION** | **VERB**] [**ARGUMENTS**] [**TARGETS**]	

## DESCRIPTION
A package management front-end which utilises libalpm to facilitate the creation of unprivileged, 
namespace containers with parallelised, filesystem-agnostic deduplication. These containers
are constructed with bubblewrap to execute package transactions and launch applications.

This application is designed to allow for the creation and execution of secure, replicable 
containerised environments for general-purpose use. CLI and GUI applications are all supported. 
Once a container environment is configured, it can be re-established or replicated on any system. 

Each long-option parameter can also be specified herein as a command verb for a matter of convenience.
Additional command verb shortcuts are available and are documented alongside their relevancy.

## OPERATIONS
#### **-E, --exec, run**
Invoke a container to execute the provided command sequence.

#### **-S, --sync**
Synchronize package databases and containers in aggregate. 

#### **-R, --remove**
Remove packages from target containers in aggregate.

#### **-C, --compose**
Compose a container from configuration.

#### **-Q, --query**
Query package information from target container.

#### **-P, --process**
Manage and show status of running container processes.

#### **-L, --list**
List available containers managed by pacwrap.

#### **-U, --utils**
Engage miscellaneous utilities to manage containers.

#### **-V, --version**
Display version banner or information.

#### **-h, --help** <**OPERATION** | **VERB** | **TOPIC**>
Print the help manual to **STDOUT**.

## EXECUTE
Invoke a container to execute the provided command sequence. Command verb **`run`** provides a 
shortcut to this module.

#### **<CONTAINER> <CMD>**
Container name to spawn an instance of, along with the proceeding command-line sequence to execute.
execute. All command-line parameters after the container name are passed through to execute inside
of the container environment.

#### **-s, --shell**
Invoke a bash shell in the target container. Command verb **`shell`** provides a shortcut
to this module with this option.

#### **-r, --root**
Execute the provided command sequence with fakeroot and fakechroot.
	
### **EXAMPLES**
#### `$ pacwrap run firefox firefox`
Launch firefox inside an instance of the firefox container.

#### `$ pacwrap shell -r base`
Open a fakeroot bash shell inside an instance of the base container.

## SYNCHRONIZATION
Provides the facilities required to be able to synchronize and create containers in aggregate. 

#### **-y, --refresh**
Synchronize remote package databases. Specify up to 2 times to force a refresh.

#### **-u, --upgrade**
Execute aggregate upgrade routine on all or specified containers. Use **`-t, --target[=CONTAINER]`** followed
by a list of packages to specify package targets. Packages applicable to a target **must** only be specified 
after the target operand.

#### **-c, --create**
Create a container with the first specified target. A container type argument is also required. Command verb 
**`init`** provides a shortcut to the synchronization module, equivalent to specifying the options **`-Syuc`**.

#### **-b, --base**
Base container type. Specify alongside **`-c, --create`** to assign this container type during creation.

This container type is used as the base layer for all downstream containers. Only one base container 
dependency per slice or aggregate is supported. Filesystem and package deduplication via slices and 
aggregate containers are recommended, but optional. This container type is not dependant.

#### **-s, --slice**
Slice container type. Specify alongside **`-c, --create`** to assign this container type during creation.

Requires a base dependency, and optionally one or more sliced dependencies, to ascertain foreign
packages and influence ordering of downstream synchronization target(s). Container slicing provides
the ability to install packages in a lightweight, sliced filesytem, which aid in the deduplication 
of common downstream package and filesystem dependencies.

Useful for graphics drivers, graphical toolkits, fonts, etc.; these are not meant for applications.

#### **-a, --aggegrate**
Aggregate container type. Specify alongside **`-c, --create`** to this assign container type during creation.

Requires a base dependency, and optionally one or more sliced dependencies, in order to acertain foreign
packages and amalgamate the target. These containers are ideal for installing software with the aid of
filesystem and package deduplication. 

Useful for all general purpose applications, browsers, e-mail clients, or even terminal user interface 
applications such as IRC clients. It is recommended to base your containers on aggregate type containers.

#### **-t, --target** <**CONTAINER**> <..**PACKAGE**>
Declare a target container for the specified operation, followed by a list of package target(s).

#### **-f, --filesystem**
Force execution of filesystem synchronization target on all or specified containers. In combination 
with **-o/--target-only**, in addition to no other specified targets, filesystems will be synchronized 
without package synhcronization on on all applicable containers. This operation is useful for propagation 
of manual filesystem changes to all aggregate containers.

#### **-o, --target-only**
Apply specified operation on the specified target(s) only.

#### **-d, --dep** <**CONTAINER**>
Specify dependencies for a container create operation.

#### **-p, --preview**
Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified.
Only applicable to pre-existing targets and not create operations.

#### **-l, --lazy-load**
Enable lazy-database initialization for this transaction. **NOTE**: This feature is experimental.
Edge cases exist wherein the use of **`--force-foreign`** may be required.

#### **--force-foreign**
Force synchronization of foreign packages on resident container. Useful for when installing 
a new package in an aggregate container without all the prerequisite foreign dependencies
synchronized to the resident container's package database.

#### **--dbonly**
Transact on resident containers with a database-only transaction.

#### **--noconfirm**
Override confirmation prompts and confirm all operations.

#### **--disable-sandbox**
Instruct libalpm to disable its own sandbox, utilizing landlock and seccomp, in order to mitigate potential
issues with kernel compatibillity.

#### **--debug**
Use this option when reporting bugs.

### **EXAMPLES**
#### `$ pacwrap init --base --target base`
Synchronize remotes and create a base-type container named `base` with no additional packages.

#### `$ pacwrap -Syucst common gtk3 qt6-base --dep=base -st nvidia nvidia-utils --dep=base,common`
Synchronize remote databases, create two sliced containers, one named `common` with the packages 
`gtk3`, `qt6-base`, and another named `nvidia` with the package `nvidia-utils`.

#### `$ pacwrap -Syucat mozilla firefox --dep=base,common,nvidia`
Synchronize remote databases and upgrade container dependencies, then create aggregate container 
named `mozilla` with the package `firefox`.

#### `$ pacwrap -Sot mozilla thunderbird`
Install `thunderbird` in the target container `mozilla`.

#### `$ pacwrap -Sof`
Synchronize filesystem state of all associated containers present in the data directory.

## REMOVE
Remove packages from specified containers.

#### **-s, --recursive**
Recursively remove all target packages with the associated target container. This does
not apply to packages upstream of a downstream container.

#### **-c, --cascade**
Remove all target packages with the associated target container, including all their 
associated dependencies, provided they are not required by other packages, and are not
marked as being upstream of the target container.

#### **-t, --target** <**CONTAINER**>
Specify a target container for the specified operation. At least one container target is 
is required for package removal operations.

#### **--force-foreign**
Force the removal of foreign packages on target container. Useful for cleaning up
the package database of foreign, upstream dependencies synchronized to the target
container's package database.

#### **-m, --delete**
Delete root filesystem(s) of specified targets. Shortcout to **-Ur**.

#### **-p, --preview**
Preview operation and perform no transaction.

#### **--dbonly**
Transact on resident containers with a database-only transaction.

#### **--noconfirm**
Override confirmation prompts and confirm all operations.

#### **--disable-sandbox**
Instruct libalpm to disable its own sandbox, utilizing landlock and seccomp, in order to mitigate potential
issues with kernel compatibillity.

#### **--debug**
Use this option when reporting bugs.

### **EXAMPLES**
#### `$ pacwrap -Rt firefox firefox`
Remove the target package firefox from target container firefox.

#### `$ pacwrap rm firefox`
Delete the root filesystem for the firefox container.

## COMPOSE
Compose containers from container configuration files. This functionality provides a way
to deterministically compose containers from an established configuration.

#### **<FILE_PATH>**
Compose a container from the specified configuration file on disk. Unless a target is
otherwise specified, the container will be initialized with a name derived from the
filename provided.

#### **-r, --reinitialize**
Compose an available, existing container for composition. The pre-existing container root
will be deleted and the container will be composited from the configuration data enumerated.

#### **-t, --target** <**CONTAINER**>
Specify a target container for the specified operation.

#### **-f, --force**
Disable sanity checks and force removal of container filesystem(s).

#### **--reinitialize-all**
Queues all available, existing containers for composition. All pre-existing container roots
will be deleted and composited from the available configuration data enumerated.

#### **-l, --lazy-load**
Enable lazy-database initialization for this transaction. **NOTE**: This feature is experimental.
Edge cases exist wherein the use of **`--force-foreign`** may be required.

#### **--from-config**
Instruct pacwrap to populate configuration data from uninitialized containers. Under normal
circumstances, configuration data will only be populated from containers with configuration
data and an associative container root present. This option engages an alternate enuermation 
pathway to allow composition of dormant, uninitialized container configurations.

#### **--noconfirm**
Override confirmation prompts and confirm all operations.

#### **--disable-sandbox**
Instruct libalpm to disable its own sandbox, utilizing landlock and seccomp, in order to mitigate potential
issues with kernel compatibillity.

#### **--debug**
Use this option when reporting bugs.

### **EXAMPLES**
#### `$ pacwrap compose -rt element element.yml`
Reinitialize an existing container named element with its configuration derived 
from the file 'element.yml'.

#### `$ pacwrap compose --reinitialize-all --from-config`
Reinitialize all container configurations available in '**$PACWRAP_CONFIG_DIR**/container/'.

## QUERY
Query package list on target container.

#### **-q, --quiet**
Quiet the output by truncating the package string.

#### **-t, --target** <**CONTAINER**>
Specify a target container for the specified operation.

#### **-e, --explicit**
Filter output to explicitly-marked packages.

### **EXAMPLE**
#### `$ pacwrap -Qqe base`
Print a list of explicit packages from the **base** container to **STDOUT**.

## PROCESS
Table a process list of running containers. Containers may be filtered on target and process depth.

#### **-s, --summary**
Enumerate a process summary of containers instantiated by pacwrap.

#### **-i, --id-list**
Enumerate a process id list of containers instantiated by pacwrap. 

#### **-k, --kill**
Kill target containers and their associated processes.

#### **-a, --all**
Target all containers and enumerate their associated processes.

#### **-d, --depth**
Enumerate all processes at the specified depth associated with running containers.

#### **-t, --target** <**CONTAINER**>
Specify a target container for the specified operation.

#### **--noconfirm**
Override confirmation prompts and confirm all operations.

### **EXAMPLES**
#### `$ pacwrap -Psaxc`
Print table enumerating all container processes to **STDOUT** with process arguments
and execution path split into separate columns.

#### `$ ps up "$(pacwrap -Pia)"`
Enumerate container processes with `ps` via encapsulating an enumeration of pids from all instances
into a space-delimited bash string.

## LIST
List all initialized containers presently managed by pacwrap. 

This command module is a shortcut to **-Ul**. Command verb **`ls`** also is a
shortcut to this command module.

#### **-t, --total**
Display a total column.

#### **-o, --on-disk**
Display a size on disk column.

#### **-b, --bytes**
Toggle byte unit display.

### **EXAMPLES**
#### `$ pacwrap -Ld`
Print container tabulation out to **STDOUT** with two total columns, one listing the
container name, and the other detailing the total size-on-disk consumption displayed with byteunits.

#### `$ pacwrap ls -btbts`
Print container tabulation to **STDOUT** with three total columns, first listing the
container name, second the total amount of bytes, and the last showing the total with byteunits. 
Then print a summation of total, actual consumption below.

## UTILITIES
Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and
maintenance of containers. Each utility is considered a command module and therefore can be shortcuted
with a command verb.

#### **-d, --desktop**
Create desktop file to launch application inside of a pacwrap container.

#### **-v, --view**
Invoke **$EDITOR** to view file associated with pacwrap.

#### **-e, --edit**
Invoke **$EDITOR** to edit file associated with pacwrap.

#### **-o, --open**
Invoke default file viewer on specified target's home or root directory.

#### **-l, --list**
Print a list of containers and basic metrics.

#### **-s, --symlink**
Create a symbolic container.

#### **-r, --remove**
Delete a container(s) root filesystem.

### **DESKTOP OPTIONS**
Create and manage desktop files to launch applications in pacwrap from your favourite applications menu.

#### **-c, --create** <**CONTAINER**> <**APPLICATION**>
Create desktop file associated with application at `$HOME/.local/share/applications/` launching an 
application in pacwrap.

#### **-l, --list** <**CONTAINER**>
List available desktop files in the container root located at `/usr/share/applications/`.

#### **-r, --remove** <**APPLICATION**>
Remove desktop file associated with application from `$HOME/.local/share/applications/`. 

### **EDITOR OPTIONS**
These options are associated with the **--edit** and **--view** utility command modules.

#### **-c, --config** <**CONTAINER**>
Edit specified container configuration located in the pacwrap data directory. Defaults to
the primary configuration file: '**$PACWRAP_CONFIG_DIR**/pacwrap.yml' if no option is otherwise
specified.

#### **-d, --desktop** <**APPLICATION**>
Edit specified desktop file associated with a pacwrap container.

#### **-r, --repo**
Edit repositories configuration file: `$PACWRAP_CONFIG_DIR/repositories.conf`.

#### **-l, --log**
View 'pacwrap.log'. This file contains transaction log iformation.

### **OPEN OPTIONS**
These options are associated with the **--open** utility command module.

#### **-h, --home** <**CONTAINER**>
Specified container's home filesystem.

#### **-r, --root** <**CONTAINER**>
Specified container's root filesystem.

#### **-t, --target** <**CONTAINER**>
Target container to perform the operation.

### **LIST**
These options are associated with the **--list** utility command module.

#### **-t, --total**
Display a total column.

#### **-d, --on-disk**
Display a size on disk column.

#### **-s, --summary**
Print out a summary table to **STDOUT**.

#### **-b, --bytes**
Toggle byte unit display for the proceeding item.

### **REMOVE OPTIONS**
These options are associated with the **--remove** utility command module.

#### **-t, --target** <**CONTAINER**>
Target container to perform the operation.

#### **--noconfirm**
Peform the operation without confirmation.

#### **--force**
Disable sanity checks and force removal of conatiner filesystem.

### **SYMBOLIC**
These options are associated with the **--symlink** utility command module.

#### **<TARGET> <DEST>**
Create a symbolic container of target at destination.

#### **-n, --new**
Create a fresh configuration rather than derive it from the target.

### **EXAMPLES**
#### `$ pacwrap -Uoh firefox`
Open firefox's home directory in the default file manager.

#### `$ pacwrap -Uvl`
View `**$PACWRAP_DATA_DIR**/pacwrap.log` with **$EDITOR**.

#### `$ pacwrap -Uec firefox`
Edit `$PACWRAP_CONFIG_DIR**/container/firefox.yml` with **$EDITOR**.

#### `$ pacwrap utils -dc firefox firefox`
Create desktop file `$HOME/.local/share/applications/pacwrap.firefox.desktop` derived from
`/usr/share/applications/firefox.desktop` in the root of the firefox container.

#### `$ pacwrap utils symlink java runelite`
Create a symbolic container called `runelite` of `java`.

#### `$ pacwrap -Uld`
Print container tabulation out to **STDOUT** with two total columns, one listing the
container name, and the other detailing the total size-on-disk consumption displayed with byteunits.

#### `$ pacwrap utils -lbtbts`
Print container tabulation to **STDOUT** with three total columns, first listing the
container name, second the total amount of bytes, and the last showing the total with byteunits. 
Then print a summation of total, actual consumption below.

## VERSION
#### **-V, --version, --version=min**
Sends version information to **STDOUT** with colourful ASCII art. 
The 'min' option provides a minimalistic output as is provided to non-colour terms.

## HELP
#### **-h, --help** <**TOPIC**>
Print the specified topic to **STDOUT**.

#### **-m, --more**
When specifying a topic to display, show the default topic in addition to specified options.

#### **-f, --format** <**FORMAT**>
Change output format of help in **STDOUT**. Format options include: 'ansi', 'dumb', 'markdown', and 'man'. 
This option is for the express purposes of generating documentation at build time, and has little utility
outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages.

#### **-a, --all, --help=all**
Display all help topics.

## ENVIRONMENT
Provided herein are environment variables of which can be used to configure pacwrap's runtime parameters.
All environment variables listed are case sensitive.

Use with care: These variables if used improperly could result in undesired behaviour.

#### **PACWRAP_CONFIG_DIR** <**DIR**>
Set path of the configuration directory, overriding the default location.

#### **PACWRAP_DATA_DIR** <**DIR**>
Set path of the data directory, overriding the default location.

#### **PACWRAP_CACHE_DIR** <**DIR**> 
Set path of the cache directory, overriding the default location.

#### **PACWRAP_HOME** <**DIR**>
Upon container invocation, mount the set path provided when engaging the **`home`** filesystem module.

#### **PACWRAP_ROOT** <**DIR**>
Upon container invocation, mount the set path provided when engaging the **`root`** filesystem module.

#### **PACWRAP_VERBOSE** <**0** | **1**>
Toggle verbose output during a transaction. Valid options are `1` for enablement and `0` for 
disablement of verbosity.

### **DEFAULT**
For the following environment variables, contained herein are default runtime values. Any variables not
included here in this subsection are to be assumed to have inert values by default.

#### **PACWRAP_CACHE_DIR**
`$HOME/.cache/pacwrap`: Default cache directory.

#### **PACWRAP_CONFIG_DIR**
`$HOME/.config/pacwrap`: Default configuration directory.

#### **PACWRAP_DATA_DIR**
`$HOME/.local/share/pacwrap`: Default data directory.

## AUTHOR
Copyright (C) 2023-2024 Xavier Moffett <sapphirus@azorium.net>

## LICENSE
This program may be freely redistributed under the terms of the GNU General Public License v3 only.