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 /README.html | |
| parent | 0ecfe53b2d271133fac36de11ecfc0f7e47840f0 (diff) | |
| download | sh-ves-master.tar.gz | |
Diffstat (limited to 'README.html')
| -rw-r--r-- | README.html | 317 |
1 files changed, 317 insertions, 0 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> |