.. cram documentation master file, created by sphinx-quickstart on Mon Jul 1 10:52:24 2013. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. 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 :doc:`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 . 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 --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. .. toctree:: :maxdepth: 2 Commands ======== * :doc:`ls ` - Show current releases, available releases, unused releases etc. * :doc:`push ` - Push/submit a new release for a software package to all facilities. * :doc:`upgrade ` - Upgrade/deploy a previously submitted release to one or more IOCs/HLA app in one or more sites/facilities. * :doc:`revert ` - Reverts a IOC/HLA/other release to the previous release. * :doc:`history ` - Displays the upgrade history for a software package. * :doc:`delete ` - Delete a previously submitted release from the release repository if it is unused. * :doc:`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/_push_exclude`` and ``.cram/_push_include`` are included when pushing to facility with 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 :download:`this document.` * To see more details on the folder structure of IOC and HLA apps, please see :doc:`this document. `. * :ref:`genindex` * :ref:`modindex` * :ref:`search`