diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 132 |
1 files changed, 132 insertions, 0 deletions
@@ -0,0 +1,132 @@ +# 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 add <variable> <value> +``` +will prepend `<value>:` to the specified variable. + +To remove an entry from a path-like variable, +```bash +ves rm <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. |