====== Using VALET ======

VALET, a module-like system developed and maintained at UD, makes it easy to manage your environment so you have access to the software that you use to conduct your work on Caviness.  On a system like Caviness there are simultaneously many different software packages present, and many unique versions and variants of those packages.  Some software is maintained by UD IT for all of the users of Caviness.  Some software is maintained by individual workgroups or users.  Having a single consistent mechanism for adding software into a shell's environment is of critical importance.

A VALET //package definition// describes the changes that must be made to the environment, such as adding directories to ''$PATH'' or ''$LD_LIBRARY_PATH'' so the system can find the executables and libraries associated with the package.

  * Package definitions maintained for all users by UD IT can be found in the ''/opt/shared/valet/etc'' directory
  * Users can create their own VALET package definition files in the ''~/.valet'' directory
  * Workgroups can create VALET package definition files in the ''$WORKDIR/sw/valet'' directory

To determine what packages are available to you at any time, use the ''vpkg_list'' command:

<code>
[«username»@login00 ~]$ vpkg_list

Available packages:
  in /home/«user id»/.valet
    lolcow
  in /opt/shared/valet/2.1/etc
    abaqus
    ambertools
    anaconda
    arpack
    arpack-ng
      :
    valgrind
    vile
    vmd
</code>

To see what versions and variants of a package are available, use the ''vpkg_versions'' command:

<code>
[«username»@login00 ~]$ vpkg_versions intel

Available versions in package (* = default version):

[/opt/shared/valet/2.1/etc/intel.vpkg_yaml]
intel     Intel Compiler Suite
  2013    alias to intel/2013u6
  2013u6  Version 2013, SP1 Update 6 (2013_sp1.6.214)
  2015    alias to intel/2015u7
  2015u7  Version 2015, Update 7 (2015.7.235)
  2016    alias to intel/2016u5
  2016u5  Version 2016, Update 5 (2016.8.266)
  2017    alias to intel/2017u7
  2017u7  Version 2017, Update 7 (2017.7.259)
* 2018    alias to intel/2018u4
  2018u3  Version 2018, Update 3 (2018.3.222)
  2018u4  Version 2018, Update 4 (2018.5.274)
  2019    alias to intel/2019u2
  2019u2  Version 2019, Update 2 (2019.2.187)
</code>

A detailed list of the actions taken for a package or a version of a package can be displayed with the ''vpkg_info'' command:

<code>
[«username»@login00 ~]$ vpkg_info udunits/2.2.26
[udunits/2.2.26] {
  contexts: all
  udunits compiled with system compilers
  prefix: /opt/shared/udunits/2.2.26
  standard paths: {
    bin: /opt/shared/udunits/2.2.26/bin
    lib: /opt/shared/udunits/2.2.26/lib
    info: /opt/shared/udunits/2.2.26/share/info
    include: /opt/shared/udunits/2.2.26/include
  }
}
</code>

===== Adding packages =====

The ''vpkg_require'' command is used to add a package's changes to your environment.  One or more versioned package identifiers can be passed to the command:

<code>
[«username»@login00 ~]$ vpkg_require intel/2019 ffmpeg/4.0 python/3.6.5
Adding package `intel/2019u2` to your environment
Adding package `ffmpeg/4.0` to your environment
Adding package `python/3.6.5` to your environment
</code>

Before making changes to the environment, VALET creates an //environment snapshot// that it can use to remove the changes it makes((Environment snapshots are stored in a directory created in ''$TMPDIR'' (or ''/tmp'' if ''$TMPDIR'' is not set).)).

<WRAP center round tip 60%>
Whenever possible, try to merge your package requests into as few ''vpkg_require'' commands as possible.  This limits the number of environment snapshots that must be created and stored on disk.
</WRAP>

To see what packages have been added to your environment, use the ''vpkg_history'' command:

<code>
[«username»@login00 ~]$ vpkg_history
[standard]
  intel/2019u2
  ffmpeg/4.0
  python/3.6.5
</code>

===== Removing packages =====

The changes produced by each invocation of ''vpkg_require'' can be rolled back using the ''vpkg_rollback'' command:

<code>
[«username»@login00 ~]$ which ifort
/opt/shared/intel/2019u2/compilers_and_libraries_2019.2.187/linux/bin/intel64/ifort
[«username»@login00 ~]$ vpkg_rollback
[«username»@login00 ~]$ which ifort
/usr/bin/which: no ifort in (/home/1001/bin:/opt/shared/valet/2.1/bin/bash:/opt/shared/valet/2.1/bin:/opt/shared/slurm/add-ons/bin:/opt/shared/slurm/bin:/usr/lib64/qt-3.3/bin:/opt/shared/gqueue/bin:/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin)
</code>

By default, ''vpkg_rollback'' undoes the last ''vpkg_require''.  To rollback the last //N// ''vpkg_require'' commands issued in your current shell, use ''vpkg_rollback //N//''.

To undo all ''vpkg_require'' commands issued in your current shell, use ''vpkg_rollback all''.

===== Getting help =====

VALET includes several Linux manual (man) pages for online help:

^Name^Section^Description^
|valet|7|General discussion of what VALET is, how it's used, etc.  Good starting point.|
|vpkg_yaml|5|Outlines the YAML VALET package definition file format (see also the vpkg_json page); this is currently the preferred format|
|vpkg_json|5|Outlines the JSON VALET package definition file format (the YAML format is similar)|
|vpkg_xml|5|Outlines the XML VALET package definition file format; this was the original format and is now more or less deprecated in favor of YAML/JSON|
|vpkg_py|5|Outlines the Python package definition file format; there are two variants, literal and executable (dynamic), with availability of the latter determined by the sysadmin|
|vpkg_attr|1|Describes the ''vpkg_attr'' command|
|vpkg_devrequire|1|Describes the ''vpkg_devrequire'' command|
|vpkg_history|1|Describes the ''vpkg_history'' command|
|vpkg_info|1|Describes the ''vpkg_info'' command|
|vpkg_list|1|Describes the ''vpkg_list'' command|
|vpkg_require|1|Describes the ''vpkg_require'' command|
|vpkg_rollback|1|Describes the ''vpkg_rollback'' command|
|vpkg_versions|1|Describes the ''vpkg_versions'' command|