# Pacwrap User Manual

This document was generated by the pacwrap binary with version 0.7.2-91b5c79-RELEASE (30/03/2024) of the program.

## NAME
pacwrap

## SYNOPSIS
pacwrap [**OPERATION** | **COMMAND MODULE**] [**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. 

## OPERATIONS
#### **-S, --sync**
Synchronize package databases and update packages in target containers. 

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

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

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

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

#### **-E, --execute**
Executes application in target container using bubblewrap.

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

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

#### **-h, --help=<MODULE>**
Invoke a printout of this manual to **STDOUT**.

#### **-V, --version**
Display version and copyright information in **STDOUT**.

## EXECUTE
#### **-r, --root**
Execute operation with fakeroot and fakechroot. Facilitates a command with faked privileges.
	
#### **-s, --shell**
Invoke a bash shell

## 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=<TARGET>** followed by
a list of packages to specify package targets. Packages applicable to a target **must** only be specified 
after the target operand.

#### **-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, filesystem slices 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.

#### **-c, --create**
Create a container with the first specified target. A container type argument is also required.

#### **-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=TARGET**
Specify a target container for the specified operation.

#### **-d, --dep=DEPEND**
Specify a dependent container for the specified operation.

#### **-p, --preview**
Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified.
Only applicable to 

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

#### **--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 this container's package database.

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

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

### **EXAMPLES**
#### `$ pacwrap -Syucbt base`
Create a base container named base with no additional packages

#### `$ pacwrap -Syucbt firefox firefox --dep=base,common,nvidia`
Create aggregate container named firefox with firefox installed.

#### `$ pacwrap -Syut electron element-desktop -t mozilla firefox thunderbird`
Synchronize package databases and upgrade all containers, as well as install element-desktop 
in the target electron, and install firefox and thunderbird in the target mozilla.

#### `$ pacwrap -Syucst common gtk3 qt6-base --dep=base -cst nvidia nvidia-utils --dep=base,common`
Create two sliced containers, one named common with the packages gtk3, qt6-base, and another 
named nvidia with the package nvidia-utils.

#### `$ 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=TARGET**
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.

### **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.

Reinitialize container 

#### **-t, --target=TARGET**
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.

#### **--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.

### **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 available containers as configured in '**$PACWRAP_CONFIG_DIR**/container/'.

## QUERY
Query package list on target container. This module presently is not complete.

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

#### **-t, --target=TARGET**
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 being executed by pacwrap.

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

#### **-a, --all**
Enumerate all processes associated with running containers.

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

#### **-t, --target=TARGET**
Specify a target container for the specified operation.

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

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

## UTILITIES
Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and
maintenance of operate containers.

#### **-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.

### **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 information.

### **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**
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 -Ulbtbts`
Print table listing containers out to **STDOUT** with two total columns, one showing
the total amount of bytes. Then print a summary calculation of total consumption below.

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

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

This command module is a shortcut to **-Ul**.

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

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

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

### **EXAMPLE**
#### `$ pacwrap ls -btbts`
Print table listing containers out to **STDOUT** with two total columns, one showing
the total amount of bytes. Then print a summary calculation of total consumption below.

## HELP
#### **-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 VARIABLES
Provided herein are environment variables of which can be used to configure pacwrap's runtime parameters.
Use with care: These variables if used improperly could result in undesired behaviour.

#### **PACWRAP_CONFIG_DIR**
Set the configuration directory. This environment variable overrides the default, 
XDG Directory Specification compliant path. 

#### **PACWRAP_DATA_DIR**
Set the data directory. This environment variable overrides the default, 
XDG Directory Specification compliant path. 

#### **PACWRAP_CACHE_DIR**
Set the cache directory. This environment variable overrides the default, 
XDG Directory Specification compliant path. 

#### **PACWRAP_VERBOSE=[0|1]**
Toggle verbose output during a transaction. This option may be removed or otherwise
differ in functionality in future.

#### **PACWRAP_HOME**
Upon execution, mount the set path provided when engaging the 'home' module.

#### **PACWRAP_ROOT**
Upon execution, Mount the set path provided when engaging the 'root' module.

## 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.

## COPYRIGHT
Copyright (C) 2023-2024 Xavier R.M.

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