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 base versions up to 7.0.1 can be
used.

.. _EPICS base: http://www.aps.anl.gov/epics/base/
.. _GNU make: http://www.gnu.org/software/make/
.. _Perl: http://www.perl.org/

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.

.. _re2c: http://re2c.org/
.. _old re2c download: http://sourceforge.net/projects/re2c/files/old/
.. _EPICS-re2c: https://github.com/FreddieAkeroyd/EPICS-re2c
.. _re2c-1.0.3 on Appveyor: https://ci.appveyor.com/project/FreddieAkeroyd/re2c/build/artifacts

Download
--------

Releases are available here:

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

The current stable release is `2.2.9`_. Please take a look at the
`VersioningPolicy` 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. The `documentation for version 2.1`_ is still there and will
  be maintained at least until version 2.3 is released.

Development snapshots are available under the name

   seq-<version>-snapshot-<date>.tar.gz

where <version> is the branch name without the 'branch-' prefix.

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

Here are all releases for version 2.2:

   ========== ======================= ============================
   Version    Release Notes           Known Problems
   ========== ======================= ============================
   `2.2.9`_   `Release_Notes_2.2.9`   n/a
   `2.2.8`_   `Release_Notes_2.2.8`   n/a
   `2.2.7`_   `Release_Notes_2.2.7`   `Known_Problems_2.2.7`
   `2.2.6`_   `Release_Notes_2.2.6`   `Known_Problems_2.2.6`
   `2.2.5`_   `Release_Notes_2.2.5`   `Known_Problems_2.2.5`
   `2.2.4`_   `Release_Notes_2.2.4`   `Known_Problems_2.2.4`
   `2.2.3`_   `Release_Notes_2.2.3`   `Known_Problems_2.2.3`
   `2.2.2`_   `Release_Notes_2.2.2`   `Known_Problems_2.2.2`
   `2.2.1`_   `Release_Notes_2.2.1`   `Known_Problems_2.2.1`
   ========== ======================= ============================

If you want to help testing, please use the `latest snapshot`_, or check out
the `darcs`_ repository for `branch-2-2`_::

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

Since release 2.2.2 there is also a git mirror, so you can as well ::

   git clone http://www-csr.bessy.de/control/SoftDist/sequencer/repo/branch-2-2.git

but please note that this is just a mirror, no more: I cannot accept git
patches (or whatever they are called in git); 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.

You can also follow development by using the `repository browser`_.

.. _latest snapshot: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2-2-snapshot-latest.tar.gz
.. _2.2.9: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.2.9.tar.gz
.. _2.2.8: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.2.8.tar.gz
.. _2.2.7: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.2.7.tar.gz
.. _2.2.6: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.2.6.tar.gz
.. _2.2.5: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.2.5.tar.gz
.. _2.2.4: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.2.4.tar.gz
.. _2.2.3: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.2.3.tar.gz
.. _2.2.2: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.2.2.tar.gz
.. _2.2.1: http://www-csr.bessy.de/control/SoftDist/sequencer/releases/seq-2.2.1.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
.. _branch-2-3: http://www-csr.bessy.de/cgi-bin/darcsweb.cgi?r=seq%20branch-2-3;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/
.. _documentation for version 2.1: http://www-csr.bessy.de/control/SoftDist/sequencer-2-1/index.html

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:

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
<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:

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.

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

.. _Verifyingtheinstallation:


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` and `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).
For minor changes you don't need to bother with `darcs`_, just send me a
`patch file`_.

.. _patch file: http://en.wikipedia.org/wiki/Patch_%28Unix%29

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