Update documentation to reflect 5e9211a530
and inclusion of dbus module docs - Updated pacwrap.1 manpage and manual.md - Dbus module documentation enumerating the available modules to configure xdg-dbus-proxy in containers
This commit is contained in:
parent
5e9211a530
commit
de42ff8960
7 changed files with 371 additions and 203 deletions
232
docs/manual.md
232
docs/manual.md
|
|
@ -1,12 +1,12 @@
|
|||
# Pacwrap User Manual
|
||||
|
||||
This document was generated by the pacwrap binary with version 0.8.0-a444442-RELEASE (30/03/2024) of the program.
|
||||
This document was generated by the pacwrap binary with version 0.8.0-6fedde1-RELEASE (05/04/2024) of the program.
|
||||
|
||||
## NAME
|
||||
pacwrap
|
||||
|
||||
## SYNOPSIS
|
||||
pacwrap [**OPERATION** | **COMMAND MODULE**] [**ARGUMENTS**] [**TARGETS**]
|
||||
pacwrap [**OPERATION** | **VERB**] [**ARGUMENTS**] [**TARGETS**]
|
||||
|
||||
## DESCRIPTION
|
||||
A package management front-end which utilises libalpm to facilitate the creation of unprivileged,
|
||||
|
|
@ -17,45 +17,64 @@ This application is designed to allow for the creation and execution of secure,
|
|||
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 update packages in target containers.
|
||||
Synchronize package databases and containers in aggregate.
|
||||
|
||||
#### **-R, --remove**
|
||||
Remove packages from target containers.
|
||||
|
||||
#### **-Q, --query**
|
||||
Query package information from target container.
|
||||
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.
|
||||
|
||||
#### **-E, --execute**
|
||||
Executes application in target container using bubblewrap.
|
||||
|
||||
#### **-L, --list**
|
||||
List of available containers managed by pacwrap.
|
||||
List available containers managed by pacwrap.
|
||||
|
||||
#### **-U, --utils**
|
||||
Invoke miscellaneous utilities to manage containers.
|
||||
Engage miscellaneous utilities to manage containers.
|
||||
|
||||
#### **-h, --help=MODULE**
|
||||
Invoke a printout of this manual to **STDOUT**.
|
||||
#### **-h, --help, --help=[OPERATION | VERB]**
|
||||
Print this manual to **STDOUT**.
|
||||
|
||||
#### **-V, --version**
|
||||
Display version and copyright information in **STDOUT**.
|
||||
Display version banner or information.
|
||||
|
||||
## EXECUTE
|
||||
#### **-r, --root**
|
||||
Execute operation with fakeroot and fakechroot. Facilitates a command with faked privileges.
|
||||
|
||||
#### **-s, --shell**
|
||||
Invoke a bash shell
|
||||
Invoke a container to execute the provided command sequence. Command verb `**run**` provides a
|
||||
shortcut to this module.
|
||||
|
||||
## SYNCHRONIZATION
|
||||
#### **<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**
|
||||
|
|
@ -66,14 +85,9 @@ Execute aggregate upgrade routine on all or specified containers. Use **-t, --ta
|
|||
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.
|
||||
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.
|
||||
|
|
@ -84,6 +98,7 @@ aggregate containers are recommended, but optional. This container type is not d
|
|||
|
||||
#### **-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
|
||||
|
|
@ -101,23 +116,32 @@ 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.
|
||||
#### **-t, --target=<TARGET>**
|
||||
Declare a target container for the specified operation.
|
||||
|
||||
#### **-d, --dep=DEPEND**
|
||||
Specify a dependent container for the specified operation.
|
||||
#### **<PACKAGE>**
|
||||
Package target declared for target container specified.
|
||||
|
||||
#### **-p, --preview**
|
||||
Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified.
|
||||
Only applicable to
|
||||
#### **-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.
|
||||
|
||||
#### **--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.
|
||||
synchronized to the resident container's package database.
|
||||
|
||||
#### **--dbonly**
|
||||
Transact on resident containers with a database-only transaction.
|
||||
|
|
@ -126,19 +150,19 @@ Transact on resident containers with a database-only transaction.
|
|||
Override confirmation prompts and confirm all operations.
|
||||
|
||||
### **EXAMPLES**
|
||||
#### `$ pacwrap -Syucbt base`
|
||||
Create a base container named base with no additional packages
|
||||
#### `$ pacwrap init --base --target base`
|
||||
Synchronize remotes and create a base-type container named `base` with no additional packages.
|
||||
|
||||
#### `$ pacwrap -Syucbt firefox firefox --dep=base,common,nvidia`
|
||||
Create aggregate container named firefox with firefox installed.
|
||||
#### `$ 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 -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 -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 -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 -Sot mozilla thunderbird`
|
||||
Install `thunderbird` in the target container `mozilla`.
|
||||
|
||||
#### `$ pacwrap -Sof`
|
||||
Synchronize filesystem state of all associated containers present in the data directory.
|
||||
|
|
@ -183,7 +207,6 @@ 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.
|
||||
|
|
@ -197,8 +220,6 @@ filename provided.
|
|||
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.
|
||||
|
||||
|
|
@ -224,10 +245,10 @@ 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/'.
|
||||
Reinitialize all container configurations available in '**$PACWRAP_CONFIG_DIR**/container/'.
|
||||
|
||||
## QUERY
|
||||
Query package list on target container. This module presently is not complete.
|
||||
Query package list on target container.
|
||||
|
||||
#### **-q, --quiet**
|
||||
Quiet the output by truncating the package string.
|
||||
|
|
@ -268,9 +289,34 @@ Override confirmation prompts and confirm all operations.
|
|||
Print table enumerating all container processes to **STDOUT** with process
|
||||
arguments and execution path split into separate columns.
|
||||
|
||||
## 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 operate containers.
|
||||
maintenance of containers.
|
||||
|
||||
#### **-v, --view**
|
||||
Invoke **$EDITOR** to view file associated with pacwrap.
|
||||
|
|
@ -356,31 +402,31 @@ Create a symbolic container of target at destination.
|
|||
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 -Uoh firefox`
|
||||
Open firefox's home directory in the default file manager.
|
||||
|
||||
#### `$ pacwrap -Us java runelite`
|
||||
Create a symbolic container called `runelite` of `java`.
|
||||
|
||||
#### `$ pacwrap -Uvl`
|
||||
View '**$PACWRAP_DATA_DIR**/pacwrap.log' with **$EDITOR**.
|
||||
|
||||
## LIST
|
||||
List all initialized containers presently managed by pacwrap.
|
||||
#### `$ pacwrap -Uec firefox`
|
||||
Edit '**$PACWRAP_CONFIG_DIR**/container/firefox.yml' with **$EDITOR**.
|
||||
|
||||
This command module is a shortcut to **-Ul**.
|
||||
#### `$ 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.
|
||||
|
||||
#### **-t, --total**
|
||||
Display a total column.
|
||||
#### `$ pacwrap -Ulbtbts`
|
||||
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.
|
||||
|
||||
#### **-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.
|
||||
## 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
|
||||
#### **-m, --more**
|
||||
|
|
@ -394,36 +440,42 @@ outside the context of package maintenance. 'man' option produces troff-formatte
|
|||
#### **-a, --all, --help=all**
|
||||
Display all help topics.
|
||||
|
||||
## ENVIRONMENT VARIABLES
|
||||
## 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**
|
||||
Set the configuration directory. This environment variable overrides the default,
|
||||
XDG Directory Specification compliant path.
|
||||
#### **PACWRAP_CONFIG_DIR=<DIR>**
|
||||
Set the configuration directory, overriding the default location.
|
||||
|
||||
#### **PACWRAP_DATA_DIR**
|
||||
Set the data directory. This environment variable overrides the default,
|
||||
XDG Directory Specification compliant path.
|
||||
#### **PACWRAP_DATA_DIR=<DIR>**
|
||||
Set the data directory, overriding the default location.
|
||||
|
||||
#### **PACWRAP_CACHE_DIR**
|
||||
Set the cache directory. This environment variable overrides the default,
|
||||
XDG Directory Specification compliant path.
|
||||
#### **PACWRAP_CACHE_DIR=<DIR>**
|
||||
Set the cache directory, overriding the default location.
|
||||
|
||||
#### **PACWRAP_VERBOSE=[0|1]**
|
||||
Toggle verbose output during a transaction. This option may be removed or otherwise
|
||||
differ in functionality in future.
|
||||
Toggle verbose output during a transaction. This option may be subject to change.
|
||||
|
||||
#### **PACWRAP_HOME**
|
||||
Upon execution, mount the set path provided when engaging the 'home' module.
|
||||
#### **PACWRAP_HOME=<DIR>**
|
||||
Upon container invocation, mount the set path provided when engaging the '**home**' filesystem module.
|
||||
|
||||
#### **PACWRAP_ROOT**
|
||||
Upon execution, Mount the set path provided when engaging the 'root' module.
|
||||
#### **PACWRAP_ROOT=<DIR>**
|
||||
Upon container invocation, mount the set path provided when engaging the '**root**' filesystem 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.
|
||||
### **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.
|
||||
|
||||
## COPYRIGHT
|
||||
Copyright (C) 2023-2024 Xavier R.M.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue