From 0ecfe53b2d271133fac36de11ecfc0f7e47840f0 Mon Sep 17 00:00:00 2001 From: "Douglas B. Rumbaugh" Date: Sat, 6 Jun 2026 12:27:03 -0400 Subject: Initial version complete I dusted this off after years and had Claude finish it for me. caveat emptor: this is largely (though not entirely) LLM generated as of this commit --- man/ves.1 | 223 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 man/ves.1 (limited to 'man/ves.1') diff --git a/man/ves.1 b/man/ves.1 new file mode 100644 index 0000000..79f27ce --- /dev/null +++ b/man/ves.1 @@ -0,0 +1,223 @@ +.TH VES 1 "June 2026" "sh-ves" "User Commands" +.SH NAME +ves \- Bourne shell virtual environment system +.SH SYNOPSIS +.B ves +.I command +.RI [ arguments ] +.SH DESCRIPTION +.B sh-ves +manages named collections of environment variables, called +.IR environments , +and swaps between them within a shell session. Activating an environment +applies its stored variables over the current shell; deactivating it +restores every variable to its prior state exactly, including variables +that did not previously exist. +.PP +.B sh-ves +is not a package manager and does not install software. It only manages +environment variables, so installing the different versions of compilers +or libraries that an environment points at is up to the user. +.PP +The +.B ves +command is a shell function, not a binary; it must be loaded by sourcing +.I ves-init.sh +in the shell's rc or profile file (see +.BR FILES ). +Environments do not compose: only one environment may be active at a +time, and activating a second one is refused (but see +.BR switch ). +.SH COMMANDS +.TP +.BI "create " [\-\-override] " " name +Create a new environment. By default the new environment overrides +nothing. With +.BR \-\-override , +the variables listed in +.B SHVES_OVERRIDE_VARS +(by default: PATH, LDPATH, LD_LIBRARY_PATH, and CPATH) are stored as +empty strings, so activating the environment truncates them. +.TP +.BI "delete " name +Delete an environment. The active environment cannot be deleted. +.TP +.BI "copy " "src dst" +Copy an environment to a new name. +.TP +.BI "rename " "old new" +Rename an environment. The active environment cannot be renamed. +.TP +.BI "activate " name +Activate an environment, exporting all of its stored variables. The +prior value of each variable is saved for restoration. Fails if another +environment is already active. +.TP +.B deactivate +Deactivate the active environment, restoring all overridden variables +to their pre-activation values. +.TP +.BI "switch " name +Deactivate the current environment (if any), then activate +.IR name . +.TP +.BI "run " "name command ..." +Run a single command inside an environment without activating it in the +current shell. The environment is applied in a subshell, so no +deactivation is necessary. The exit status is that of the command. +.TP +.BI "export " [\-\-env=name] " " "variable value" +Set a variable within an environment. With no +.B \-\-env +option, the active environment is targeted. If the target environment is +active, the variable is also exported into the live shell. +.TP +.BI "unset " [\-\-env=name] " " variable +Remove a variable from an environment entirely. If the target +environment is active, the live variable is restored to its +pre-activation value. +.TP +.BI "show " [name] +Print the variables stored in an environment, one +.I VAR=value +per line. Defaults to the active environment. +.TP +.BI "var-add " [\-\-env=name] " " [\-\-append] " " "variable value" +Prepend +.I value +to a path-like (colon-delimited) variable, or append it with +.BR \-\-append . +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. +Values are expanded according to the rules in +.B PATH EXPANSION +below. +.TP +.BI "var-rm " [\-\-env=name] " " "variable value" +Remove an entry from a path-like variable. The value is expanded with +the same rules as +.BR var-add , +so entries can be removed using the same form they were added with. +.TP +.BI "list " [\-\-index] " " variable +List the entries of a path-like variable from the live shell, one per +line, in order of precedence. With +.BR \-\-index , +each entry is prefixed with its numeric (0-based) index. +.TP +.B envs +List all created environments. +.TP +.BI "prompt " [symbol] +Print a prompt fragment of the form +.BI ( "symbol name" ) +when an environment is active, and nothing otherwise. +.I symbol +defaults to +.BR VENV . +Intended for inclusion in PS1; it performs no color manipulation, so +color codes may be added around it. +.TP +.B help +Print a usage summary. +.SH PATH EXPANSION +For +.B var-add +and +.BR var-rm , +values that do not begin with +.B / +or +.B ./ +are expanded for convenience: values added to PATH are prefixed with +.IR $XDG_DATA_HOME /ves/bin/, +and values added to LDPATH or LD_LIBRARY_PATH are prefixed with +.IR $XDG_DATA_HOME /ves/lib/. +It is advisable to install binaries and libraries that participate in +ves environments into independent directories within these two +locations, e.g. +.IR ~/.local/share/ves/bin/gcc-4/ . +Other variables are never expanded. +.SH ENVIRONMENT +.TP +.B XDG_DATA_HOME +Base directory for sh-ves data. Defaults to +.IR ~/.local/share . +.TP +.B SHVES_SCRIPTS_DIR +Location of the sh-ves scripts. Defaults to +.IR ~/.local/bin/ves_scripts . +.TP +.B SHVES_OVERRIDE_VARS +Space-separated list of variables truncated by +.BR "create \-\-override" . +Defaults to +.BR "PATH LDPATH LD_LIBRARY_PATH CPATH" . +.TP +.B SHVES_ENV_NM +Name of the currently active environment. Exported while an environment +is active; read by +.BR "ves prompt" . +Do not set manually. +.SH FILES +.TP +.I ~/.local/bin/ves_scripts/ves-init.sh +Initialization file. Source this from your shell's rc or profile file: +.IP +.EX +\&. ~/.local/bin/ves_scripts/ves-init.sh +.EE +.TP +.I $XDG_DATA_HOME/ves/envs/ +One file per environment, holding its name header and stored variables. +.TP +.I $XDG_DATA_HOME/ves/bin/, $XDG_DATA_HOME/ves/lib/ +Suggested locations for binaries and libraries used by ves environments +(see +.BR "PATH EXPANSION" ). +.SH FISH +In +.BR fish (1), +.B ves +is provided by a shim function installed to +.IR ~/.config/fish/functions/ves.fish , +with tab completions in +.IR ~/.config/fish/completions/ . +The shim runs each command through the POSIX implementation in an +.BR sh (1) +subshell and replays the resulting environment changes into the fish +session, so all commands behave identically. For prompt integration, use +the quoted command substitution form so that empty output does not +swallow adjacent arguments: +.IP +.EX +function fish_prompt + echo -n "$(ves prompt) "(prompt_pwd)' $ ' +end +.EE +.SH EXAMPLES +Set up an environment for a project needing GCC 4 and libexample 6.12, +previously installed under the sh-ves data directories: +.IP +.EX +$ ves create example_project +$ ves activate example_project +$ ves var-add PATH gcc-4 +$ ves var-add LDPATH libexample-6.12 +.EE +.PP +Run a single build inside that environment without activating it: +.IP +.EX +$ ves run example_project make +.EE +.SH EXIT STATUS +0 on success, 1 on operational errors (missing environment, activation +conflicts, and similar), 2 on usage errors. +.SH SEE ALSO +.BR sh (1), +.BR env (1), +.BR fish (1) +.SH LICENSE +sh-ves is licensed under the GNU Affero General Public License, +version 3. -- cgit v1.2.3