GETTING STARTED WITH EPICS V4

Getting Started with EPICS V4, Editors draft

This version:
gettingStarted_20151017.html
Latest version:
gettingStarted.html
Previous version:
gettingStarted_20150805.html
Editors:
Greg White, SLAC
Dave Hickin, Diamond
Timo Korhonen, ESS
Ralph Lange, ITER

Abstract

This document describes how to download and build the EPICS V4 toolkit. It is a step by step guide to downloading the appropriate EPICS V4 products and associated software, and to using them to create the example programs. Presently, the document concentrates on interfacing to EPICS Base IOC control data, through the C++ bindings of new EPICS V4 modules pvAccess and pvData, and on developing middleware EPICS data services using the RPC capability of pvAccess in Java and C++.

Status of this Document

This is version 20151017 of the Getting Started document. This version has been updated with respect to EPICS V4.5.

A more complete developers guide is in preparation.

Table of Contents


Introduction

EPICS V4 is implemented in C++ and Java. Its APIs are in C++ and Java mainly, though wrappers are being produced for Python and Matlab. However, this document covers only development in Java and C++.

Please note that while we make effort to keep this document up to date, we don't regenerate all examples and graphics to be consistent with every release number etc. Please offer us some latitude in keeping this document perfect.

The Core Modules that Comprise EPICS V4

Release "EPICS V4.5" is comprised of 2 "core" modules: pvData, and pvAccess. These are the minimum required to create V4 clients and services.

In addition there are a number of higher-level modules: pvDatabase and pvaClient make it easier to create services and clients respectively; pvaSrv adds pvAccess services to V3 IOCs; normativeTypes implements certain standard pvData types (the Normative Types). You don't need to use these higher-level. For example you can create V4 applications that don't use the normativeTypes module - either because they don't use Normative Types or because the latter are implemented without using the module. Similarly you can create clients without pvaClient and services without pvDatabase or pvaSrv (and there is an RPC framework in pvAccess to implement RPC services and clients). However using these higher-level modules make it much easier to build many applications.

The specifications for the function of these are (or are presently being) defined as normative documents of the EPICS V4 working group, and available from the homepage the EPICS V4 homepage. There are Java and C++ implementations of each of the core modules. The source code of each can be acquired from Git. To use them, you can download and build them from the source, from Git or from a release bundle tar file, as described below. For Java, the release bundle tar file includes prebuilt Jars. This document deals with acquiring, building, and first steps in using the core modules, plus pvaSrv to connect to EPICS Base IOCs. However, there are many more pieces of software in the EPICS V4 "ecosphere", please see the homepage, and the EPICS V4 Git web site.

The following is a summary of the modules of EPICS V4.5.

C++ Module Summary:

pvDataCPP           The EPICS V4 data types.
pvAccessCPP         The EPICS V4 "wire protocol". Supports pvData.
normativeTypesCPP   Support for EPICS V4 Normative Types.
pvaSrv              pvAccess interface to EPICS Base IOC databases.
pvDatabaseCPP       EPICS V4 record/database framework for providing services over pvAccess.
pvaClientJava       A higher-level API for writing pvAccess clients.
pvaPy               Python API for pvAccess.
exampleCPP          Code examples, including use of pvData containers, RPC, demo servers.
pvCommonCPP         Utility libraries.

Java Module Summary: 

pvDataJava          The EPICS V4 data types.
pvAccessJava        The EPICS V4 "wire protocol". Supports pvData.
normativeTypesJava  Support for EPICS V4 Normative Types.
pvDatabaseJava      EPICS V4 record/database framework for providing services over pvAccess.
pvaClientJava       A higher-level API for writing pvAccess clients.
easyPVAJava         (Deprecated) Older version of pvaClientJava. 
exampleJava         Code examples, including use of pvData containers, RPC, demo servers. 
directoryService    EPICS V4 interface to classic EPICS directoryService.
caj                 An all Java implementation of the Channel Access protocol.
jca                 A Java API and wrapper interface to the C++ implementation of
                    the Channel Access protocol.

The versions of each module are formally listed in RELEASE_VERSIONS.

The dependency hierarchy between the above is the following:

In addition for C++ there is the utility module pvCommonCPP. This contains boost, needed in particular for shared_pointers, and a microbenchmark framework. If you don't intend to use the latter then you may not need pvCommonCPP, depending on your compilers support for shared_pointers.

When building the modules these interdependencies must be taken into account.

Interoperation with EPICS Base (aka V3)

To link the new EPICS V4 modules to EPICS Base IOC records, two basic approaches are possible.

In the first, an embedded pvAccess server inside a Base IOC (say running EPICS V3.14/15) accesses records directly through the database, allowing a V4 client to communicate with the "V3" records through pvAccess. This is provided by pvaSrv and implemented in C++.

Alternatively EPICS V4 can link to the Base IOC records using Channel Access. Starting with the past release V4.3, this may be done in both Java and C++ implementations of pvAccess, though for Java, jca*.jar and caj*.jar, are prerequisites. There are two modes of such interoperation. Firstly, an embedded Channel Access client inside a pvAccess server allows it to communicate with an EPICS Base IOC. Secondly, the pvAccess server (part of pvAccess above) allows an existing EPICS Base Channel Access client to access a pvIOC database. These interoperability functions require JCA and CAJ jcaandcaj. These are available from the EPICS V4 download site http://sourceforge.net/projects/epics-pvdata/files/ or from their reference sources.

Version Compatibility

When we say "EPICS Base", or loosely "V3", in general we mean EPICS Base version 3.14.12 (preferably 3.14.12.4 or later) or 3.15.x.

Prior to 4.5.0, the implementation of pvaSrv did not reflect API changes made in Base 3.15.1. As a result, using pvaSrv required 3.14.12.x. As of 4.5.0 pvaSrv has been updated to build against 3.15.1.

As of EPICS V4.4.0, pvAccessJava requires at least Java 1.7.

Where to find more information

The programmers reference documentation for each software component of EPICS V4 is listed in the Literature page. The pvAccess protocol is described in its specification. Environment settings, EPICS_PVA_ADDR_LIST etc, are described in the pvAccess Configuration spreadsheet (Excel). Check CPU architecture compatibility in the Compatibility Tracker (Excel).

If you get into trouble, you might first check the Troubleshooting EPICS V4 cheatsheet, which lists very first steps in finding and resolving problems with EPICS V4 connections. After that, email EPICS tech-talk or contact the EPICS V4 working group.

Java and C++ development

Since the development cycle (compile, build, etc.) is significantly different for each language, and to match suitable language API description to suitable use cases, this guide is split into 2 major parts. Firstly, Java development and secondly C++ development.

Java Development

This section is on software development, with and of, the Java implementation of EPICS V4. For C++ development, see below.

V4.4+ Java requires Java 1.7

The Java implementation of the EPICS V4 modules, is made available in two ways. Firstly, you can download EPICS V4 as a tarball of the jar files directly from the EPICS V4 SourceForge site. Alternatively, you can download the Java sources from their Git repos and build it yourself.

You would use the tar file mechanism of acquiring EPICS V4 if you only intend to use EPICS V4's Java implementation as a user. If you want to contribute to development at all, or to examine the source for other reasons, you probably want to acquire EPICS V4 by the method of downloading the Git source, and building with Maven. Each of these will be described below.

Since the minimum EPICS V4 runtime is composed of the 2 modules pvData and pvAccess, you will need at least those two. The sections below will guide you through acquiring them from Jars or building from the source.

If you intend to use EPICS V4's Java client side to talk Channel Access to EPICS Base IOCs, then you will additionally need caj and jca. Those two are bundled in the Java tar file.

Getting EPICS V4 Java Implementation from the tar of the Jar Files

The simplest way to acquire EPICS V4's Java implementation is to download the tar file of the jars, from the EPICS V4 SourceForge download site, http://sourceforge.net/projects/epics-pvdata/files/ [downloadsite]. See in particular the README file at the site..

The table above lists the modules that comprise the Java implementation of the EPICS V4 suite. The 2 modules named pvAccess*.jar and pvData*.jar make up the core of EPICS V4 The tar file contains these and others. You'll need at least what's in the tar.gz.

To get off the ground using Java download, see the examples in the epics-pvdata exampleJava Git repo [ev4examples-java]. The setup files of those examples (helloWorld_setup.bash and rdb_setup.bash) are written assuming local .class files, you'll have to convert them so the CLASSPATH points to the jar files instead - as described below ). So far only examples of the "ChannelRPC" functionality of EPICS V4 are included in the exampleJava repo, since it's assumed Java would mainly be used for host side services, but more will be added.

Step by step

This section is a guide for acquiring and configuring the files in the Java tar.gz. For illustration we test successful execution of the helloWorld client/server example.

  1. Download the tar.gz from SourceForge http://sourceforge.net/projects/epics-pvdata/files/
  2. Untar it,
    % tar xvfz EPICS-Java-4.4.0.tar.gz  [if you got it compressed]
    % tar xvf EPICS-Java-4.4.0.tar      [if you got it uncompressed]
    
    You should see about 30 jar files, of executable, source and javadoc (exact version numbers may have changed by the time you read this):
    % ls  EPICS-Java-4.5.0
    caj-1.1.15.jar                      LICENSE.txt
    caj-1.1.15-javadoc.jar              normativeTypesJava-0.1.2.jar
    caj-1.1.15-sources.jar              normativeTypesJava-0.1.2-javadoc.jar
    directoryService-0.4.2.jar          normativeTypesJava-0.1.2-sources.jar
    directoryService-0.4.2-javadoc.jar  pvAccessJava-4.1.2.jar
    directoryService-0.4.2-sources.jar  pvAccessJava-4.1.2-javadoc.jar
    easyPVAJava-4.1.2.jar               pvAccessJava-4.1.2-sources.jar
    easyPVAJava-4.1.2-javadoc.jar       pvaClientJava-4.1.3.jar
    easyPVAJava-4.1.2-sources.jar       pvaClientJava-4.1.3-javadoc.jar
    exampleJava-4.0.5.jar               pvaClientJava-4.1.3-sources.jar
    exampleJava-4.0.5-javadoc.jar       pvDatabaseJava-4.1.2.jar
    exampleJava-4.0.5-sources.jar       pvDatabaseJava-4.1.2-javadoc.jar
    jca-2.3.6.jar                       pvDatabaseJava-4.1.2-sources.jar
    jca-2.3.6-javadoc.jar               pvDataJava-5.0.2.jar
    jca-2.3.6-sources.jar               pvDataJava-5.0.2-javadoc.jar
    lib                                 pvDataJava-5.0.2-sources.jar
    
  3. To play with exampleJava, you'll need to edit setup files. So create an exampleJava subdirectory and extract exampleJava from its sources jar file into it:
    % mkdir exampleJava
    % cd exampleJava
    % jar xf ../EPICS-Java-4.5.0/exampleJava-4.0.5-sources.jar
    % ls -l
    total 8
    0 drwxrwxr-x. 3 greg  staff 4096 Oct 16 20:28 illustrations
    0 drwxrwxr-x. 2 greg  staff 4096 Oct 16 20:28 META-INF
    0 -rw-rw-r--. 1 greg  staff 1211 Oct 16 20:28 overview.html
    0 drwxrwxr-x. 4 greg  staff 4096 Oct 16 20:28 services
    
  4. Try out helloWorld RPC service.

    The simplest example of an EPICS V4 pvAccess server that provides functions new in V4, is the helloWorld in exampleJava. It shows a pvAccess server taking a argument, and returning a string based on the argument.

    Modify helloWorld_setup.bash.

    The helloWorld example is in exampleJava/services/helloWorld/. Note that exactly how the setup must be, will depend on whether you intend to execute the example code from its jar, as download in the distribution tar, or to extract the source of the example so you can look at it and build it, or whether thirdly you may have cloned the repos. This example will assume you want to extract the source of the exampleJava, and compile that, and execute it using the support in the jar files of the EPICS V4 core. Again note, version ids may be different.

    1. Set the root dir of the EPICS V4 stuff (i.e., the directory created by the untar):
      WORKSPACE=$HOME/Temporary/EPICS-Java-4.5.0
      
    2. Set the location of the examples (i.e., the directory created by the unjarring the example source jar):
      EXAMPLES=$HOME/Temporary/exampleJava
      
    3. Edit CLASSPATH to point to where your examples code class files are, or will be; and to point to the downloaded jars:
      CLASSPATH=${EXAMPLES}
      CLASSPATH=${CLASSPATH}:${WORKSPACE}/pvDataJava-5.0.2.jar
      CLASSPATH=${CLASSPATH}:${WORKSPACE}/pvAccessJava-4.1.2.jar
    4. Compile examples. This can be done simply with javac (after you've used helloWorld_setup.bash to set the CLASSPATH):
      cd to exampleJava/services/helloWorld, then
      $ source helloWorld_setup.bash
      $ javac *.java
      
    5. Start the server (you'll see quite a bit of output. Check there are no complaints of file-not-found). First, just once, you'll need to chmod +x the runner scripts:
      $ chmod +x helloServerRunner helloClientRunner 
      % ./helloServerRunner
      
      Tip: If you get a ClassNotFound, you can diagnose your runtime environment's CLASSPATH by sourcing helloWorld_setup.bash, and then running a command like printenv CLASSPATH | tr : '\n' | xargs -I{} ls {}
    6. In another process, or even another network node, run the client, giving an argument. The client will find the server process, send the argument, receive a greeting for that argument, and print it:
      % ./helloClientRunner Stefania
      Hello Stefania
      

Getting EPICS V4 Java Implementation Source and Building using Git and Maven

The use case of downloading the source using Git (aka "git"), and building with Maven, would be applicable if you are a Java developer and wish either to contribute to EPICS V4, or like to use a command line for your Java builds, or both.

The EPICS V4 software components (pvData, pvAccess) are each in distinct Git repositories in the SourceForge project epics-pvdata. There are separate Git repos for each of the C++ and Java implementations of each component [EPICSV4repos]. They can all be checked out via the Git unix shell command git, or using a Git GUI client suitable for your platform.

The procedure defined below will help you download the source for the pv core modules above, plus the caj/jca jars, and build pv core jars.

Prerequisites

V4.4+ Java requires Java 1.7

Clone from the Git repositories can be done anonymously. Below is an example of how to check out the pvDataJava Git repository, using the git unix command via anonymous access:

% git clone https://github.com/epics-base/pvDataJava.git

Create your local Git "repo" for your EPICS V4 work

Having installed Git, now download the source. You'll create a local Git "repository" for each EPICS V4 module you get.

First, you may want to create a root directory in which to house your repo directories, e.g.:

% pwd
/Users/greg/Development/epicsV4/
% mkdir git
% cd git

Download minimum EPICSv4 Java implementation repos from epics-pvdata into local repos

To download the source using Git, use an "git clone" command, executed while in the directory you created, i.e. "git/" in the example above. You will need at least the 2 core "normative" module Java implementations pvDataJava and pvAccessJava (the first 2 below). You may well also want:

See RELEASE_VERSIONS relver for the other modules bundled with the release, that you may also want to clone.

[from git/ directory in this example, created above]
% git clone https://github.com/epics-base/pvDataJava.git
% git clone https://github.com/epics-base/pvAccessJava.git
% git clone https://github.com/epics-base/exampleJava.git
% git clone https://github.com/epics-base/normativeTypesJava.git
...

See the complete list in the file which formally lists all of the components in each EPICS V4 release, RELEASE_VERSIONS

EPICS V4 Java Implementation Build

The build dependencies of the EPICS v4 modules are:

When building (instructions below) you will see warnings, but should not see any errors if the build is successful. Warnings come from both source compiles and many from javadoc compiles. At the end of each "mvn compile install" process, you should see:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

The build itself is handled by Maven for Java builds. The actions for the build of each EPICS V4 module is handled by its own pom.xml file, there is no global one. So, the build process involves "cd" ing to the cloned repository (as they're called in Git speak) of each one of the core modules, and issuing "mvn compile install" in each one. Start with pvDataJava since it has no dependencies, then pvAccessJava, then the others.

If this is really the first Maven build you've done, the first mvn compile line below will result in 2 things: First, it will create your local "m2 repo" (in ~/.m2 by default). Then it will initiate many downloads from sourceForge and Maven as well as prerequisites of Maven. But if you chose this path to EPICS v4, you probably knew that!

% pwd
/Users/greg/Development/epicsV4/git             [in this example]

% cd pvDataJava/
% mvn compile install

% cd ../pvAccessJava/
% mvn compile install -Dmaven.test.skip=true

Note that as written here, the mvn compile install commands skip the post compilation tests. These tests would include exception handling tests, the output of which look like errors, because the tests are specifically to test for correctly dealing with runtime errors. If you you would like to include the tests, remove the Maven option -Dmaven.test.skip=true.

The above 2 complete the build of the EPICS v4 core. You may also want to try the examples which are in the exampleJava module, and a somewhat simplified pvAccess API named easyPVA. exampleJava uses easyPVAJava, so get them both and build it with the following:

% cd ../easyPVAJava/
% mvn compile install -Dmaven.test.skip=true

% cd ../examplesJava
% mvn compile install

The outcome of these builds is that you should see all of the build products in your local Maven repository (~/.m2/repository/ by default).

The minimum EPICS V4 runtime is composed of only 2 Jars, for the core, plus 2 if you want to access EPICS V3 IOCs, so you can check the outcome of the builds with the find command below, to verify that from the 100s now in your local Maven directory (probably ~/.m2/), you have the few you really need. Again, actual version tags, i.e. "2.1-SNAPSHOT" in the example below, will vary as EPICS V4 matures:

% find ~/.m2 -name "pv*SNAPSHOT.jar" -o -name "*caj*.jar" -o -name "*jca*.jar"
.m2/repository/epics/pvData/2.1-SNAPSHOT/pvData-2.1-SNAPSHOT.jar
.m2/repository/epics/jca/2.3.6/jca-2.3.6.jar
.m2/repository/epics/caj/1.1.10/caj-1.1.10.jar
.m2/repository/epics/pvAccess/2.1-SNAPSHOT/pvAccess-2.1-SNAPSHOT.jar
.m2/repository/epics/pvIOC/2.1-SNAPSHOT/pvIOC-2.1-SNAPSHOT.jar

Note that the results gave you not only jar files under ~/.m2/, but the sources and javadoc jars too (in the Maven standard naming).

The above completes the build of EPICS V4 locally. To use it, you would write code that compiles and executes against the jar files above.

Java Eclipse Development

To use or develop these, the steps might be:

Java Service Examples

For Java client and server V4 service examples, at the time of writing, see the source code in the examplesJava module. You can find this on the epics-pvdata web site [ev4examples-java]. At the time of writing, examplesJava contains 2 examples of RPC style servers (that is, pass arguments to an EPICS V4 pvAccess server, get data back that is dependent on the arguments).

helloWorld
In particular, you may like to start with the, helloWorld example service. HelloWorld is composed of a server and a client. The server is built on top of the RPCSever framework in pvAccessJava. The service returns a string which greets that person and the client prints the received greeting. Start with its HELLOWORLD_README.txt. This demonstrates an EPICS V4 record whose value is subject to a user argument. The client and server interoperate with their C++ equivalents in exampleCPP.
rdbService
The rdbService example is a complete functional server for accessing SQL databases such Oracle via an EPICS V4 server, and returning the resulting table ResultSet data back to an EPICS V4 client. rdbService illustrates:
  1. channelRPC functionality of EPICS V4
  2. use of JDBC for accessing Oracle to execute a SQL query within a pattern that retries the query and can rebuild the connection if any query fails - for high reliability and to make sure if the database backend ever cycles, the EPICS v4 server need not be restarted.
  3. Passing string messages back to the client in the event of the server detecting an error or other diagnostic
  4. Putting complex data into an EPICS V4 pvStructure (the basic complex data object of pvData), ready for returning results back to the EPICS V4 client
  5. Client side calling the server, and getting the results
  6. Unpacking complex data out of a pvStructure
  7. Illustration of the idea of using the NTTable EPICS V4 "normative type" (though the definition of an NTTable is likely to change soon)
  8. Helpers for transformation of array pvData to Java Vectors
  9. Formatting pvStructure encoded data for printing.

C++ Development

This section is on software development, with and of, the C++ implementation of EPICS V4. It guides you through the process of acquiring the source, building the modules and running some simple examples.

Prerequisites

If you are already an EPICS V3 user, it's likely that, apart from the V4 source, you will already have everything you need to build the EPICS V4 C++ implementation from its source.

In addition to the EPICS V4 C++ source, you will need the following:

  1. An installed version of EPICS (V3) Base. You should use 3.14.12 or later. You will also need the variable EPICS_HOST_ARCH appropriately set for your host architecture. See Appendix A for an an example of building a local EPICS Base, 3.14.12.3, and setting EPICS_HOST_ARCH.

    For specific help for building on a Mac, see also Appendix B: Help with Mac OS X build.

  2. You'll need gnu make and the C++ compiler used to build EPICS Base.

  3. To build one example, the Channel Archiver Service, you will also need the EPICS Channel Archiver. See http://ics-web.sns.ornl.gov/kasemir/archiver/. Nothing else depends on this service and this can be omitted if desired.

  4. Some of the steps below will depend on you having specified the location of your EPICS Base installation through the shell variable EPICS_BASE. For example if your installation is in /epics/R3.14.12.3/base:

    % export EPICS_BASE=/epics/R3.14.12.3/base
    

The Application Developer's Guide has more details on the set up required for building EPICS applications, including setting the host architecture and the versions of the various tools needed.

Obtaining the source

There are two ways to to get the EPICS V4 C++ source.

The simplest way is to download it as a tar from the Sourceforge website site http://sourceforge.net/projects/epics-pvdata/files/. This is a good option if you wish to deploy EPICS V4 services and clients and want a stable release. The tar consists of a number of EPICS V4 modules and is designed to be relatively easy to build. This is recommended for those new to EPICS V4.

If you want the latest code or wish to contribute to development you will need to clone the Github repositories. In this case you can choose which modules you want.

The next two sections describe how to obtain the source and build it via these two methods.

Building the EPICS V4.5.0 C++ Implementation Tar

Quick start instructions

For those familiar with EPICS V3 and with a V3 base installation and the appropriate toolchain already in place, doing the following should build the source (at least on Linux hosts).

You'll need EPICS_BASE set to point to your V3 base installation and EPICS_HOST_ARCH appropriately set. Download the V4.4.0 C++ tar from the SourceForge site http://sourceforge.net/projects/epics-pvdata/files/4.5.0/, untar, configure and build:

% tar xzf EPICS-CPP-4.5.0.tar.gz
% cd EPICS-CPP-4.5.0
% chmod +x configure.sh
% make configure
% make

[The command make configure sets your build dependencies. You can alternatively do this by creating and completing a top-level RELEASE.local based on ExampleRelease.local, which will work for other host architectures. ]

Then do the following to build pvaPy:

% export EPICS4_DIR=`pwd`
% cd pvaPy
% make configure
% make

For how to build the remaining target, the Channel Archiver Service, consult the sub-section of the step-by-step below.


For those less familiar with EPICS or requiring more information, the following sub-sections will take you through the requirements and build process step-by-step and in a little more detail:

Step by step

  1. Download the V4.5.0 C++ tar.gz from the SourceForge site: http://sourceforge.net/projects/epics-pvdata/files/4.5.0/.
  2. Untar it

    Move the tar to where you want your installation to be and untar it in the usual way:

    % tar xzf EPICS-CPP-4.5.0.tar.gz
    

    If you cd into the resulting directory and examine the contents you should see something like

    % cd EPICS-CPP-4.5.0
    % ls
    CONFIG_SITE.local     Makefile           pvaPy          pvDataCPP
    configure.sh          normativeTypesCPP  pvaSrv         README.md
    exampleCPP            pvAccessCPP        pvCommonCPP    RELEASE_IDS
    ExampleRelease.local  pvaClientCPP       pvDatabaseCPP  RELEASE_NOTES.md
    

  3. Configure EPICS V4 for your site in CONFIG_SITE.local

    You can modify the default configuration for your site by setting this in CONFIG_SITE.local. This file is included by the CONFIG_SITE file in each module's configure directory.

    The source tar should in general build out the box without modifying this CONFIG_SITE.local. This should be the case if your EPICS Base installation has no site-specific config. If this is not the case however you may have to modify CONFIG_SITE.local. If you have problems building the source tar you can try building against a clean EPICS Base without site-specific config.

    Some site-specific configs may by default cause cross compilation for unsupported target architectures. To help ensure the tar builds out the box for as many new users as possible the supplied CONFIG_SITE.local sets CROSS_COMPILER_TARGET_ARCHS to be an empty string:

    CROSS_COMPILER_TARGET_ARCHS=
    
    turning off any cross compilation. You can remove this line or set cross compilation targets here if you wish.

  4. Set your module locations in RELEASE.local,

    The EPICS build system needs you to specify the locations of the dependencies for each module. The easiest way to do this is to specify this in a single RELEASE.local in the top-level. This file will then be included by the RELEASE file in each module's configure directory.

    For Linux host development, a script is provided to make it easy to create your RELEASE.local, provided that you have specified the location of your EPICS Base installation through the shell variable EPICS_BASE. If your EPICS Base installation is in /epics/R3.14.12.3/base, from the top level of your EPICS V4 source do the following:

    % export EPICS_BASE=/epics/R3.14.12.3/base
    % chmod +x configure.sh
    % make configure
    

    Alternatively create the RELEASE.local based on the supplied example. Save the file ExampleRelease.local as RELEASE.local and modify so that EPICS_BASE points to your EPICS Base installation and EV4_BASE points to the top-level EPICS V4 directory. So if you've untarred the source tar in /epicsv4 the file would look like.

    EV4_BASE=/epicsv4/EPICS-CPP-4.5.0
    PVDATABASE=$(EV4_BASE)/pvDatabaseCPP
    PVASRV=$(EV4_BASE)/pvaSrv
    PVACCESS=$(EV4_BASE)/pvAccessCPP
    NORMATIVETYPES=$(EV4_BASE)/normativeTypesCPP
    PVDATA=$(EV4_BASE)/pvDataCPP
    PVCOMMON=$(EV4_BASE)/pvCommonCPP
    ARCHIVER=
    EPICS_BASE=/epics/R3.14.12.3/base
    

    [ Note: An alternative to a single top-level RELEASE.local is to specify the dependency locations on a per-module basis by creating a RELEASE.local in the configure directory. This allows you to specify only those modules you need and thus avoid recursive dependencies. You can do this through the configure script by typing

    % make config_multi
    
    instead of make configure. ]

  5. Build the modules

    Simple type

    % make
    

    This will build the default target which consist of the modules pvCommonCPP, pvDataCPP, normativeTypesCPP, pvAccessCPP, pvaSrv, pvDatabaseCPP and pvaClientCPP followed by exampleCPP/HelloWorld.

  6. Build pvaPy

    pvaPy is built separately as it has its own configuration script. From the top directory of the V4 source, do the following to build pvaPy:

    % export EPICS_BASE=/epics/R3.14.12.3/base
    % export EPICS4_DIR=`pwd`
    % cd pvaPy
    % make configure
    % make
    

  7. Build the Channel Archiver Service (optional)

    This is an example EPICS V4 service. It is not part of the default target as it has an external dependency on the EPICS Channel Archiver. See http://ics-web.sns.ornl.gov/kasemir/archiver/.

    The Channel Archiver can also be a little difficult to build. If it isn't part of your existing installation you may wish to leave this example out initially when getting started with EPICS V4.

    To build the Channel Archiver Service example you will need to have built the EPICS Channel Archiver and to specify its location in the RELEASE.local. If your archiver is in the src/ChannelArchiver directory of /epics/R3.14.12.3/extensions then set in the make configure

    % ARCHIVER_DIR=/epics/R3.14.12.3/extensions make configure
    
    or set ARCHIVER in your RELEASE.local
    ARCHIVER=/epics/R3.14.12.3/extensions
    

    Then to build the service, from the top directory, do

    % make archSrv
    
    or
    % cd exampleCPP/ChannelArchiverService
    % make
    

Building the EPICS V4.5.0 C++ Implementation from the Repositories

For the latest code or to contribute to development you will need to clone the Github repositories. This will of course give you the full revision history of the modules including previous releases and all branches.

Note there is no single, top-level repository, so you will need to obtain the modules you want and build them individually.

Getting the EPICS V4 C++ Implementation source

The modules can be obtained using the Git clone command.

For this you will need the Git client tools, as described above. Choose the location for your EPICS V4 modules and obtain the required modules with a Git clone using either the SSH or HTTP URI. You're not required to put all the modules in the same directory, but it makes sense and can simplify the build process. The minimum you'll need is the modules pvCommonCPP, pvDataCPP and pvAccessCPP. So if you're using the SSH URI, clone as follows:

[commands issued from the desired location for each repo]
% git clone https://github.com/epics-base/pvCommonCPP.git
% git clone https://github.com/epics-base/pvDataCPP.git
% git clone https://github.com/epics-base/pvAccessCPP.git

Other modules can be obtained similarly:

% git clone https://github.com/epics-base/exampleCPP.git
% git clone https://github.com/epics-base/normativeTypesCPP.git
% git clone https://github.com/epics-base/pvaSrv.git
% git clone https://github.com/epics-base/pvDatabaseCPP.git
% git clone https://github.com/epics-base/pvaClientCPP.git
% git clone https://github.com/epics-base/pvaPy.git

Building the EPICS V4 C++ implementation source with make

The C++ implementations of the EPICS V4 modules use the EPICS V3 build system, based on unix make (in contrast to the Java implementation, which uses Maven). A basic understanding of the EPICS V3 make system is helpful, although the following instructions do not assume this knowledge. The build command itself is simple - it's just make. However you will have to do some configuration - in particular specifying where the modules' dependencies are and possibly also which targets are built.

EPICS V4 uses the EPICS build facility. In particular each module has a directory called configure containing a file, CONFIG_SITE, which is used to specify build choices and target architectures and another, RELEASE, which is used to specify directory structures containing files needed by the module (i.e. the locations of dependencies).

For EPICS V4 modules CONFIG_SITE includes files CONFIG_SITE.local in the configure directory or in the module's parent directory (providing these exist).

Similarly RELEASE includes files RELEASE.local in the configure directory or in the module's parent directory (again, providing these exist).

So you can create a configure/RELEASE.local for each module specifying the module's dependencies or you can create a single RELEASE.local in the parent directory of a group of modules containing all the dependencies for those modules. The former has the advantage that you can specify only those dependencies you need (which prevents issues with recursive dependencies). The latter has the advantage that you only need specify the dependency locations once.

Similarly if you need to, you can create configure/CONFIG_SITE.local for each module specifying build choices and targets or you can create a single CONFIG_SITE.local in the parent directory of the group of modules. For example the line

CROSS_COMPILER_TARGET_ARCHS=
specifies that there are no cross compilation targets, i.e. the only target is the host architecture.

You may which to create a top-level makefile to simplify your build process. You can get an example makefile and configuration script, as well as an example RELEASE.local and CONFIG_SITE.local from the source tar (see Building the EPICS V4.5.0 C++ Implementation Tar) or from the EPICS V4 website. For example on Linux or Mac you might wget (if you get Unsupported Scheme error, try curl -O <url> instead):

% wget https://raw.githubusercontent.com/epics-base/pvDataWWW/master/scripts/Makefile
% wget https://raw.githubusercontent.com/epics-base/pvDataWWW/master/scripts/configure.sh
% wget https://raw.githubusercontent.com/epics-base/pvDataWWW/master/scripts/CONFIG_SITE.local
% wget https://raw.githubusercontent.com/epics-base/pvDataWWW/master/scripts/RELEASE.local

The instructions below do not assume a top-level Makefile.

EPICS V4 Core C++ Implementation Build

As a minimum you'll need to build the two core modules pvData and pvAccess as well as the module pvCommon on which these depend. The build dependencies of the EPICS v4 core modules are:

The module interdependencies require that they are built in the following order: first pvCommonCPP, then pvDataCPP, and finally pvAccessCPP, as detailed below.

It is assumed that your EPICS V4 modules are all in a single parent directory.

To build the core modules

  1. Specify the dependencies for all the modules: In the parent directory (i.e. the directory containing pvCommonCPP, pvDataCPP and pvAccessCPP) create a RELEASE.local file which sets EPICS_BASE to point to your EPICS release and PVCOMMON and PVDATA to point to the locations of pvCommon and pvData respectively. So if your EPICS V4 source is in /epics/v4/latest and your EPICS Base in /epics/R3.14.12.3/base your RELEASE.local will be

    PVDATA=/epics/v4/latest/pvDataCPP
    PVCOMMON=/epics/v4/latest/pvCommonCPP
    EPICS_BASE=/epics/R3.14.12.3/base
    

    In addition set any targets or build choices. For example, if you need to prevent cross-compiling set CROSS_COMPILER_TARGET_ARCHS to be the empty string by creating a CONFIG_SITE.local in the parent directory which contains the line

    CROSS_COMPILER_TARGET_ARCHS=
    

  2. Build pvCommon: cd into pvCommonCPP and build the module:

    [from the top level directory of pvCommonCPP, issue make]
    % make 

    pvCommon should then build without errors.

  3. Build pvData: cd into pvDataCPP and build the module:

    [from the top level directory of pvDataCPP, issue make]
    % make 

    pvData should then build without errors.

  4. Build pvAccess: Again, cd into pvAccessCPP and build the module:

    [from the top level directory of pvAccessCPP, issue make]
    % make 

    pvAccess should build without errors.

Building exampleCPP

The module exampleCPP currently contains two C++ examples of RPC-style clients and servers. These services require that you have built the core modules as described above. In addition the Channel Archiver Service has a dependency on the EPICS V3 Channel Archiver. See http://ics-web.sns.ornl.gov/kasemir/archiver/.

To build the HelloWorld, you need to specify the dependency locations in a RELEASE.local, e.g. this should include the lines like:

EV4_BASE=/epicsv4/latest
PVACCESS=$(EV4_BASE)/pvAccessCPP
PVDATA=$(EV4_BASE)/pvDataCPP
PVCOMMON=$(EV4_BASE)/pvCommonCPP
EPICS_BASE=/epics/R3.14.12.3/base
depending on your EPICS Base and V4 module locations. This file can be located in the parent directory of exampleCPP, in the parent of HelloWorld (i.e. in exampleCPP) or in HelloWorld/configure.

Then cd into the HelloWorld directory and type make.

The instructions are similar for ChannelArchiverService, except that you will need to specify the location of the Archiver, e.g.

EV4_BASE=/epicsv4/latest
PVACCESS=$(EV4_BASE)/pvAccessCPP
PVDATA=$(EV4_BASE)/pvDataCPP
PVCOMMON=$(EV4_BASE)/pvCommonCPP
ARCHIVER=/epics/R3.14.12.3/extensions
EPICS_BASE=/epics/R3.14.12.3/base
before you cd into the ChannelArchiverService directory and type make.

More detailed instructions for building and running the services are in their respective READMEs HELLOWORLD_README.txt and CHANNEL_ARCHIVER_SERVICE__README.txt (and also available in the source).

Building the other EPICS V4 C++ modules

The other modules are built in a similar fashion, typing make in each module, after first specifying dependencies in a RELEASE.local and build choices and targets in a CONFIG_SITE.local in either each module's configure directory or in the parent directory.

The remaining EPICS V4 modules have the following dependencies:


Greg White, SLAC, PSI. Dave Hickin, Diamond. Timo Korhonen, ESS. Ralph Lange, ITER
Last modified: Wed Oct 19 05:40:58 PDT 2015