From e8ceaa75c35e853a2eec4844f57c189a8f988ce1 Mon Sep 17 00:00:00 2001 From: "Douglas B. Rumbaugh" Date: Sat, 6 Jun 2026 12:54:31 -0400 Subject: HTML Readme --- README.html | 317 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 229 ------------------------------------------- 2 files changed, 317 insertions(+), 229 deletions(-) create mode 100644 README.html delete mode 100644 README.md diff --git a/README.html b/README.html new file mode 100644 index 0000000..cab8496 --- /dev/null +++ b/README.html @@ -0,0 +1,317 @@ + + + + +sh-ves: Bourne Shell Virtual Environment System + + + +

sh-ves: Bourne Shell Virtual Environment System

+ +

+sh-ves is a collection of simple scripts for managing the values +of environment variables. It can be used to create independent +collections of variables, with their values, which are called +environments, and swap between them. +

+ +

+sh-ves is not a package manager, and does not directly interface +with a package manager. It simply allows swapping between environments, +so it is on the user to install the different versions of various packages +on their own, if they would like to use sh-ves for this. +

+ +

Installation

+ +

To install, run

+$ make install
+

+which will copy the scripts into ~/.local/bin/ves_scripts, +create the sh-ves data directories, and install the ves(1) +man page to ~/.local/share/man/man1. Then add the following +line to your shell's rc or profile file, +

+. ~/.local/bin/ves_scripts/ves-init.sh
+

+sh-ves operates by defining shell functions, so this file must be sourced +into each shell session that wants to use it. make uninstall +removes the scripts; make purge additionally removes all +data, including your saved environments. +

+ +

fish

+ +

+sh-ves also works in fish via a shim. If fish is detected, +make install copies ves.fish to +~/.config/fish/functions/ (which autoloads a +ves function — no rc file changes needed) and tab +completions to ~/.config/fish/completions/. The shim runs +each command through the real POSIX implementation in an +sh subshell, then replays any environment changes into the +fish session, so all commands behave identically. Activation state is +carried in exported SHVES_SAVED_* variables, so +activate/deactivate work across invocations. +

+ +

Commands

+ +

+sh-ves consists of a series of related scripts, which can be called +from a global wrapper function for convenience. All of these examples use +the global wrapper. +

+ +

Create a new environment

+ +

A new environment can be created by using the command,

+$ ves create <name>
+

+The default environment will not override any environment variables +from the parent process. If you would like to override the PATH and LDPATH +variables, use the following, +

+$ ves create --override <name>
+

+Be aware that this will truncate PATH and LDPATH to empty strings initially, +and so you will need to set these up yourself within the environment. +

+ +

Activate an environment

+ +

To activate a created environment, use the command,

+$ ves activate <name>
+

+An environment of the specified name must exist, and no other ves environment +can be active already. ves environments do not support composition, and the +system will not allow a second environment to be activated on top of an +existing one. +

+Activating a ves environment will apply all of the stored environment +variables over top of the parent environment. +

+ +

Deactivate an environment

+ +

To deactivate a ves environment, use the command,

+$ ves deactivate
+

+when within an active environment. This will restore the environment variables +to the state they were prior to activating the environment. +

+ +

Switch between environments

+ +

As a convenience, the command,

+$ ves switch <name>
+

+will deactivate the current environment (if any) and activate the named +one in a single step. +

+ +

Run a command inside an environment

+ +

To run a one-off command inside an environment without activating it,

+$ ves run <name> <command...>
+

+The environment is applied in a subshell, so the current shell is left +untouched and no deactivation is necessary. +

+ +

Add a variable to the environment

+ +

To add a new environment variable to the environment, use the command

+$ ves export [--env=<name>] <variable> <value>
+

+If called from within an active ves environment, the --env +flag can be omitted, which will result in the export applying to the +active environment. +

+ +

To remove a variable from an environment entirely,

+$ ves unset [--env=<name>] <variable>
+

+If the target environment is active, the live variable is restored to its +pre-activation value. +

+ +

To see all variables stored in an environment,

+$ ves show [<name>]
+

which defaults to the active environment when no name is given.

+ +

Manage PATH, LDPATH, etc.

+ +

+A variety of important environment variables actually represent :-delimited +arrays, such as PATH and LDPATH. These are called "path-like" in sh-ves. +To facilitate managing these, sh-ves has some specific functionality +related to adding and removing elements from these variables. +

+ +

To add an entry to a path-like variable,

+$ ves var-add [--env=<name>] [--append] <variable> <value>
+

+will prepend <value>: to the specified variable (or +append :<value> with the --append flag, +for fallback entries). If the variable is not yet stored in the +environment, it is seeded from the live shell value first, so prepending +to PATH never truncates it. To truncate PATH and friends deliberately, +create the environment with --override. +

+ +

To remove an entry from a path-like variable,

+$ ves var-rm [--env=<name>] <variable> <value>
+

+will remove <value>: from a path-like variable, if it +is present. +

+ +

+ves will automatically expand <value> to an absolute +path using certain rules, for convenience, if it does not begin with a +/ or a ./. For example, values added to the +PATH will have, +

+$XDG_DATA_HOME/ves/bin/
+

+prepended to them, and values added to LDPATH and LD_LIBRARY_PATH will +have, +

+$XDG_DATA_HOME/ves/lib/
+

+prepended. It is advisable to install binaries and libraries that you +would like to participate in ves environments into independent +directories within these two locations. +

+ +

You can also list the contents of a path-like variable using,

+$ ves list [--index] <variable>
+

+which will list the contents of the variable, each on its own line, +in order of precedence. The --index flag will cause the +command to list a numeric (starting at 0) index before each entry. Note +that ves list reads from the live shell, so it reflects the +current state of the variable, whether or not an environment is active. +

+ +

List, copy, rename, and delete environments

+ +

To see all created environments,

+$ ves envs
+

Environments can be duplicated and renamed with,

+$ ves copy <src> <dst>
+$ ves rename <old> <new>
+

and deleted with,

+$ ves delete <name>
+

+The currently active environment cannot be deleted or renamed; deactivate +it first. +

+ +

Potential Use-cases

+ +

+sh-ves can be used to manage different projects requiring specified +versions of compilers or libraries in a fairly transparent manner. For +example, consider a project that is targeted to GCC version 4 and +requires libexample version 6.12. +

+ +

+Using distribution/application specific means, the proper versions of +these packages are installed to ~/.local/share/ves/bin/gcc-4/ +and ~/.local/share/ves/lib/libexample-6.12/ respectively. +A ves environment can be then set up for this project, +

+$ ves create example_project
+$ ves activate example_project
+$ ves var-add PATH gcc-4
+$ ves var-add LDPATH libexample-6.12
+

+ +

Shell prompt integration

+ +

+sh-ves has a built in helper that will automatically generate a string to +be included in your POSIX compliant shell's PS1 string (or where-ever else +you want it to go). +

+$ ves prompt [symbol]
+([symbol] <name>)
+

+This script doesn't do any color manipulation, so you can add color codes +prior to it within your prompt to configure it however you like. The +prompt string will only appear when an sh-ves environment is currently +active. +

+ +

+In fish, use the quoted command substitution form within your fish_prompt +function, so that the empty output when no environment is active does not +swallow adjacent arguments, +

+function fish_prompt
+    echo -n "$(ves prompt) "(prompt_pwd)' $ '
+end
+

+ +

Testing

+ +

The test suite requires no external framework and can be run with,

+$ make test
+

+ +

License

+ +

+sh-ves is licensed under the GNU Affero General Public License, +version 3. See the LICENSE file for details. +

+ + + diff --git a/README.md b/README.md deleted file mode 100644 index 23b7ddd..0000000 --- a/README.md +++ /dev/null @@ -1,229 +0,0 @@ -# sh-ves: Bourne Shell Virtual Environment System - -sh-ves is a collection of simple scripts for managing the values -of environment variables. It can be used to create independent -collections of variables, with their values, which are called -environments, and swap between them. - -sh-ves is not a package manager, and does not directly interface -with a package manager. It simple allows swapping between environments, -so it is on the user to install the different versions of various packages -on their own, if they would like to use sh-ves for this. - -## Installation -To install, run -```bash -$ make install -``` -which will copy the scripts into `~/.local/bin/ves_scripts`, create the -sh-ves data directories, and install the `ves(1)` man page to -`~/.local/share/man/man1`. Then add the following line to your shell's rc or -profile file, -```bash -. ~/.local/bin/ves_scripts/ves-init.sh -``` -sh-ves operates by defining shell functions, so this file must be sourced -into each shell session that wants to use it. `make uninstall` removes the -scripts; `make purge` additionally removes all data, including your saved -environments. - -### fish -sh-ves also works in fish via a shim. If fish is detected, `make install` -copies `ves.fish` to `~/.config/fish/functions/` (which autoloads a `ves` -function — no rc file changes needed) and tab completions to -`~/.config/fish/completions/`. The shim runs each command through -the real POSIX implementation in an `sh` subshell, then replays any -environment changes into the fish session, so all commands behave -identically. Activation state is carried in exported `SHVES_SAVED_*` -variables, so activate/deactivate work across invocations. - -## Commands -sh-ves consists of a series of related scripts, which can be called -from a global wrapper function for convenience. All of these examples use -the global wrapper. - -### Create a new environment -A new environment can be created by using the command, -```bash -$ ves create -``` - -The default environment will not override any environment variables -from the parent process. If you would like to override the PATH and LDPATH -variables, use the following, -```bash -$ ves create --override -``` - -Be aware that this will truncate PATH and LDPATH to empty strings initially, -and so you will need to set these up yourself within the environment. - -### Activate an environment -To activate a created environment, use the command, -```bash -$ ves activate -``` -An environment of the specified name must exist, and no other ves environment -can be active already. ves environments do not support composition, and the -system will not allow a second environment to be activated on top of an -existing one. - -Activating a ves environment will apply all of the stored environment -variables over top of the parent environment. - -### Deactivate an environment -To deactivate a ves environment, use the command, -```bash -$ ves deactivate -``` -when within an active environment. This will restore the environment variables -to the state they were prior to activating the environment. - -### Switch between environments -As a convenience, the command, -```bash -$ ves switch -``` -will deactivate the current environment (if any) and activate the named -one in a single step. - -### Run a command inside an environment -To run a one-off command inside an environment without activating it, -```bash -$ ves run -``` -The environment is applied in a subshell, so the current shell is left -untouched and no deactivation is necessary. - -### Add a variable to the environment -To add a new environment variable to the environment, use the command -```bash -$ ves export [--env=] -``` -If called from within an activate ves environment, the `--env` flag can -be omitted, which will result in the export applying to the active -environment. - -To remove a variable from an environment entirely, -```bash -$ ves unset [--env=] -``` -If the target environment is active, the live variable is restored to its -pre-activation value. - -To see all variables stored in an environment, -```bash -$ ves show [] -``` -which defaults to the active environment when no name is given. - -### Manage PATH, LDPATH, etc. -A variety of important environment variables actually represent :-delimited -arrays, such as PATH and LDPATH. These are called "path-like" in sh-ves. -To facilitate managing these, sh-ves has some specific functionality -related to adding and removing elements from these variables. - -To add an entry to a path-like variable, -```bash -$ ves var-add [--env=] [--append] -``` -will prepend `:` to the specified variable (or append `:` -with the `--append` flag, for fallback entries). If the variable is not -yet stored in the environment, it is seeded from the live shell value -first, so prepending to PATH never truncates it. To truncate PATH and -friends deliberately, create the environment with `--override`. - -To remove an entry from a path-like variable, -```bash -ves var-rm [--env=] -``` -will remove `:` from a path-like variable, if it is present. - -ves will automatically expand `` to an absolute path using certain -rules, for convenience, if it does not begin with a `/` or a `./`. For example, -values added to the PATH will have, -``` -$XDG_DATA_HOME/ves/bin/ -``` -prepended to them, and values added to LDPATH and LD_LIBRARY_PATH will have, -``` -$XDG_DATA_HOME/ves/lib/ -``` -prepended. It is advisable to install binaries and libraries that you would -like to participate in ves environments into independent directories within -these two locations. - -You can also list the contents of a path-like variable using, -```bash -$ ves list [--index] -``` -which will list the contents of the variable, each on its own line, -in order of precedence. The `--index` flag will cause the command to -list a numeric (starting at 0) index before each entry. Note that `ves list` -reads from the live shell, so it reflects the current state of the variable, -whether or not an environment is active. - -### List, copy, rename, and delete environments -To see all created environments, -```bash -$ ves envs -``` -Environments can be duplicated and renamed with, -```bash -$ ves copy -$ ves rename -``` -and deleted with, -```bash -$ ves delete -``` -The currently active environment cannot be deleted or renamed; deactivate -it first. - -## Potential Use-cases -sh-ves can be used to manage different projects requiring specified -versions of compilers or libraries in a fairly transparent manner. For -example, consider a project that is targeted to GCC version 4 and -requires libexample version 6.12. - -Using distribution/application specific means, the proper versions of -these packages are installed to `~/.local/share/ves/bin/gcc-4/` and -`~/.local/share/ves/lib/libexample-6.12/` respectively. A ves environment -can be then set up for this project, -``` -$ ves create example_project -$ ves activate example_project -$ ves var-add PATH gcc-4 -$ ves var-add LDPATH libexample-6.12 -``` - -## Shell prompt integration -sh-ves has a built in helper that will automatically generate a string to -be included in your POSIX compliant shell's PS1 string (or where-ever else -you want it to go). -```bash -$ ves prompt [symbol] -([symbol] ) -``` -This script doesn't do any color manipulation, so you can add color codes prior -to it within your prompt to configure it however you like. The prompt -string will only appear when an sh-ves environment is currently active. - -In fish, use the quoted command substitution form within your fish_prompt -function, so that the empty output when no environment is active does not -swallow adjacent arguments, -```fish -function fish_prompt - echo -n "$(ves prompt) "(prompt_pwd)' $ ' -end -``` - -## Testing -The test suite requires no external framework and can be run with, -```bash -$ make test -``` - -## License -sh-ves is licensed under the GNU Affero General Public License, -version 3. See the LICENSE file for details. -- cgit v1.2.3