This page documents the process to follow when deploying a new versions of EPICS Extensions at SLAC. Extensions at SLAC live in separate directories under $EPICS_TOP/extensions where they can be worked on separately. When it comes time to release new versions, they are re-bundled and placed also under $EPICS_TOP/extensions in a directory named after the version, such as R1.2.0.

NOTE: A video recording with additional information from Bruce Hill is available here.

To make the process for creating a new release clear, let's go through an actual example of creating and deploying a new release.

Making the new build

Let's say the current release is R1.2.1, and we'd like to make a new R1.3.0 release which will include updating eget, labca, and removing procServ. To start, create a local copy of the extensions repository somewhere in a sandbox in your home directory to work with:

git clone /afs/slac/g/cd/swe/git/repos/package/epics/extensions/extensions.git

A fresh copy should look similar to the following:

jesseb@aird-b50-srv01:/afs/slac/g/controls/development/users/jesseb/sandbox/extensions $ ls
configure  Makefile  RELEASE_NOTES  RELEASE_SITE

The file we will want to modify is configure/RELEASE. The current version looks like this:

jesseb@aird-b50-srv01:/afs/slac/g/controls/development/users/jesseb/sandbox/extensions $ cat configure/RELEASE 
#
# Extension release versions
#
include $(TOP)/RELEASE_SITE

EPICS_EXTENSIONS	= $(EPICS_SITE_TOP)/extensions

CAMCOM			= $(EPICS_EXTENSIONS)/Camcom/R3.0.0
CATOOLS			= $(EPICS_EXTENSIONS)/catools/R1.0.0
CHANNELWATCHER	= $(EPICS_EXTENSIONS)/ChannelWatcher/R3.0.1
STRIPTOOL		= $(EPICS_EXTENSIONS)/StripTool/R2.5.18.0-1.1.0
VISUALDCT		= $(EPICS_EXTENSIONS)/VisualDCT/R2.7.0-0.1.0
ALH				= $(EPICS_EXTENSIONS)/alh/R1.2.35-1.0.2
CASNOOPER		= $(EPICS_EXTENSIONS)/caSnooper/R2.1.2.3-0.1.0
EDM				= $(EPICS_EXTENSIONS)/edm/R1.12.105B-1.3.0
EGET			= $(EPICS_EXTENSIONS)/eget/R0.0.0-0.0.2
FWDCLIS			= $(EPICS_EXTENSIONS)/fwdCliS/R1.2.6
GATEWAY			= $(EPICS_EXTENSIONS)/gateway/R2.1.2.0-1.0.0
JCA				= $(EPICS_EXTENSIONS)/jca/R2.3.7-0.2.0
LABCA			= $(EPICS_EXTENSIONS)/labca/R3.8.0
PARSECASW		= $(EPICS_EXTENSIONS)/parsecasw/R1.0.3.0-0.1.0
PROBE			= $(EPICS_EXTENSIONS)/probe/R1.1.8.0-0.1.0
PROCSERV		= $(EPICS_EXTENSIONS)/procServ/R2.7.0-1.1.0
IOCLOGMSGSERVER	= $(EPICS_EXTENSIONS)/iocLogMsgServer/R1.7.0

Now assuming you have already made your changes to the relevant extensions and rebuilt them under $EPICS_TOP/extensions, making the new release of the extensions bundle is as simple as modifying the RELEASE file to point to the updated versions. For this example, we will be updating eget to R0.0.0-0.0.4, and labca to R3.8.1-0.1.0. We will also be removing procServ as it does not fit well with the other extensions. So the updated file will look as follows:

#
# Extension release versions
#
include $(TOP)/RELEASE_SITE

EPICS_EXTENSIONS	= $(EPICS_SITE_TOP)/extensions

CAMCOM			= $(EPICS_EXTENSIONS)/Camcom/R3.0.0
CATOOLS			= $(EPICS_EXTENSIONS)/catools/R1.0.0
CHANNELWATCHER	= $(EPICS_EXTENSIONS)/ChannelWatcher/R3.0.1
STRIPTOOL		= $(EPICS_EXTENSIONS)/StripTool/R2.5.18.0-1.1.0
VISUALDCT		= $(EPICS_EXTENSIONS)/VisualDCT/R2.7.0-0.1.0
ALH				= $(EPICS_EXTENSIONS)/alh/R1.2.35-1.0.2
CASNOOPER		= $(EPICS_EXTENSIONS)/caSnooper/R2.1.2.3-0.1.0
EDM				= $(EPICS_EXTENSIONS)/edm/R1.12.105B-1.3.0
EGET			= $(EPICS_EXTENSIONS)/eget/R0.0.0-0.0.4
FWDCLIS			= $(EPICS_EXTENSIONS)/fwdCliS/R1.2.6
GATEWAY			= $(EPICS_EXTENSIONS)/gateway/R2.1.2.0-1.0.0
JCA				= $(EPICS_EXTENSIONS)/jca/R2.3.7-0.2.0
LABCA			= $(EPICS_EXTENSIONS)/labca/R3.8.1-0.1.0
PARSECASW		= $(EPICS_EXTENSIONS)/parsecasw/R1.0.3.0-0.1.0
PROBE			= $(EPICS_EXTENSIONS)/probe/R1.1.8.0-0.1.0
IOCLOGMSGSERVER	= $(EPICS_EXTENSIONS)/iocLogMsgServer/R1.7.0

To generate the links to the new versions, just run make from the top level extensions directory. Note that it will generate both the RHEL 6 and RHEL 7 versions at the same time, so there is no need to change to a different machine and run make twice for these.

jesseb@aird-b50-srv01:/afs/slac/g/controls/development/users/jesseb/sandbox/extensions $ make

<lots of output>

jesseb@aird-b50-srv01:/afs/slac/g/controls/development/users/jesseb/sandbox/extensions $ ls bin
rhel6-x86_64  rhel7-x86_64

jesseb@aird-b50-srv01:/afs/slac/g/controls/development/users/jesseb/sandbox/extensions $ ls -la bin/rhel6-x86_64

<lots of output>

Running the ls commands will verify that the softlinks are all pointing to the expected versions.

As long as everything looks good, go ahead and commit the changes to configure/RELEASE. Then update the RELEASE_NOTES file explaining what has changed for the new version. Finally go ahead and push the commits, as well as tagging and pushing the new release.

# Assuming you have already pushed your commits changing RELEASE and RELEASE_NOTES:
git tag -a R1.3.0 -m "Tagging new extensions release R1.3.0"
git push origin R1.3.0

Deploying the release to DEV

Now it's time to get the new release to the correct place under afs. Go ahead and make the new directory with the same name as the new release under $EPICS_TOP/extensions, and place the extensions repository there ensuring you check out the correct tag you just created:

jesseb@lcls-dev3:/afs/slac/g/lcls/epics/extensions/R1.3.0 $ git log -1
commit 69b12295bb6bd7429d27e144d5c06113fc444d89
Author: jbellister-slac <jesseb@slac.stanford.edu>
Date:   Mon Mar 13 14:19:05 2023 -0700

    Update RELEASE_NOTES for new version R1.3.0

Once again, run make to generate the softlinks, and verify that everything looks as expected. Assuming it all looks good, to deploy the release to everyone else requires editing an startup script. All EPICS related startup scripts are located under $EPICS_SETUP, and the repository backing them can be cloned as such:

git clone /afs/slac.stanford.edu/g/cd/swe/git/repos/slac/epicstools/epics-setup.git

The relevant files to edit are epicsenv-7.0.3.1-1.0.bash and epicsenv-7.0.6.1-1.0.bash. Note that 7.0.3.1-1.0 is the current version of EPICS as of the writing of this documentation, editing 7.0.6.1-1.0 is just to keep that up to date as well in case we update to the version of EPICS base in the future. This will be a one line change, update this to point to the new extensions version, would change to R1.3.0 in this example:

export EPICS_EXTENSIONS=${EPICS_SITE_TOP}/extensions/R1.2.1

Also update the standard SLAC header comments up top just to say the modification is for a new extensions release. Commit and push the changes.

Now to release it to everybody - go to $EPICS_SETUP and use git pull to update the files you just modified. Now everyone who logs in and sources ENVS64.bash will be on the latest extensions version.

Deploying the release to PROD

Log into lcls-srv01 as the epicsmgr shared account. The following steps will mostly mirror what was just done on dev.

[epicsmgr@lcls-srv01 jesseb]$ cd $EPICS_TOP/extensions
[epicsmgr@lcls-srv01 jesseb]$ mkdir R1.3.0
[epicsmgr@lcls-srv01 jesseb]$ git clone ssh:///afs/slac/g/cd/swe/git/repos/package/epics/extensions/extensions.git R1.3.0
[epicsmgr@lcls-srv01 jesseb]$ git checkout R1.3.0
[epicsmgr@lcls-srv01 jesseb]$ make

The only main thing to note there is the link to the afs repository, that will manage to grab it from mcclogin.

Again verify that the softlinks were created as expected. Since the epics setup files were already committed to git in the DEV release, all that remains is to pull them onto production:

[epicsmgr@lcls-srv01 R1.3.0]$ cd $EPICS_SETUP

[epicsmgr@lcls-srv01 R1.3.0]$ git pull
<various output>

[epicsmgr@lcls-srv01 setup]$ git log -1
commit 496a37e70c3814ce55d0de1a45736c5b8aea6aaa
Author: jbellister-slac <jesseb@slac.stanford.edu>
Date:   Mon Mar 13 15:03:20 2023 -0700

    Update extensions version to R1.3.0 in epicsenv-7.0.3.1-1.0.bash and epicsenv-7.0.6.1-1.0.bash (CATER 162103)

And that is everything. Run any final tests as needed.