fsc2: A.3 Preparing for installation

A.3 Preparing for installation

After installing the required tools and libraries (see above) and extracting the archive with the distribution of fsc2 go into the newly created directory `fsc2'. Now you have to set up fsc2 for your system and requirements. You can use two methods. You either edit the `Makefile' directly and change the variables at its top. Alternatively, go into the `machines' subdirectory and copy the file `template.nowhere' to a file with the fully qualified hostname of your machine (i.e. its full name, including the domain name - but please make also sure that your machine has a domain name set!) as its name. Now edit this file and it will automatically get evaluated during the make process. This is probably more convenient: when you edit the `Makefile' you will have to do it again each time you install a new version. In contrast the file in the `machines' subdirectory can just be copied from an existing installation to a new version and everything should stay the same.

Now follows a description of all the variables that can be set to change the way fsc2 is created and installed (which is more or less identical to the comments in the Makefile as well as the template for the machine file in the 'machine' directory):

Normally, fsc2 and all auxiliary files needed will be installed below `/usr/local/' (in `/usr/local/bin/', `/usr/local/lib/fsc2/', `/usr/local/info/' and `/usr/local/share/doc/'). To change this location edit the lines defining the variable prefix in the `Makefile' or the file you're setting up for your machine.

If you're on a rather old system that doesn't support linker version scripts (probably on a system with a 2.0 or 2.2 kernel) you may need to define the variable NO_VERSION_SCRIPTS.

The next two variables, OWNER and GROUP, will be used when setting the owner of all the files that will be installed as well as its group. See the preceeding section for all the details and security implications.

The variable DEF_INCL_DIR sets a default directory for EDL include files (see the documentation for the EDL #INCLUDE directive for details).

The next lines are for setting the GPIB library that you are going to use. You may set the first variable, GPIB_LIBRARY, either to

`LLP': for the old Linux Lab Project library
`SLG': for the updated version of the Linux Lab Project library, now hosted on SourceForge
`NI': for the newer National Instruments library (but up until know I haven't got that to work correctly),
`NI_OLD': for the old National Instruments library (you can distinguish them from the include file they install, if it's `ni488.h' then it's the newer version, if it's `ugpib.h' it's the older one)
`JTT': for the library I wrote for some ISA GPIB cards
`NONE': if you don't use any GPIB cards

In the last case (i.e. if GPIB_LIBRARY is set to NONE) fsc2 won't be able to run experiments requiring devices that are controlled via the GPIB bus (but you still can test such EDL programs). Use this option only if you either want to built a test version or if all your devices are controlled via other means (i.e via serial ports, are PCI or ISA cards, Rulbus devices or are controlled via the LAN).

If you use the SourceForge or the Linux Lab Project driver and library you also may have to define the name of the GPIB card as it is set in the GPIB configuration file by defining the variable GPIB_CARD_NAME (the default is "gpib0").

If you use the National Instruments GPIB driver you can set the location where fsc2 will expect the GPIB configuration file, `gpib.conf' via the variable GPIB_CONF_FILE (this is only needed for the National Instruments library, in all other cases fsc2 doesn't need to know about this file). But usually there is no reason to change the default value, which is `/etc/gpib.conf'.

For the new National Instruments library you can also set the variable GPIB_CIB_FILE. If this is set the Makefile will try to link against this file (normally it's called cib.o). By linking in this file the dynamic library (libgpibapi.so) will only be loaded when the first call is made into the library, otherwise the library gets loaded on start of the program. To be able to link the file in the exact location of the file is needed and must be set by the variable GPIB_CIB_FILE.

While running fsc2 may write out information about the activity on the GPIB bus into a log file. You can change the default log file q`/tmp/fsc2_gpib.log' to something appropriate for your setup by setting the variable GPIB_LOG_FILE (if it's not set logs will be written to stderr unless GPIB_LOG_LEVEL is set to OFF). You can also set the verbosity of the logs by changing the variable GPIB_LOG_LEVEL to either HIGH (logs everything including messages sent over the bus) MEDIUM (logs function calls and errors), LOW (the default, just logs errors) or OFF (no logging ta all). Please note that the file can get rather large, so better have it on a partition where there is a lot of free space. In order not to have it grow indefinitely each time a new experiment is started the log file is truncated to zero length, so it contains only information about the last experiment you run.

If the header files for the GPIB library aren't in either '/usr/include' or '/usr/local/include' you will have to tell fsc2 where to look for them by setting the variable GPIB_HEADER_DIR accordingly.

With the variable WITHOUT_SERIAL_PORTS you can set if modules controlled via serial ports (or via USB-serial converters) are to created. If this variable is not set (i.e. serial port suppor is enabled) the next three variables, SERIAL_LOCK_DIR, SERIAL_LOG_FILE and SERIAL_LOG_LEVEL allow finer-grained control.

If set SERIAL_LOCK_DIR must be a string with the name of the directory where UUCP type lock files for the serial ports are created (there is a convention that programs opening a serial port create such a lock file that contains the process ID (PID) of the program as a decimal ASCII number, so that other programs can check if the port is already in use and by whom). According to version 2.2 of the Filesystem Hierarchy Standard this directory should be `/var/lock', but on old systems also `/usr/spool/locks' and `/usr/spool/uucp' were commonly used, so this can be adjusted via this variable. If you don't want lock files for the serial port to be created simply don't define this variable. A possible problem arises if you use programs creating lock files not in the HDB UUCP format (the PID being stored in a ten byte string, left-padded with spaces and with a trailing newline). In this case fsc2 will not try to remove stale lock files and instead print an error message to the terminal that the lock file has to be removed manually.

While running fsc2 may write out information about the activity on the serial ports into a log file. You can change the default log file `/tmp/fsc2_serial.log' to something appropriate for your setup via the variable SERIAL_LOG_FILE (if it's not set logs will be written to stderr unless SERIAL_LOG_LEVEL is set to OFF). You can set the verbosity of the logs by changing the variable SERIAL_LOG_LEVEL to either HIGH (logs everything including messages passed between the computer and the device), MEDIUM (logs function calls and errors), LOW (the default, just logs errors) or OFF (no logging at all). Please note that the file can get rather large, so better have it on a partition with enough free space. In order not to have it grow indefinitely each time a new experiment is started the log file is truncated to zero length, so it contains only information about the last experiment you run.

If there are devices controlled via LAN also a log file will get generated for keeping track of the communications. Again, you can change the default log file `/tmp/fsc2_lan.log' to something else via the variable LAN_LOG_FILE (if it's not set logs will be written to stderr unless LAN_LOG_LEVEL is set to OFF). You can set the verbosity of the logs by changing the variable LAN_LOG_LEVEL to either HIGH (logs everything including data exchanged over the network), MEDIUM (logs function calls and errors), LOW (the default, just logs errors) or OFF (no logging at all).

Via the EDITOR variable you can set the editor that gets invoked by fsc2 by default when the user clicks on the Edit button or wants to send a bug report. The user can still override this setting by setting the EDITOR environment variable.

By setting the variable BROWSER you can select the default browser to use when the Help button gets pressed and the manual is to be shown. Currently supported are netscape, mozilla, firefox,Opera, konqueror, galeon, lnyx and w3m (but a user can still override this by setting an environment variable named 'BROWSER).

The WITH_NI6601, WITH_PCI_MIO_16E_1, WITH_ME6000, WITH_WITIO_48 and WITH_RS_SPEC10 variables are only needed when support for the National Instruments 6601 GPCT card, the National Instruments PCI-MIO-16E-1 card, the Meilhaus Electronic 6000 or 6100 DAC card, the Wasco WITIO-48 DIO card or the Roper Scientific Spec-10 CCD camera are required. In these cases the lines where these variables are defined must be uncommented and the additional variables for the include paths and the exact locations for the required libraries may have to be changed. Please see the comments in the `Makefile' or the template file in the `machines' directory for details. Please note that defining WITH_RS_SPEC10 will lead to a few warnings during the compilation of the corresponding module of fsc2 since the header files for the PVCAM library for the Roper Scientific Spec-10 CCD have some issues I can't do anything about.

Moreover, support for the National Instruments PCI-MIO-16E-1 and the 6601 GPCT cards, the Meilhaus ME6000 and ME6100 DAQ and the Wasco WITIO-48 DIO card requires that the drivers and libraries for the cards (which are part of fsc2) are already successfully install, otherwise the corresponding modules can't be built. For support for the Roper Scientific CCD Spec-10 camera the PVCAM library supplied by Roper Scientific is required and also must be installed together with its header files before you should try to compile fsc2.

The WITH_HTTP_SERVER variable tells if support for the web server should be built into fsc2. Just comment out the line and the web server won't be available. If the web server gets included into fsc2 the next variable, DEFAULT_HTTP_PORT, determines on which port the web server will listen for incoming connections by default (use a number above 1023, lower numbered ports are only accessible by programs with root privileges). A reasonable choice is 8080.

Should fsc2 ever crash it tries to write out a file with information about the state of the program at that moment, the EDL script being executed etc. Per default this file will be written to the default directory for temporary files (usually `/tmp'). The file has a name like `fsc2.crash.1QfdRL', where the last 6 characters are picked randomly to avoid overwriting already existing files.

In some cases it can be preferable to write these files to some other location than the default directory for temporary files. For that case the variable CRASH_REPORT_DIR can be set up with the name of the directory (as an absolute path) these files are to written to. Please keep in mind that this directory must be writable by all users of fsc2.

A.3.1 Device setup

For each device there exists a configuration file in the `config' subdirectory. In some cases you don't have to change anything there, but e.g. for devices controlled via a serial port by may have to set the number of the port in the device's configuration file and for devices controlled via the LAN its IP number. There are also a number of modules with support for several models of a certain device and in this case typically the models type must be set correctly. Please take the time and have a look at the configuration files for all devices you're planning to use, the adjustable parameters should be documented clearly in the individual files.

This document was generated by Jens Thoms Toerring on September 6, 2017 using texi2html 1.82.