High Performance Computing: Using Dotkit

Using Dotkit

Use and Unuse | Dotfile Setup | Searching for Packages
Dot Floats | Writing Package Files | Bugs

Dotkit Overview | Using Dotkit | Creating Dotkit Packages | Dotkit Commands | How Dotkit Works

Use and Unuse

Use and unuse load, unload, or display dotkits (also known as packages). Use and unuse help you control and understand your UNIX environment. They simplify dotfile setup and maintenance and are also available for interactive use, allowing you to easily modify your environment as you go. Together, the use/unuse pair provides a do/undo facility that is convenient, informative, and quick.

Use and Unuse Synopsis

use [ -alqv ] [ pkg ... ]

unuse [ -alqv ] [ pkg ... ]

reuse [ -alqv ] [ pkg ... ]

Use and Unuse Options

Append components from the given package(s) to the end of the environment variables they affect. This generally makes the added component(s) the last item searched instead of the first, as is the behavior of the default "prepend" action. This option has no effect with the unuse command.

Note: Do not use this option unless you know what you are doing. The default prepend action is better at avoiding possible conflicts with any pre-existing dotkits or PATH components, etc. The only common package that should arguably be appended is the '.' (dot) package, which adds '.' to your PATH.

The -l "long listing" option turns off the interpretation (sourcing) of any pkg arguments that follow. With no other arguments, this option produces a summary of available dotkits. If a pkg argument follows, the descriptive text and any help text for that pkg is printed to the screen. The -l option can be combined with -v to produce more verbose output. With no arguments, -lv prints a usage message, a list of packages currently in use, a summary of available packages, and a list of all nodes in the Dotkit search path. With a pkg argument, -lv prints the entire contents of the pkg. The -l option is quietly ignored by unuse.
Make use, unuse, or reuse quiet in operation. You generally want this option for commands inside startup dotfiles.
Be verbose about the location of package files found in satisfying your request. With -l, show the full contents of any pkg arguments, or give a more verbose listing if no arguments were given.

If no package arguments are given, a usage message is displayed, followed by a list of the available packages. It is sometimes handy to save the output of this usage message in a file. Because the use command is an alias for csh and tcsh, it may require some extra syntax to redirect its output:

(use -lv) > mycopy.out

How Use and Unuse Work

Suppose there is an application named "viztools" made up of one or more executable programs, documentation, etc. Typing the short command

use viztools

will add the needed components to your PATH, MANPATH, or other environment variables necessary for your use of those programs.

Assuming all is well, you will get a message

Prepending: viztools (ok),

which means that the package file was found and your PATH, MANPATH, or other environment variables needed to access it were adjusted correctly. (If you give the -a option, the message will instead say "Appending" and any new components will be added at the end of the respective variable instead of at the beginning.)

If you type use viztools again, it will say

Prepending: viztools (already loaded),

meaning that the package has already been read once.

If you typed use vzitools (misspelled), the response would read

Prepending: vzitools (not found),

to let you know that the requested package had a problem of some sort.

Later on, when you are done, you type

unuse viztools

and all the relevant adjustments will be made to your environment to remove the package, with the message

Dropping: viztools (ok).

You can use or unuse more than one package at a time. Typing use or unuse without arguments causes a help message to be printed. You can get a list of all the packages available for a given platform by typing use -l with no arguments, and you can learn more about the "viztools" package by typing use -l viztools.

If you know you always want the viztools package to be loaded, you can add the line use -q viztools (the -q option makes the command quiet) to one of your dotfiles and get it automatically included whenever you start a session.

Dotfile Setup

The setup required to make the use command available is simple. Add the following line to your .profile or .cshrc file, or execute it directly in a current shell window if you do not want to modify your startup file:

source /usr/global/tools/dotkit/init.csh     (for csh or tcsh users)
. /usr/global/tools/dotkit/init.ksh              (for bash or ksh users)

Init adds aliases or shell functions for use, unuse, and related commands, and sets the two environment variables, SYS_TYPE and DK_ROOT, if they are not set already.

After initializing Dotkit, you may want to read a few packages in your dotfiles. Lines such as follows can be added to your .profile, .login or .cshrc files, after initialization:

use -q bin usr sbin x11
use -qa .        # Puts '.' last on your path.

The four packages loaded in the first line arrange to put /bin, /usr/bin, /sbin, and (usually) /usr/bin/X11 on the PATH, and set up MANPATH accordingly. The action of the x11 package will vary - on Linux systems, it adds /usr/X11R6/{bin,man} to the PATH and MANPATH, respectively. The last package loaded, a literal '.' (dot), appends '.' to your PATH.

It does no harm to ask for a package that is not present on all platforms. Let use sort out which packages are actually available on your current system. You will get it on those platforms where it is installed, and the request is quietly skipped otherwise.

It is redundant (but does no harm) to put code like

if($SYS_TYPE == "solaris_8_s64") then
  use -q SUNWspro # load sun compilers

in your dotfiles. This is just the kind of check that use is designed to do for you.

You can start using Dotkit interactively without making any changes to your dotfiles other than the initialization step above. It won't change your environment except when you use or unuse packages. Alternatively, you can start from a mostly empty environment and use Dotkit commands to build the one you like.

Searching for Packages

To look at a list of all the available packages for your current SYS_TYPE, type use -l with no arguments. This gives you a categorized listing of packages, with a short description of what each one does.

The search package allows you to type in a word or pattern, much like grep(1), then looks through all the available dotkits for lines that match that word or pattern. To use it, simply type use search. It prompts for the pattern and prints the results to your screen.

To see the entire contents of a given package, type use -lv pkg.

To find packages, use and unuse look in $HOME/.kits/, if that directory exists, then each component of DK_NODE, if it exists, and finally in DK_ROOT, for files named *.dk. To be precise, they look first in three subdirectories of each of those directories, in the following order: *sh/$SYS_TYPE, $SYS_TYPE, *sh, where *sh stands for whichever of bash, csh, ksh, or tcsh is your login shell, and $SYS_TYPE is the name of the current system type. In this way, you (or the Dotkit maintainer) can specialize a package to a given architecture or shell if needed, and arrange for that package to override a "generic" version whenever someone is running on the given architecture or with the given shell. Most packages are independent of shell and SYS_TYPE. For more on the package search process, see the dotkit(7) man page.

Dot Floats

The dot (.) character has a special meaning when discussing UNIX directories; it signifies your current working directory. Many users add "dot" (called '.' hereafter) to their PATH environment variable so as to be able to easily execute programs located in the current directory, wherever that might be. Although there are some security considerations, this convenience is important. Dotkit supports the use of '.' with a special package by that name:

use .       # Puts '.' at the beginning of your PATH
use -a .    # Puts '.' at the end of your PATH.

Moreover, once '.' is in your PATH (or any other colon-separated environment variable), Dotkit arranges for it to "float" up or down as future changes are made, so as to always remain at the beginning or end.

Writing Your Own Package Files

As a simple example, suppose you keep some personal programs at $HOME/bin, with their associated man pages under $HOME/man. You can add a personal package to Dotkit by creating the new file $HOME/.kits/mybin.dk, containing the following five lines:

#c personal
#d My very own programs

dk_alter PATH $HOME/bin
dk_alter MANPATH $HOME/man

Most package files are no more complicated than that. To learn more about writing package files, and the overall organization of Dotkit, see the man pages for dk-examples(5), dk-commands(5) and dotkit(7). They give extensive instruction on the usually simple, but occasionally subtle, art of writing package files.


Unuse removes the first instance of a given component from PATH, MANPATH, etc. (There could be more than one if your PATH was not empty when Dotkit was initialized or if two packages happened to include the same component.) This is usually correct, but can be wrong in a few cases.

Use and unuse are aliases in csh and tcsh; you cannot redirect their output to a file. (However, you can pipe their output to another command, so use|cat>file will usually get the job done. Failing that, try a subshell: (use -lv)>file.)