.. index::
   pair: idcp; build

=============================
How to build and install IDCP
=============================

Prerequisites
-------------

IDCP supports two platforms for the
`IOC <https://docs.epics-controls.org/en/latest/guides/EPICS_Intro.html?highlight=IOC#ioc-software-components>`_:

- `RTEMS <https://www.rtems.org>`_ 4.9 on a
  `mvme2100 <https://bitsavers.trailing-edge.com/pdf/motorola/VME/MVME2100/MVME2100_Brochure.pdf>`_
  `VME Bus <https://en.wikipedia.org/wiki/VMEbus>`_ CPU.
- `Linux <https://en.wikipedia.org/wiki/Linux>`_ on a
  `PC <https://en.wikipedia.org/wiki/Personal_computer>`_

RTEMS
+++++

For RTEMS you need a RTEMS cross compiler, the RTEMS kernel and some extensions.

In order to build the RTEMS cross compiler on your Linux system see:

`rtems-from-scratch <https://rtems-from-scratch.sourceforge.io/index.html>`_

To build the RTEMS kernel you need

`rtems-build-tool <https://rtems-build-tool.sourceforge.io/>`_

See also :doc:`VME Bus CPU with RTEMS <vme>`.

Linux
+++++

For Linux you need a common Linux system. IDCP was tested on
`Debian 12 ("bookworm") <https://www.debian.org/releases/bookworm/>`_.

You need common development tools like gcc, g++, make, python, perl.

See also :doc:`How to set up a Linux IOC <LinuxPC>`.

Prepare your $HOME/.hgrc file
-----------------------------

If you already have this file, ensure that it contains the following line which
enables the "mq" extension in mercurial::

  hgext.mq=

If you don't have this file, you must create it, below is an example. Create it
with your favorite text editor and **don't forget to replace NAME and EMAIL
with your real name and email addess**::

  # This is is a Mercurial configuration file.
  [ui]
  username = NAME <EMAIL>
  [trusted]
  groups= epima
  [diff]
  git=0
  [mq]
  git=yes
  [extensions]
  fetch =
  hgk=
  extdiff=
  transplant=
  hgext.graphlog=
  hgext.rebase=
  hgext.mq=
  hgext.convert=
  hgext.record=

Create a directory where to build the application
-------------------------------------------------

Here is an example example::

  mkdir myidcp && cd myidcp

Check out IDCP repository only (not recommended)
------------------------------------------------

You get the current version from the main repository URL like this, but as
explained below, **this is not recommended**.

From the internal network of the 
`Helmholtz-Zentrum Berlin <https://www.helmholtz-berlin.de>`_ at the 
BESSY II site with this command::

  hg clone http://repo.acc.bessy.de/hg/idcp/idcp idcp

From anywhere else with this command::

  hg clone http://hg.code.sf.net/p/idcp/code idcp

Currently, the installed versions of IDCP at the Helmholtz-Zentrum Berlin
contain additional mq patches, which you do not get with the command above.

Check out IDCP repository with MQ Patches (recommended)
-------------------------------------------------------

The **recommended way** to get IDCP sources is to use the `idcp-get-source
<https://sourceforge.net/p/bii-scripts/code/ci/master/tree/bin/idcp-get-source>`_
script which is part of the `bii_scripts <https://bii-scripts.sourceforge.io/>`_
script collection.

In order to get a recent version of IDCP you should first see which versions of
IDCP are installed. Run this command::

  idcp-get-source versions

It shows the versions of IDCP that are currently in use. The output could look
like this::

  version                  names
  2021-11-15T10:44:50      UE46 UE48 U17 UE56/2 U41 UE49 UE52
  2021-12-13T10:43:03      UE112
  2021-12-14T10:48:21      UE56/1 U139 U49/2 U125/2 U49/1


The ISO date starting in the first column is the name of the version. You check
out the repository for version "2021-12-14T10:48:21" including all mq patches
with this command::

  idcp-get-source version 2021-12-14T10:48:21

In this example, the repository is created in directory::

  2021-12-14T104821

The directory name is a bit different than the name of the version since the
darcs version control system has a problem with colons ":" in directory names.

Configure IDCP
--------------

Go to the project directory and run idcp_configure::

  cd 2021-12-14T104821/idcp
  ./idcp-configure --arch ARCH

'ARCH' must be "Linux" when you compile for a Linux IOC or "RTEMS" when you
compile for an RTEMS VME Bus IOC.

Sumo
----

Ensure that `sumo <https://epics-sumo.sourceforge.io/>`_ is installed.

Enter::

  sumo build use

If this fails, enter::

  sumo build new --makeflags "-sj" --progress
  sumo build use

If this also fails, you have to configure and use sumo with a local sandbox.
Run the following commands::

  rm sumo.config
  sumo config local SUMO
  sumo build new --makeflags "-sj" --progress
  sumo build use

Now all support modules should have been built, and idcp is ready to be
compiled.

Build IDCP
----------

Build the project with this command::

  make -sj

Option "-j" means that the build is done with as many processes the host system
can provide, so on a modern system it is much faster. In rare cases, this
command fails, which is a bug in idcp makefiles. If this happens, please mail
me <Goetz.Pfeiffer@helmholtz-berlin.de> the output of the error message.

In this case you can still build idcp with::

  make clean -sj && make -s

Distribute a version
--------------------

You distribute a version with the idcp-dist script, which is part of idcp.
You get online help for this script with the command ``./idcp-dist -h``.
Distribute your IDCP program with this command::

  ./idcp-dist dist

Activate a version
------------------

Activation is also done with idcp-dist with this command::

  ./idcp-dist activate INSERTIONDEVICE

where INSERTIONDEVICE is any common name for a HZB insertion device.
The :ref:`iddb <iddb_doc>` command shows what names are known::

  iddb -a idcp

From the table that is shown, the columns "name", "devicename" and "prefix" can
be used to specify an insertion device for ``idcp-dist``.