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.md | 229 -------------------------------------------------------------- 1 file changed, 229 deletions(-) delete mode 100644 README.md (limited to 'README.md') 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