CRAM migration guide

1. This should be the module name in CVS.
2. This should be the name used with eco.
3. This should be the name of the folder in iocTop where the releases are located.

drwxrwxr-x  9 iocegr  lcls MatlabSupport-R3-0-0-0
drwxrwxr-x  9 softegr lcls MatlabSupport-R3-1-0-0
drwxrwxr-x 10 softegr lcls MatlabSupport-R3-2-0-0
lrwxrwxrwx  1 softegr lcls current -> MatlabSupport-R3-2-0-0
[softegr@lcls-builder MatlabSupport]$

lrwxrwxrwx st.cmd -> startup.cmd
-rwxrwxr-x startup.cmd
lrwxrwxrwx iocSpecificRelease -> ../../iocTop/MatlabSupport/current
[softegr@lcls-builder sioc-sys0-ml00]$

• For softIOC's, remove the bin softlink to the iocTop area (many softIOC's used this approach) if you previously had one. It does not hurt to have the bin softlink but it is confusing and it makes it very hard to debug cram failures. The recommended way to refer to collateral in iocTop is to use the iocSpecificRelease link.

[softegr@lcls-builder sioc-sys0-ml00]$ cat startup.cmd 
#!iocSpecificRelease/bin/linux-x86/matlabSupport
#==============================================================
#
#  Abs:  EPICS Soft IOC Startup Script for sioc-sys0-ml00

# Go to IOC top directory and execute IOC startup script
cd <iocCommon>/sioc-sys0-ml00/iocSpecificRelease/iocBoot/sioc-sys0-ml00
< st.cmd 

# Execute soft_post_st.cmd script
< /usr/local/lcls/epics/iocCommon/All/Prod/soft_post_st.cmd

[softegr@lcls-builder Prod]$ grep -e "^sioc-sys0-ml00" ${IOC_SCREEN}/screeniocs
sioc-sys0-ml00 <iocCommon>/sioc-sys0-ml00/iocSpecificRelease/bin/linux-x86/...
[softegr@lcls-builder Prod]$

1. For softIOC's, after changing screeniocs, you'll need to log into the machine hosting the softIoc and restart the softIoc using the /etc/init.d scripts. You need to do this only during migration; this is because merely exiting from iocSh in iocConsole does not start a new screen session. You can also accomplish the same using iocConsole your_ioc -cleanup

[mshankar@lcls-dev2 test]$ eco
Enter name of module/package to checkout: MatlabSupport
Enter name of tag or [RETURN] to use HEAD>
Using MAIN_TRUNK. The name of the directory will be 'MAIN TRUNK'.
...
[mshankar@lcls-dev2 test]$ cd MatlabSupport/MAIN_TRUNK 
[mshankar@lcls-dev2 MAIN_TRUNK]$ 

[mshankar@lcls-dev2 MAIN_TRUNK]$ cram describe

1. Change configure/CONFIG for static builds with:

   SHARED_LIBRARIES=NO
   STATIC_BUILD=YES
   
   

2. If using streamdevice, add USR_SYS_LIBS += pcre to your application's Makefile. This will include libpcre.a from the system libraries.
3. If using areadetector, add asyn to PROD_LIBS using PROD_LIBS += asyn and remove it from your <APP_libs> in your application's Makefile.
4. If using the motor module, you may need to include the motor and asyn module's as part of PROD_LIBS and remove it from your <APP_libs> in your application's Makefile.
5. If using the calc module, you may need to include the sscan module in your configure/RELEASE

   SSCAN_MODULE_VERSION=sscan-R2-8-1_1-0
   SSCAN=$(EPICS_MODULES)/sscan/$(SSCAN_MODULE_VERSION)
   
   

   and in your app's Makefile

   softLlrf_LIBS += sscan
   
   

6. On linux, ldd is a very useful tool. If you do an ldd bin/linux-x86/your_app, you should only see .so's from /usr/lib or /lib. If you see .so's from other folders, you need to include the .a's or you need to ship the .so's using LIB_INSTALLS.

• We are building on dev and copying over to production. Some of the variables in envPaths will be fixed by the upgrade script. However, there will not be any modules on the production side of the fence. So, any templates that are being loaded from the module folder need to be included in the application. The EPICS build system already has support for adding a wide variety of file types to your software package and also allows for custom types. In general, adding a file to your application consists of adding the file using something suitable like DB_INSTALLS. For example, to add autosave's save_restoreStatus.db to your application, add the following line to your applications <app>/Db/Makefile

  DB_INSTALLS += $(AUTOSAVE)/db/save_restoreStatus.db

  and change your st.cmd to point to dbLoadRecords("db/save_restoreStatus.db", "P=SIOC_$(AREA)-$(IOC_SUFF):") instead of dbLoadRecords("$(AUTOSAVE)/db/save_restoreStatus.db", "P=SIOC_$(AREA)-$(IOC_SUFF):")
• If using areaDetector, remember to change areaDetector.cfg if you have one. Some areaDetector.cfg have a cd $(AREA_DETECTOR)/ADApp/Db as the first line. You may want to comment this out as we are not loading templates from the db area.
• cram has some ability to detect external resources using cram lint. You typically run cram lint in a cycle with make clean and make. An IOC make generates the st.cmd and envPaths for all the ioc's in the software package. cram lint parses the st.cmd for all the ioc's in the software package and points out
  1. All includes from external sources like < $(AREA_DETECTOR)/include.cmd
  2. All cd's to external folders like cd $(AREA_DETECTOR)/ADApp/Db
  3. External EPICS databases loaded using dbLoadRecords; for example, dbLoadRecords("$(IOCADMIN)/db/iocAdminSoft.db", "IOC=SIOC:$(AREA):$(IOC_SUFF)")
  4. Missing EPICS databases loaded using dbLoadRecords; these could be elements that were not added to the app's Makefile using DB_INSTALLS
  To use cram lint, run make clean followed by make and then run cram lint. You should see some thing like this

  
  [mshankar@lcls-dev2 ProfileMonitorAD-R1-0-2]$ cram lint
  Linting IOC iocBoot/sioc-b34-pm02
  Linting IOC iocBoot/sioc-li20-pm20
  iocBoot/sioc-b34-pm02/st.cmd:125 Missing file db/iocAdminSoft.db in ${TOP}; perhaps you...
  iocBoot/sioc-b34-pm02/st.cmd:147 Add DB_INSTALLS += $(AREA_DETECTOR)/ADApp/Db/ADBase.te...
  
  

  Fix these errors as appropriate and then run make clean followed by make followed by cram lint.

[mshankar@lcls-dev2 MAIN_TRUNK]$ cvs add .cram
[mshankar@lcls-dev2 MAIN_TRUNK]$ cvs add .cram/packageinfo
[mshankar@lcls-dev2 MAIN_TRUNK]$ cvs commit

[mshankar@lcls-dev2 test]$ eco
Enter name of module/package to checkout: archiveviewer
Enter name of tag or [RETURN] to use HEAD>
Using MAIN_TRUNK. The name of the directory will be 'MAIN TRUNK'.
...
[mshankar@lcls-dev2 test]$ cd archiveviewer/MAIN_TRUNK/
[mshankar@lcls-dev2 MAIN_TRUNK]$ 

[mshankar@lcls-dev2 MAIN_TRUNK]$ cram describe

[mshankar@lcls-dev2 MAIN_TRUNK]$ cvs add .cram
[mshankar@lcls-dev2 MAIN_TRUNK]$ cvs add .cram/packageinfo
[mshankar@lcls-dev2 MAIN_TRUNK]$ cvs commit

[mshankar@lcls-dev2 test]$ eco
Enter name of module/package to checkout: archiveviewer
Enter name of tag or [RETURN] to use HEAD>ArchiveViewer-R1-2-11
Using ArchiveViewer-R1-2-11. The name of the directory will be ...
...
[mshankar@lcls-dev2 test]$ cd archiveviewer/ArchiveViewer-R1-2-11/
[mshankar@lcls-dev2 ArchiveViewer-R1-2-11]$

1. At least during the initial migration, avoid using MAIN_TRUNK.

[mshankar@lcls-dev2 ArchiveViewer-R1-2-11]$ cram ls
Current version on facility: LCLS  => ArchiveViewer-R1-2-11
Current version on facility: FACET  => ArchiveViewer-R1-2-11
Current version on facility: TestFac  => ArchiveViewer-R1-2-11
Current version on facility: Dev  => ArchiveViewer-R1-2-11
[mshankar@lcls-dev2 ArchiveViewer-R1-2-11]$

[mshankar@lcls-dev2 ArchiveViewer-R1-2-11]$ cram push
Pushed release ArchiveViewer-R1-2-11 to LCLS
...

...ArchiveViewer-R1-2-11]$ cram upgrade -f LCLS ArchiveViewer-R1-2-11
...ArchiveViewer-R1-2-11]