LCLS How-To Release Software

High Level Apps Release Procedure

EPICS IOC Applicaion Deployment and Release Procedure Rev 4
LCLS How-to Release Soft IOCs for Production

LCLS Code Management

• LCLS CVS Repository
• LCLS Directory Tree
• EPICS Modules and Dependencies
• LCLS How-to Tag a Release
• LCLS How-to Branch a Release
• EPICS Modules Maintenance and Patch Management Guidelines

LCLS PLC Development Getting Started

• How-to Download PLC Ladder Logic
• LCLS How-To Restore PLC Software from CVS

LCLS How-To Boot an EPICS IOC

• LCLS Directory Tree
• How-to Setup DHCP for an IOC
• Cheetsheet for AFS IOC boot pararmters
• Cheetsheet for NFS IOC boot parameters
• Cheetsheet for Reflashing RTEMS IOC

Note: PLC applications are generated on windows machines. See subsystem controls engineer for details

It is important to note that releasing software to the Development System during the 2007 run will affect the production system displays, standalone process restarts, and IOC's upon boot.

For plc's follow Step 1-4 only.

Step 1: General Instructions

1. Log into your SLAC Unix account on the host lcls-dev2
2. Setup your CVS environment variables for the LCLS environment.
3. All EPICS IOC Application should include the site modules iocAdmin, which provides ioc statisticts. Those applications that require restore capabilities should include the module autosave or restore, which uses ChannelWatcher. To add these modules, please note that the configure/RELEASE file will need to be modified. # US

Step 2: Modifying existing software in CVS:
Note: if a cross compiler does not exist for your source, for example plc ladder logic and firmware, skip item 4 below.

1. Change directory to your local sandbox
2. cvs co -d <directory> <module name>
3. modify software
4. if applicable, build your application to verify that the build is successfully.
5. test your changes in development
6. if possible test your changes in production
7. if ready to commit your changes, edit the RELEASE_NOTES file to prepare for the tagged release.

Step 3: Importing new software into CVS:

1. Change directory to the TOP of your new application
2. Make sure you have a RELEASE_NOTES and README file at the top of your application
3. Modify you configure/RELEASE file for production use
4. Import your software into CVS. The cvs import syntax is

cvs import -m "Initial import of ..." epics/base <vendor_tag> <release_tag>
cvs import -m "Initial import of ..." epics/site/src/<package> <vendor_tag> <release_tag>
cvs import -m "Initial import of ..." epics/ioc/<subsystem> <vendor_tag> <release_tag>

EPICS IOC Example)
cvs import -m "Initial import of...." epics/ioc/Vacuum Vacuum Vacuum-R1-0-0
PLC Example)
cvs import -m "Initial import of...." plc/Water/ioc-in20-wa01 ioc-in20-wa01 ioc-in20-wa01-R1-0-0

Step 4: Commit your changes to CVS and Tag

1. Change directory to the directory where your changes were made locally.
2. Commit all changed files to cvs: cvs commit -m "comment" <filename>
3. Move to the top level directory of your application you wish to tag. For PLC applications this will be the nodename directory.
4. Tag software: cvs tag <modulename>-RX-Y-Z

EPICS IOC Applicaiton Example: cvs tag Vacuum-R1-0-1
PLC Example: cvs tag ioc-in20-wa01-R1-0-0

Step 5: CVS Tag your changes

For ioc common startup: cd /afs/slac/g/lcls/epics/iocCommon/<subsystem>/<nodename>
For ioc application: cd /nfs/slac/g/lcls/epics/iocTop/<subsystem>
For modules: cd /afs/slac/g/lcls/epics/modules/<module>
For epics base: cd /afs/slac/g/lcls/epics/base/base-<version>

1. cvs co -P -d <tagged version> -r <tagged version> <module name>
2. cd <tagged version>
3. gmake
4. Send an email to controls-software-release regarding your tagged software release. If other applications need your changes, describe how to include your new version and the features of this new release.

Step 6: ChannelWatcher

1. Update configuration files for your ioc if necessary.
2. Create or modify the Master.XX file for your subsystem.
3. Restart your ChannelWatcher monitoring process. For more information click here.

Step 7: Follow instructions on[How-To Boot an EPICS ioc|LCLS How-To Boot an EPICS IOC]

1. Test your new release on the development system.
2. If booting form the LCLSCA subnet proceed to Step 9. Otherwise, request permission from mcc ops to reboot your ioc. Once permission has been granted, send an email to controls-software-release regarding your ioc boot. This email message is forwarded to the Operations E-log. Boot your ioc and test. Send email to controls-software-release when your test has finished, providing the results of your test. If you have to backout your release, go to Step 8, Otherwise, your done!

Step 8: Backout out a Release

1. cd $EPICS_IOCS/<nodename>
2. for hard iocs: mv startup.cmd to st.cmd_new and ~_{mv red:startup.cmd_bck startup.cmd}~
3. for soft iocs: mv st.cmd to st.cmd_new and mv st.cmd_bck to st.cmd
4. Reboot your ioc.
5. Send a message to controls-software-release.

Step 9: Before Exporting Software to Production System
Check duplicate PV before exporting software to production system
for ALL iocs: use the dupePVs.bash iocname

Examples:
1) get usage
dupePVs.bash -h

2) check all iocs found in $IOC
dupePVs.bash

3) check all eioc's
dupePVs.bash eioc

4) check all iocs with mg in the name
dupePVs.bash mg

5) check all soft magnet IOCs
dupePVs.bash sioc-.*-mg01

Step 10: Exporting Software to Production System

When your EPICS IOC Application is ready for release to production, which means that you have completed the following;

1. committed your changes to CVS
2. tagged you release
3. built and tested on the development system (lcls-dev2)

You are ready to export your softwthe production host, opi00gtw03.

From lcls-prod02:

1. ssh iocegr@lcls-builder or ssh physics@lcls-srv01
2. export CVSROOT=:ext:luchini@lcls-prod02:/afs/slac/g/lcls/cvs

Note: replace the username "luchini" with your own unix username

For EPICS IOC applications:

1. cd $EPICS_IOC_TOP/<subsystem>
2. cvs co -d Laser-R1-0-0 -r Laser-R1-0-0 Laser
3. cd Laser-R1-0-0/configure

Edit RELEASE file and replace path /afs/slac/g/lcls with /user/local/lcls/

1. cd ..
2. gmake
3. cd $EPICS_IOCS/<nodename>
4. For hard iocs cp -p startup.cmd startup.cmd_bckup and the edit startup.cmd file and point to the new tagged release
5. For soft iocs mv bin bin_bckup and ln -s ../../iocTop/<subsystem>/<tagged-version>/bin/<OS> bin
6. Reboot ioc, after mcc has granted permission.
7. Enter a log in the operations elog book by sending email to controls-software-release.

Matlab Programs Released to Production:

1. how-to release matlab software on production
2. or all new release, enter a message in the operation elog book by sending email to controls-software-release.

Step 11: Export ChannelWatcher Config Files
(see the example below)

1. ssh iocegr@lcls-builder or ssh physics@lcls-srv01
2. export CVSROOT=:ext:luchini@lcls-prod02:/afs/slac/g/lcls/cvs
3. cd $TOOLS/ChannelWatcher/config
4. cvs update <filename>
5. ssh laci@lcls-daemon1
6. cd /etc/init.d
7. ./st.cw<Subsystem> restart ex) st.cwMG for Magnets
8. logout
9. Note: if you have the Message Logger up (from lclshome) note the number of pv's that failed to connect to ChannelWatcher.
10. Enter a message in the operation elog book by sending email to controls-software-release.