OVERVIEW

To keep the files associated with spec organized, CSS recommends creating a user account named specadm that will own the spec files. We also recommend that the distribution files associated with each version of spec be placed in a subdirectory named after the release number in the home directory of specadm. For example, if installing spec release 6.12.03 and if the home directory of specadm is /home/specadm, then the spec distribution might be placed in a directory named /home/specadm/spec6.12.03. The downloaded distribution "tarball" files might be stored in a separate directory, such as /home/specadm/dist/.

The above are just suggestions. The spec files can be owned by any user and placed anywhere. spec uses a specific directory for its auxiliary files, which by default is /usr/local/bin/spec.d. If a different location is selected using the Install script, described below, spec will be compiled to use that location. Or if the environment variable, SPECD, is set to a different location, that will directory will be used. Or the directory can be specified using the -D start-up option. See the spec help file.

DOWNLOADING

spec is distributed as a tar format file, usually retrieved from the certif.com server. One generally receives emailed instructions on the exact path name to access a particular spec distribution from the http server. Distributions can only be retrieved by name, as the contents of the distribution directory are hidden.

Assuming the recommended locations, the usual procedure for downloading the spec distribution is as follows:

cd /home/specadm/dist

then

wget http://certif.com/css_dist/spec_distver.tar

or

curl -O http://certif.com/css_dist/spec_distver.tar

(The -O option saves the file using the same name as the remote file.) The distver part of the file name will be unique to each download and will include the release number.

EXTRACTING

Again, assuming recommended locations, use commands along the following lines to extract the spec distribution from the tar file. For example, for release 6.12.03 use:

cd /home/specadm
mkdir spec6.12.03
cd spec6.12.03
tar xvf ../dist/spec_distver.tar

INSTALLING

If updating a previous installation of spec, copy the install_data file from the previous distribution directory to the current distribution directory. That will save having to retype the same responses to the configuration questions.

From the distribution directory, run the script ./Install, with possible options as described below.

By default, spec expects to be installed by the super user (root). The -S flag allows spec to be installed by a non-root user. However, to access certain privileged I/O (such as PCI card registers for hardware control), root installation may be necessary. See the Privileged I/O Access section below.

Some of the following Install options may be of interest.

-c	Don't clear screen between questions.
-d	Use defaults from "install_data", don't ask questions.
-p	Just install configuration-dependent files.
-C	Remove locally compiled files from last Install.
-y	With -C, don't ask for confirmation.
-s	Just build the spec executable in the current folder.
-S	Install even if not root.
-v	Display make commands as executed.
-f file	Use file instead of install_data.

MOVING TO A NEW COMPUTER

If moving to a new computer, easiest (if possible) is to move or copy the auxiliary file directory (normally /usr/local/lib/spec.d) from the old computer to the new computer. Then install from the new spec distribution as described above. The installation will replace files it needs to replace and update files it needs to update. Files such as those containing the hardware configuration and motor settings will remain in place.

One way to transfer the files is on the old computer:

cd /
tar cvfz /tmp/spec.tgz /usr/local/lib/spec.d

Then copy the file /tmp/spec.tgz to the new computer. On the new computer:

cd /
tar xvfz /tmp/spec.tgz

INSTALLING splot

The spec distribution includes a stand-alone plotting utility called splot, which is written in Python. There is a script in the spec distribution directory called install_splot_needs. Run the script to make sure the many Python packages needed by splot are installed. The splot utility is a many featured alternative to the basic X11 plotting included with spec. Enable use of this splot using the setplot macro in spec.

INSTALLING C-PLOT

The spec package includes C-PLOT from CSS. The C-PLOT package is distributed as a compressed tar file and can be retrieved using wget or curl with the download link provided in the instructions from CSS.

Standard C-PLOT installation is as follows. If a first time installation, using the customary locations:

mkdir /usr/local/cplot
ln -s /usr/local/cplot/bin/cplot /usr/local/bin/cplot
ln -s /usr/local/cplot/bin/newfunc /usr/local/bin/newfunc

Then

cd /usr/local/cplot
tar xvfz path_to/cplot_dist.tgz

where cplot_dist is the unique part of the file name provided in the email from CSS and path_to is where the file was downloaded.

It is safe to install a new C-PLOT distribution on top of an existing one.

RESTARTING AFTER AN UPDATE

spec stores each user's state information in a file when it exits and restores that information the next time the user starts the program. The state file contains current macro definitions, parameter values and other information. spec updates often include updated standard macro definitions. After updating spec, users should run the standard macro newmac, which will reread the standard macro definitions and incorporate those new definitions into the spec state. Alternatively, users can start spec with the -f flag which starts spec with a new (fresh) state which will include the current standard macro definitions. See the spec help file.

NOTES

install_data Options

The file install_data (or an alternative file specified by the -f option) is created to hold the parameters used by the Install script. If the file exists and the parameters are current, use the -d option to skip the interactive part of the script. The install_data parameters are as follows. For most, a value of "no" means the parameter is not needed. If multiple values are given separated by spaces, enclose the value list in double quotes.

geo

The diffractometer geometries to include. Each geometry includes special code to translate between motor positions and reciprocal space coordinates. A file named geometries in the spec distribution lists the possibilities. A simple "spec" means a geometry-less configuration. Multiple geometries can be given.

name

The first four letters of the installed name determine the geometry. The full name determines the directory for the hardware configuration and user state files. There is a one-to-one correspondence between the names given here and the "geo" names given above. Both geometry and directory name can be overridden with the -g and/or -N command line flags when starting spec from the shell. See the spec help file.

owner

If installing as root, file ownership of the installed spec files will be given to the owner selected here. The default is specadm.

install

The directory for the executable files. The default is /usr/local/bin/. The directory should be in each user's PATH environment variable.

aux

The directory for spec's auxiliary files. The default is /usr/local/lib/spec.d/.

taco_home

The location of the TACO device server libraries, if using. There should be a subdirectory named lib in this directory. If using TANGO, set to "no".

tango_home

The location of the TANGO device server libraries, if using.

epics_home

The location of the EPICS channel access libraries, if using. It should be a path that has a subdirectory named base, a path to the base directory that has a subdirectory named lib, or the complete path to the directory containing the EPICS libraries for this platform.

hdf5_libs

The location of the HDF5 (Hierarchical Data Format) libraries, if using. Note, the library version should match the spec build. Appropriate prebuilt libraries are included in the spec distribution. The prebuilt library is static. If one has shared HDF5 libraries with the correct version available, set this parameter to point to such a library.

tiff_lib

The location of the TIFF library. Include to enable reading TIFF image files using fmt_read(). See notes in the fmt_tiff.c file included in the spec distribution for details.

perm

The permissions given to the hardware config files. The default is "u=rw,g=rw,o=rw", which is writable by anyone.

editline

The command-line editing library. The default is the libedit/libedit.a included in the spec distribution. A locally provided libreadline.a can be configured. If no library is used, only a very simple built-in history feature will be available.

site_flags

Extra compile flags for building the site-dependent files.

site_obj

Additional site-dependent object files, such as those provided by hardware vendors.

site_lib

Additional site-dependent libraries.

The default install_data contains the following:

geo=fourc
name=fourc
owner=specadm
install=/usr/local/bin
aux=/usr/local/lib/spec.d
taco_home=no
tango_home=no
epics_home=no
hdf5_libs=no
tiff_lib=no
perm=u=rw,g=rw,o=rw
editline=libedit/libedit.a
site_flags=no
site_obj=no
site_lib=no

Missing Linux Packages

The spec executable is linked with various libraries during installation. This method allows sites to customize whether spec includes support for such packages as EPICS or TACO along with which diffractometer geometries to include. The EPICS and TACO libraries are not included in the spec distribution. The libraries must be installed locally.

On Linux systems, a couple of other libraries may need to be installed:

libncurses

spec links with the ncurses package which provides support for terminal screen drawing. The library is part of a development package, and is not typically installed by default on Linux systems. On Redhat, CentOS, Rocky, Alma, Fedora, Scientific Linux, Vine and openSUSE, the package is called ncurses-devel. On Debian, the package is libncurses-dev. On Ubuntu and Mint, the name is libncurses5-dev.

libtirpc

Some supported hardware requires the old Sun RPC (remote procedure call) library. The needed library functions are no longer included in glibc (the implementation was not compatible with IPv6). The function calls are available in a separate library called libtirpc. Most Linux distributions do not include this package by default. If the library is missing, the spec Install script will link with a dummy library and print a message that the RPC hardware will not be available.

The RPC calls are used in the spec support for ESRF TACO libraries, SPring-8 MADOCA RPC hardware, VXI-11 generic access, and HP/Agilent E2050/E5810 GPIB. If RPC support is needed for any of these, install the library and rebuild spec. (Use the -C option with Install to ensure spec gets relinked.) On Redhat, CentOS, Rocky, Alma, Fedora, Scientific Linux, Vine, openSUSE and similar, the package is libtirpc-devel. On Debian, Ubuntu, Mint and similar, the library is libtirpc-dev.

Privileged I/O Access

On Linux platforms, spec is often configured to use USB devices or PCI cards for instrument control and data acquisition. The default Linux installation generally limits access to such hardware to privileged users. There are several ways for ordinary users to gain access to this hardware.

On modern Linux platforms, the udev facility provides a way to configure access to privileged hardware with a set of rules that are acted on at boot time. The rules can also be triggered when connecting a USB device or by the command udevadm trigger (on modern Linux platforms). spec includes a rules file that handles most of the modern hardware that spec supports. Note, root access is required to install that file. See udev Rules below.

To accommodate hardware that isn't covered by the udev rules, the default spec installation uses the Linux capabilities facility to gain access to privileged I/O. Earlier versions of spec (prior to release 6.05) used setuser-id root mode. With either method, the privileges are only enabled briefly around the calls that gain access. After gaining access, the code releases the capabilities or privilege level.

One can run spec as the root user and have access to all hardware, but CSS strongly recommends against running spec (or even a shell) as the root user as normal operating procedure. One can of do catastrophic damage to the operating system with a single mistyped command when one has root privilege.

If the udev rules provide access to all the needed hardware, it is not necessary for spec to have special privileges. The spec Install script can be run with the -S flag, which allows a non-privileged user to install or update spec, as long as the user has write permission in the configured "install" (for executables) and "aux" (auxiliary files) directories. Note, though, root access is required initially to install the udev rules file. After running the Install script as an unprivileged user, run the install_udev_rules file as root as explained below.

The command to give the spec executable the needed capabilities is issued during installation when the spec Install script is run by the root user. The command used is:

setcap "cap_sys_rawio=ep cap_dac_override=ep cap_sys_admin=ep"

The "raw io" capability grants access to I/O ports. The "dac override" capability is needed for mapping PCI/PCIe memory space to the spec process. ("Dac override" overrides discretionary access control, that is, bypasses file access permissions.) In order for spec to enable PCI/PCIe cards that were disabled on boot by the Linux kernel, spec requires "sys admin" capability.

Linux ldconfig Considerations For Shared Libraries

On Linux platforms, the default installation parameters give the spec executable special privileges in order to access hardware interfaces. If installed with special privileges, there are additional considerations when linking spec with local shared libraries, such as those providing EPICS or TACO/TANGO support. Shared libraries used by spec must be configured system wide when the spec executable has privileged capabilities. That can be accomplished by creating (or editing if it already exists) a file called, for example:

/etc/ld.so.conf.d/local.conf

The file should contain a line with the complete path name of the shared library folder, such as:

/opt/EPICS/base/lib/linux-x86

Run the following command (as root) to update the shared library information on the system:

/sbin/ldconfig

See the Linux man pages for ldconfig, ld.so and capabilities for further information.

udev Rules

spec can use the Linux udev dynamic device management facility to ensure users have permission to access spec-supported hardware. During installation as root user on Linux platforms, spec will run the command in the spec distribution:

install_udev_rules

to copy the file spec_usb.rules (with possible substitutions depending on Linux version) to

/etc/udev/rules.d/10-spec_usb.rules

In addition to setting permission for USB devices nodes of spec-supported hardware to allow access to all users, the file contains rules that unbind certain devices from the kernel drivers that otherwise would take over, preventing spec from controlling the hardware. Also, some of the rules create special nodes in /dev to ease spec configuration by having predictable device names. For a few USB-to-serial devices, rules load required driver modules. As of spec release 6.13.04, there are rules to allow access to memory addresses of selected PCI/PCIe modules and to ensure such modules are enabled. See the comments in the spec_usb.rules file in the spec distribution for details.

spec.conf and Help File Formatting

The spec Install script creates a text file in the auxiliary file directory (normally /usr/local/lib/spec.d) named spec.conf. This file contains the paths and argument strings for several standard utilities used for help file formatting and display. Default values for these parameters are:

CAT="/bin/cat"
SED="/usr/bin/sed"
GROFF="/usr/bin/groff"
NROFF="/usr/bin/nroff"
TBL="/usr/bin/tbl"
PAGER="/usr/bin/less"
PYTHON="/usr/bin/python"
DOCUTILS_OK="OK"
GROFF_ARGS="-Wall -mtty-char -Tascii"
NROFF_ARGS="-Tascii"
PAGER_ARGS="-deisRX"

The spec.conf file can contain alternate pathnames for the utilities. If the alternate doesn't exist but the default does, spec will use the default.

The spec distribution includes three versions of each standard help file: the original restructured text (.rst) version, a version converted to the standard man page (or roff) format, and a pre-formatted version for an 80 column wide window. If the display window is between 80 and 92 columns, the preformatted version is displayed. Otherwise, the man format is run through tbl and groff (or nroff if that is present and no groff). In each case, the output is piped through the PAGER utility, if one is available.

If the help file topic ends with a .rst extension, if Python is available and if the Python docutils package is installed, spec will use Python with an rst2man Python script in the spec distribution to format the file to display and fit in the current screen window.

The current spec help utility can also display help files from spec release 5 and earlier that use the old roff style formatting if groff or nroff is available.

Linked Configurations

Consider an installation such as a synchrotron beamline that has many motors associated with beamline control along with multiple spectrometers that have their own unique set of motors. To avoid having to merge the motor configurations and settings from one set of files to another when the spectrometer is changed, hardware configuration can be set up so that a single version of the config and settings files will describe a number of different spectrometers. Scaler channels can also be designated as common or can be assigned to a specific spectrometer configuration.

Here is how to set up the a linked configuration:

1) As a precaution, if there are already several geometry configurations installed, make backup copies of the config and settings files from the current geometries.

2) Remove the config and settings files from all but one of the geometry directories.

3) Edit the remaining config file by hand to add new control lines that assign numbers to the different geometries. These control lines must be before the lines that assign motor information. The format of the geometry control lines is as follows:

GEO0 = common
GEO1 = fourc
GEO2 = surf
GEO3 = fivec
etc.

The parameter GEO0 always refers to the motors that are common to all the geometries. Subsequent lines assign consecutive numbers to the other geometries.

4) Set up hard links in all the geometry directories so that the config and settings in all the geometry directories refer to the same file. For example, if the files already exist in the fourc directory, use the commands:

ln fourc/config surf/config
ln fourc/settings surf/settings

to create hard links in the surf directory. Don't use symbolic links.

5) Now run the hardware configuration editor. Use config from spec or edconf from the shell. For the latter, use something like:

cd /usr/local/lib/spec.d
./edconf fourc

The motor and scaler screens will have a new field that assigns a spectrometer geometry to each motor or scaler or makes the motor or scaler common with all the spectrometers.

The hard links must be maintained for the shared config and settings file scheme to work. The vi and cp utilities can be safely used to manipulate the files. However, the mv utility will destroy the links.

When running edconf with a geometry directory as an argument or when invoking the config macro from spec, the G command toggles between displaying all the motors and counters in the config file and just those motors and counters used by the given geometry.

Server Mode

In server mode, in addition to responding to keyboard commands, spec also listens for remote commands from other instances of spec or possibly non-spec clients. See the server help file for details.

Daemon Mode

Daemon mode is similar to server mode, except that spec completely disconnects from the terminal session. See the daemon help file for details.

Start-Up Log Files

The spec start-up option -l logfile specifies an output for logging. Output to the file will begin immediately, so will include the initial hardware configuration messages. Files will be opened even when starting fresh. Files opened this way will not be saved as output files in the state file, so will not automatically be reopened the next time spec starts.