# 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.

## Commands
sh-ves consists of a series of related scripts, which can be called
from a global wrapper script 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.

### 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.

### 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>] <variable> <value>
```
will prepend `<value>:` to the specified variable.

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_ROOT/ves/bin/
```
prepended to them, and values added to LDPATH will have,
```
$XDG_DATA_ROOT/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.


## 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 add PATH gcc-4
$ ves add LDPATH libexample-6.12
```

## Shell prompt integration
sh-ves has a built in helper script called ves-prompt 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.