pacwrap/pacwrap
pacwrap/pacwrap
1
0
Fork 0
Code Issues Activity Actions

Update documentation to reflect 5e9211a530

Browse source 
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:
Xavier Moffett 2024-04-05 23:35:41 -04:00
parent 5e9211a530
commit de42ff8960
7 changed files with 371 additions and 203 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

276
dist/man/pacwrap.1 vendored
View file

@ -1,5 +1,5 @@
.nh .nh
.TH pacwrap 1 "30/03/2024" "pacwrap version_string_placeholder" "User Manual" .TH pacwrap 1 "05/04/2024" "pacwrap version_string_placeholder" "User Manual"
.SH .SH
NAME\fR NAME\fR
@ -7,7 +7,7 @@ pacwrap
.SH .SH
SYNOPSIS\fR SYNOPSIS\fR
pacwrap [\fBOPERATION\fR | \fBCOMMAND MODULE\fR] [\fBARGUMENTS\fR] [\fBTARGETS\fR] pacwrap [\fBOPERATION\fR | \fBVERB\fR] [\fBARGUMENTS\fR] [\fBTARGETS\fR]
.SH .SH
DESCRIPTION\fR DESCRIPTION\fR
@ -21,60 +21,85 @@ 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. 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. Once a container environment is configured, it can be re-established or replicated on any system.
.PP
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.
.SH .SH
OPERATIONS\fR OPERATIONS\fR
.TP
\fB-E, --exec, run\fR
Invoke a container to execute the provided command sequence.
.TP .TP
\fB-S, --sync\fR \fB-S, --sync\fR
Synchronize package databases and update packages in target containers. Synchronize package databases and containers in aggregate.
.TP .TP
\fB-R, --remove\fR \fB-R, --remove\fR
Remove packages from target containers. Remove packages from target containers in aggregate.
.TP
\fB-Q, --query\fR
Query package information from target container.
.TP .TP
\fB-C, --compose\fR \fB-C, --compose\fR
Compose a container from configuration. Compose a container from configuration.
.TP
\fB-Q, --query\fR
Query package information from target container.
.TP .TP
\fB-P, --process\fR \fB-P, --process\fR
Manage and show status of running container processes. Manage and show status of running container processes.
.TP
\fB-E, --execute\fR
Executes application in target container using bubblewrap.
.TP .TP
\fB-L, --list\fR \fB-L, --list\fR
List of available containers managed by pacwrap. List available containers managed by pacwrap.
.TP .TP
\fB-U, --utils\fR \fB-U, --utils\fR
Invoke miscellaneous utilities to manage containers. Engage miscellaneous utilities to manage containers.
.TP .TP
\fB-h, --help=<MODULE>\fR \fB-h, --help, --help=[OPERATION | VERB]\fR
Invoke a printout of this manual to \fBSTDOUT\fR. Print this manual to \fBSTDOUT\fR.
.TP .TP
\fB-V, --version\fR \fB-V, --version\fR
Display version and copyright information in \fBSTDOUT\fR. Display version banner or information.
.SH .SH
EXECUTE\fR EXECUTE\fR
.PP
Invoke a container to execute the provided command sequence. Command verb `\fBrun\fR` provides a
shortcut to this module.
.TP .TP
\fB-r, --root\fR \fB<CONTAINER> <CMD>\fR
Execute operation with fakeroot and fakechroot. Facilitates a command with faked privileges. 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.
.TP .TP
\fB-s, --shell\fR \fB-s, --shell\fR
Invoke a bash shell Invoke a bash shell in the target container. Command verb `\fBshell\fR` provides a shortcut
to this module with this option.
.TP
\fB-r, --root\fR
Execute the provided command sequence with fakeroot and fakechroot.
.SS
EXAMPLES\fR
.TP
`$ pacwrap run firefox firefox`
Launch firefox inside an instance of the firefox container.
.TP
`$ pacwrap shell -r base`
Open a fakeroot bash shell inside an instance of the base container.
.SH .SH
SYNCHRONIZATION\fR SYNCHRONIZATION\fR.
.PP .PP
Provides the facilities required to be able to synchronize and create containers in aggregate. Provides the facilities required to be able to synchronize and create containers in aggregate.
@ -84,20 +109,14 @@ Synchronize remote package databases. Specify up to 2 times to force a refresh.
.TP .TP
\fB-u, --upgrade\fR \fB-u, --upgrade\fR
Execute aggregate upgrade routine on all or specified containers. Use \fB-t, --target=<TARGET>\fR followed by Execute aggregate upgrade routine on all or specified containers. Use \fB-t, --target=TARGET\fR followed by
a list of packages to specify package targets. Packages applicable to a target \fBmust\fR only be specified a list of packages to specify package targets. Packages applicable to a target \fBmust\fR only be specified
after the target operand. after the target operand.
.TP
\fB-f, --filesystem\fR
Force execution of filesystem synchronization target on all or specified containers. In combination
with \fB-o/--target-only\fR, 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.
.TP .TP
\fB-c, --create\fR \fB-c, --create\fR
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
`\fBinit\fR` provides a shortcut to the synchronization module, equivalent to specifying the options `\fB-Syuc\fR`.
.TP .TP
\fB-b, --base\fR \fB-b, --base\fR
@ -110,6 +129,7 @@ aggregate containers are recommended, but optional. This container type is not d
.TP .TP
\fB-s, --slice\fR \fB-s, --slice\fR
Slice container type. Specify alongside \fB-c, --create\fR to assign this container type during creation. Slice container type. Specify alongside \fB-c, --create\fR to assign this container type during creation.
Requires a base dependency, and optionally one or more sliced dependencies, to ascertain foreign 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 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 the ability to install packages in a lightweight, sliced filesytem, which aid in the deduplication
@ -129,27 +149,38 @@ Useful for all general purpose applications, browsers, e-mail clients, or even t
applications such as IRC clients. It is recommended to base your containers on aggregate type containers. applications such as IRC clients. It is recommended to base your containers on aggregate type containers.
.TP .TP
\fB-t, --target=TARGET\fR \fB-t, --target=<TARGET>\fR
Specify a target container for the specified operation. Declare a target container for the specified operation.
.TP .TP
\fB-d, --dep=DEPEND\fR \fB<PACKAGE>\fR
Specify a dependent container for the specified operation. Package target declared for target container specified.
.TP .TP
\fB-p, --preview\fR \fB-f, --filesystem\fR
Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified. Force execution of filesystem synchronization target on all or specified containers. In combination
Only applicable to with \fB-o/--target-only\fR, 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.
.TP .TP
\fB-o, --target-only\fR \fB-o, --target-only\fR
Apply specified operation on the specified target(s) only. Apply specified operation on the specified target(s) only.
.TP
\fB-d, --dep=<CONTAINER>\fR
Specify dependencies for a container create operation.
.TP
\fB-p, --preview\fR
Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified.
Only applicable to pre-existing targets and not create operations.
.TP .TP
\fB--force-foreign\fR \fB--force-foreign\fR
Force synchronization of foreign packages on resident container. Useful for when installing 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 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.
.TP .TP
\fB--dbonly\fR \fB--dbonly\fR
@ -162,22 +193,22 @@ Override confirmation prompts and confirm all operations.
.SS .SS
EXAMPLES\fR EXAMPLES\fR
.TP .TP
`$ pacwrap -Syucbt base` `$ pacwrap init --base --target base`
Create a base container named base with no additional packages Synchronize remotes and create a base-type container named `base` with no additional packages.
.TP .TP
`$ pacwrap -Syucbt firefox firefox --dep=base,common,nvidia` `$ pacwrap -Syucst common gtk3 qt6-base --dep=base -st nvidia nvidia-utils --dep=base,common`
Create aggregate container named firefox with firefox installed. 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`.
.TP .TP
`$ pacwrap -Syut electron element-desktop -t mozilla firefox thunderbird` `$ pacwrap -Syucat mozilla firefox --dep=base,common,nvidia`
Synchronize package databases and upgrade all containers, as well as install element-desktop Synchronize remote databases and upgrade container dependencies, then create aggregate container
in the target electron, and install firefox and thunderbird in the target mozilla. named `mozilla` with the package `firefox`.
.TP .TP
`$ pacwrap -Syucst common gtk3 qt6-base --dep=base -cst nvidia nvidia-utils --dep=base,common` `$ pacwrap -Sot mozilla thunderbird`
Create two sliced containers, one named common with the packages gtk3, qt6-base, and another Install `thunderbird` in the target container `mozilla`.
named nvidia with the package nvidia-utils.
.TP .TP
`$ pacwrap -Sof` `$ pacwrap -Sof`
@ -236,7 +267,6 @@ Remove the target package firefox from target container firefox.
`$ pacwrap rm firefox` `$ pacwrap rm firefox`
Delete the root filesystem for the firefox container. Delete the root filesystem for the firefox container.
.SH .SH
COMPOSE\fR COMPOSE\fR
Compose containers from container configuration files. This functionality provides a way Compose containers from container configuration files. This functionality provides a way
@ -253,8 +283,6 @@ filename provided.
Compose an available, existing container for composition. The pre-existing container root 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. will be deleted and the container will be composited from the configuration data enumerated.
Reinitialize container
.TP .TP
\fB-t, --target=TARGET\fR \fB-t, --target=TARGET\fR
Specify a target container for the specified operation. Specify a target container for the specified operation.
@ -288,12 +316,12 @@ from the file 'element.yml'.
.TP .TP
`$ pacwrap compose --reinitialize-all --from-config` `$ pacwrap compose --reinitialize-all --from-config`
Reinitialize all available containers as configured in '\fB$PACWRAP_CONFIG_DIR\fR/container/'. Reinitialize all container configurations available in '\fB$PACWRAP_CONFIG_DIR\fR/container/'.
.SH .SH
QUERY\fR QUERY\fR
.PP .PP
Query package list on target container. This module presently is not complete. Query package list on target container.
.TP .TP
\fB-q, --quiet\fR \fB-q, --quiet\fR
@ -349,11 +377,45 @@ EXAMPLE\fR
Print table enumerating all container processes to \fBSTDOUT\fR with process Print table enumerating all container processes to \fBSTDOUT\fR with process
arguments and execution path split into separate columns. arguments and execution path split into separate columns.
.SH
LIST\fR
.PP
List all initialized containers presently managed by pacwrap.
.PP
This command module is a shortcut to \fB-Ul\fR. Command verb `\fBls\fR` also is a
shortcut to this command module.
.TP
\fB-t, --total\fR
Display a total column.
.TP
\fB-o, --on-disk\fR
Display a size on disk column.
.TP
\fB-b, --bytes\fR
Toggle byte unit display.
.SS
EXAMPLES\fR
.TP
`$ pacwrap -Ld`
Print container tabulation out to \fBSTDOUT\fR with two total columns, one listing the
container name, and the other detailing the total size-on-disk consumption displayed with byteunits.
.TP
`$ pacwrap ls -btbts`
Print container tabulation to \fBSTDOUT\fR 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.
.SH .SH
UTILITIES\fR UTILITIES\fR
.PP .PP
Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and
maintenance of operate containers. maintenance of containers.
.TP .TP
\fB-v, --view\fR \fB-v, --view\fR
@ -473,40 +535,38 @@ Create a fresh configuration rather than derive it from the target.
.SS .SS
EXAMPLES\fR EXAMPLES\fR
.TP .TP
`$ pacwrap -Ulbtbts` `$ pacwrap -Uoh firefox`
Print table listing containers out to \fBSTDOUT\fR with two total columns, one showing Open firefox's home directory in the default file manager.
the total amount of bytes. Then print a summary calculation of total consumption below.
.TP
`$ pacwrap -Us java runelite`
Create a symbolic container called `runelite` of `java`.
.TP .TP
`$ pacwrap -Uvl` `$ pacwrap -Uvl`
View '\fB$PACWRAP_DATA_DIR\fR/pacwrap.log' with \fB$EDITOR\fR. View '\fB$PACWRAP_DATA_DIR\fR/pacwrap.log' with \fB$EDITOR\fR.
.TP
`$ pacwrap -Uec firefox`
Edit '\fB$PACWRAP_CONFIG_DIR\fR/container/firefox.yml' with \fB$EDITOR\fR.
.TP
`$ pacwrap -Uld`
Print container tabulation out to \fBSTDOUT\fR with two total columns, one listing the
container name, and the other detailing the total size-on-disk consumption displayed with byteunits.
.TP
`$ pacwrap -Ulbtbts`
Print container tabulation to \fBSTDOUT\fR 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.
.SH .SH
LIST\fR VERSION\fR
.PP
List all initialized containers presently managed by pacwrap.
.PP
This command module is a shortcut to \fB-Ul\fR.
.TP .TP
\fB-t, --total\fR \fB-V, --version, --version=min\fR
Display a total column. Sends version information to \fBSTDOUT\fR with colourful ASCII art.
The 'min' option provides a minimalistic output as is provided to non-colour terms.
.TP
\fB-o, --on-disk\fR
Display a size on disk column.
.TP
\fB-b, --bytes\fR
Toggle byte unit display.
.SS
EXAMPLE\fR
.TP
`$ pacwrap ls -btbts`
Print table listing containers out to \fBSTDOUT\fR with two total columns, one showing
the total amount of bytes. Then print a summary calculation of total consumption below.
.SH .SH
HELP\fR HELP\fR
@ -525,45 +585,55 @@ outside the context of package maintenance. 'man' option produces troff-formatte
Display all help topics. Display all help topics.
.SH .SH
ENVIRONMENT VARIABLES\fR ENVIRONMENT\fR
.PP .PP
Provided herein are environment variables of which can be used to configure pacwrap's runtime parameters. Provided herein are environment variables of which can be used to configure pacwrap's runtime parameters.
All environment variables listed are case sensitive.
.PP
Use with care: These variables if used improperly could result in undesired behaviour. Use with care: These variables if used improperly could result in undesired behaviour.
.TP .TP
\fBPACWRAP_CONFIG_DIR\fR \fBPACWRAP_CONFIG_DIR=<DIR>\fR
Set the configuration directory. This environment variable overrides the default, Set the configuration directory, overriding the default location.
XDG Directory Specification compliant path.
.TP .TP
\fBPACWRAP_DATA_DIR\fR \fBPACWRAP_DATA_DIR=<DIR>\fR
Set the data directory. This environment variable overrides the default, Set the data directory, overriding the default location.
XDG Directory Specification compliant path.
.TP .TP
\fBPACWRAP_CACHE_DIR\fR \fBPACWRAP_CACHE_DIR=<DIR>\fR
Set the cache directory. This environment variable overrides the default, Set the cache directory, overriding the default location.
XDG Directory Specification compliant path.
.TP .TP
\fBPACWRAP_VERBOSE=[0|1]\fR \fBPACWRAP_VERBOSE=[0|1]\fR
Toggle verbose output during a transaction. This option may be removed or otherwise Toggle verbose output during a transaction. This option may be subject to change.
differ in functionality in future.
.TP .TP
\fBPACWRAP_HOME\fR \fBPACWRAP_HOME=<DIR>\fR
Upon execution, mount the set path provided when engaging the 'home' module. Upon container invocation, mount the set path provided when engaging the '\fBhome\fR' filesystem module.
.TP .TP
\fBPACWRAP_ROOT\fR \fBPACWRAP_ROOT=<DIR>\fR
Upon execution, Mount the set path provided when engaging the 'root' module. Upon container invocation, mount the set path provided when engaging the '\fBroot\fR' filesystem module.
.SS
DEFAULT\fR
.PP
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.
.SH
VERSION\fR
.TP .TP
\fB-V, --version, --version=min\fR \fBPACWRAP_CACHE_DIR\fR
Sends version information to \fBSTDOUT\fR with colourful ASCII art. `\fB$HOME\fR/.cache/pacwrap`: Default cache directory.
The 'min' option provides a minimalistic output as is provided to non-colour terms.
.TP
\fBPACWRAP_CONFIG_DIR\fR
`\fB$HOME\fR/.config/pacwrap`: Default configuration directory.
.TP
\fBPACWRAP_DATA_DIR
`$\fBHOME\fR/.local/share/pacwrap`: Default data directory.
.SH .SH
COPYRIGHT\fR COPYRIGHT\fR

14
docs/dbus/README.md
View file

@ -1,13 +1,9 @@
# Modules # Dbus Modules
This directory contains brief documentation along with examples for each permission module. This directory contains brief documentation along with examples for each dbus module.
### Table of Contents ### Table of Contents
- [Devices](./dev.md) - [AppIndicator](./appindicator.md)
- [Display Servers](./display.md) - [Socket](./socket.md)
- [Environment Variables](./env.md) - [XDG Portal](./xdg_portal.md)
- [Graphics Devices](./gpu.md)
- [Networking](./gpu.md)
- [Pipewire](./pipewire.md)
- [PulseAudio](./pulseaudio.md)

14
docs/dbus/appindicator.md Normal file
View file

@ -0,0 +1,14 @@
# Appindicator Module
Permiss access to the appindicator dbus namespace.
## Example
```
dbus:
- module: xdg_portal
```
## Description
Use this module to proxy the appindicator namespace through a socket provided by xdg-dbus-proxy.

22
docs/dbus/socket.md Normal file
View file

@ -0,0 +1,22 @@
# Socket Module
Avail namespace to xdg-dbus-proxy instance.
## Example
Grant TALK access to org.free.desktop.secrets namespace.
```
dbus:
- module: socket
policy: TALK
address:
- org.freedesktop.secrets
```
## Description
Socket module allows permission to be granted through the `xdg-dbus-proxy` job managed by pacwrap
to grant selective access to dbus namespaces on the host dbus session bus.
See the [**contents**]!(./README.md) for modules with pre-defined dbus policies.

14
docs/dbus/xdg_portal.md Normal file
View file

@ -0,0 +1,14 @@
# XDG Portal Module
Permiss access to the xdg-portal dbus namespace.
## Example
```
dbus:
- module: xdg_portal
```
## Description
Use this module to proxy the xdg-portal namespace through a socket provided by xdg-dbus-proxy.

232
docs/manual.md
View file

@ -1,12 +1,12 @@
# Pacwrap User Manual # 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 ## NAME
pacwrap pacwrap
## SYNOPSIS ## SYNOPSIS
pacwrap [**OPERATION** | **COMMAND MODULE**] [**ARGUMENTS**] [**TARGETS**] pacwrap [**OPERATION** | **VERB**] [**ARGUMENTS**] [**TARGETS**]
## DESCRIPTION ## DESCRIPTION
A package management front-end which utilises libalpm to facilitate the creation of unprivileged, 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. 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. 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 ## OPERATIONS
#### **-E, --exec, run**
Invoke a container to execute the provided command sequence.
#### **-S, --sync** #### **-S, --sync**
Synchronize package databases and update packages in target containers. Synchronize package databases and containers in aggregate.
#### **-R, --remove** #### **-R, --remove**
Remove packages from target containers. Remove packages from target containers in aggregate.
#### **-Q, --query**
Query package information from target container.
#### **-C, --compose** #### **-C, --compose**
Compose a container from configuration. Compose a container from configuration.
#### **-Q, --query**
Query package information from target container.
#### **-P, --process** #### **-P, --process**
Manage and show status of running container processes. Manage and show status of running container processes.
#### **-E, --execute**
Executes application in target container using bubblewrap.
#### **-L, --list** #### **-L, --list**
List of available containers managed by pacwrap. List available containers managed by pacwrap.
#### **-U, --utils** #### **-U, --utils**
Invoke miscellaneous utilities to manage containers. Engage miscellaneous utilities to manage containers.
#### **-h, --help=MODULE** #### **-h, --help, --help=[OPERATION | VERB]**
Invoke a printout of this manual to **STDOUT**. Print this manual to **STDOUT**.
#### **-V, --version** #### **-V, --version**
Display version and copyright information in **STDOUT**. Display version banner or information.
## EXECUTE ## EXECUTE
#### **-r, --root** Invoke a container to execute the provided command sequence. Command verb `**run**` provides a
Execute operation with fakeroot and fakechroot. Facilitates a command with faked privileges. shortcut to this module.
#### **-s, --shell**
Invoke a bash shell
## 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. Provides the facilities required to be able to synchronize and create containers in aggregate.
#### **-y, --refresh** #### **-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 a list of packages to specify package targets. Packages applicable to a target **must** only be specified
after the target operand. 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** #### **-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** #### **-b, --base**
Base container type. Specify alongside **-c, --create** to assign this container type during creation. 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** #### **-s, --slice**
Slice container type. Specify alongside **-c, --create** to assign this container type during creation. 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 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 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 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 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. applications such as IRC clients. It is recommended to base your containers on aggregate type containers.
#### **-t, --target=TARGET** #### **-t, --target=<TARGET>**
Specify a target container for the specified operation. Declare a target container for the specified operation.
#### **-d, --dep=DEPEND** #### **<PACKAGE>**
Specify a dependent container for the specified operation. Package target declared for target container specified.
#### **-p, --preview** #### **-f, --filesystem**
Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified. Force execution of filesystem synchronization target on all or specified containers. In combination
Only applicable to 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** #### **-o, --target-only**
Apply specified operation on the specified target(s) 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-foreign**
Force synchronization of foreign packages on resident container. Useful for when installing 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 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** #### **--dbonly**
Transact on resident containers with a database-only transaction. 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. Override confirmation prompts and confirm all operations.
### **EXAMPLES** ### **EXAMPLES**
#### `$ pacwrap -Syucbt base` #### `$ pacwrap init --base --target base`
Create a base container named base with no additional packages Synchronize remotes and create a base-type container named `base` with no additional packages.
#### `$ pacwrap -Syucbt firefox firefox --dep=base,common,nvidia` #### `$ pacwrap -Syucst common gtk3 qt6-base --dep=base -st nvidia nvidia-utils --dep=base,common`
Create aggregate container named firefox with firefox installed. 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` #### `$ pacwrap -Syucat mozilla firefox --dep=base,common,nvidia`
Synchronize package databases and upgrade all containers, as well as install element-desktop Synchronize remote databases and upgrade container dependencies, then create aggregate container
in the target electron, and install firefox and thunderbird in the target mozilla. named `mozilla` with the package `firefox`.
#### `$ pacwrap -Syucst common gtk3 qt6-base --dep=base -cst nvidia nvidia-utils --dep=base,common` #### `$ pacwrap -Sot mozilla thunderbird`
Create two sliced containers, one named common with the packages gtk3, qt6-base, and another Install `thunderbird` in the target container `mozilla`.
named nvidia with the package nvidia-utils.
#### `$ pacwrap -Sof` #### `$ pacwrap -Sof`
Synchronize filesystem state of all associated containers present in the data directory. 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` #### `$ pacwrap rm firefox`
Delete the root filesystem for the firefox container. Delete the root filesystem for the firefox container.
## COMPOSE ## COMPOSE
Compose containers from container configuration files. This functionality provides a way Compose containers from container configuration files. This functionality provides a way
to deterministically compose containers from an established configuration. 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 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. will be deleted and the container will be composited from the configuration data enumerated.
Reinitialize container
#### **-t, --target=TARGET** #### **-t, --target=TARGET**
Specify a target container for the specified operation. 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'. from the file 'element.yml'.
#### `$ pacwrap compose --reinitialize-all --from-config` #### `$ 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
Query package list on target container. This module presently is not complete. Query package list on target container.
#### **-q, --quiet** #### **-q, --quiet**
Quiet the output by truncating the package string. 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 Print table enumerating all container processes to **STDOUT** with process
arguments and execution path split into separate columns. 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 ## UTILITIES
Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and
maintenance of operate containers. maintenance of containers.
#### **-v, --view** #### **-v, --view**
Invoke **$EDITOR** to view file associated with pacwrap. 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. Create a fresh configuration rather than derive it from the target.
### **EXAMPLES** ### **EXAMPLES**
#### `$ pacwrap -Ulbtbts` #### `$ pacwrap -Uoh firefox`
Print table listing containers out to **STDOUT** with two total columns, one showing Open firefox's home directory in the default file manager.
the total amount of bytes. Then print a summary calculation of total consumption below.
#### `$ pacwrap -Us java runelite`
Create a symbolic container called `runelite` of `java`.
#### `$ pacwrap -Uvl` #### `$ pacwrap -Uvl`
View '**$PACWRAP_DATA_DIR**/pacwrap.log' with **$EDITOR**. View '**$PACWRAP_DATA_DIR**/pacwrap.log' with **$EDITOR**.
## LIST #### `$ pacwrap -Uec firefox`
List all initialized containers presently managed by pacwrap. 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** #### `$ pacwrap -Ulbtbts`
Display a total column. 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** ## VERSION
Display a size on disk column. #### **-V, --version, --version=min**
Sends version information to **STDOUT** with colourful ASCII art.
#### **-b, --bytes** The 'min' option provides a minimalistic output as is provided to non-colour terms.
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 ## HELP
#### **-m, --more** #### **-m, --more**
@ -394,36 +440,42 @@ outside the context of package maintenance. 'man' option produces troff-formatte
#### **-a, --all, --help=all** #### **-a, --all, --help=all**
Display all help topics. Display all help topics.
## ENVIRONMENT VARIABLES ## ENVIRONMENT
Provided herein are environment variables of which can be used to configure pacwrap's runtime parameters. 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. Use with care: These variables if used improperly could result in undesired behaviour.
#### **PACWRAP_CONFIG_DIR** #### **PACWRAP_CONFIG_DIR=<DIR>**
Set the configuration directory. This environment variable overrides the default, Set the configuration directory, overriding the default location.
XDG Directory Specification compliant path.
#### **PACWRAP_DATA_DIR** #### **PACWRAP_DATA_DIR=<DIR>**
Set the data directory. This environment variable overrides the default, Set the data directory, overriding the default location.
XDG Directory Specification compliant path.
#### **PACWRAP_CACHE_DIR** #### **PACWRAP_CACHE_DIR=<DIR>**
Set the cache directory. This environment variable overrides the default, Set the cache directory, overriding the default location.
XDG Directory Specification compliant path.
#### **PACWRAP_VERBOSE=[0|1]** #### **PACWRAP_VERBOSE=[0|1]**
Toggle verbose output during a transaction. This option may be removed or otherwise Toggle verbose output during a transaction. This option may be subject to change.
differ in functionality in future.
#### **PACWRAP_HOME** #### **PACWRAP_HOME=<DIR>**
Upon execution, mount the set path provided when engaging the 'home' module. Upon container invocation, mount the set path provided when engaging the '**home**' filesystem module.
#### **PACWRAP_ROOT** #### **PACWRAP_ROOT=<DIR>**
Upon execution, Mount the set path provided when engaging the 'root' module. Upon container invocation, mount the set path provided when engaging the '**root**' filesystem module.
## VERSION ### **DEFAULT**
#### **-V, --version, --version=min** For the following environment variables, contained herein are default runtime values. Any variables not
Sends version information to **STDOUT** with colourful ASCII art. included here in this subsection are to be assumed to have inert values by default.
The 'min' option provides a minimalistic output as is provided to non-colour terms.
#### **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
Copyright (C) 2023-2024 Xavier R.M. Copyright (C) 2023-2024 Xavier R.M.

2
docs/modules/env.md
View file

@ -22,4 +22,4 @@ When an environment variable is not available in the host environment, this modu
provide warning and set a blank value in the target container. provide warning and set a blank value in the target container.
By default pacwrap, will not passthrough environment variables from the host, unless specified By default pacwrap, will not passthrough environment variables from the host, unless specified
otherwise by the user with the elidation of the `set` parameter when definining a `var`. otherwise by the user with the elidation of the `set` parameter when defining a `var`.