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

Additional documentation with refactoring and bug fix

Browse source 
- Documentation for desktop utils command module
- Split authorship and license sections in manual
- Cleaned up and reformatted some parameters in manual output
- Don't include symbolic containers with queue in filesystem module
- Tidy-up refactor of a few different functions across the library
This commit is contained in:
Xavier Moffett 2024-04-10 20:12:08 -04:00
parent fde67122ad
commit 6c8f7374e6
8 changed files with 298 additions and 200 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

155
dist/man/pacwrap.1 vendored
View file

@ -1,5 +1,5 @@
.nh .nh
.TH pacwrap 1 "05/04/2024" "pacwrap version_string_placeholder" "User Manual" .TH pacwrap 1 "10/04/2024" "pacwrap version_string_placeholder" "User Manual"
.SH .SH
NAME\fR NAME\fR
@ -59,18 +59,18 @@ List available containers managed by pacwrap.
\fB-U, --utils\fR \fB-U, --utils\fR
Engage miscellaneous utilities to manage containers. Engage miscellaneous utilities to manage containers.
.TP
\fB-h, --help, --help=[OPERATION | VERB]\fR
Print this manual to \fBSTDOUT\fR.
.TP .TP
\fB-V, --version\fR \fB-V, --version\fR
Display version banner or information. Display version banner or information.
.TP
\fB-h, --help\fR <\fBOPERATION\fR | \fBVERB\fR | \fBTOPIC\fR>
Print the help manual to \fBSTDOUT\fR.
.SH .SH
EXECUTE\fR EXECUTE\fR
.PP .PP
Invoke a container to execute the provided command sequence. Command verb \fB`run`\fR` provides a Invoke a container to execute the provided command sequence. Command verb \fB`run`\fR provides a
shortcut to this module. shortcut to this module.
.TP .TP
@ -81,7 +81,7 @@ of the container environment.
.TP .TP
\fB-s, --shell\fR \fB-s, --shell\fR
Invoke a bash shell in the target container. Command verb `\fBshell\fR` provides a shortcut Invoke a bash shell in the target container. Command verb \fB`shell`\fR provides a shortcut
to this module with this option. to this module with this option.
.TP .TP
@ -99,7 +99,7 @@ Launch firefox inside an instance of the firefox container.
Open a fakeroot bash shell inside an instance of the base container. 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.
@ -109,7 +109,7 @@ 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=[CONTAINER]`\fR followed Execute aggregate upgrade routine on all or specified containers. Use \fB`-t, --target[=CONTAINER]`\fR followed
by a list of packages to specify package targets. Packages applicable to a target \fBmust\fR only be specified by 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.
@ -149,12 +149,8 @@ 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=[CONTAINER]\fR \fB-t, --target\fR <\fBCONTAINER\fR> <..\fBPACKAGE\fR>
Declare a target container for the specified operation. Declare a target container for the specified operation, followed by a list of package target(s).
.TP
\fB<PACKAGE>\fR
Package target declared for target container specified.
.TP .TP
\fB-f, --filesystem\fR \fB-f, --filesystem\fR
@ -168,7 +164,7 @@ of manual filesystem changes to all aggregate containers.
Apply specified operation on the specified target(s) only. Apply specified operation on the specified target(s) only.
.TP .TP
\fB-d, --dep=[CONTAINER]\fR \fB-d, --dep\fR <\fBCONTAINER\fR>
Specify dependencies for a container create operation. Specify dependencies for a container create operation.
.TP .TP
@ -231,7 +227,7 @@ associated dependencies, provided they are not required by other packages, and a
marked as being upstream of the target container. marked as being upstream of the target container.
.TP .TP
\fB-t, --target=[CONTAINER]\fR \fB-t, --target\fR <\fBCONTAINER\fR>
Specify a target container for the specified operation. At least one container target is Specify a target container for the specified operation. At least one container target is
is required for package removal operations. is required for package removal operations.
@ -284,7 +280,7 @@ Compose an available, existing container for composition. The pre-existing conta
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.
.TP .TP
\fB-t, --target=[CONTAINER]\fR \fB-t, --target=\fR <\fBCONTAINER\fR>
Specify a target container for the specified operation. Specify a target container for the specified operation.
.TP .TP
@ -328,7 +324,7 @@ Query package list on target container.
Quiet the output by truncating the package string. Quiet the output by truncating the package string.
.TP .TP
\fB-t, --target=[CONTAINER]\fR \fB-t, --target\fR <\fBCONTAINER\fR>
Specify a target container for the specified operation. Specify a target container for the specified operation.
.TP .TP
@ -348,7 +344,11 @@ Table a process list of running containers. Containers may be filtered on target
.TP .TP
\fB-s, --summary\fR \fB-s, --summary\fR
Enumerate a process summary of containers being executed by pacwrap. Enumerate a process summary of containers instantiated by pacwrap.
.TP
\fB-i, --id-list\fR
Enumerate a process id list of containers instantiated by pacwrap.
.TP .TP
\fB-k, --kill\fR \fB-k, --kill\fR
@ -356,14 +356,14 @@ Kill target containers and their associated processes.
.TP .TP
\fB-a, --all\fR \fB-a, --all\fR
Enumerate all processes associated with running containers. Target all containers and enumerate their associated processes.
.TP .TP
\fB-d, --depth\fR \fB-d, --depth\fR
Enumerate all processes at the specified depth associated with running containers. Enumerate all processes at the specified depth associated with running containers.
.TP .TP
\fB-t, --target=[CONTAINER]\fR \fB-t, --target\fR <\fBCONTAINER\fR>
Specify a target container for the specified operation. Specify a target container for the specified operation.
.TP .TP
@ -371,11 +371,16 @@ Specify a target container for the specified operation.
Override confirmation prompts and confirm all operations. Override confirmation prompts and confirm all operations.
.SS .SS
EXAMPLE\fR EXAMPLES\fR
.TP .TP
`$ pacwrap -Psaxc` `$ pacwrap -Psaxc`
Print table enumerating all container processes to \fBSTDOUT\fR with process Print table enumerating all container processes to \fBSTDOUT\fR with process arguments
arguments and execution path split into separate columns. and execution path split into separate columns.
.TP
`$ ps up "$(pacwrap -Pia)"`
Enumerate container processes with `ps` via encapsulating an enumeration of pids from all instances
into a space-delimited bash string.
.SH .SH
LIST\fR LIST\fR
@ -415,7 +420,12 @@ Then print a summation of total, actual consumption below.
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 containers. maintenance of containers. Each utility is considered a command module and therefore can be shortcuted
with a command verb.
.TP
\fB-d, --desktop\fR
Create desktop file to launch application inside of a pacwrap container.
.TP .TP
\fB-v, --view\fR \fB-v, --view\fR
@ -441,24 +451,42 @@ Create a symbolic container.
\fB-r, --remove\fR \fB-r, --remove\fR
Delete a container(s) root filesystem. Delete a container(s) root filesystem.
.SS
DESKTOP OPTIONS\fR
.PP
Create and manage desktop files to launch applications in pacwrap from your favourite applications menu.
.TP
\fB-c, --create\fR <\fBCONTAINER\fR> <\fBAPPLICATION\fR>
Create desktop file associated with application at `$HOME/.local/share/applications/` launching an
application in pacwrap.
.TP
\fB-l, --list\fR <\fBCONTAINER\fR>
List available desktop files in the container root located at `/usr/share/applications/`.
.TP
\fB-r, --remove\fR <\fBAPPLICATION\fR>
Remove desktop file associated with application from `$HOME/.local/share/applications/`.
.SS .SS
EDITOR OPTIONS\fR EDITOR OPTIONS\fR
.PP .PP
These options are associated with the \fB--edit\fR and \fB--view\fR utility command modules. These options are associated with the \fB--edit\fR and \fB--view\fR utility command modules.
.TP .TP
\fB-c, --config=[CONTAINER]\fR \fB-c, --config\fR <\fBCONTAINER\fR>
Edit specified container configuration located in the pacwrap data directory. Defaults to Edit specified container configuration located in the pacwrap data directory. Defaults to
the primary configuration file: '\fB$PACWRAP_CONFIG_DIR\fR/pacwrap.yml' if no option is otherwise the primary configuration file: '\fB$PACWRAP_CONFIG_DIR\fR/pacwrap.yml' if no option is otherwise
specified. specified.
.TP .TP
\fB-d, --desktop=[APPLICATION]\fR \fB-d, --desktop\fR <\fBAPPLICATION\fR>
Edit specified desktop file associated with a pacwrap container. Edit specified desktop file associated with a pacwrap container.
.TP .TP
\fB-r, --repo\fR \fB-r, --repo\fR
Edit repositories configuration file: '\fB$PACWRAP_CONFIG_DIR\fR/repositories.conf'. Edit repositories configuration file: `$PACWRAP_CONFIG_DIR/repositories.conf`.
.TP .TP
\fB-l, --log\fR \fB-l, --log\fR
@ -470,15 +498,15 @@ OPEN OPTIONS\fR
These options are associated with the \fB--open\fR utility command module. These options are associated with the \fB--open\fR utility command module.
.TP .TP
\fB-h, --home, --home=[CONTAINER]\fR \fB-h, --home\fR <\fBCONTAINER\fR>
Specified container's home filesystem. Specified container's home filesystem.
.TP .TP
\fB-r, --home, --root=[CONTAINER]\fR \fB-r, --root\fR <\fBCONTAINER\fR>
Specified container's root filesystem. Specified container's root filesystem.
.TP .TP
\fB-t, --target=[CONTAINER]\fR \fB-t, --target\fR <\fBCONTAINER\fR>
Target container to perform the operation. Target container to perform the operation.
.SS .SS
@ -508,7 +536,7 @@ REMOVE OPTIONS\fR
These options are associated with the \fB--remove\fR utility command module. These options are associated with the \fB--remove\fR utility command module.
.TP .TP
\fB-t, --target\fR \fB-t, --target\fR <\fBCONTAINER\fR>
Target container to perform the operation. Target container to perform the operation.
.TP .TP
@ -538,17 +566,22 @@ EXAMPLES\fR
`$ pacwrap -Uoh firefox` `$ pacwrap -Uoh firefox`
Open firefox's home directory in the default file manager. Open firefox's home directory in the default file manager.
.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 .TP
`$ pacwrap -Uec firefox` `$ pacwrap -Uec firefox`
Edit '\fB$PACWRAP_CONFIG_DIR\fR/container/firefox.yml' with \fB$EDITOR\fR. Edit `$PACWRAP_CONFIG_DIR\fR/container/firefox.yml` with \fB$EDITOR\fR.
.TP
`$ 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.
.TP
`$ pacwrap utils symlink java runelite`
Create a symbolic container called `runelite` of `java`.
.TP .TP
`$ pacwrap -Uld` `$ pacwrap -Uld`
@ -556,7 +589,7 @@ Print container tabulation out to \fBSTDOUT\fR with two total columns, one listi
container name, and the other detailing the total size-on-disk consumption displayed with byteunits. container name, and the other detailing the total size-on-disk consumption displayed with byteunits.
.TP .TP
`$ pacwrap -Ulbtbts` `$ pacwrap utils -lbtbts`
Print container tabulation to \fBSTDOUT\fR with three total columns, first listing the 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. 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. Then print a summation of total, actual consumption below.
@ -570,12 +603,16 @@ The 'min' option provides a minimalistic output as is provided to non-colour ter
.SH .SH
HELP\fR HELP\fR
.TP
\fB-h, --help\fR <\fBTOPIC\fR>
Print the specified topic to \fBSTDOUT\fR.
.TP .TP
\fB-m, --more\fR \fB-m, --more\fR
When specifying a topic to display, show the default topic in addition to specified options. When specifying a topic to display, show the default topic in addition to specified options.
.TP .TP
\fB-f, --format=[FORMAT]\fR \fB-f, --format\fR <\fBFORMAT\fR>
Change output format of help in \fBSTDOUT\fR. Format options include: 'ansi', 'dumb', 'markdown', and 'man'. Change output format of help in \fBSTDOUT\fR. 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 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. outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages.
@ -594,28 +631,29 @@ 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.
.TP .TP
\fBPACWRAP_CONFIG_DIR=[DIR]\fR \fBPACWRAP_CONFIG_DIR\fR <\fBDIR\fR>
Set the configuration directory, overriding the default location. Set path of the configuration directory, overriding the default location.
.TP .TP
\fBPACWRAP_DATA_DIR=[DIR]\fR \fBPACWRAP_DATA_DIR\fR <\fBDIR\fR>
Set the data directory, overriding the default location. Set path of the data directory, overriding the default location.
.TP .TP
\fBPACWRAP_CACHE_DIR=[DIR]\fR \fBPACWRAP_CACHE_DIR\fR <\fBDIR\fR>
Set the cache directory, overriding the default location. Set path of the cache directory, overriding the default location.
.TP .TP
\fBPACWRAP_VERBOSE=[0 | 1]\fR \fBPACWRAP_HOME\fR <\fBDIR\fR>
Toggle verbose output during a transaction. This option may be subject to change. Upon container invocation, mount the set path provided when engaging the \fB`home`\fR filesystem module.
.TP .TP
\fBPACWRAP_HOME=[DIR]\fR \fBPACWRAP_ROOT\fR <\fBDIR\fR>
Upon container invocation, mount the set path provided when engaging the '\fBhome\fR' filesystem module. Upon container invocation, mount the set path provided when engaging the \fB`root`\fR filesystem module.
.TP .TP
\fBPACWRAP_ROOT=[DIR]\fR \fBPACWRAP_VERBOSE\fR <\fB0\fR | \fB1\fR>
Upon container invocation, mount the set path provided when engaging the '\fBroot\fR' filesystem module. Toggle verbose output during a transaction. Valid options are `1` for enablement and `0` for
disablement of verbosity.
.SS .SS
DEFAULT\fR DEFAULT\fR
@ -632,13 +670,14 @@ included here in this subsection are to be assumed to have inert values by defau
`$HOME/.config/pacwrap`: Default configuration directory. `$HOME/.config/pacwrap`: Default configuration directory.
.TP .TP
\fBPACWRAP_DATA_DIR \fBPACWRAP_DATA_DIR\fR
`$HOME/.local/share/pacwrap`: Default data directory. `$HOME/.local/share/pacwrap`: Default data directory.
.SH .SH
COPYRIGHT\fR AUTHOR\fR
Copyright (C) 2023-2024 Xavier R.M. Copyright (C) 2023-2024 Xavier R.M. <sapphirus@azorium.net>
This program may be freely redistributed under the .SH
terms of the GNU General Public License v3 only. LICENSE\fR
This program may be freely redistributed under the terms of the GNU General Public License v3 only.

139
docs/manual.md
View file

@ -1,6 +1,6 @@
# Pacwrap User Manual # Pacwrap User Manual
This document was generated by the pacwrap binary with version 0.8.0-51027e2-RELEASE (05/04/2024) of the program. This document was generated by the pacwrap binary with version 0.8.0-fde6712-RELEASE (10/04/2024) of the program.
## NAME ## NAME
pacwrap pacwrap
@ -45,14 +45,14 @@ List available containers managed by pacwrap.
#### **-U, --utils** #### **-U, --utils**
Engage miscellaneous utilities to manage containers. Engage miscellaneous utilities to manage containers.
#### **-h, --help, --help=[OPERATION | VERB]**
Print this manual to **STDOUT**.
#### **-V, --version** #### **-V, --version**
Display version banner or information. Display version banner or information.
#### **-h, --help** <**OPERATION** | **VERB** | **TOPIC**>
Print the help manual to **STDOUT**.
## EXECUTE ## EXECUTE
Invoke a container to execute the provided command sequence. Command verb **`run`**` provides a Invoke a container to execute the provided command sequence. Command verb **`run`** provides a
shortcut to this module. shortcut to this module.
#### **<CONTAINER> <CMD>** #### **<CONTAINER> <CMD>**
@ -61,7 +61,7 @@ execute. All command-line parameters after the container name are passed through
of the container environment. of the container environment.
#### **-s, --shell** #### **-s, --shell**
Invoke a bash shell in the target container. Command verb `**shell**` provides a shortcut Invoke a bash shell in the target container. Command verb **`shell`** provides a shortcut
to this module with this option. to this module with this option.
#### **-r, --root** #### **-r, --root**
@ -74,14 +74,14 @@ Launch firefox inside an instance of the firefox container.
#### `$ pacwrap shell -r base` #### `$ pacwrap shell -r base`
Open a fakeroot bash shell inside an instance of the base container. Open a fakeroot bash shell inside an instance of the base container.
## SYNCHRONIZATION. ## 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**
Synchronize remote package databases. Specify up to 2 times to force a refresh. Synchronize remote package databases. Specify up to 2 times to force a refresh.
#### **-u, --upgrade** #### **-u, --upgrade**
Execute aggregate upgrade routine on all or specified containers. Use **`-t, --target=[CONTAINER]`** followed 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 by 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.
@ -116,11 +116,8 @@ 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=[CONTAINER]** #### **-t, --target** <**CONTAINER**> <..**PACKAGE**>
Declare a target container for the specified operation. Declare a target container for the specified operation, followed by a list of package target(s).
#### **<PACKAGE>**
Package target declared for target container specified.
#### **-f, --filesystem** #### **-f, --filesystem**
Force execution of filesystem synchronization target on all or specified containers. In combination Force execution of filesystem synchronization target on all or specified containers. In combination
@ -131,7 +128,7 @@ 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]** #### **-d, --dep** <**CONTAINER**>
Specify dependencies for a container create operation. Specify dependencies for a container create operation.
#### **-p, --preview** #### **-p, --preview**
@ -179,7 +176,7 @@ Remove all target packages with the associated target container, including all t
associated dependencies, provided they are not required by other packages, and are not associated dependencies, provided they are not required by other packages, and are not
marked as being upstream of the target container. marked as being upstream of the target container.
#### **-t, --target=[CONTAINER]** #### **-t, --target** <**CONTAINER**>
Specify a target container for the specified operation. At least one container target is Specify a target container for the specified operation. At least one container target is
is required for package removal operations. is required for package removal operations.
@ -220,7 +217,7 @@ 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.
#### **-t, --target=[CONTAINER]** #### **-t, --target=** <**CONTAINER**>
Specify a target container for the specified operation. Specify a target container for the specified operation.
#### **-f, --force** #### **-f, --force**
@ -253,7 +250,7 @@ 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.
#### **-t, --target=[CONTAINER]** #### **-t, --target** <**CONTAINER**>
Specify a target container for the specified operation. Specify a target container for the specified operation.
#### **-e, --explicit** #### **-e, --explicit**
@ -267,27 +264,34 @@ Print a list of explicit packages from the **base** container to **STDOUT**.
Table a process list of running containers. Containers may be filtered on target and process depth. Table a process list of running containers. Containers may be filtered on target and process depth.
#### **-s, --summary** #### **-s, --summary**
Enumerate a process summary of containers being executed by pacwrap. Enumerate a process summary of containers instantiated by pacwrap.
#### **-i, --id-list**
Enumerate a process id list of containers instantiated by pacwrap.
#### **-k, --kill** #### **-k, --kill**
Kill target containers and their associated processes. Kill target containers and their associated processes.
#### **-a, --all** #### **-a, --all**
Enumerate all processes associated with running containers. Target all containers and enumerate their associated processes.
#### **-d, --depth** #### **-d, --depth**
Enumerate all processes at the specified depth associated with running containers. Enumerate all processes at the specified depth associated with running containers.
#### **-t, --target=[CONTAINER]** #### **-t, --target** <**CONTAINER**>
Specify a target container for the specified operation. Specify a target container for the specified operation.
#### **--noconfirm** #### **--noconfirm**
Override confirmation prompts and confirm all operations. Override confirmation prompts and confirm all operations.
### **EXAMPLE** ### **EXAMPLES**
#### `$ pacwrap -Psaxc` #### `$ pacwrap -Psaxc`
Print table enumerating all container processes to **STDOUT** with process Print table enumerating all container processes to **STDOUT** with process arguments
arguments and execution path split into separate columns. 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
List all initialized containers presently managed by pacwrap. List all initialized containers presently managed by pacwrap.
@ -316,7 +320,11 @@ 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 containers. 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** #### **-v, --view**
Invoke **$EDITOR** to view file associated with pacwrap. Invoke **$EDITOR** to view file associated with pacwrap.
@ -336,19 +344,32 @@ Create a symbolic container.
#### **-r, --remove** #### **-r, --remove**
Delete a container(s) root filesystem. 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** ### **EDITOR OPTIONS**
These options are associated with the **--edit** and **--view** utility command modules. These options are associated with the **--edit** and **--view** utility command modules.
#### **-c, --config=[CONTAINER]** #### **-c, --config** <**CONTAINER**>
Edit specified container configuration located in the pacwrap data directory. Defaults to 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 the primary configuration file: '**$PACWRAP_CONFIG_DIR**/pacwrap.yml' if no option is otherwise
specified. specified.
#### **-d, --desktop=[APPLICATION]** #### **-d, --desktop** <**APPLICATION**>
Edit specified desktop file associated with a pacwrap container. Edit specified desktop file associated with a pacwrap container.
#### **-r, --repo** #### **-r, --repo**
Edit repositories configuration file: '**$PACWRAP_CONFIG_DIR**/repositories.conf'. Edit repositories configuration file: `$PACWRAP_CONFIG_DIR/repositories.conf`.
#### **-l, --log** #### **-l, --log**
View 'pacwrap.log'. This file contains transaction log iformation. View 'pacwrap.log'. This file contains transaction log iformation.
@ -356,13 +377,13 @@ View 'pacwrap.log'. This file contains transaction log iformation.
### **OPEN OPTIONS** ### **OPEN OPTIONS**
These options are associated with the **--open** utility command module. These options are associated with the **--open** utility command module.
#### **-h, --home, --home=[CONTAINER]** #### **-h, --home** <**CONTAINER**>
Specified container's home filesystem. Specified container's home filesystem.
#### **-r, --home, --root=[CONTAINER]** #### **-r, --root** <**CONTAINER**>
Specified container's root filesystem. Specified container's root filesystem.
#### **-t, --target=[CONTAINER]** #### **-t, --target** <**CONTAINER**>
Target container to perform the operation. Target container to perform the operation.
### **LIST** ### **LIST**
@ -383,7 +404,7 @@ Toggle byte unit display for the proceeding item.
### **REMOVE OPTIONS** ### **REMOVE OPTIONS**
These options are associated with the **--remove** utility command module. These options are associated with the **--remove** utility command module.
#### **-t, --target** #### **-t, --target** <**CONTAINER**>
Target container to perform the operation. Target container to perform the operation.
#### **--noconfirm** #### **--noconfirm**
@ -405,20 +426,24 @@ Create a fresh configuration rather than derive it from the target.
#### `$ pacwrap -Uoh firefox` #### `$ pacwrap -Uoh firefox`
Open firefox's home directory in the default file manager. Open firefox's home directory in the default file manager.
#### `$ 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**.
#### `$ pacwrap -Uec firefox` #### `$ pacwrap -Uec firefox`
Edit '**$PACWRAP_CONFIG_DIR**/container/firefox.yml' with **$EDITOR**. 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` #### `$ pacwrap -Uld`
Print container tabulation out to **STDOUT** with two total columns, one listing the 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. container name, and the other detailing the total size-on-disk consumption displayed with byteunits.
#### `$ pacwrap -Ulbtbts` #### `$ pacwrap utils -lbtbts`
Print container tabulation to **STDOUT** with three total columns, first listing the 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. 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. Then print a summation of total, actual consumption below.
@ -429,10 +454,13 @@ Sends version information to **STDOUT** with colourful ASCII art.
The 'min' option provides a minimalistic output as is provided to non-colour terms. The 'min' option provides a minimalistic output as is provided to non-colour terms.
## HELP ## HELP
#### **-h, --help** <**TOPIC**>
Print the specified topic to **STDOUT**.
#### **-m, --more** #### **-m, --more**
When specifying a topic to display, show the default topic in addition to specified options. When specifying a topic to display, show the default topic in addition to specified options.
#### **-f, --format=[FORMAT]** #### **-f, --format** <**FORMAT**>
Change output format of help in **STDOUT**. Format options include: 'ansi', 'dumb', 'markdown', and 'man'. 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 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. outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages.
@ -446,23 +474,24 @@ 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=[DIR]** #### **PACWRAP_CONFIG_DIR** <**DIR**>
Set the configuration directory, overriding the default location. Set path of the configuration directory, overriding the default location.
#### **PACWRAP_DATA_DIR=[DIR]** #### **PACWRAP_DATA_DIR** <**DIR**>
Set the data directory, overriding the default location. Set path of the data directory, overriding the default location.
#### **PACWRAP_CACHE_DIR=[DIR]** #### **PACWRAP_CACHE_DIR** <**DIR**>
Set the cache directory, overriding the default location. Set path of the cache directory, overriding the default location.
#### **PACWRAP_VERBOSE=[0 | 1]** #### **PACWRAP_HOME** <**DIR**>
Toggle verbose output during a transaction. This option may be subject to change. Upon container invocation, mount the set path provided when engaging the **`home`** filesystem module.
#### **PACWRAP_HOME=[DIR]** #### **PACWRAP_ROOT** <**DIR**>
Upon container invocation, mount the set path provided when engaging the '**home**' filesystem module. Upon container invocation, mount the set path provided when engaging the **`root`** filesystem module.
#### **PACWRAP_ROOT=[DIR]** #### **PACWRAP_VERBOSE** <**0** | **1**>
Upon container invocation, mount the set path provided when engaging the '**root**' filesystem module. Toggle verbose output during a transaction. Valid options are `1` for enablement and `0` for
disablement of verbosity.
### **DEFAULT** ### **DEFAULT**
For the following environment variables, contained herein are default runtime values. Any variables not For the following environment variables, contained herein are default runtime values. Any variables not
@ -474,12 +503,12 @@ included here in this subsection are to be assumed to have inert values by defau
#### **PACWRAP_CONFIG_DIR** #### **PACWRAP_CONFIG_DIR**
`$HOME/.config/pacwrap`: Default configuration directory. `$HOME/.config/pacwrap`: Default configuration directory.
#### **PACWRAP_DATA_DIR #### **PACWRAP_DATA_DIR**
`$HOME/.local/share/pacwrap`: Default data directory. `$HOME/.local/share/pacwrap`: Default data directory.
## COPYRIGHT ## AUTHOR
Copyright (C) 2023-2024 Xavier R.M. Copyright (C) 2023-2024 Xavier R.M. <sapphirus@azorium.net>
This program may be freely redistributed under the ## LICENSE
terms of the GNU General Public License v3 only. This program may be freely redistributed under the terms of the GNU General Public License v3 only.

11
pacwrap-core/src/config/cache.rs
View file

@ -190,14 +190,9 @@ pub fn populate_config<'a>() -> Result<ContainerCache<'a>> {
&read_dir(&format!("{}/container", *CONFIG_DIR)) &read_dir(&format!("{}/container", *CONFIG_DIR))
.prepend_io(|| format!("{}/container", *CONFIG_DIR))? .prepend_io(|| format!("{}/container", *CONFIG_DIR))?
.filter(|e| e.as_ref().is_ok_and(|e| e.metadata().is_ok_and(|m| m.is_file() && !m.is_symlink()))) .filter(|e| e.as_ref().is_ok_and(|e| e.metadata().is_ok_and(|m| m.is_file() && !m.is_symlink())))
.filter_map(|e| { .filter_map(|e| match e.unwrap().file_name().to_str() {
let file = e.unwrap().file_name(); Some(f) => f.ends_with(".yml").then(|| f.to_string().leak().split_at(f.len() - 4).0),
let file = file.to_str().unwrap_or_default(); None => None,
match file.ends_with(".yml") {
true => Some(file.to_string().leak().split_at(file.len() - 4).0 as &'a str),
false => None,
}
}) })
.collect(), .collect(),
) )

23
pacwrap-core/src/process.rs
View file

@ -18,6 +18,7 @@
*/ */
use std::{ use std::{
fmt::Write,
fs::{read_dir, File}, fs::{read_dir, File},
io::{BufRead, BufReader, Read, Seek, SeekFrom}, io::{BufRead, BufReader, Read, Seek, SeekFrom},
}; };
@ -67,10 +68,7 @@ impl ProcessList {
} }
pub fn keys_by_instance(&self, ins: &str) -> Option<&Vec<i32>> { pub fn keys_by_instance(&self, ins: &str) -> Option<&Vec<i32>> {
match self.groups.get(ins) { self.groups.get(ins)
Some(ins) => Some(ins),
None => None,
}
} }
} }
@ -105,15 +103,14 @@ impl Process {
self.cmd.iter().map(|a| a.as_str()).collect() self.cmd.iter().map(|a| a.as_str()).collect()
} }
pub fn cmdlist_string(&self, start: usize) -> String { pub fn cmdlist_string(&self, start: usize) -> Result<String, Error> {
let mut string = String::new(); let mut string = String::new();
for idx in start .. self.cmd.len() { for idx in start .. self.cmd.len() {
string.push_str(&self.cmd[idx]); write!(string, "{} ", self.cmd[idx]).prepend(|| format!("Failure writing string to cmd buffer."))?;
string.push_str(" ");
} }
string Ok(string)
} }
pub fn stat(&self) -> &ProcStat { pub fn stat(&self) -> &ProcStat {
@ -206,10 +203,7 @@ fn procfs() -> Result<Vec<i32>, Error> {
Ok(read_dir("/proc/") Ok(read_dir("/proc/")
.prepend_io(|| "/proc/".into())? .prepend_io(|| "/proc/".into())?
.filter(|s| s.as_ref().is_ok_and(|s| s.metadata().is_ok_and(|m| m.is_dir()))) .filter(|s| s.as_ref().is_ok_and(|s| s.metadata().is_ok_and(|m| m.is_dir())))
.filter_map(|e| match e.unwrap().file_name().to_str().unwrap().parse() { .filter_map(|e| e.unwrap().file_name().to_str().unwrap().parse().map_or_else(|_| None, |v| Some(v)))
Ok(val) => Some(val),
Err(_) => None,
})
.collect()) .collect())
} }
@ -290,8 +284,5 @@ fn instance_from_path(var: &str) -> &str {
let length = CONTAINER_DIR.len(); let length = CONTAINER_DIR.len();
let var = var.split_at(length).1; let var = var.split_at(length).1;
match var.find('/') { var.find('/').map_or_else(|| var, |idx| var.split_at(idx).0)
None => var,
Some(index) => var.split_at(index).0,
}
} }

2
pacwrap-core/src/sync/filesystem.rs
View file

@ -218,6 +218,8 @@ impl<'a> FilesystemSync<'a> {
self.link_instance(inshandle, tx.clone())?; self.link_instance(inshandle, tx.clone())?;
} else if let Base | Slice = ins_type { } else if let Base | Slice = ins_type {
self.obtain_slice(inshandle, tx.clone())?; self.obtain_slice(inshandle, tx.clone())?;
} else {
continue;
} }
self.queued.insert(ins); self.queued.insert(ins);

12
pacwrap/src/help.rs
View file

@ -49,7 +49,8 @@ lazy_static! {
HelpTopic::Version, HelpTopic::Version,
HelpTopic::Help, HelpTopic::Help,
HelpTopic::Env, HelpTopic::Env,
HelpTopic::Copyright HelpTopic::Authors,
HelpTopic::License,
] ]
.into(); .into();
} }
@ -136,7 +137,8 @@ enum HelpTopic {
Help, Help,
Version, Version,
Env, Env,
Copyright, Authors,
License,
PacwrapYml, PacwrapYml,
} }
@ -154,7 +156,8 @@ impl HelpTopic {
"V" | "version" => &HelpTopic::Version, "V" | "version" => &HelpTopic::Version,
"h" | "help" => &HelpTopic::Help, "h" | "help" => &HelpTopic::Help,
"env" | "environment" => &HelpTopic::Env, "env" | "environment" => &HelpTopic::Env,
"copyright" => &HelpTopic::Copyright, "author" | "authors" => &HelpTopic::Authors,
"license" => &HelpTopic::License,
"synopsis" => &HelpTopic::Default, "synopsis" => &HelpTopic::Default,
"pacwrap.yml" => &HelpTopic::PacwrapYml, "pacwrap.yml" => &HelpTopic::PacwrapYml,
_ => err!(ErrorKind::InvalidTopic(str.into()))?, _ => err!(ErrorKind::InvalidTopic(str.into()))?,
@ -175,7 +178,8 @@ impl HelpTopic {
Self::List => manual::list(buf, layout), Self::List => manual::list(buf, layout),
Self::Help => manual::meta(buf, layout), Self::Help => manual::meta(buf, layout),
Self::Query => manual::query(buf, layout), Self::Query => manual::query(buf, layout),
Self::Copyright => manual::copyright(buf, layout), Self::Authors => manual::authors(buf, layout),
Self::License => manual::license(buf, layout),
Self::PacwrapYml => config::default(buf, layout), Self::PacwrapYml => config::default(buf, layout),
} }
} }

152
pacwrap/src/help/manual.rs
View file

@ -93,11 +93,11 @@ pub fn default(buf: &mut String, layout: &HelpLayout) -> Result {
{sub_bold}-U, --utils{reset_bold} {sub_bold}-U, --utils{reset_bold}
{tab}{tab}Engage miscellaneous utilities to manage containers. {tab}{tab}Engage miscellaneous utilities to manage containers.
{sub_bold}-h, --help, --help=[OPERATION | VERB]{reset_bold}
{tab}{tab}Print this manual to {bold}STDOUT{reset_bold}.
{sub_bold}-V, --version{reset_bold} {sub_bold}-V, --version{reset_bold}
{tab}{tab}Display version banner or information.\n" {tab}{tab}Display version banner or information.
{sub_bold}-h, --help{reset_bold} <{bold}OPERATION{reset_bold} | {bold}VERB{reset_bold} | {bold}TOPIC{reset_bold}>
{tab}{tab}Print the help manual to {bold}STDOUT{reset_bold}.\n"
) )
} }
@ -115,7 +115,7 @@ pub fn execute(buf: &mut String, layout: &HelpLayout) -> Result {
writeln!( writeln!(
buf, buf,
"{head}EXECUTE{reset} "{head}EXECUTE{reset}
{sub_para}Invoke a container to execute the provided command sequence. Command verb {bold}`run`{reset_bold}` provides a {sub_para}Invoke a container to execute the provided command sequence. Command verb {bold}`run`{reset_bold} provides a
{tab}shortcut to this module. {tab}shortcut to this module.
{sub_bold}<CONTAINER> <CMD>{reset_bold} {sub_bold}<CONTAINER> <CMD>{reset_bold}
@ -124,7 +124,7 @@ pub fn execute(buf: &mut String, layout: &HelpLayout) -> Result {
{tab}{tab}of the container environment. {tab}{tab}of the container environment.
{sub_bold}-s, --shell{reset_bold} {sub_bold}-s, --shell{reset_bold}
{tab}{tab}Invoke a bash shell in the target container. Command verb `{bold}shell{reset_bold}` provides a shortcut {tab}{tab}Invoke a bash shell in the target container. Command verb {bold}`shell`{reset_bold} provides a shortcut
{tab}{tab}to this module with this option. {tab}{tab}to this module with this option.
{sub_bold}-r, --root{reset_bold} {sub_bold}-r, --root{reset_bold}
@ -152,14 +152,14 @@ pub fn sync(buf: &mut String, layout: &HelpLayout) -> Result {
writeln!( writeln!(
buf, buf,
"{head}SYNCHRONIZATION{reset}. "{head}SYNCHRONIZATION{reset}
{sub_para}Provides the facilities required to be able to synchronize and create containers in aggregate. {sub_para}Provides the facilities required to be able to synchronize and create containers in aggregate.
{sub_bold}-y, --refresh{reset_bold} {sub_bold}-y, --refresh{reset_bold}
{tab}{tab}Synchronize remote package databases. Specify up to 2 times to force a refresh. {tab}{tab}Synchronize remote package databases. Specify up to 2 times to force a refresh.
{sub_bold}-u, --upgrade{reset_bold} {sub_bold}-u, --upgrade{reset_bold}
{tab}{tab}Execute aggregate upgrade routine on all or specified containers. Use {bold}`-t, --target=[CONTAINER]`{reset_bold} followed {tab}{tab}Execute aggregate upgrade routine on all or specified containers. Use {bold}`-t, --target[=CONTAINER]`{reset_bold} followed
{tab}{tab}by a list of packages to specify package targets. Packages applicable to a target {bold}must{reset_bold} only be specified {tab}{tab}by a list of packages to specify package targets. Packages applicable to a target {bold}must{reset_bold} only be specified
{tab}{tab}after the target operand. {tab}{tab}after the target operand.
@ -194,11 +194,8 @@ pub fn sync(buf: &mut String, layout: &HelpLayout) -> Result {
{tab}{tab}Useful for all general purpose applications, browsers, e-mail clients, or even terminal user interface {tab}{tab}Useful for all general purpose applications, browsers, e-mail clients, or even terminal user interface
{tab}{tab}applications such as IRC clients. It is recommended to base your containers on aggregate type containers. {tab}{tab}applications such as IRC clients. It is recommended to base your containers on aggregate type containers.
{sub_bold}-t, --target=[CONTAINER]{reset_bold} {sub_bold}-t, --target{reset_bold} <{bold}CONTAINER{reset_bold}> <..{bold}PACKAGE{reset_bold}>
{tab}{tab}Declare a target container for the specified operation. {tab}{tab}Declare a target container for the specified operation, followed by a list of package target(s).
{sub_bold}<PACKAGE>{reset_bold}
{tab}{tab}Package target declared for target container specified.
{sub_bold}-f, --filesystem{reset_bold} {sub_bold}-f, --filesystem{reset_bold}
{tab}{tab}Force execution of filesystem synchronization target on all or specified containers. In combination {tab}{tab}Force execution of filesystem synchronization target on all or specified containers. In combination
@ -209,7 +206,7 @@ pub fn sync(buf: &mut String, layout: &HelpLayout) -> Result {
{sub_bold}-o, --target-only{reset_bold} {sub_bold}-o, --target-only{reset_bold}
{tab}{tab}Apply specified operation on the specified target(s) only. {tab}{tab}Apply specified operation on the specified target(s) only.
{sub_bold}-d, --dep=[CONTAINER]{reset_bold} {sub_bold}-d, --dep{reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}Specify dependencies for a container create operation. {tab}{tab}Specify dependencies for a container create operation.
{sub_bold}-p, --preview{reset_bold} {sub_bold}-p, --preview{reset_bold}
@ -272,7 +269,7 @@ pub fn remove(buf: &mut String, layout: &HelpLayout) -> Result {
{tab}{tab}associated dependencies, provided they are not required by other packages, and are not {tab}{tab}associated dependencies, provided they are not required by other packages, and are not
{tab}{tab}marked as being upstream of the target container. {tab}{tab}marked as being upstream of the target container.
{sub_bold}-t, --target=[CONTAINER]{reset_bold} {sub_bold}-t, --target{reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}Specify a target container for the specified operation. At least one container target is {tab}{tab}Specify a target container for the specified operation. At least one container target is
{tab}{tab}is required for package removal operations. {tab}{tab}is required for package removal operations.
@ -327,7 +324,7 @@ pub fn compose(buf: &mut String, layout: &HelpLayout) -> Result {
{tab}{tab}Compose an available, existing container for composition. The pre-existing container root {tab}{tab}Compose an available, existing container for composition. The pre-existing container root
{tab}{tab}will be deleted and the container will be composited from the configuration data enumerated. {tab}{tab}will be deleted and the container will be composited from the configuration data enumerated.
{sub_bold}-t, --target=[CONTAINER]{reset_bold} {sub_bold}-t, --target={reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}Specify a target container for the specified operation. {tab}{tab}Specify a target container for the specified operation.
{sub_bold}-f, --force{reset_bold} {sub_bold}-f, --force{reset_bold}
@ -375,7 +372,7 @@ pub fn query(buf: &mut String, layout: &HelpLayout) -> Result {
{sub_bold}-q, --quiet{reset_bold} {sub_bold}-q, --quiet{reset_bold}
{tab}{tab}Quiet the output by truncating the package string. {tab}{tab}Quiet the output by truncating the package string.
{sub_bold}-t, --target=[CONTAINER]{reset_bold} {sub_bold}-t, --target{reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}Specify a target container for the specified operation. {tab}{tab}Specify a target container for the specified operation.
{sub_bold}-e, --explicit{reset_bold} {sub_bold}-e, --explicit{reset_bold}
@ -404,27 +401,34 @@ pub fn process(buf: &mut String, layout: &HelpLayout) -> Result {
{sub_para}Table a process list of running containers. Containers may be filtered on target and process depth. {sub_para}Table a process list of running containers. Containers may be filtered on target and process depth.
{sub_bold}-s, --summary{reset_bold} {sub_bold}-s, --summary{reset_bold}
{tab}{tab}Enumerate a process summary of containers being executed by pacwrap. {tab}{tab}Enumerate a process summary of containers instantiated by pacwrap.
{sub_bold}-i, --id-list{reset_bold}
{tab}{tab}Enumerate a process id list of containers instantiated by pacwrap.
{sub_bold}-k, --kill{reset_bold} {sub_bold}-k, --kill{reset_bold}
{tab}{tab}Kill target containers and their associated processes. {tab}{tab}Kill target containers and their associated processes.
{sub_bold}-a, --all{reset_bold} {sub_bold}-a, --all{reset_bold}
{tab}{tab}Enumerate all processes associated with running containers. {tab}{tab}Target all containers and enumerate their associated processes.
{sub_bold}-d, --depth{reset_bold} {sub_bold}-d, --depth{reset_bold}
{tab}{tab}Enumerate all processes at the specified depth associated with running containers. {tab}{tab}Enumerate all processes at the specified depth associated with running containers.
{sub_bold}-t, --target=[CONTAINER]{reset_bold} {sub_bold}-t, --target{reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}Specify a target container for the specified operation. {tab}{tab}Specify a target container for the specified operation.
{sub_bold}--noconfirm{reset_bold} {sub_bold}--noconfirm{reset_bold}
{tab}{tab}Override confirmation prompts and confirm all operations. {tab}{tab}Override confirmation prompts and confirm all operations.
{sub_sect}EXAMPLE{reset_bold} {sub_sect}EXAMPLES{reset_bold}
{sub}`$ pacwrap -Psaxc` {sub}`$ pacwrap -Psaxc`
{tab}{tab}Print table enumerating all container processes to {bold}STDOUT{reset_bold} with process {tab}{tab}Print table enumerating all container processes to {bold}STDOUT{reset_bold} with process arguments
{tab}{tab}arguments and execution path split into separate columns.\n" {tab}{tab}and execution path split into separate columns.
{sub}`$ ps up \"$(pacwrap -Pia)\"`
{tab}{tab}Enumerate container processes with `ps` via encapsulating an enumeration of pids from all instances
{tab}{tab}into a space-delimited bash string.\n"
) )
} }
@ -483,7 +487,11 @@ pub fn utils(buf: &mut String, layout: &HelpLayout) -> Result {
buf, buf,
"{head}UTILITIES{reset} "{head}UTILITIES{reset}
{sub_para}Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and {sub_para}Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and
{tab}maintenance of containers. {tab}maintenance of containers. Each utility is considered a command module and therefore can be shortcuted
{tab}with a command verb.
{sub_bold}-d, --desktop{reset_bold}
{tab}{tab}Create desktop file to launch application inside of a pacwrap container.
{sub_bold}-v, --view{reset_bold} {sub_bold}-v, --view{reset_bold}
{tab}{tab}Invoke {bold}$EDITOR{reset_bold} to view file associated with pacwrap. {tab}{tab}Invoke {bold}$EDITOR{reset_bold} to view file associated with pacwrap.
@ -503,19 +511,32 @@ pub fn utils(buf: &mut String, layout: &HelpLayout) -> Result {
{sub_bold}-r, --remove{reset_bold} {sub_bold}-r, --remove{reset_bold}
{tab}{tab}Delete a container(s) root filesystem. {tab}{tab}Delete a container(s) root filesystem.
{sub_sect}DESKTOP OPTIONS{reset_bold}
{sub_para}Create and manage desktop files to launch applications in pacwrap from your favourite applications menu.
{sub_bold}-c, --create{reset_bold} <{bold}CONTAINER{reset_bold}> <{bold}APPLICATION{reset_bold}>
{tab}{tab}Create desktop file associated with application at `$HOME/.local/share/applications/` launching an
{tab}{tab}application in pacwrap.
{sub_bold}-l, --list{reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}List available desktop files in the container root located at `/usr/share/applications/`.
{sub_bold}-r, --remove{reset_bold} <{bold}APPLICATION{reset_bold}>
{tab}{tab}Remove desktop file associated with application from `$HOME/.local/share/applications/`.
{sub_sect}EDITOR OPTIONS{reset_bold} {sub_sect}EDITOR OPTIONS{reset_bold}
{sub_para}These options are associated with the {bold}--edit{reset_bold} and {bold}--view{reset_bold} utility command modules. {sub_para}These options are associated with the {bold}--edit{reset_bold} and {bold}--view{reset_bold} utility command modules.
{sub_bold}-c, --config=[CONTAINER]{reset_bold} {sub_bold}-c, --config{reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}Edit specified container configuration located in the pacwrap data directory. Defaults to {tab}{tab}Edit specified container configuration located in the pacwrap data directory. Defaults to
{tab}{tab}the primary configuration file: '{bold}$PACWRAP_CONFIG_DIR{reset_bold}/pacwrap.yml' if no option is otherwise {tab}{tab}the primary configuration file: '{bold}$PACWRAP_CONFIG_DIR{reset_bold}/pacwrap.yml' if no option is otherwise
{tab}{tab}specified. {tab}{tab}specified.
{sub_bold}-d, --desktop=[APPLICATION]{reset_bold} {sub_bold}-d, --desktop{reset_bold} <{bold}APPLICATION{reset_bold}>
{tab}{tab}Edit specified desktop file associated with a pacwrap container. {tab}{tab}Edit specified desktop file associated with a pacwrap container.
{sub_bold}-r, --repo{reset_bold} {sub_bold}-r, --repo{reset_bold}
{tab}{tab}Edit repositories configuration file: '{bold}$PACWRAP_CONFIG_DIR{reset_bold}/repositories.conf'. {tab}{tab}Edit repositories configuration file: `$PACWRAP_CONFIG_DIR/repositories.conf`.
{sub_bold}-l, --log{reset_bold} {sub_bold}-l, --log{reset_bold}
{tab}{tab}View 'pacwrap.log'. This file contains transaction log iformation. {tab}{tab}View 'pacwrap.log'. This file contains transaction log iformation.
@ -523,13 +544,13 @@ pub fn utils(buf: &mut String, layout: &HelpLayout) -> Result {
{sub_sect}OPEN OPTIONS{reset_bold} {sub_sect}OPEN OPTIONS{reset_bold}
{sub_para}These options are associated with the {bold}--open{reset_bold} utility command module. {sub_para}These options are associated with the {bold}--open{reset_bold} utility command module.
{sub_bold}-h, --home, --home=[CONTAINER]{reset_bold} {sub_bold}-h, --home{reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}Specified container's home filesystem. {tab}{tab}Specified container's home filesystem.
{sub_bold}-r, --home, --root=[CONTAINER]{reset_bold} {sub_bold}-r, --root{reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}Specified container's root filesystem. {tab}{tab}Specified container's root filesystem.
{sub_bold}-t, --target=[CONTAINER]{reset_bold} {sub_bold}-t, --target{reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}Target container to perform the operation. {tab}{tab}Target container to perform the operation.
{sub_sect}LIST{reset_bold} {sub_sect}LIST{reset_bold}
@ -550,7 +571,7 @@ pub fn utils(buf: &mut String, layout: &HelpLayout) -> Result {
{sub_sect}REMOVE OPTIONS{reset_bold} {sub_sect}REMOVE OPTIONS{reset_bold}
{sub_para}These options are associated with the {bold}--remove{reset_bold} utility command module. {sub_para}These options are associated with the {bold}--remove{reset_bold} utility command module.
{sub_bold}-t, --target{reset_bold} {sub_bold}-t, --target{reset_bold} <{bold}CONTAINER{reset_bold}>
{tab}{tab}Target container to perform the operation. {tab}{tab}Target container to perform the operation.
{sub_bold}--noconfirm{reset_bold} {sub_bold}--noconfirm{reset_bold}
@ -572,20 +593,24 @@ pub fn utils(buf: &mut String, layout: &HelpLayout) -> Result {
{sub}`$ pacwrap -Uoh firefox` {sub}`$ pacwrap -Uoh firefox`
{tab}{tab}Open firefox's home directory in the default file manager. {tab}{tab}Open firefox's home directory in the default file manager.
{sub}`$ pacwrap -Us java runelite`
{tab}{tab}Create a symbolic container called `runelite` of `java`.
{sub}`$ pacwrap -Uvl` {sub}`$ pacwrap -Uvl`
{tab}{tab}View '{bold}$PACWRAP_DATA_DIR{reset_bold}/pacwrap.log' with {bold}$EDITOR{reset_bold}. {tab}{tab}View `{bold}$PACWRAP_DATA_DIR{reset_bold}/pacwrap.log` with {bold}$EDITOR{reset_bold}.
{sub}`$ pacwrap -Uec firefox` {sub}`$ pacwrap -Uec firefox`
{tab}{tab}Edit '{bold}$PACWRAP_CONFIG_DIR{reset_bold}/container/firefox.yml' with {bold}$EDITOR{reset_bold}. {tab}{tab}Edit `$PACWRAP_CONFIG_DIR{reset_bold}/container/firefox.yml` with {bold}$EDITOR{reset_bold}.
{sub}`$ pacwrap utils -dc firefox firefox`
{tab}{tab}Create desktop file `$HOME/.local/share/applications/pacwrap.firefox.desktop` derived from
{tab}{tab}`/usr/share/applications/firefox.desktop` in the root of the firefox container.
{sub}`$ pacwrap utils symlink java runelite`
{tab}{tab}Create a symbolic container called `runelite` of `java`.
{sub}`$ pacwrap -Uld` {sub}`$ pacwrap -Uld`
{tab}{tab}Print container tabulation out to {bold}STDOUT{reset_bold} with two total columns, one listing the {tab}{tab}Print container tabulation out to {bold}STDOUT{reset_bold} with two total columns, one listing the
{tab}{tab}container name, and the other detailing the total size-on-disk consumption displayed with byteunits. {tab}{tab}container name, and the other detailing the total size-on-disk consumption displayed with byteunits.
{sub}`$ pacwrap -Ulbtbts` {sub}`$ pacwrap utils -lbtbts`
{tab}{tab}Print container tabulation to {bold}STDOUT{reset_bold} with three total columns, first listing the {tab}{tab}Print container tabulation to {bold}STDOUT{reset_bold} with three total columns, first listing the
{tab}{tab}container name, second the total amount of bytes, and the last showing the total with byteunits. {tab}{tab}container name, second the total amount of bytes, and the last showing the total with byteunits.
{tab}{tab}Then print a summation of total, actual consumption below.\n" {tab}{tab}Then print a summation of total, actual consumption below.\n"
@ -603,10 +628,13 @@ pub fn meta(buf: &mut String, layout: &HelpLayout) -> Result {
writeln!( writeln!(
buf, buf,
"{head}HELP{reset} "{head}HELP{reset}
{sub_bold}-h, --help{reset_bold} <{bold}TOPIC{reset_bold}>
{tab}{tab}Print the specified topic to {bold}STDOUT{reset_bold}.
{sub_bold}-m, --more{reset_bold} {sub_bold}-m, --more{reset_bold}
{tab}{tab}When specifying a topic to display, show the default topic in addition to specified options. {tab}{tab}When specifying a topic to display, show the default topic in addition to specified options.
{sub_bold}-f, --format=[FORMAT]{reset_bold} {sub_bold}-f, --format{reset_bold} <{bold}FORMAT{reset_bold}>
{tab}{tab}Change output format of help in {bold}STDOUT{reset_bold}. Format options include: 'ansi', 'dumb', 'markdown', and 'man'. {tab}{tab}Change output format of help in {bold}STDOUT{reset_bold}. Format options include: 'ansi', 'dumb', 'markdown', and 'man'.
{tab}{tab}This option is for the express purposes of generating documentation at build time, and has little utility {tab}{tab}This option is for the express purposes of generating documentation at build time, and has little utility
{tab}{tab}outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages. {tab}{tab}outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages.
@ -634,23 +662,24 @@ pub fn environment(buf: &mut String, layout: &HelpLayout) -> Result {
{sub_para}Use with care: These variables if used improperly could result in undesired behaviour. {sub_para}Use with care: These variables if used improperly could result in undesired behaviour.
{sub_bold}PACWRAP_CONFIG_DIR=[DIR]{reset_bold} {sub_bold}PACWRAP_CONFIG_DIR{reset_bold} <{bold}DIR{reset_bold}>
{tab}{tab}Set the configuration directory, overriding the default location. {tab}{tab}Set path of the configuration directory, overriding the default location.
{sub_bold}PACWRAP_DATA_DIR=[DIR]{reset_bold} {sub_bold}PACWRAP_DATA_DIR{reset_bold} <{bold}DIR{reset_bold}>
{tab}{tab}Set the data directory, overriding the default location. {tab}{tab}Set path of the data directory, overriding the default location.
{sub_bold}PACWRAP_CACHE_DIR=[DIR]{reset_bold} {sub_bold}PACWRAP_CACHE_DIR{reset_bold} <{bold}DIR{reset_bold}>
{tab}{tab}Set the cache directory, overriding the default location. {tab}{tab}Set path of the cache directory, overriding the default location.
{sub_bold}PACWRAP_VERBOSE=[0 | 1]{reset_bold} {sub_bold}PACWRAP_HOME{reset_bold} <{bold}DIR{reset_bold}>
{tab}{tab}Toggle verbose output during a transaction. This option may be subject to change. {tab}{tab}Upon container invocation, mount the set path provided when engaging the {bold}`home`{reset_bold} filesystem module.
{sub_bold}PACWRAP_HOME=[DIR]{reset_bold} {sub_bold}PACWRAP_ROOT{reset_bold} <{bold}DIR{reset_bold}>
{tab}{tab}Upon container invocation, mount the set path provided when engaging the '{bold}home{reset_bold}' filesystem module. {tab}{tab}Upon container invocation, mount the set path provided when engaging the {bold}`root`{reset_bold} filesystem module.
{sub_bold}PACWRAP_ROOT=[DIR]{reset_bold} {sub_bold}PACWRAP_VERBOSE{reset_bold} <{bold}0{reset_bold} | {bold}1{reset_bold}>
{tab}{tab}Upon container invocation, mount the set path provided when engaging the '{bold}root{reset_bold}' filesystem module. {tab}{tab}Toggle verbose output during a transaction. Valid options are `1` for enablement and `0` for
{tab}{tab}disablement of verbosity.
{sub_sect}DEFAULT{reset_bold} {sub_sect}DEFAULT{reset_bold}
{sub_para}For the following environment variables, contained herein are default runtime values. Any variables not {sub_para}For the following environment variables, contained herein are default runtime values. Any variables not
@ -662,7 +691,7 @@ pub fn environment(buf: &mut String, layout: &HelpLayout) -> Result {
{sub_bold}PACWRAP_CONFIG_DIR{reset_bold} {sub_bold}PACWRAP_CONFIG_DIR{reset_bold}
{tab}{tab}`$HOME/.config/pacwrap`: Default configuration directory. {tab}{tab}`$HOME/.config/pacwrap`: Default configuration directory.
{sub_bold}PACWRAP_DATA_DIR {sub_bold}PACWRAP_DATA_DIR{reset_bold}
{tab}{tab}`$HOME/.local/share/pacwrap`: Default data directory.\n" {tab}{tab}`$HOME/.local/share/pacwrap`: Default data directory.\n"
) )
} }
@ -684,17 +713,26 @@ pub fn version(buf: &mut String, layout: &HelpLayout) -> Result {
) )
} }
pub fn copyright(buf: &mut String, layout: &HelpLayout) -> Result { pub fn authors(buf: &mut String, layout: &HelpLayout) -> Result {
let head = layout.head(); let head = layout.head();
let tab = layout.tab(); let tab = layout.tab();
let reset = layout.reset(); let reset = layout.reset();
writeln!( writeln!(
buf, buf,
"{head}COPYRIGHT{reset} "{head}AUTHOR{reset}
{tab}Copyright (C) 2023-2024 Xavier R.M. {tab}Copyright (C) 2023-2024 Xavier R.M. <sapphirus@azorium.net>\n"
)
{tab}This program may be freely redistributed under the }
{tab}terms of the GNU General Public License v3 only.\n"
pub fn license(buf: &mut String, layout: &HelpLayout) -> Result {
let head = layout.head();
let tab = layout.tab();
let reset = layout.reset();
writeln!(
buf,
"{head}LICENSE{reset}
{tab}This program may be freely redistributed under the terms of the GNU General Public License v3 only.\n"
) )
} }

4
pacwrap/src/proc.rs
View file

@ -156,8 +156,8 @@ fn summary(args: &mut Arguments) -> Result<()> {
let ins = process.instance().to_string(); let ins = process.instance().to_string();
let row = table.insert(match col { let row = table.insert(match col {
(true, false, _) => vec![pid, ins, process.exec().into()], (true, false, _) => vec![pid, ins, process.exec().into()],
(false, true, i) => vec![pid, ins, process.cmdlist_string(i)], (false, true, i) => vec![pid, ins, process.cmdlist_string(i)?],
(true, true, i) => vec![pid, ins, process.exec().into(), process.cmdlist_string(i)], (true, true, i) => vec![pid, ins, process.exec().into(), process.cmdlist_string(i)?],
_ => vec![pid, ins], _ => vec![pid, ins],
}); });