diff options
| author | Douglas B. Rumbaugh <doug@douglasrumbaugh.com> | 2026-06-06 12:54:31 -0400 |
|---|---|---|
| committer | Douglas B. Rumbaugh <doug@douglasrumbaugh.com> | 2026-06-06 13:42:29 -0400 |
| commit | e8ceaa75c35e853a2eec4844f57c189a8f988ce1 (patch) | |
| tree | abb579935fd463380455101a4246cffc05842714 | |
| parent | 0ecfe53b2d271133fac36de11ecfc0f7e47840f0 (diff) | |
| download | sh-ves-master.tar.gz | |
| -rw-r--r-- | README.html | 317 | ||||
| -rw-r--r-- | README.md | 229 |
2 files changed, 317 insertions, 229 deletions
diff --git a/README.html b/README.html new file mode 100644 index 0000000..cab8496 --- /dev/null +++ b/README.html @@ -0,0 +1,317 @@ +<!DOCTYPE html> +<html lang="en"> +<head> +<meta charset="utf-8"> +<title>sh-ves: Bourne Shell Virtual Environment System</title> +</head> +<body> + +<h1>sh-ves: Bourne Shell Virtual Environment System</h1> + +<p> +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. +</p> + +<p> +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. +</p> + +<h2>Installation</h2> + +<p>To install, run</p> +<pre> +$ make install +</pre> +<p> +which will copy the scripts into <code>~/.local/bin/ves_scripts</code>, +create the sh-ves data directories, and install the <code>ves(1)</code> +man page to <code>~/.local/share/man/man1</code>. Then add the following +line to your shell's rc or profile file, +</p> +<pre> +. ~/.local/bin/ves_scripts/ves-init.sh +</pre> +<p> +sh-ves operates by defining shell functions, so this file must be sourced +into each shell session that wants to use it. <code>make uninstall</code> +removes the scripts; <code>make purge</code> additionally removes all +data, including your saved environments. +</p> + +<h3>fish</h3> + +<p> +sh-ves also works in fish via a shim. If fish is detected, +<code>make install</code> copies <code>ves.fish</code> to +<code>~/.config/fish/functions/</code> (which autoloads a +<code>ves</code> function — no rc file changes needed) and tab +completions to <code>~/.config/fish/completions/</code>. The shim runs +each command through the real POSIX implementation in an +<code>sh</code> subshell, then replays any environment changes into the +fish session, so all commands behave identically. Activation state is +carried in exported <code>SHVES_SAVED_*</code> variables, so +activate/deactivate work across invocations. +</p> + +<h2>Commands</h2> + +<p> +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. +</p> + +<h3>Create a new environment</h3> + +<p>A new environment can be created by using the command,</p> +<pre> +$ ves create <name> +</pre> +<p> +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, +</p> +<pre> +$ ves create --override <name> +</pre> +<p> +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. +</p> + +<h3>Activate an environment</h3> + +<p>To activate a created environment, use the command,</p> +<pre> +$ ves activate <name> +</pre> +<p> +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. +</p> +<p> +Activating a ves environment will apply all of the stored environment +variables over top of the parent environment. +</p> + +<h3>Deactivate an environment</h3> + +<p>To deactivate a ves environment, use the command,</p> +<pre> +$ ves deactivate +</pre> +<p> +when within an active environment. This will restore the environment variables +to the state they were prior to activating the environment. +</p> + +<h3>Switch between environments</h3> + +<p>As a convenience, the command,</p> +<pre> +$ ves switch <name> +</pre> +<p> +will deactivate the current environment (if any) and activate the named +one in a single step. +</p> + +<h3>Run a command inside an environment</h3> + +<p>To run a one-off command inside an environment without activating it,</p> +<pre> +$ ves run <name> <command...> +</pre> +<p> +The environment is applied in a subshell, so the current shell is left +untouched and no deactivation is necessary. +</p> + +<h3>Add a variable to the environment</h3> + +<p>To add a new environment variable to the environment, use the command</p> +<pre> +$ ves export [--env=<name>] <variable> <value> +</pre> +<p> +If called from within an active ves environment, the <code>--env</code> +flag can be omitted, which will result in the export applying to the +active environment. +</p> + +<p>To remove a variable from an environment entirely,</p> +<pre> +$ ves unset [--env=<name>] <variable> +</pre> +<p> +If the target environment is active, the live variable is restored to its +pre-activation value. +</p> + +<p>To see all variables stored in an environment,</p> +<pre> +$ ves show [<name>] +</pre> +<p>which defaults to the active environment when no name is given.</p> + +<h3>Manage PATH, LDPATH, etc.</h3> + +<p> +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. +</p> + +<p>To add an entry to a path-like variable,</p> +<pre> +$ ves var-add [--env=<name>] [--append] <variable> <value> +</pre> +<p> +will prepend <code><value>:</code> to the specified variable (or +append <code>:<value></code> with the <code>--append</code> 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 <code>--override</code>. +</p> + +<p>To remove an entry from a path-like variable,</p> +<pre> +$ ves var-rm [--env=<name>] <variable> <value> +</pre> +<p> +will remove <code><value>:</code> from a path-like variable, if it +is present. +</p> + +<p> +ves will automatically expand <code><value></code> to an absolute +path using certain rules, for convenience, if it does not begin with a +<code>/</code> or a <code>./</code>. For example, values added to the +PATH will have, +</p> +<pre> +$XDG_DATA_HOME/ves/bin/ +</pre> +<p> +prepended to them, and values added to LDPATH and LD_LIBRARY_PATH will +have, +</p> +<pre> +$XDG_DATA_HOME/ves/lib/ +</pre> +<p> +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. +</p> + +<p>You can also list the contents of a path-like variable using,</p> +<pre> +$ ves list [--index] <variable> +</pre> +<p> +which will list the contents of the variable, each on its own line, +in order of precedence. The <code>--index</code> flag will cause the +command to list a numeric (starting at 0) index before each entry. Note +that <code>ves list</code> reads from the live shell, so it reflects the +current state of the variable, whether or not an environment is active. +</p> + +<h3>List, copy, rename, and delete environments</h3> + +<p>To see all created environments,</p> +<pre> +$ ves envs +</pre> +<p>Environments can be duplicated and renamed with,</p> +<pre> +$ ves copy <src> <dst> +$ ves rename <old> <new> +</pre> +<p>and deleted with,</p> +<pre> +$ ves delete <name> +</pre> +<p> +The currently active environment cannot be deleted or renamed; deactivate +it first. +</p> + +<h2>Potential Use-cases</h2> + +<p> +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. +</p> + +<p> +Using distribution/application specific means, the proper versions of +these packages are installed to <code>~/.local/share/ves/bin/gcc-4/</code> +and <code>~/.local/share/ves/lib/libexample-6.12/</code> respectively. +A ves environment can be then set up for this project, +</p> +<pre> +$ ves create example_project +$ ves activate example_project +$ ves var-add PATH gcc-4 +$ ves var-add LDPATH libexample-6.12 +</pre> + +<h2>Shell prompt integration</h2> + +<p> +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). +</p> +<pre> +$ ves prompt [symbol] +([symbol] <name>) +</pre> +<p> +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. +</p> + +<p> +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, +</p> +<pre> +function fish_prompt + echo -n "$(ves prompt) "(prompt_pwd)' $ ' +end +</pre> + +<h2>Testing</h2> + +<p>The test suite requires no external framework and can be run with,</p> +<pre> +$ make test +</pre> + +<h2>License</h2> + +<p> +sh-ves is licensed under the GNU Affero General Public License, +version 3. See the LICENSE file for details. +</p> + +</body> +</html> 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 <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, -```bash -$ 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, -```bash -$ 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, -```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 <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, -```bash -$ 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 -```bash -$ ves export [--env=<name>] <variable> <value> -``` -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=<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, -```bash -$ 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, -```bash -$ 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, -```bash -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, -```bash -$ 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, -```bash -$ ves envs -``` -Environments can be duplicated and renamed with, -```bash -$ ves copy <src> <dst> -$ ves rename <old> <new> -``` -and deleted with, -```bash -$ 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). -```bash -$ 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, -```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. |