WRspice Environment Variables

The following environment variables are used by all XicTools programs.

WRSPICE_HOME
If found in the environment when WRspice starts, it is expected to contain a path to the WRspice installation area or equivalent, which defaults to ``/usr/local/xictools/wrspice''. This overrides XT_PREFIX if that environment variable is also found.

There is an important subtlety when using this variable. Although it allows WRspice to find its startup files anywhere, only the directory structure implied by XT_PREFIX, that is, for <i>WRspice</i>,

$XT_PREFIX/xictools/wrspice

is compatible with the program installation script. The variable is perhaps useful for pointing WRspice toward a secondary set of startup files, perhaps heavily customized by the user, which may reside in an arbitrary location.

WRSPICE_FIFO
When WRspice starts, it creates a ``named pipe'', otherwise known as a fifo (see 3.15.11). Text written to the fifo is piped into WRspice, as if input with the source command. If this variable is found in the environment, the text of this variable is taken as the base name for the fifo, instead of ``wrsfifo''. In Unix/Linux, this name can have a full path. All components of the path except for the file name must exist. If there is a conflict with an existing entity, an integer suffix will be added to make the name unique. In Windows, any path given is stripped and ignored.

XT_PREFIX
All of the XicTools programs respond to the XT_PREFIX environment variable. When the tools are installed in a non-standard location, i.e., other than /usr/local, this can be set to the directory prefix which effectively replaces ``/usr/local'', and the programs will be able to access the installation library files without further directives. This should not be needed under Windows, as the Registry provides the default paths.

XT_HOMEDIR
Under Windows, the user's ``home'' directory is determined by looking at environment variables.

In Linux, the HOME environment variable is set the the user's home directory, and this is also true under Windows if using a Linux emulation package such as Cygwin or MSYS. However, in this case HOME will be relative to the file system as seen within the emulator, and not the actual Windows file system as seen in Xic or WRspice which are Windows-native programs. Therefor, the HOME environment variable is ignored under Windows.

Instead, the programs will first look for XT_HOMEDIR. This should be set to the Windows path to the user's MSYS2 or Cygwin home directory. For example, this can be done from the bash_profile file by adding a line

export XT_HOMEDIR=c:/msys64/home/yourlogin

Setting this will allow Xic and WRspice to find files in the user's MSYS2 home directory, even though the programs are Windows native and don't know the MSYS2 paths.

The deprecated XIC_START_DIR variable is checked next, and if found its value is taken as the user's home directory in the same manner.

If not found, the HOMEDIR and HOMEPATH variables, if both are found, are concatenated to yield the home directory path. In the unlikely event that these are not set, the USERPROFILE variable is checked, and if all else fails, ``C: \ '' is assumed. The HOMEDIR/HOMEPATH and USERPROFILE variables are set by Windows, at least in some Windows versions.

Under other operating systems, the home directory is well-defined and is obtained from operating system calls.

XTNETDEBUG
If the variable XTNETDEBUG is defined, Xic and WRspice will echo interprocess messages sent and received to the console. In server mode, Xic will not go into the background, but will remain in the foreground, printing status messages while servicing requests.

XT_KLU_PATH
This can be set to the full path to the KLU (sparse matrix solver) plug-in. For example, this path by default in a Linux installation is

/usr/local/xictools/wrspice/startup/klu_wr.so

The plug-in is found automatically so this variable is needed only for special cases.

The KLU version changed in wrspice-4.2.7, and the plug-ins are not compatible. Current WRspice releases will not load the old plug-in, however older releases will load a new plug-in if found in the default location, which will likely cause a program crash. This variable can be set in this case to avoid the problem.

XT_LOCAL_MALLOC
Linux and FreeBSD releases can use an included local memory allocation package. In earlier WRspice releases, this allocator, rather than the allocator provided by the operating system, was used by default. In 32-bit releases, the local allocator was often able to allocate more memory than the allocators provided by the operating system. It also provided custom error reporting and statistics.

This feature is now disabled, as in modern operating systems there is dubious benefit, and it can produce stability problems in some cases. However, if this variable is set in the environment when WRspice is started, the local allocator will be used. The interested user is encouraged to experiment.

XT_SYSTEM_MALLOC
This variable was once used to disable the internal local memory allocator, which in earlier releases was enabled by default. Currently, this variable is ignored.

XT_GUI_COMPACT
When set, no extra space is allowed around pushbutton contents in the graphical interface. Such space can cause menu button images to be truncated on low-resolution displays if the theme in use imposes too much space. Setting this variable is a quick fix for this problem, though one could also change the theme.

There are several environment variables which can be used to alter some of the WRspice defaults. On startup, WRspice checks for the following variables in the environment, and alters internal defaults accordingly. The defaults can be modified when the program is built, the defaults listed below are those assigned in the distribution.

HOME
This is used only in the Microsoft Windows version, and can be set to a full directory path which will be taken as the user's home directory.

DISPLAY
This variable defines the X window system display that WRspice will use, but is ignored if the -d option is used on the WRspice command line. The display must be specified for graphics to be enabled in WRspice.

EDITOR
If defined to the invoking string for a text editor, that editor will be used in the edit command. This is superseded by the SPICE_EDITOR variable, if set.

SPICE_EDITOR
The text editor called by the edit command can be set with this variable. The variable is defined to the command string one would type to invoke the editor. This will supersede the EDITOR variable, if set, but which would otherwise have the same effect. If no editor is specified in the environment, or with the editor shell variable, which supersedes the environment variables, a default internal editor is used. The default internal editor can also be specified by setting SPICE_EDITOR to nothing, ``default'', or ``xeditor''.

TMPDIR
This specifies a directory to use for temporary files, and is superseded by SPICE_TMP_DIR, if defined. The default location if not specified is /tmp.

SPICE_TMP_DIR
When WRspice creates a temporary file, it will look for a directory named by the SPICE_TMP_DIR environment variable, and if not found the directory named in the TMPDIR variable, and if still not found the file will be created in /tmp.

SPICE_EXEC_DIR
This variable can be used to define the directory containing the XicTools binaries, used by the aspice command and the wrspiced daemon. If not set, the default is ``/usr/local/xictools/bin'', or, if XT_PREFIX is set, its value replaces ``/usr/local''.

SPICE_PATH
This can be used to set the full path to the WRspice executable, for the aspice command and the wrspiced daemon. If not set, the default is ``/usr/local/xictools/bin/wrspice'', or, if XT_PREFIX is set, its value replaces ``/usr/local''. The SPICE_EXEC_DIR variable can also be used for this purpose, unless the wrspice executable has been renamed. The spicepath shell variable, if set, will override the path set in the environment.

SPICE_LIB_DIR
This variable can be used to change the default location where WRspice looks for system startup files. If not set, the internal default is ``/usr/local/xictools/wrspice/startup'', or, if XT_PREFIX is set, its value replaces ``/usr/local''.

SPICE_INP_PATH
This can be set to a list of directories to search for input files and scripts. If not set, the internal default is ``( . /usr/local/xictools/wrspice/scripts )'', or, if XT_PREFIX is set, its value replaces ``/usr/local''.

SPICE_HLP_PATH
This can be set to a list of directories to search for help database files. If not set, the internal default is ``( /usr/local/xictools/wrspice/help )'', or, if XT_PREFIX is set, its value replaces ``/usr/local''. This is superseded by the helppath shell variable, if set.

SPICE_NEWS_FILE
This variable can be set to the full path to a text file which is printed when WRspice starts. If not set, the file /usr/local/xictools/wrspice/startup/news will be printed, if it exists (if XT_PREFIX is set, its value replaces ``/usr/local'').

SPICE_BUGADDR
This variable can be set to an internet mail address to use in the bug reporting command. If not set, the built in default is the Whiteley Research technical support address.

SPICE_OPTCHAR
This variable can be defined to a character that will be used to flag options on the WRspice command line. If not defined, the option character is ``- ''.

SPICE_ASCIIRAWFILE
If this variable is defined to ``0'' (zero), or to a word starting with `f' or `F' such as ``False'', or `n' or `N' such as ``No'', WRspice will create binary plot-data files (rawfiles). If not set or set to something else, WRspice will create the default ASCII-format rawfiles. The filetype shell variable can also be used to set the mode, which will supersede the environment variable. The rawfiles are normally created with the write command.

SPICE_HOST
This variable can be used to set the host name to use for remote SPICE runs. The host name can optionally be suffixed by a colon followed by the port number to use for communication with the wrspiced daemon. If not given, the port is obtained from the operating system for ``wrspice/tcp'', or 6114 (the IANA registered port number for this service) if this is not defined. There is no default for this variable. Hosts can also be specified with the rhost command, and given with the rhost shell variable.

SPICE_DAEMONLOG
This variable is used by the wrspiced daemon program to set an alternate path for the log file. The default path is /tmp/wrspiced.log.

SPICENOMAIL
If the variable SPICENOMAIL is set, no mail will be sent during a program crash. If a fatal error is encountered, a file named ``gdbout'' is created in the current directory, which contains a stack backtrace from the stack frame of the error. Despite the name, the file is generated internally on all platforms, and no longer makes use of the gdb program.

By default, this file will be emailed to Whiteley Research for analysis. However, the emailing can be suppressed by setting this variable in the environment. The gdbout file is produced in any case, and would be very useful to Whiteley Research for fixing program bugs.

XTNOMAIL
This has the same effect as SPICENOMAIL but also prevents email from the Xic program.