Installation

Prerequisites

You need to have an EPICS-3.14 base and its dependencies (GNU make, Perl) installed.

From version 2.1 onwards, building the sequencer requires the lexer generator tool re2c. If you are on a Linux system, you will probably want to use the re2c package your distribution provides, otherwise sources and windows binaries are available from the re2c download page. The minimum version required is 0.9.9, but I recommend using the latest version that is avaliable for your system.

Download

Releases are available here:

The current stable release is 2.1.16. Please take a look at the Versioning Policy if you are unsure whether to upgrade to a new release.

Development snapshots are available under the name

seq-snapshot-<date>.tar.gz

In the releases directory there is always a symbolic link to the latest snapshot.

Older releases can be downloaded by following the links here:

Version Release Notes Known Problems
2.1.16 Release 2.1.16 n/a
2.1.15 Release 2.1.15 Known Problems in Release 2.1.15
2.1.14 Release 2.1.14 Known Problems in Release 2.1.14
2.1.13 Release 2.1.13 Known Problems in Release 2.1.13
2.1.12 Release 2.1.12 Known Problems in Release 2.1.12
2.1.11 Release 2.1.11 n/a
2.1.10 Release 2.1.10 Known Problems in Release 2.1.10
2.1.9 Release 2.1.9 n/a
2.1.8 Release 2.1.8 Known Problems in Release 2.1.8
2.1.7 Release 2.1.7 Known Problems in Release 2.1.7
2.1.6 Release 2.1.6 Known Problems in Release 2.1.6
2.1.5 Release 2.1.5 Known Problems in Release 2.1.5
2.1.4 Release 2.1.4 Known Problems in Release 2.1.4
2.1.3 Release 2.1.3 n/a
2.1.2 Release 2.1.2 n/a
2.1.1 Release 2.1.1 n/a
2.1.0 Release 2.1.0 n/a
2.0.14 Release 2.0.14 n/a
2.0.13 Release 2.0.13 n/a
2.0.12 Release 2.0.12 n/a
2.0.11 Release 2.0.11 n/a
2.0.10 Release 2.0.10 n/a
2.0.9 Release 2.0.9 n/a
2.0.8 Release 2.0.8 n/a
2.0.7 Release 2.0.7 n/a
2.0.6 Release 2.0.6 n/a
2.0.5 Release 2.0.5 n/a
2.0.4 Release 2.0.4 n/a
2.0.3 n/a n/a
2.0.2 n/a n/a
2.0.1 Release 2.0.1 n/a
2.0.0 Release 2.0 n/a
1.9.5 Release 1.9 n/a
1.9.4 Release 1.9 n/a

(Not listed are alpha releases and repository snapshots.)

If you want to help testing, please use the latest snapshot, or check out the darcs repository:

> darcs get http://www-csr.bessy.de/control/SoftDist/sequencer/repo/<branch>

where <branch> is the branch name. There are currently three branches:

  • branch-2-0 is the previous version. This branch is now frozen and will receive no more patches, nor will there be any new releases.
  • branch-2-1 is the current “stable” version. Development is restricted to bug fixes (including fixes for build problems) and improvement of the documentation.
  • branch-2-2 is where new features are developed that will appear in version 2.2. Release 2.2.0 will soon go into beta testing phase.

See Contribute for a short description how to record and send patches.

You can also follow development by using the repository browser.

Unpack

Change to the directory that you wish to be the parent of the sequencer source tree. Then unpack and untar the file. For example:

> gunzip seq-x.y.z.tar.gz
> tar xf seq-x.y.z.tar

or, if you have GNU tar, simply:

> tar zxf seq-x.y.z.tar.gz

You can now:

> cd seq-x.y.z

and look at the source tree. The actual source code for the sequencer is under src. The documentation sources are under documentation and consist of plain readable text files (actually, the format is reStructuredText but you need to know about that only if you plan to make changes to the docs).

In what follows, $SEQ refers to the directory where you are now, i.e. .../seq-x.y.z/.

Configure and Build

The sequencer uses the EPICS build system. This means there is no automatic configuration, instead you have to edit the file configure/RELEASE and perhaps also configure/CONFIG_SITE. These are make include files, so the syntax is that of (GNU) make.

In configure/RELEASE, change the definition of the variable EPICS_BASE to the path where your EPICS base is installed.

In configure/CONFIG_SITE, you can specify the target architectures for which to build via the CROSS_COMPILER_TARGET_ARCHS variable (a subset of those for which EPICS has been built, default is all), and the message systems to support via the PVXXX variables (the default is to use only CA). You can also configure where the re2c tool is installed (the default configuration assumes that it can be found in your PATH).

Your environment should be configured for building EPICS applications. This means that EPICS_HOST_ARCH and (possibly) LD_LIBRARY_PATH should be correctly defined. See the EPICS Application Developer’s Guide for details.

After changing the files in configure, run GNU make.

Note that make builds first in the configure directory, then the src tree, and finally the test and examples trees. A failure in the latter two will not impact your ability to write SNL programs (but is still a bug and should be reported, see Report Bugs).

Building the Manual

From 2.0.99 on, the manual is in reStructuredText format. This format is (more or less) readable plain text, so this section is optional.

Building the manual means generating a set of html pages and maybe a single pdf from the sources.

The html pages are generated by issuing:

> make docs=1

This will generate the home page and install it into the directory $SEQ/html. This step requires that you have Python and Sphinx installed on your system.

If, in addition, you want a printable version (pdf), do:

> make docs=1 pdf=1

This generates a pdf file named Manual.pdf and also puts it into the html subdirectory. Note that pdf generation is done via latex, so you need to have a working latex installation. On my system (kubuntu karmic) I also needed to install the package tetex-extra.

Test

Since version 2.1, the sequencer comes with an automated test suite. You can run all tests by issuing

> make -s runtests

(the -s option is to suppress irrelevant output generated by make). Note that this requires EPICS base R3.14.10 or later, since we use the test support in base.

To run just one test from the suite, switch to the architecture build directory of the test and execute perl with the name of the test program ending in .t. For example, to run the evflag test on a linux-x86_64 host, change directory to test/validate/O.linux-x86_64 and run

> perl evflag.t

There are two ways to run a test that has an associated database (evflag is such a test). The above will run the state machine and database on the same IOC. To run the test as two separate IOCs, use the test program ending in Ioc.t (e.g. evflagIoc.t). The IOC running the state machine runs in the foreground, and the one running the database runs in the background.

The test suite can also be run on an embedded system. Currently only vxWorks systems are supported, but RTEMS will follow soon. To do this, point the vxWorks startup script to

$SEQ/test/validate/O.$T_A/st.cmd

where $T_A is the name of the target architecture and $SEQ refers to the (absolute) path of your sequencer installation. The system will start an IOC and will run a number of SNL test programs, one after the other, after each one giving a summary of how many tests failed etc.

To check out an example, change directory to examples/demo and run

> ../../bin/$EPICS_HOST_ARCH/demo stcmd.host

The output should look something like this:

ben@sarun[1]: .../examples/demo > ../../bin/linux-x86/demo stcmd.host
dbLoadDatabase "../../dbd/demo.dbd"
demo_registerRecordDeviceDriver(pdbbase)
dbLoadRecords "demo.db"
iocInit
Starting iocInit
############################################################################
###  EPICS IOC CORE built on Mar  3 2010
###  EPICS R3.14.8.2 $R3-14-8-2$ $2006/01/06 15:55:13$
############################################################################
iocInit: All initialization complete
seq &demo "debug=0"
SEQ Version 2.1.0, compiled Fri Jul 15 12:44:09 2011
Spawning sequencer program "demo", thread 0x8064f48: "demo"
start -> ramp_up
epics> light_off -> light_on
ramp_up -> ramp_down
light_on -> light_off
ramp_down -> ramp_up
light_off -> light_on
ramp_up -> ramp_down
...

If you see the “start -> ramp_up” etc. messages, things are good. From another shell, do the following:

> camonitor demo:ss_light demo:ss_ramp demo:ss_limit
demo:ss_light                  2011-07-15 12:35:24.809118 LIGHT_ON
demo:ss_ramp                   2011-07-15 12:35:24.809131 RAMP_DOWN
demo:ss_limit                  2011-07-15 12:35:24.809126 START
demo:ss_light                  2011-07-15 12:35:29.829946 LIGHT_OFF
demo:ss_ramp                   2011-07-15 12:35:34.850682 RAMP_UP
demo:ss_light                  2011-07-15 12:35:40.873949 LIGHT_ON
...

This illustrates the very basic “sequencer device support” that was added in release 2.0. These records are returning the names of the first two state-sets of the demo program.

Use

This is a short description how to use the sequencer in an EPICS application. For more general usage information, see the section on Compiling SNL Programs and Running SNL Programs.

To use the sequencer in an EPICS application, change the definition of SNCSEQ in configure/RELEASE (that is, the one in your application, not the sequencer’s) to contain the path to your sequencer installation.

As soon as SNCSEQ is defined, the EPICS build system automagically includes the build rules defined in the sequencer. To add an SNL program to your application, write something like

SRCS += xyz.st
abc_LIBS += seq pv

into your Makefile. Here, xyz.st is the name of your SNL program, and abc is the name of the library or binary to produce. Note that .st files are run through the C preprocessor (cpp) before giving them to the SNL compiler. Use the extension .stt to avoid this. For details, see Chapter 4 of the EPICS Application Developer’s Guide.

A complete example application that also uses the sequencer can be produced using makeBaseApp, e.g.

> makeBaseApp.pl -t example ex

Take a look at exApp/src, especially the Makefile.

Report Bugs

Please send bug reports to to tech-talk@aps.anl.gov or the maintainer (currently this is me). It helps if you include which release of the sequencer and EPICS base release you are using.

Contribute

I am always happy to receive patches (bug fixes, improvements, whatever). You can create a local copy of the darcs repository (the stable branch in this example) by saying:

> darcs get http://www-csr.bessy.de/control/SoftDist/sequencer/repo/stable

Assuming you have made some changes, first update your repository to include the latest changes from upstream (with darcs this is not strictly necessary, but good practice as it helps to avoid unnecessary conflicts):

> darcs pull

(darcs will ask you for each patch that is not yet in your repo). Then record your changes (if you haven’t already):

> darcs record

(darcs will prompt you for every single change you made and then prompt you for giving the patch a name). Finally say:

> darcs send

A word of caution: it may happen that I darcs obliterate patches in the experimental branch. If darcs send asks whether to include patches that you don’t have authored, this is probably what happened. In that case can (but you need not necessarily) quit and obliterate them in your source tree, too, before trying to darcs send again.

Please respect the coding style when making changes. This includes indentation (tabs or spaces, how many) and all the other little things on which programmers like to differ ;-) like placement of braces etc. Note that for historical reasons the style differs somewhat between files and subdirectories. It is much easier for me to review patches if they do not contain gratuitous changes or combine several unrelated changes in a single patch.

Also, please take care that your patch does not accidentally contain site-specific changes (typically done in configure). For my own work, I usually record such changes with a description that contains ‘DONT SEND THIS’ or something similar, so I don’t accidentally record them together with other changes.