.. index::
   single: idcp-versions
   single: activate
   single: rsync-dist
   single: rsync-dist.pl
   pair: idcp; versions

==============================================
Change IDCP versions used by IOCs (rsync-dist)
==============================================

Introduction
------------

All software for the BESSY undulators is managed by the
`rsync-dist.pl <https://rsync-dist.sourceforge.io/>`_.
tool.

Old versions of the software are always kept on the boot server. A 
symbolic link 
`symbolic link <http://en.wikipedia.org/wiki/Symbolic_link>`_
is used to reference the current version of the software. So of all the
software versions on the server for each insertion device there is one
**active** version which the IOC loads when it is booted.

In case of a problem with a new version of the software you can select one of
all the previous versions for that insertion device to be the new **active**
version.

Each version of the software has a name, that is compliant to 
`ISO 8601 <http://en.wikipedia.org/wiki/ISO_8601>`_
The format is:

**YYYY-MM-DDTHH:MM:SS**

for example "2012-05-10T12:03:57". This is the date and time when this version of the software was created.

In order to make it easier to browse and explore what old versions are
available, we have the idcp-dist-info tool which is part of
`bii_scripts <https://bii-scripts.sourceforge.io/>`_.

This is a small script that actually calls 
`rsync-dist.py <https://rsync-dist.sourceforge.io/>`_
While rsync-dist-info.py is more generic, idcp-dist-info is suited to work with
the insertion device control software only. Have a look at the next section for
a detailed description on how to use idcp-dist-info.

This is a link to the current actually versons of IDCP and the time the IOCs were booted at the HZB: `Current IDCP versions and boot times <http://help.bessy.de/infos/iocboot/idcp-boottimes.html>`_.

Using idcp-dist-info to generate reports 
-----------------------------------------

You can use idcp-dist-info to generate a large variety of reports on the
software versions that are currently used or were used in the past. This tool
is documented here:

:doc:`The idcp-dist-info tool <idcp_dist_info>`

.. attention:: If you just want a version name to perform a fallback look at :ref:`Get fallback information for an insertion device <idcp_dist_info-fallback>`.

Checking out the source with idcp-get-source
--------------------------------------------

Usually, the version of IDCP that is active on an IOC *is not* identical with a
tagged version that can be found in the central mercurial repository. An
installed version may include patches that were not published at the time the
version was build, distributed and activated.

In order to get the sources of an installed version of IDCP you have to run a
script that is installed on build hosts stretch.acc.bessy.de and
bullseye.acc.bessy.de. This is the script
`idcp-get-source <https://sourceforge.net/p/bii-scripts/code/ci/master/tree/bin/idcp-get-source>`_
part of the `bii_scripts <https://bii-scripts.sourceforge.io/>`_ project.

The script has some options to configure what does, you can see all options here:
`idcp-get-source documentation <https://bii-scripts.sourceforge.io/scripts/idcp-get-source.html>`_ 

Examples for for getting IDCP sources
+++++++++++++++++++++++++++++++++++++

**Get the source of the latest installed IDCP version**::

  idcp-get-source latest

**Get the source of IDCP that is used on a certain undulator**::

  idcp-get-source id INSERTIONDEVICE

**Get and build the source of IDCP that is used on a certain undulator**:

Note that this currently will only work on host stretch.acc.bessy.de::

  idcp-get-source id INSERTIONDEVICE --build

**Get the source of IDCP for a VERSION**::

  idcp-get-source version VERSION

Display information with idcp-get-source
++++++++++++++++++++++++++++++++++++++++

**Show all insertion devices in a table**::

  idcp-get-source ids

**Show all versions od IDCP currently in use**::

  idcp-get-source versions

how to activate a version
-------------------------

A version of the software is activated with the **idcp-dist** tool. You can get a short help on it's command line options by entering::

  idcp-dist -h

This is how you activate a different software version for an insertion device::

  idcp-dist [DISTGROUP] activate [ID] [VERSION]

DISTGROUP
  Is the name of the facility where the ID is located. Known DISTGROUPS are 
  ``BII`` and ``MLS``. If DISTGROUP is omitted the program assumes "BII".
  With ``idcp-dist -l`` this is column "group".

ID
  Is the name of the insertion device. You can get a list of all insertion
  devices known to the program with ``idcp-dist -l``. You can specify an
  insertion device by column "name", "prefix" or "devicename".

VERSION
  is the name of the software version, an ISO date of the form 
  **YYYY-MM-DDTHH:MM:SS**.

You can control if you changed the software version successfully with this
command::

  idcp-dist-info --filter-names [ID]

.. attention:: Don't forget the reboot the IOC after the new version was activated, you usually use the program "TkReboot" for this.