DESCRIPTION

These notes describe how to download and install spec.

PREPARATION

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 needs 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), spec must be installed by root.

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

If moving to a new computer, easiest (if possible) is to move 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.

NOTES

install_data Options

The file install_data 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.

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 give.

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. Both geometry and directory can be overridden with the -g and/or -N command line flags. See the spec help file. There is a one-to-one correspondence between the names given here the "geo" names given above.

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 spec build. Appropriate prebuilt libraries are included in the spec distribution. Note, 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 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.

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. 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 uses the Linux capabilities facility to gain access to privileged I/O (such as PCI card registers for hardware control). Earlier versions of spec (prior to release 6.05) used setuser-id root mode.

Privileges are only enabled briefly around the calls that gain access. After gaining access, the code releases the capabilities. One can run spec as the root user and have access to all hardware, but CSS strongly recommends not running spec (or even a shell) as the root user as normal operating procedure due to the possibility of doing catastrophic damage to the operating system with a single mistyped command.

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.

During installation as root user, spec installs a file /etc/udev/rules.d/10-spec_usb.rules which uses the udev dynamic device management capability to ensure users have access to spec-supported hardware. If udev rules are not in place to set permissions for USB devices supported by spec, spec can use the escalated permissions provided by the "dac override" capability to access the device nodes.

udev Rules

On Linux platforms, when the spec Install script is run by the root user, a file /etc/udev/rules.d/10-spec_usb.rules is installed or updated, as mentioned above. 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 some devices from kernel drivers that otherwise would take over, preventing spec from controlling the hardware. Also, some rules create special nodes in /dev to ease spec configuration by having predictable names.

See the comments in the spec_usb.rules file in the spec distribution for details.