icshwi / e3

ESS EPICS Environment : E3 Development

Deprecation notice

2023-04-03: This is no longer the mechanism intended to deploy e3. Please see https://e3.pages.esss.lu.se/ for more documentation.

2020-08-26: This remote has been deprecated. Moved to https://gitlab.esss.lu.se/e3/e3.

e3 developing environment

This is the setup and maintenance scripts for the ESS EPICS Environment (E3).

Notice

This repository was developed in order to check each module compatibility easily and quickly within E3. Therefore it has no purpose to serve as a production environment. If one would like to see a reproducable single point release of E3, please check https://github.com/icshwi/e3-manifest . By this manifest repository the exactly same E3 can be built in many different places. However, the manifest E3 doesn't have any convenient tools.

Tested Platforms

• Building, requiring (loading), and running modules should be tested carefully if one would like to run an EPICS IOC within e3.
• The following Linux distributions cover Building and Requiring Tests.

Building and Requiring Tests

• Debian
• CentOS
• Ubuntu

Procedure to duplicate the minimal E3 in your system.

• This procedure has many assumptions, so it most likely doesn't work "out of the box".

• However, if one would like to challenge this, please follow the below basic instructions.

• This script, e3.bash, is not the proper tool to deploy the E3 in any production environment, but it is a system with which one can design, develop, and debug E3 in many different scenarios. One can use it to duplicate the E3 in most Linux flavor without any difficulties.

Note that the user account should be in sudo group. And please install "git" and "make" first.

Get e3

$ git clone https://github.com/icshwi/e3

Install base within the e3 directory

NOTICE, before going to run the next command, PLEASE INSTALL ALL REQUIRED PACKAGES FIRST. For CentOS 8, one should carefully install all necessary packages with their various repositories and with source codes first. If not, one CANNOT install and run e3. One can see the e3 training workbook for the up-to-date information [1]. For example, the following packages mostly are needed to compile e3 and some additional services in CentOS and Debian. Note that one may not need them all according to one's configuration.

• CentOS 7

* Note there is also a temporary internal mirror of CentOS packages required for E3 available inside ESS network.*  
For configruation details look here: https://gitlab.esss.lu.se/icshwi/centos_mirror_proxy.  

Otherwise the required packages can be installed manually from CentOS community mirrors as below:  
$ sudo yum --enablerepo=extras install epel-release  
$ sudo yum install -y git tree ipmitool autoconf libtool automake m4 re2c tclx \
coreutils graphviz patch readline-devel libXt-devel libXp-devel libXmu-devel \
libXpm-devel lesstif-devel gcc-c++ ncurses-devel perl-devel net-snmp net-snmp-utils \
net-snmp-devel libxml2-devel libpng12-devel libzip-devel libusb-devel \
python-devel darcs hdf5-devel boost-devel pcre-devel opencv-devel \
libcurl-devel blosc-devel libtiff-devel libjpeg-turbo-devel \
libusbx-devel systemd-devel libraw1394.x86_64 hg libtirpc-devel \
liberation-fonts-common liberation-narrow-fonts \
liberation-mono-fonts liberation-serif-fonts liberation-sans-fonts \
logrotate xorg-x11-fonts-misc cpan kernel-devel symlinks \
dkms procServ curl netcdf netcdf-devel

• Debian

git tree emacs ipmitool autoconf libtool automake m4 re2c tclx coreutils graphviz build-essential libreadline-dev libxt-dev x11proto-print-dev libxmu-headers libxmu-dev libxmu6 libxpm-dev libxmuu-dev libxmuu1 libpcre++-dev libmotif-dev libsnmp-dev re2c darcs python-dev libnetcdf-dev libhdf5-dev libbz2-dev libxml2-dev libblosc-dev libtiff-dev libusb-dev libusb-1.0-0-dev libudev-dev libsystemd-dev linux-source mercurial libboost-dev libboost-regex-dev libboost-filesystem-dev libopencv-dev libpng-dev libraw1394-11 libtirpc-dev fonts-liberation logrotate curl netcdf netcdf-devel symlinks dkms procserv linux-headers-$(uname -r)

$ bash e3_building_config.bash -t ${HOME}/epics setup

$ bash e3.bash base

Install require within the e3 directory

$ bash e3.bash req

Install common modules within the e3 directory

One should install base and require first before each modules's configuration.

$ bash e3.bash -c vars

>> Vertical display for the selected modules :

 Modules List 
    0 : e3-ess
    1 : e3-autosave
    2 : e3-caPutLog
    3 : e3-asyn
    4 : e3-busy
    5 : e3-modbus
    6 : e3-ipmiComm
    7 : e3-seq
    8 : e3-sscan
    9 : e3-std
   10 : e3-ip
   11 : e3-calc
   12 : e3-iocStats
   13 : e3-delaygen
   14 : e3-pcre
   15 : e3-StreamDevice
   16 : e3-s7plc
   17 : e3-recsync
   18 : e3-MCoreUtils


e3 (master)$ bash e3.bash -c mod

e3 (master)$ bash e3.bash -c load

If you see the clean ioc shell prompt, e3 is ready to use. Please exit this test ioc.

Enable e3 in only current terminal

Technically, one can have multiple e3 and community EPICS environments in a single host. To enable e3, please use the following command:

e3 (master)$ source tools/setenv 

The above environment file will be generated automatically by the building procedure.

After this, you can run the example ioc through

e3 (master)$  iocsh.bash cmds/iocStats.cmd 

Open another terminal, set the environment via source first, then run the caget_pvs.bash with the generated pv list file.

e3 (master)$ bash caget_pvs.bash -l IOC-9999_PVs.list 
.............
.............

IOC-9999-IocStats:ACCESS       Running
IOC-9999-IocStats:APP_DIR 160 47 104 111 109 101 47 106 104 108 101 101 47 101 51 45 51 46 49 53 46 53 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
IOC-9999-IocStats:APP_DIR1     /home/jhlee/e3-3.15.5
IOC-9999-IocStats:APP_DIR2     
IOC-9999-IocStats:CA_ADDR_LIST 
IOC-9999-IocStats:CA_AUTO_ADDR YES
IOC-9999-IocStats:CA_BEAC_TIME 15.0
IOC-9999-IocStats:CA_CLNT_CNT  0
IOC-9999-IocStats:CA_CONN_CNT  0
IOC-9999-IocStats:CA_CONN_TIME 30.0
IOC-9999-IocStats:CA_MAX_ARRAY 16384
IOC-9999-IocStats:CA_RPTR_PORT 5065
IOC-9999-IocStats:CA_SRCH_TIME 300.0
IOC-9999-IocStats:CA_SRVR_PORT 5064
IOC-9999-IocStats:CA_UPD_TIME  15
IOC-9999-IocStats:CPU_CNT      4
IOC-9999-IocStats:ENGINEER     jhlee
IOC-9999-IocStats:EPICS_VERS   EPICS R3.15.5-E3-3.15.5-patch
IOC-9999-IocStats:FD_CNT       7
IOC-9999-IocStats:FD_FREE      1017
IOC-9999-IocStats:FD_MAX       1024
IOC-9999-IocStats:FD_UPD_TIME  20
IOC-9999-IocStats:GTIM_CUR_SRC OS Clock
IOC-9999-IocStats:GTIM_ERR_CNT 0
IOC-9999-IocStats:GTIM_EVT_SRC No working providers
IOC-9999-IocStats:GTIM_HI_SRC  OS Clock
IOC-9999-IocStats:GTIM_RESET   Reset
IOC-9999-IocStats:GTIM_TIME    9.18241e+08
IOC-9999-IocStats:HEARTBEAT    17
IOC-9999-IocStats:HOSTNAME     faiserver
IOC-9999-IocStats:IOC_CPU_LOAD 0
IOC-9999-IocStats:IOC_LOG_INET 
IOC-9999-IocStats:IOC_LOG_PORT 7004
IOC-9999-IocStats:KERNEL_VERS  Linux 4.9.0-8-amd64 x86_64
IOC-9999-IocStats:LOAD         0
.............

e3 (master)$   bash caget_pvs.bash -l IOC-9999_PVs.list -f "LOAD"

>> Selected PV and its value with caget
IOC-9999-IocStats:IOC_CPU_LOAD 0.0250242
IOC-9999-IocStats:LOAD         0.0250242
IOC-9999-IocStats:LOAD_UPD_TIME 10
IOC-9999-IocStats:SYS_CPU_LOAD 30.2042

The most useful option is the fake watch with -w option such as

$ bash caget_pvs.bash -l IOC-9999_PVs.list -f "HEARTBEAT" -w 1

$ watch -n 1 "bash caget_pvs.bash -l IOC-9999_PVs.list -f "HEARTBEAT"

If you would like to do more, please visit https://github.com/icshwi/e3training

Outside the e3 directory

Each base, Require module, and other modules have its own MAKEFILE and its own configuration files. Thus, one can put e3-base, e3-require, and all other e3-modules in any directories where one would like to keep them.

Usage for e3.bash

e3 (master)$ ./e3.bash 

Usage    : ./e3.bash [ -ctpifealb4do ] <option> 


           -c     : common       : epics modules
           -t     : timing       : mrf timing modules
           -4     : epics v4     : EPICS V4 modules (testing)
           -p{c}  : psi          : PSI modules
           -i{c}  : ifc free     : ifc modules without user accounts
           -f{ic}  : ifc nonfree : ifc modules with user accounts
           -e{c}  : ecat         : ethercat modules
           -a{c}  : area         : area detector modules / BI Modules
           -l{c}  : llrf         : LLRF modules
           -b{ca} : bi           : beam instrumentation modules (based on AD)
           -d     : developing   : no dependency, one should installl all before
           {c,ci} : dep modules  : enable by default if not defined (dependent modules)
             -o   : only         : ignore dependent modules
                                   the option -e is actually -ec. And -eo means -e.


 < option > 

           env    : Print enabled Modules

           call   : Clean all (base, require, selected module group)
           gall   : Clone all (base, require, selected module group)
            all   : call, gall, ibase, bbase, ireq, breq, imod, bmod

           cbase  : Clean Base
           gbase  : Clone Base
           ibase  : Init  Base 
           bbase  : Build, Install Base
            base  : cbase, gbase, ibase, bbase

           creq   : Clean Require
           greq   : Clone Require
           ireq   : Init  Require
           breq   : Build, Install Require
            req   : creq, gbase ireq, breq

           cmod   : Clean Modules (selected module group)
           gmod   : Clone Modules (selected module group)
           imod   : Init  Modules (selected module group)
           bmod   : Build, Install Modules (selected module group)
            mod   : cmod, mod, imod, bmod

        co_base "_check_out_name_" : Checkout Base
         co_req "_check_out_name_" : Checkout Require
         co_mod "_check_out_name_" : Checkout Modules  (selected module group)
         co_all "_check_out_name_" : co_base, co_req, co_mod

          vbase   : Print BASE    Version Information in e3-*
           vreq   : Print REQUIRE Version Information in e3-*
           vmod   : Print MODULES Version Information in e3-*
           vall   : Print ALL     Version Information in e3-*
           vins   : Print INSTALLED Version Information for locally installed e3 modules
           vdep   : Print DEPENDENCY Version Information in e3-*

         allall   : Print ALL Version Information in e3-* by using "make vars"

           load   : Load all installed Modules into iocsh.bash
           cmd    : create .cmd file in /home/jhlee/e3-7.0.3.1
        setenv    : create setenv in /home/jhlee/e3-7.0.3.1/tools

           vers   : Print Source Tag / Module Versions
            dep   : Print DEP_VERSION information
        plotdep   : Plot the naive module depdendency drawing
      closeplot   : Close all active opened plots

           tags   : Print the latest tag for a repo manifest



  Examples : 

          ./e3.bash creq 
          ./e3.bash -ctpifealb cmod
          ./e3.bash -t env
          ./e3.bash base
          ./e3.bash req
          ./e3.bash -e cmod
          ./e3.bash -t load

SSH KEY Usage

One needs to have the ESS bitbucket/gitlab accout in order to use ifc nonfree and llrf modules. The procedure make init will ask the ESS user name and its password several times. In order not to type account and password many time, one can add the ssh key in the account configurations in bitbucket and gitlab. After that, the following command should be executed in order to use the different url instead of the default one. Note that ESS gitlab repository cannot be accessible outside the ESS network. Several modules (in the group t and b) cannot be cloned.

source tools/use_sshkey.sh

Customized e3 Building Configuration

To build EPICS 7 with e3

$ bash e3_building_config.bash -t /epics/test -b 7.0.3.1 setup 
$ bash e3.bash base
$ bash e3.bash req
$ bash e3.bash -ctpiao mod

Note that the -4 option is not necessary, but -o option is, because EPICS 7 has the "EPICS 4" modules (pvAccess, etc) already in base.

Please look at README_developing.md for more details.

---

[1] https://github.com/icshwi/e3training/blob/master/workbook/chapter1.md

e3's Issues

e3.bash "die" command

Hi Han,
I noticed that in the e3.bash there are several lines with "... || die 1 " commands.
This looks to me to some leftover from some perl script.
Could you please check?

update most DEFINES_FT in modules

e3-calc has the proper DEFINES_FT, should be copied most of modules

root privileges?

Why do ./e3.bash base and ./e3.bash req ask for my sudo password?

nullify all pre-existent EPICS variables

EEE has the hardcorded EPICS and EEE variables in /etc/profile.d/ In this case, HOST_ARCH is selected as centos7, instead of linux. Then, require building will be failed.

It would be better to void all of them in addition with EPICS variables.

Fresh installed Debian 9

• usermod -a -G sudo user
• apt-get install git build-essential aptitude

Should add them in README.md

define in makefile doesn't work with makefile 3.8.x in Linux Mint

We have to check which version of Makefile can work with the current version of E3 building system.

I think it was Linx Mint 2 "Betsy"

AD Integration : ADCore

Interesting fail case in MK_DEFINES

Some Repo has its own conflict

git submodule update --remote --merge m-epics-axiscore/
Auto-merging Makefile.EEE
CONFLICT (add/add): Merge conflict in Makefile.EEE
Automatic merge failed; fix conflicts and then commit the result.
Unable to merge '3d9cbfdf6c2130f9b1e89df8480d619d0766c4f1' in submodule path 'm-epics-axiscore'
/home/jhlee/e3/tools/e3-axiscore/configure/BUILD_E3:74: recipe for target 'm-epics-axiscore' failed
make: *** [m-epics-axiscore] Error 2

Installation issue on Fedora 30

cannot compile Asyn with Fedora 30.

db_module_list should be checked with configure/MODULE

db_module_list is hard-coded in e3.bash. So, we can expect module mismatch with active modules in configure/MODULE.

Need additional logic to check both properly.

Maybe to move that into makefile itself, will resolve this situation permanently.

AD Integration : ADSupport

• E3
• E3+

e3.bash should handle root privilege according to the e3 installation location

The e3 building system can detect whether it needs root privilege or not according to EPICS_BASE. However, e3.bash cannot detect it automatically. Most case, we don't have any issue. However, if one compiles a module with root privilege, clean_module cannot remove that directory without sudo. So, it is quite possible to check EPICS_BASE within e3.bash.

I will leave this issue here in order to clean up them later.

`bash caget_pvs.bash E3Test_PVs.list` fails

https://github.com/icshwi/e3/blame/master/README.md#L118 says I should run bash caget_pvs.bash E3Test_PVs.list, but that doesn't work:

$ bash caget_pvs.bash E3Test_PVs.list

Usage    : caget_pvs.bash [-l pvlist_file] [-w watch_interval_sec] [-f <filter_string>] [-c] [-7] 

               -l : pvlist file generated by dbl output or hand
               -w : watch interval sec
               -f : without arg, select all
               -c : disable existent EPICS CA ADDR environment
               -7 : use pvget instead of caget

 bash caget_pvs.bash -l pvlist_file
 bash caget_pvs.bash -l pvlist_file -f "RB" 
 bash caget_pvs.bash -l pvlist_file -w 5 

remove non-existent symlinks in E3_SITELIBS_PATH

PKG is installed throught pkg_automation, but the following command should be executed at the end of e3 builder.

sudo symlinks -d ${E3_SITELIBS_PATH}

Build problem: illegal option for e3.bash

I cloned a fresh e3 version from the repo. I start to follow the instructions in the README.
I get the following error:

$make env
e3.bash: illegal option -- g
Usage : e3.bash [ -ctifeal ]
......

am I doing something wrong? I am pretty sure that this used to work...

AD Integration : ADAndor

**Cleaning SiteLibs**

make uninstall should remove "creating symbolic links in siteLibs

Arch Linux support

All but one of the Arch packages I need can be installed like this:

pacman -Syu  tcl glibmm libtirpc readline libxt libxmu libxpm pcre net-snmp re2c darcs python2 netcdf hdf5 libpng bzip2 libxml2 libxml2 libusb libusb-compat remake systemd linux-headers mercurial boost boost-libs libraw1394 opencv

the tclx package is also needed but it's the only one that's not in an official Arch repository. Line number 3 of e3/e3-require/require-ess/App/tools/expandDBD.tcl is package require TclxDo we really need it?

glibc beyond version 2.26 has removed some headers that asyn needs to compile. Arch is on version 2.28. The asyn build needs -I/usr/include/tirpc to find the new location for these header files (rpc.h and netconfig.h).

Migration tool should be updated according to sscan

Update additional features dependent upon sequencer

Command not found

pi@raspberrypi:~/git/e3 $ bash e3.bash base
[sudo] password for pi: 
Cleaning .... e3-base
>> e3-base
>> No target directroy is found, Cloning...

Cloning into 'e3-base'...
remote: Enumerating objects: 21, done.
remote: Counting objects: 100% (21/21), done.
remote: Compressing objects: 100% (16/16), done.
remote: Total 547 (delta 10), reused 12 (delta 5), pack-reused 526
Receiving objects: 100% (547/547), 100.10 KiB | 0 bytes/s, done.
Resolving deltas: 100% (309/309), done.

mkdir: cannot create directory ‘/home/grey’: Permission denied
make: /home/pi/git/e3/e3-base/epics-base/startup/EpicsHostArch.pl: Command not found
Can't open perl script "/home/pi/git/e3/e3-base/epics-base/src/tools/EpicsHostArch.pl": No such file or directory

Two issues here:
mkdir: cannot create directory ‘/home/grey’: Permission denied why is this directory trying to be created!?
and
Can't open perl script "/home/pi/git/e3/e3-base/epics-base/src/tools/EpicsHostArch.pl": No such file or directory

should fix update_e3_plus.bash

patch _site and patch_revert_site are needed to fix in order to generate the properly DEFINES_FT.

Add option to set output path with prepare_module

I find that prepare module should be improved providing an option (e.g. -d) to set the destination path of the module. Currently everything is extracted under the e3/tool directory.