EPICS V4 Release 4.X.0 C++ Bundle Read-Me

This is the README.md file from the bundleCPP master branch.

This README provides a guide to building the EPICS V4 C++ modules from this packaged release.

Authors:

• David Hickin, Diamond
• Andrew Johnson, Argonne National Laboratory

Prerequisites

The EPICS V4 C++ Release Bundle is provided as source code, and must be built for the specific set of target architectures needed.

The bundle requires recent versions of following software:

1. EPICS Base (3.14.12.x or 3.15.x) already built
2. Standard development tools as required for EPICS Base
3. Doxygen (optional, for generating documentation)

The pvAccess for Python package, pvaPy, requires:

1. Python development header files/libraries (v2.6.6 or later)
2. Boost (v1.41 or later) with Boost.Python
3. Boost.NumPy (optional, for use with NumPy)
4. Sphinx (optional, for generating documentation)

Building EPICS V4

This bundle automates the steps of configuring and building the individual sub-modules that make up the C++ implementation of EPICS V4. The modules themselves rely on the EPICS Base build system. Detailed documentation of the EPICS Base build facility can be found in the EPICS Application Developers Guide.

Simple builds of the bundle can be achieved on most operating systems with a single command, specifying the path to EPICS Base as a parameter:

make EPICS_BASE=/path/to/epics/base

This will create configuration files for each module and build them in order. If you have a computer with multiple CPUs you can make use of GNUmake's ability to compile different parts in parallel on different CPUs by adding the -j flag; on Windows you should use -j8 for example on an 8-CPU box since GNUmake's load detection doesn't work very well. With EPICS Base 3.14.12.x on Windows the parallel build rules don't work properly though so -j should not be used.

It is only necessary to give the EPICS_BASE=... argument the first time you run make; for any subsequent commands you can omit that as it will be saved in a file RELEASE.<host-arch>.Common that gets created on the first run.

Some additional make commands that may be useful are:

• make host - This only builds for the host operating system, avoiding any cross-compiled architectures that the EPICS Base installation might be configured for. See the Manual Configuration section below for an alternative to using this target though.
• make doxygen - Run the doxygen tool on all sub-modules that use this to generate reference documents. Excludes the pvaPy and exampleCPP modules.
• make runtests - This executes all of the self-test programs that are delivered in the EPICS V4 C++ modules.
• make clean - Delete intermediate files which are not required after the build has finished for all architectures built on this host. This may be useful on systems where disk space is tight.
• make distclean - Delete all generated files for all architectures, including installed headers, binaries and library files. This also removes the file that saves the location of EPICS Base, so after running this the next build must specify the EPICS_BASE=... argument again.

Building the Python API (pvaPy)

This bundle includes a copy of the pvaPy python module, but the build commands above will not compile it (pvaPy cannot be built on Microsoft Windows at all). To configure and build pvaPy after the above build has completed:

make python

If you only want to build EPICS V4 for the python API, you can avoid compiling some of the modules in the first step above by just running

make EPICS_BASE=/path/to/epics/base python

If you use the Python library NumPy and have the Boost.NumPy package installed, you can build pvaPy with NumPy support by adding the path to that package on either of the above command-lines:

make python BOOST_NUMPY=/path/to/boost/numpy

or

make EPICS_BASE=/path/to/epics/base BOOST_NUMPY=/path/to/boost/numpy python

After building pvaPy you can also generate the related reference documentation if you have the Sphinx Python documentation generator installed:

make sphinx

Manually Configuring Target Architectures

In many cases the automated configuration steps described above will be sufficient to build the standard C++ modules. However in some circumstances a manual configuration step may be needed first to control which embedded cross-compiled target architectures get built. If your copy of EPICS Base is configured to also compile for unsupported VxWorks targets (i.e. any version earlier than VxWorks 6.8) you will have to exclude those targets from the build. To do that, create a file called CONFIG_SITE.local in the top-level bundle directory that overrides the CROSS_COMPILER_TARGET_ARCHS variable as appropriate.

For example

# CONFIG_SITE.local
CROSS_COMPILER_TARGET_ARCHS = vxWorks-ppc32

explicitly configures the build for only the vxWorks-ppc32 target architecture (in addition to the host architecture), while

# CONFIG_SITE.local
CROSS_COMPILER_TARGET_ARCHS = \
    $(filter-out vxWorks-68040,$(CROSS_COMPILER_TARGET_ARCHS))

removes just the vxWorks-68040 cross-target from the set provided by EPICS Base.

Further Information

For information about the individual modules, consult the documentation that comes with each one. In particular these files

• README.md
• documentation/RELEASE_NOTES.md
• Other files in the documentation directory

Additional information about EPICS V4 can be found on the EPICS V4 Website and its Documentation page