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
Download patch file Download diff file Expand all files Collapse all files

139
docs/manual.md
View file

@ -1,6 +1,6 @@
# 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
pacwrap
@ -45,14 +45,14 @@ List available containers managed by pacwrap.
#### **-U, --utils**
Engage miscellaneous utilities to manage containers.
#### **-h, --help, --help=[OPERATION | VERB]**
Print this manual to **STDOUT**.
#### **-V, --version**
Display version banner or information.
#### **-h, --help** <**OPERATION** | **VERB** | **TOPIC**>
Print the help manual to **STDOUT**.
## EXECUTE
Invoke a container to execute the provided command sequence. Command verb **`run`**` provides a
Invoke a container to execute the provided command sequence. Command verb **`run`** provides a
shortcut to this module.
#### **<CONTAINER> <CMD>**
@ -61,7 +61,7 @@ execute. All command-line parameters after the container name are passed through
of the container environment.
#### **-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.
#### **-r, --root**
@ -74,14 +74,14 @@ 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.
## SYNCHRONIZATION
Provides the facilities required to be able to synchronize and create containers in aggregate.
#### **-y, --refresh**
Synchronize remote package databases. Specify up to 2 times to force a refresh.
#### **-u, --upgrade**
Execute aggregate upgrade routine on all or specified containers. Use **`-t, --target=[CONTAINER]`** followed
Execute aggregate upgrade routine on all or specified containers. Use **`-t, --target[=CONTAINER]`** followed
by a list of packages to specify package targets. Packages applicable to a target **must** only be specified
after the target operand.
@ -116,11 +116,8 @@ filesystem and package deduplication.
Useful for all general purpose applications, browsers, e-mail clients, or even terminal user interface
applications such as IRC clients. It is recommended to base your containers on aggregate type containers.
#### **-t, --target=[CONTAINER]**
Declare a target container for the specified operation.
#### **<PACKAGE>**
Package target declared for target container specified.
#### **-t, --target** <**CONTAINER**> <..**PACKAGE**>
Declare a target container for the specified operation, followed by a list of package target(s).
#### **-f, --filesystem**
Force execution of filesystem synchronization target on all or specified containers. In combination
@ -131,7 +128,7 @@ of manual filesystem changes to all aggregate containers.
#### **-o, --target-only**
Apply specified operation on the specified target(s) only.
#### **-d, --dep=[CONTAINER]**
#### **-d, --dep** <**CONTAINER**>
Specify dependencies for a container create operation.
#### **-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
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
is required for package removal operations.
@ -220,7 +217,7 @@ filename provided.
Compose an available, existing container for composition. The pre-existing container root
will be deleted and the container will be composited from the configuration data enumerated.
#### **-t, --target=[CONTAINER]**
#### **-t, --target=** <**CONTAINER**>
Specify a target container for the specified operation.
#### **-f, --force**
@ -253,7 +250,7 @@ Query package list on target container.
#### **-q, --quiet**
Quiet the output by truncating the package string.
#### **-t, --target=[CONTAINER]**
#### **-t, --target** <**CONTAINER**>
Specify a target container for the specified operation.
#### **-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.
#### **-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**
Kill target containers and their associated processes.
#### **-a, --all**
Enumerate all processes associated with running containers.
Target all containers and enumerate their associated processes.
#### **-d, --depth**
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.
#### **--noconfirm**
Override confirmation prompts and confirm all operations.
### **EXAMPLE**
### **EXAMPLES**
#### `$ pacwrap -Psaxc`
Print table enumerating all container processes to **STDOUT** with process
arguments and execution path split into separate columns.
Print table enumerating all container processes to **STDOUT** with process arguments
and execution path split into separate columns.
#### `$ ps up "$(pacwrap -Pia)"`
Enumerate container processes with `ps` via encapsulating an enumeration of pids from all instances
into a space-delimited bash string.
## LIST
List all initialized containers presently managed by pacwrap.
@ -316,7 +320,11 @@ Then print a summation of total, actual consumption below.
## UTILITIES
Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and
maintenance of containers.
maintenance of containers. Each utility is considered a command module and therefore can be shortcuted
with a command verb.
#### **-d, --desktop**
Create desktop file to launch application inside of a pacwrap container.
#### **-v, --view**
Invoke **$EDITOR** to view file associated with pacwrap.
@ -336,19 +344,32 @@ Create a symbolic container.
#### **-r, --remove**
Delete a container(s) root filesystem.
### **DESKTOP OPTIONS**
Create and manage desktop files to launch applications in pacwrap from your favourite applications menu.
#### **-c, --create** <**CONTAINER**> <**APPLICATION**>
Create desktop file associated with application at `$HOME/.local/share/applications/` launching an
application in pacwrap.
#### **-l, --list** <**CONTAINER**>
List available desktop files in the container root located at `/usr/share/applications/`.
#### **-r, --remove** <**APPLICATION**>
Remove desktop file associated with application from `$HOME/.local/share/applications/`.
### **EDITOR OPTIONS**
These options are associated with the **--edit** and **--view** utility command modules.
#### **-c, --config=[CONTAINER]**
#### **-c, --config** <**CONTAINER**>
Edit specified container configuration located in the pacwrap data directory. Defaults to
the primary configuration file: '**$PACWRAP_CONFIG_DIR**/pacwrap.yml' if no option is otherwise
specified.
#### **-d, --desktop=[APPLICATION]**
#### **-d, --desktop** <**APPLICATION**>
Edit specified desktop file associated with a pacwrap container.
#### **-r, --repo**
Edit repositories configuration file: '**$PACWRAP_CONFIG_DIR**/repositories.conf'.
Edit repositories configuration file: `$PACWRAP_CONFIG_DIR/repositories.conf`.
#### **-l, --log**
View 'pacwrap.log'. This file contains transaction log iformation.
@ -356,13 +377,13 @@ View 'pacwrap.log'. This file contains transaction log iformation.
### **OPEN OPTIONS**
These options are associated with the **--open** utility command module.
#### **-h, --home, --home=[CONTAINER]**
#### **-h, --home** <**CONTAINER**>
Specified container's home filesystem.
#### **-r, --home, --root=[CONTAINER]**
#### **-r, --root** <**CONTAINER**>
Specified container's root filesystem.
#### **-t, --target=[CONTAINER]**
#### **-t, --target** <**CONTAINER**>
Target container to perform the operation.
### **LIST**
@ -383,7 +404,7 @@ Toggle byte unit display for the proceeding item.
### **REMOVE OPTIONS**
These options are associated with the **--remove** utility command module.
#### **-t, --target**
#### **-t, --target** <**CONTAINER**>
Target container to perform the operation.
#### **--noconfirm**
@ -405,20 +426,24 @@ Create a fresh configuration rather than derive it from the target.
#### `$ pacwrap -Uoh firefox`
Open firefox's home directory in the default file manager.
#### `$ pacwrap -Us java runelite`
Create a symbolic container called `runelite` of `java`.
#### `$ pacwrap -Uvl`
View '**$PACWRAP_DATA_DIR**/pacwrap.log' with **$EDITOR**.
View `**$PACWRAP_DATA_DIR**/pacwrap.log` with **$EDITOR**.
#### `$ 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`
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 -Ulbtbts`
#### `$ pacwrap utils -lbtbts`
Print container tabulation to **STDOUT** with three total columns, first listing the
container name, second the total amount of bytes, and the last showing the total with byteunits.
Then print a summation of total, actual consumption below.
@ -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.
## HELP
#### **-h, --help** <**TOPIC**>
Print the specified topic to **STDOUT**.
#### **-m, --more**
When specifying a topic to display, show the default topic in addition to specified options.
#### **-f, --format=[FORMAT]**
#### **-f, --format** <**FORMAT**>
Change output format of help in **STDOUT**. Format options include: 'ansi', 'dumb', 'markdown', and 'man'.
This option is for the express purposes of generating documentation at build time, and has little utility
outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages.
@ -446,23 +474,24 @@ All environment variables listed are case sensitive.
Use with care: These variables if used improperly could result in undesired behaviour.
#### **PACWRAP_CONFIG_DIR=[DIR]**
Set the configuration directory, overriding the default location.
#### **PACWRAP_CONFIG_DIR** <**DIR**>
Set path of the configuration directory, overriding the default location.
#### **PACWRAP_DATA_DIR=[DIR]**
Set the data directory, overriding the default location.
#### **PACWRAP_DATA_DIR** <**DIR**>
Set path of the data directory, overriding the default location.
#### **PACWRAP_CACHE_DIR=[DIR]**
Set the cache directory, overriding the default location.
#### **PACWRAP_CACHE_DIR** <**DIR**>
Set path of the cache directory, overriding the default location.
#### **PACWRAP_VERBOSE=[0 | 1]**
Toggle verbose output during a transaction. This option may be subject to change.
#### **PACWRAP_HOME** <**DIR**>
Upon container invocation, mount the set path provided when engaging the **`home`** filesystem module.
#### **PACWRAP_HOME=[DIR]**
Upon container invocation, mount the set path provided when engaging the '**home**' filesystem module.
#### **PACWRAP_ROOT** <**DIR**>
Upon container invocation, mount the set path provided when engaging the **`root`** filesystem module.
#### **PACWRAP_ROOT=[DIR]**
Upon container invocation, mount the set path provided when engaging the '**root**' filesystem module.
#### **PACWRAP_VERBOSE** <**0** | **1**>
Toggle verbose output during a transaction. Valid options are `1` for enablement and `0` for
disablement of verbosity.
### **DEFAULT**
For the following environment variables, contained herein are default runtime values. Any variables not
@ -474,12 +503,12 @@ included here in this subsection are to be assumed to have inert values by defau
#### **PACWRAP_CONFIG_DIR**
`$HOME/.config/pacwrap`: Default configuration directory.
#### **PACWRAP_DATA_DIR
#### **PACWRAP_DATA_DIR**
`$HOME/.local/share/pacwrap`: Default data directory.
## COPYRIGHT
Copyright (C) 2023-2024 Xavier R.M.
## AUTHOR
Copyright (C) 2023-2024 Xavier R.M. <sapphirus@azorium.net>
This program may be freely redistributed under the
terms of the GNU General Public License v3 only.
## LICENSE
This program may be freely redistributed under the terms of the GNU General Public License v3 only.