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.

.. _EPICS-3.14: http://www.aps.anl.gov/epics/base/R3-14/
.. _GNU make: http://www.gnu.org/software/make/
.. _Perl: http://www.perl.org/
.. _re2c: http://re2c.org/
.. _re2c download: http://sourceforge.net/projects/re2c/files/


Download
--------

Releases are available here:

   http://www-csr.bessy.de/control/SoftDist/sequencer/releases/

The current stable release is `2.1.16`_. Please take a look at the
:ref:`VersioningPolicy` 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.17`_ :ref:`Release_Notes_2.1.17` n/a
   `2.1.16`_ :ref:`Release_Notes_2.1.16` :ref:`Known_Problems_2.1.16`
   `2.1.15`_ :ref:`Release_Notes_2.1.15` :ref:`Known_Problems_2.1.15`
   `2.1.14`_ :ref:`Release_Notes_2.1.14` :ref:`Known_Problems_2.1.14`
   `2.1.13`_ :ref:`Release_Notes_2.1.13` :ref:`Known_Problems_2.1.13`
   `2.1.12`_ :ref:`Release_Notes_2.1.12` :ref:`Known_Problems_2.1.12`
   `2.1.11`_ :ref:`Release_Notes_2.1.11` n/a
   `2.1.10`_ :ref:`Release_Notes_2.1.10` :ref:`Known_Problems_2.1.10`
   `2.1.9`_  :ref:`Release_Notes_2.1.9`  n/a
   `2.1.8`_  :ref:`Release_Notes_2.1.8`  :ref:`Known_Problems_2.1.8`
   `2.1.7`_  :ref:`Release_Notes_2.1.7`  :ref:`Known_Problems_2.1.7`
   `2.1.6`_  :ref:`Release_Notes_2.1.6`  :ref:`Known_Problems_2.1.6`
   `2.1.5`_  :ref:`Release_Notes_2.1.5`  :ref:`Known_Problems_2.1.5`
   `2.1.4`_  :ref:`Release_Notes_2.1.4`  :ref:`Known_Problems_2.1.4`
   `2.1.3`_  :ref:`Release_Notes_2.1.3`  n/a
   `2.1.2`_  :ref:`Release_Notes_2.1.2`  n/a
   `2.1.1`_  :ref:`Release_Notes_2.1.1`  n/a
   `2.1.0`_  :ref:`Release_Notes_2.1.0`  n/a
   `2.0.14`_ :ref:`Release_Notes_2.0.14` n/a
   `2.0.13`_ :ref:`Release_Notes_2.0.13` n/a
   `2.0.12`_ :ref:`Release_Notes_2.0.12` n/a
   `2.0.11`_ :ref:`Release_Notes_2.0.11` n/a
   `2.0.10`_ :ref:`Release_Notes_2.0.10` n/a
   `2.0.9`_  :ref:`Release_Notes_2.0.9`  n/a
   `2.0.8`_  :ref:`Release_Notes_2.0.8`  n/a
   `2.0.7`_  :ref:`Release_Notes_2.0.7`  n/a
   `2.0.6`_  :ref:`Release_Notes_2.0.6`  n/a
   `2.0.5`_  :ref:`Release_Notes_2.0.5`  n/a
   `2.0.4`_  :ref:`Release_Notes_2.0.4`  n/a
   `2.0.3`_  n/a                         n/a
   `2.0.2`_  n/a                         n/a
   `2.0.1`_  :ref:`Release_Notes_2.0.1`  n/a
   `2.0.0`_  :ref:`Release_Notes_2.0`    n/a
   `1.9.5`_  :ref:`Release_Notes_1.9`    n/a
   `1.9.4`_  :ref:`Release_Notes_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`_.

.. _latest snapshot: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-snapshot-latest.tar.gz
.. _2.1.17: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.17.tar.gz
.. _2.1.16: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.16.tar.gz
.. _2.1.15: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.15.tar.gz
.. _2.1.14: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.14.tar.gz
.. _2.1.13: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.13.tar.gz
.. _2.1.12: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.12.tar.gz
.. _2.1.11: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.11.tar.gz
.. _2.1.10: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.10.tar.gz
.. _2.1.9: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.9.tar.gz
.. _2.1.8: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.8.tar.gz
.. _2.1.7: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.7.tar.gz
.. _2.1.6: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.6.tar.gz
.. _2.1.5: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.5.tar.gz
.. _2.1.4: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.4.tar.gz
.. _2.1.3: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.3.tar.gz
.. _2.1.2: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.2.tar.gz
.. _2.1.1: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.1.tar.gz
.. _2.1.0: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.1.0.tar.gz
.. _2.0.14: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.14.tar.gz
.. _2.0.13: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.13.tar.gz
.. _2.0.12: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.12.tar.gz
.. _2.0.11: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.11.tar.gz
.. _2.0.10: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.10.tar.gz
.. _2.0.9: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.9.tar.gz
.. _2.0.8: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.8.tar.gz
.. _2.0.7: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.7.tar.gz
.. _2.0.6: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.6.tar.gz
.. _2.0.5: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.5.tar.gz
.. _2.0.4: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.4.tar.gz
.. _2.0.3: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.3.tar.gz
.. _2.0.2: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.2.tar.gz
.. _2.0.1: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.1.tar.gz
.. _2.0.0: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.0.0.tar.gz
.. _1.9.5: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-1.9.5.tar.gz
.. _1.9.4: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-1.9.4.tar.gz
.. _repository browser: http://www-csr.bessy.de/cgi-bin/darcsweb.cgi
.. _branch-2-0: http://www-csr.bessy.de/cgi-bin/darcsweb.cgi?r=seq%20branch-2-0;a=summary
.. _branch-2-1: http://www-csr.bessy.de/cgi-bin/darcsweb.cgi?r=seq%20branch-2-1;a=summary
.. _branch-2-2: http://www-csr.bessy.de/cgi-bin/darcsweb.cgi?r=seq%20branch-2-2;a=summary
.. _old: http://www-csr.bessy.de/control/SoftDist/sequencer/repo/old/
.. _stable: http://www-csr.bessy.de/control/SoftDist/sequencer/repo/stable/
.. _experimental: http://www-csr.bessy.de/control/SoftDist/sequencer/repo/experimental/

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/``.

.. _GNU tar: http://www.gnu.org/software/tar/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html


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
<http://www.aps.anl.gov/epics/base/R3-14/11-docs/AppDevGuide.pdf>`_ 
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.

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Python: http://www.python.org/
.. _Sphinx: http://sphinx.pocoo.org/

.. _Verifyingtheinstallation:


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
:doc:`Compiling` and :doc:`Using`.

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`_.

.. _EPICS Application Developer's Guide: http://www.aps.anl.gov/epics/base/R3-14/11-docs/AppDevGuide.pdf

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 <benjamin.franksen@helmholtz-berlin.de>`_). 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.

.. _darcs: http://darcs.net/
.. _darcs obliterate: http://darcs.net/manual/bigpage.html#SECTION00694000000000000000
.. _darcs send: http://darcs.net/manual/bigpage.html#SECTION00664000000000000000
