Welcome to cram’s documentation!

cram is a utility to support multi-site/multi-facility development and deployment of EPICS IOC and HLA (High level applications) software to multiple sites/facilities/accelerator programs/beamlines. cram allows one to build once in a development environment and then deploy multiple times into different IOCs on different sites.

EPICS IOC applications have these features.

• There are many IOCS running the same software package. For example, we can have many 100’s of IOC’s (instances) running the same BPM package.
• Each of these IOCs have a st.cmd that is slightly different from the others - mostly in the form of msi macro expansions.
• We cannot really test IOC applications in development; so we often have one IOC running one version of the software package while the others are running a more stable version.

HLA applications have these features.

• There is only one instance of the software package in a site. For example, there is only one current version of the ArchiveViewer in a site.
• HLA applications rarely have hardware requirements; thus, it is often possible to test them completely in development.

To see more details on the folder structure of IOC and HLA apps, please see this document.

A typical development/deployment cycle using cram is as follows

• We develop/build/test (as much as we can) a software package on a development machine.
• We push this version of the software package using cram push which rsync’s the contents of the package to all the sites managed by cram.
• We then upgrade one or more IOC instance(s)/HLA app in one or multiple sites/facilities to this new version using cram upgrade.
• If we are satisfied with this release, we can upgrade all IOC/HLA instances in all sites/facilities to this new version using cram upgrade again.
• If we are not satisfied with this new release, we can rollback the upgraded IOC/HLA instances to the previous release using cram revert.

cram is a command line tool written in Python (targeting Python 2.4+). cram syntax is similar to CVS and GIT in that cram takes a command as a first argument. To get a list of commands that cram supports, simple type cram in a Linux command prompt:

sh-3.2$ cram
Usage: cram <action> <args>.
  cram is the main script for the multi site/facility release management system
  To do something with cram, please specify the action that you'd like to perform.
  For a list of actions, just type cram.
  To get help for a particular action, use cram <action> --help.
  For example, to get help on cram ls, do cram ls --help or cram ls -h
  Actions currently supported are --
                ls  List the releases currently being used by IOC/HLA/other.
                ...

For example, to list the current release(s), type cram ls in a folder containing your software package in your development system:

sh-3.2$ cram ls
Current versions on facility: FACET
Current release  v3
IOC: sioc-ms-002 => v3
...

Note, one does not necessarily have to be in a folder containing your software package. There are enough options to run cram from anywhere in the file system on development. However, cram is meant to be used principally from the development systems.

Commands

• ls - Show current releases, available releases, unused releases etc.
• push - Push/submit a new release for a software package to all facilities.
• upgrade - Upgrade/deploy a previously submitted release to one or more IOCs/HLA app in one or more sites/facilities.
• revert - Reverts a IOC/HLA/other release to the previous release.
• history - Displays the upgrade history for a software package.
• delete - Delete a previously submitted release from the release repository if it is unused.
• run - Run a script in the current release of one or more IOCs/HLA app in one or more sites/facilities.

You do not need to type in the complete command when using cram. As long as cram has enough information to determine unambiguously what you mean, partial commands are acceptable. For example, given the list of commands above, cram up is an acceptable substitute for cram upgrade. However, it is recommended that the full command name be used in automation scripts to guard against new commands being added to cram.

For all the commands, cram uses the ${PWD}/.cram/packageinfo to determine the name of the software package and its type. If cram is being executed from a folder that does not contain a .cram/packageinfo and you do not want to create one in the current working folder, you can specify the name and type using command line options.

Manifest files

cram has support for specifying rsync include and exclude files as part of your software package. These can also be specified on a per facility basis. The files .cram/push_exclude and .cram/push_include are included when pushing to all facilities. The files .cram/<facility_name>_push_exclude and .cram/<facility_name>_push_include are included when pushing to facility with name <facility_name>. At a very high level, these are files with lists of patterns, one pattern per line. Patterns can be files, folders or entire trees. For more details of how these files work, please see the documentation for rsync for the --include and --exclude commands. Also see http://masstransmit.com/garage_blog/rsync-quirks/ for some useful patterns.

Some examples

• Add *.o to .cram/push_exclude to exclude all .o files

• Add configure/** to .cram/push_exclude to exclude all content from the configure folder.

• Add mgntApp/** to .cram/FACET_push_exclude to exclude all content from the mgntApp folder when pushing to FACET.

• To include specific files, the easiest approach is to add an include for all directories and end with a catchall exclude.

  • Start your include list with a /* to include all directories
  • Then include the individual files and folders by adding them to your include list
  • Finally, add a * to your exclude list

Running scripts as part of the upgrade process

cram has support for running custom scripts during the upgrade and revert processes. The file bin/preDeploy is automatically executed (if it exists) in the target facility before the upgrade process. The file bin/postDeploy is automatically executed (if it exists) in the target facility after the upgrade process. These can be bash or python scripts or any file that can be executed in a Linux environment. Please do remember to make these files executable. Note that when cram is used to upgrade ALL IOCs in a facility, these custom scripts will be called once when switching the MASTER link and once for each IOC. Before calling these scripts, cram sets several environment variables that can be used to switch on or switch off functionality.

• CRAM_SCRIPT is the path to the script that is running.
• CRAM_PACKAGENAME is the name of the software package.
• CRAM_PACKAGETYPE is the type of the software package.
• CRAM_RELEASEFOLDER is the full path to the folder that contains the release that we are upgrading/reverting to.
• CRAM_RELEASE is the release that we are upgrading/reverting to.
• CRAM_LINKFOLDER is the full path to the folder that contains the soft links that cram switches as part of the upgrade/revert.
• CRAM_ISMASTER is true if we are switching the master link for IOC’s; false otherwise.
• CRAM_FACILITY is the name of the facility.
• CRAM_IOC is the name of the IOC that is being upgraded. When the custom scripts are being called when upgrading the master link for IOC’s or when upgrading HLA applications, this will be set to the string MASTER.

In addition to these custom scripts, cram also runs some internal scripts as part of a push.

Currently, cram has support for

• After a push, cram automatically alters the envPaths for all IOCs in iocBoot to reflect the correct location for TOP, EPICS_TOP, EPICS_BASE_TOP and IOC_SITE_TOP.

Other documents

• For some hints on how to develop and debug IOC applications when deploying with cram, please see this document.
• To see more details on the folder structure of IOC and HLA apps, please see this document..
• Index
• Module Index
• Search Page