Table of Contents
There are several environment variables that affect the way VR Juggler works. Some of these are required to compile and run applications while others are optional. This chapter lists all such variables and explains their meanings and uses.
The syntax for setting or changing an environment variable varies with operating systems and shell interpreters. Instead of choosing one style of syntax that is specific to a particular shell type, we define our own syntax which you must then translate to your shell's specific syntax. Before defining this syntax, we present the method used to set environment variables in the three most common types of shells. We also provide a quick overview of how to set environment variables using Win32-based GUIs.
A convention used throughout this book is to name the variables using all capital letters. In almost all cases, regardless of the shell, this is the naming convention used for environment variables.
Setting a path with an environment variable can require special syntax. Because of this, the method for doing so may vary from shell to shell. Paths are important with VR Juggler when looking up the path to a shared library (dynamically linked library). For each shell, the syntax for setting a path is given.
Referring to environment variables can also vary from shell to shell. An example of how to print the value of an environment variable will be given for each shell. An example of how to refer to an environment variable is also provided as these two operations may vary even within one kind of shell!
In all shells, an environment variable is only available within that single shell instance. That is, setting an environment variable at a command prompt only affects that specific shell and will not be available from other concurrent or future shells. To make a setting “permanent”, it should be done in file read by all shell instances when they are started. This is addressed briefly as appropriate for each shell type.
In a C-style shell (i.e., one whose interface is based on the C programming language), setting environment variables is done using the built-in command setenv. It is used as follows:
% setenv <VARIABLE_NAME> <value>
where the string <VARIABLE_NAME> represents the name of the variable you are going to set and <value> represents the value assigned to that variable. Both are required. If the named variable did not exist before, it will pop into existence. Otherwise, you overwrite the old setting with the new one.
To print the value of an environment variable, use the following command:
% printenv <VARIABLE_NAME>
Referring to a variable, however, is done using the following syntax:
% cd $VARIABLE_NAME/bin
Paths are specified as a colon-separated list. An example of this is:
% printenv PATH /bin:/sbin:/usr/bin:/usr/sbin
For these types of shells, a “permanent” setting for a given variable should usually be done in your .cshrc file or in your .login file, both of which should be in your home directory. In most cases, it is better to use .cshrc because it is evaluated for every shell instance.
In a shell based on sh, setting environment variables is done using the built-in command export. It is used as follows:
% export <VARIABLE_NAME>=<value>
or
% <VARIABLE_NAME>=<value> % export <VARIABLE_NAME>
Here, the string <VARIABLE_NAME> represents the name of the variable you are going to set and <value> represents the value assigned to that variable. Both are required. Note that there is no space between the variable name and its value. If the named variable did not exist before, it will pop into existence. Otherwise, you overwrite the old setting with the new one. If the variable was already among your current shell's environment variables, the export command is not necessary.
To print the value of an environment variable, use the following command:
% echo $VARIABLE_NAME
Getting the value of a variable works the same way.
Paths are specified as a colon-separated list. An example of this is:
% echo $PATH /bin:/sbin:/usr/bin:/usr/sbin
For these types of shells, a “permanent” setting for a given variable should usually be done in the .profile file in your home directory or in your shell's “rc” file. Different shells have different names for this file. Examples are .bashrc for BASH and .zshrc for Zsh. Please refer to your shell's documentation for more information. In any case, the file will be in your home directory.
The typical syntax for setting an environment variable from the command line (in a DOS shell window) under Win32 is:
C:\ set <VARIABLE_NAME>=<value>
Here, <VARIABLE_NAME> is the name of the environment variable to be set, and <value> is the value being assigned to that variable. If the named variable did not exist before, it will pop into existence. Otherwise, you overwrite the old setting with the new one.
To print the value of an environment variable, use the following command:
C:\ set <VARIABLE_NAME>
Referring to a variable, however, is done using the following syntax:
C:\ cd %VARIABLE_NAME%\bin
Paths are specified as a semicolon-separated list. An example of this is:
C:\ set PATH C:\WINDOWS;C:\bin;C:\
For some versions of Windows, a “permanent” setting for a given variable should usually be done in C:\AUTOEXEC.BAT. In newer versions (Windows ME in particular) and in the Windows NT line of operating systems, the setting is done using the Control Panel. Please refer to the next section for more information on that method.
Before reading this section, please be sure to have read the section called “DOS Shell”. This is necessary because the Win32 GUI for setting environment variables is simply a front-end to that older method and thus uses the same conventions and syntax. The versions of Windows to which this subsection applies are indicated individually since each is a little different. For more detailed information, please refer to the Windows online help system and search for “environment variables”.
In the Control Panel, open the System icon. Under the Advanced tab, there is a button labeled Environment Variables. Here, you can set variables for yourself and, if you have the access privileges, for all users.
To avoid tying this documentation to a single style of environment variable creation, assignment and reference, the following syntax will be used exclusively from this point onward. Please read this carefully before proceeding.
When naming an environment variable in the plain text of this document, the variable will be referred to by its name only. For example, to talk about the environment variable containing your path, we will talk about it as PATH.
The syntax to set an environment variable is:
% <VARIABLE_NAME> = <value>
Setting an environment variable also creates it if it is not already present in the current shell's environment.
Printing an environment variable's value to standard output (stdout) is done as follows:
% echo $VARIABLE_NAME value
The environment variable VJ_BASE_DIR tells a VR Juggler application where to find important data files. It is required to compile and run any Juggler app. It should be set to the base directory of the installed VR Juggler library. For example, if you downloaded a UNIX version of VR Juggler 1.0 and extracted it to the directory /home/software/, you would set VJ_BASE_DIR with this command:
% VJ_BASE_DIR = /home/software/vrjuggler-1.0
The last component of the path depends on the particular version of Juggler you have downloaded.
If you downloaded and built VR Juggler from the source code, the compilation creates a directory called instlinks which can be used as a VR Juggler base:
% VJ_BASE_DIR = $HOME/juggler/my_build_dir/instlinks
In any case, on a Win32 platform, you should use /'s as the path separator for VJ_BASE_DIR rather than \'s. The compiler tools can handle either, and the utilities in juggler-tools will behave much better if UNIX-style paths are used. It is safe to use the drive letter at the start of the path (e.g., C:/software/vrjuggler-1.0.5).
The JDK_HOME environment variable is required by the script that starts VjControl, the VR Juggler configuration program. If Java is installed on your system, JDK_HOME may already be set. If not, it needs to be set to the base of the Java installation.
UNIX/Linux systems use these environment variables to find dynamically loaded libraries, such as libJuggler.so. Unless you are building everything with static libraries, you will need to set these to include the VR Juggler library directory (under VJ_BASE_DIR). IRIX supports several Application Binary Interfaces (ABIs). VR Juggler supports only the N32 and 64 formats, and there are different library path variables for each. The N32 ABI uses the LD_LIBRARYN32_PATH variable, and the 64 ABI uses LD_LIBRARY64_PATH. An example of setting the library path is as follows:
% LD_LIBRARY_PATH = $VJ_BASE_DIR/lib
On some SGI systems running IRIX, users of the MIPSpro Compilers (version 7.3) will need to add another directory as follows:
% LD_LIBRARY_PATH = $LD_LIBRARY_PATH:/usr/lib32/cmplrs:$VJ_BASE_DIR
If you intend to use the VjControl program, you may want to add the $VJ_BASE_DIR/bin directory to your PATH as follows:
% PATH = $PATH:$VJ_BASE_DIR/bin
This variable can be used to control the amount of diagnostic information a VR Juggler application outputs. Its value is a number between 0 (only very important messages are printed) and 7 (vast amounts of data) inclusive. Non-hackers are advised to use levels 0 through 3, as higher debug levels become increasingly cryptic and can severely impact application performance. The default is level 1—only errors and critical information are output. An example of setting a value for this variable is:
% VJ_DEBUG_NFY_LEVEL = 3
This variable can be used to control which components of VR Juggler are allowed to output diagnostic data. If for some reason you set VJ_DEBUG_NFY_LEVEL to 5 or higher, this variable can be used to filter the output. The value of VJ_DEBUG_CATEGORIES is a space-separated list of Juggler debug component names (defined in $VJ_BASE_DIR/include/Kernel/vjDebug.h). The default value is “DBG_ALL”, which performs no filtering whatsoever. Examples of setting it are as follows:
% VJ_DEBUG_CATAGORIES = DBG_ERROR % VJ_DEBUG_CATAGORIES = "DBG_KERNEL DBG_INPUT" % VJ_DEBUG_CATAGORIES = "DBG_CONFIGDB DBG_ENV_MGR"