INSTALL

xInstallation instructions for Py-Epics3
=======================================

To install the epics module from source, use

   python setup.py install

Or,

   pip install .

This assumes that Python 2.5 or higher is installed and is the
enviroment you wish to istall pyepics in to.

By default the object libraries for Epics Channel Access (libCom.so
and libca.so for linux, libCom.dylib and libca.dylib for Mac OS X and
Com.dll and ca.dll for windows) are included with this distribution
and installed for you.  To prevent the installation of the binaries use

   NOLIBCA=1 python setup.py install

The code is tested via continuation integration on linux for
python 2.7, 3.5, and 3.6.  It is also extensively used on
on windows and OSX machine.


Locating CA shared libraries
============================

On Unix systems, the shared libraries for Epics Channel Access (libca.so,
libCom.so) must be found by Python at runtime.  Since Epics installations
generally leaves these in an architecture-specific location (and not
"installed" into normal system-wide library directories), you will probably
need to set this up once per machine.  There are a few ways to do this:

  1. set the environmental variable LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH)
     to point to the directory with the shared object libraries:

       export LD_LIBRARY_PATH=/usr/local/epics/base/lib/linux-x86

       setenv LD_LIBRARY_PATH /usr/local/epics/base/lib/linux-x86

  2. set the PATH environmental variable to make sure that the location of
     libca is in the PATH.

Both options may need to be set for each user shell that uses CA, and so
should probably be put in a shell startup script.

Testing the Location of CA shared library
==========================================

The setup.py script will test where libca might be found and print a
prominent warning if libca.so cannot be found.

To test this yourself,  run python from the current directory and
type:
    >>> import lib as epics
    >>> epics.ca.find_libca()

This should report the full name of dynamic CA library (libca.so, ca.dll,
or libca.dylib).   It it does not, or reports an error, you should
locate libca.so and set PATH or LD_LIBRARY_PATH  to include the path
containing this file.


Matt Newville <newville@cars.uchicago.edu>
Last Update:  2017-05-01