rumodule

= Content

• Introduction
• Command Line Usage
• Rumodule File Commands
• Shell Function
• Environment Setup
• Summary

= Introduction

Rumodule is used to manage shell environment variables by adding/removing modules. By adding a module using Rumodule, for example the PATH environment variable can be setup so that the executable is found.

Modules exist per tool or per tool version. Rumodule makes it easy to maintain and provide tool setups between multiple users.

The commands are called User Commands. Modules are called Rumodule files and they include Rumodule File Commands.

Rumodule refers to modules through RUMODULE environment variable. RUMODULE includes a list of directories where Rumodule Files reside.

Rumodule command is not convenient to be used directly. The user should setup a shell function which is used to utilize Rumodule. Recommended name is "rumo". See: Shell Function.

Supported shells: zsh, sh, bash, fish

= Command Line Usage

== Overview

The most common User Commands are: "add" and "rm". "add" adds modules content to the shell environment and "rm" removes the same content (or its effects).

Execution examples: rumo add my_module rumo rm my_module

Other common commands are "list" and "avail". "list" displays a list of loaded modules and "avail" lists all modules found, defined by the RUMODULE env variable.

== List of User Commands

• add: add (load) one or many modules
• sadd: add (load) one or many system modules
• rm: remove (unload) one or many modules
• srm: remove (unload) one or many system modules
• list: list loaded modules
• slist: list loaded system modules
• which: display module that would be selected from module directory
• display: display module content
• avail: list all available modules
• savail: list all available modules (including system modules)
• help: display rumodule commands or module help if module given

= Rumodule File Commands

== Overview

The Rumodule files include commands to setup a tool for usage. Rumodule files are normal Ruby files, except a set of Rumodule commands are available in the top namespace. The Rumodule File Commands are semantically defined for the "add" command. For "rm" they have the opposite meaning.

The most common commands are "setenv", "append_path", and "prepend_path".

"append_path" adds an entry to the end of existing env variable (or new is created). "prepend_path" adds an entry to the beginning of existing env variable. New var is created if it doesn't exist.

New env variable is created with "setenv" command. Existing env var can be removed with "unsetenv" command.

Rumodule example: help( "This module is used for tool" ) tool_path = ENV['TOOL_PATH'] append_path( 'PATH', "#{tool_path}/bin" ) add( "tool_setup" )

== List of Rumodule File Commands

[ setenv( var, value ) ] Set env var "var" to "value".

[ unsetenv( var ) ] Unset env var "var".

[ append_path( var, value ) ] Append "value" to env var "var".

[ prepend_path( var, value ) ] Prepend "value" to env var "var".

[ remove_path( var, value ) ] Remove "value" from env var "var".

[ pushenv( var, value ) ] Set env var "var" to "value" and save the old value of "var" for future. When module is removed, the old value is returned.

[ prereq( mod ) ] Check that module "mod" is loaded, or abort. It is recommended to check for other modules before performing any other operation within the module command. Otherwise the Shell Function should check for "rumodule" return codes, and prevent shell env changes when aborting.

[ conflict( mod ) ] Check that module "mod" is not loaded, or abort. See "prereq" usage recommendations.

[ is_loaded( mod ) ] Check if module "mod" is loaded.

[ add( mod ) ] Add a module "mod" from Rumodule file.

= Shell Function

== Overview

Rumodule user must setup a shell function to use Rumodule easily. Recommended name for the function is "rumo". The purpose of the function is to map user arguments to "rumodule" command and pass "rumodule" output to shell for evaluation. This enables the user command to change the shell environment variable contents.

NOTE: If you are using a Ruby version which takes a long time to load into memory, please consider referencing directly into suitable Ruby version in "rumo".

== Shell Function examples

Setup "rumo" command for sh, zsh, or bash shells: rumo () { cmd=$1 shift if test $# -gt 0; then eval rumodule -s zsh -c $cmd -m $* else eval rumodule -c $cmd fi }

Setup "rumo" command for fish shell: function rumo if test (count $argv) -gt 1 set cmd (rumodule -s fish -c $argv[1] -m $argv[2..-1]) else set cmd (rumodule -s fish -c $argv[1]) end eval $cmd end

= Environment Setup

Rumodule requires the RUMODULE env var to be set to the root directory or directories where the Rumodule Files reside.

Lets assume the "$HOME/usr/share/rumodule" directory is used to store the modules.

The directory content could be the following: tool1 tool2 tool3/1.2.3 /1.2.6 tool4 system-

"tool1,2,4" are module files and "tool3" is a subdirectory including module files "1.2.3" and "1.2.6". "system-" is a system module file, which is visible only with "savail" command. System module files are used to separate between compulsory module files vs user selectable.

"tool3" has two versions and it could be referred for example with: rumo add tool3 rumo add tool3/1.2.6

If version is left out, Rumodule uses one of the version. The selection is performed by first sorting the directory entries and then selecting the last.

Usually the user should specify the actual version requested when adding the module and when removing the directory is enough.

Rumodule files can be hidden from the system by using the "." prefix to filename (as for "ls" shell utility").

= Summary

These steps are required to take Rumodule into use:

• Create Rumodule Files to dir.
• Set RUMODULE env var to dir.
• Setup rumo Shell Function.