Download and Installation

This chapter gives instructions on how to download, build, and install the sequencer, as well as how to run the tests, build the manual, report bugs, and contribute patches.

Prerequisites

EPICS base

You need to have EPICS base and its dependencies (GNU make, Perl) installed. Any version of EPICS base starting with 3.14.12.2 and up to 3.15 should do. Starting with seq-2.2.6, EPICS 7 can be used.

re2c

Building the sequencer also requires the lexer generator tool re2c. The minimum version required is 0.9.9, but I recommend using the latest version that is avaliable for your system. If you are building on a Linux system, you can use the re2c package your distribution provides.

On Windows things are not quite as smooth. The old re2c download page on sourceforge contains pre-built binaries for Windows systems, albeit only up to version 0.13.5. If this doesn’t work for you, there is EPICS-re2c, a version of re2c that has been wrapped as an EPICS module. There is also a Windows build of re2c-1.0.3 on Appveyor.

In any case, if the re2c executable is not installed in a directory listed in your PATH environment variable, you should change the definition of RE2C in configure/CONFIG_SITE to the full path name of the re2c executable before building the sequencer, see Configure and Build below.

Download

Releases are available here:

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

Note

The documentation and download links you will find on this page are for version 2.2.

Here are all releases for version 2.2:

If you want to help testing, please check out the darcs repository for branch-2-2:

darcs get https://hub.darcs.net/bf/seq-branch-2-2

Using this git mirror, you can as well

git clone https://github.com/epics-modules/sequencer.git

but please note that this is just a mirror: I cannot accept git patches or work with GitHub Pull Requests; it may also happen that I have to re-create the whole git repo from scratch (because incremental conversion sometimes fails).

Development of new features now happens on branch-2-3.

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

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 sequencer-Rx-y-z.tar.gz
tar xf sequencer-Rx-y-z.tar

or, if you have GNU tar, simply:

tar zxf sequencer-Rx-y-z.tar.gz

You can now:

cd sequencer-Rx-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. .../sequencer-Rx-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). 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 html

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

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 at the time of writing this) I also needed to install the package tetex-extra.

Test

You can run the automated test suite by issuing

make -s runtests

(the -s option is to suppress irrelevant output generated by make).

To run just one test from the suite, switch to the build directory of the test that corresonds to your EPICS_HOST_ARCH 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. 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

./O.linux-x86_64/demo demo.stcmd

The output should look something like this:

ben@sarun[1]: .../examples/demo > ./O.linux-x86_64/demo demo.stcmd
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.

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 the relevant part in 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). For minor changes you don’t need to bother with darcs, just send me a patch file.

For more involved changes you might want to send a darcs patch. You can create a local copy of the darcs repository (the stable branch in this example) by saying:

darcs get https://hub.darcs.net/bf/seq-branch-2-2

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.