All development of EPICS core software makes use of a central CVS repository at APS. Remote access to this is possible but is controlled by the requirements of the APS firewall and DoE policies on computer security. The remainder of this chapter assumes that the user has some experience in using CVS.
Until the question of future EPICS licensing is fully resolved the source code for the core software can only be made available to collaboration members, thus anonymous CVS read access to the whole repository cannot be provided. Anonymous access to the epics/modules directory containing unbundled hardware support packages is possible though, and experiments are being made in providing this facility from the APS web-site. A link to this facility will appear on the APS EPICS home page if the experiments prove successful.
The EPICS CVS repository is at /net/phoebus/epicsmgr/cvsroot on any of the machines in the APS controls group network. Users must be a member of the Unix group epicsmgr to be able to access the repository using CVS.
EPICS base is found at epics/base relative to the CVSROOT. Note that base is also defined as the CVS module name for this subdirectory.
Files are tagged with each release, and distributed versions also have a branch created to allow bug fixes to be applied and retrieved without also getting changes that are intended for the next major release. For example the branch with tag epics_R3_13_1_branch is used for all bug fixes to version 3.13.1 but not include modifications being developed for version 3.14 (which should appear only on the main branch until released).
Marty Kraimer <[email protected]> should usually be consulted before checking in changes to base. Janet B. Anderson <[email protected]> is in charge of the release process.
Hardware support code (device and driver support and some specialized record types) is being unbundled from base, and the intention is for 3.14 to not have any hardware-specific code in it. The existing support routines will be packaged up as <supporttop> applications and these will be placed into the epics/modules area of the repository. Responsibility for future maintenance of these modules is being divested from APS where other volunteers can be found, and after unbundling any remaining modules will be left fallow. Sites interested in taking on a such a module are asked to contact Andrew Johnson <[email protected]> about this. The list of modules and Module Owners will be merged into Steve Lewis' List of EPICS Supported Hardware pages in due course.
The repository structure within epics/modules will reflect the classification of the module concerned. The basic philosophy behind the repository structure is that the location of a particular module is determined by its functionality, not by the connection method needed to control it. Cross-references will obviously be needed from the particular bus involved, but these should be given in the documentation and web-site for the bus, not the repository. Some devices may have more than one method of connection, and in these cases the name of the <supporttop> directory should include the bus used (for example epics/modules/bus/gpib/mpfGpib is the module that supports GPIB communications over MPF). The module categories are as follows:
Additional categories or sub-divisions can be added if they prove necessary. For example some of the client extension programs could be converted to using the makeBaseApp structure, and it would be appropriate to give them in a suitable classification in this area rather than the existing monolithic epics/extensions area.
The above path names may seem to result in a very broad tree, putting only a very small number of devices/drivers in each <supporttop> application. This is deliberate, as at most sites an individual <ioctop> application will usually only need a reasonably small number of device types. Experience at APS has shown that bundling too much support code into a single application produces a software maintenance nightmare further down the line, and this is one reason why we are unbundling the hardware support. A broad tree should not add significantly to the tasks an application developer needs to perform, and EPICS site managers can help by including the necessary additional lines (commented out as desired) in the config/RELEASE file of the local makeBaseApp templates.
When installing packages for use by applications, we recommend that the same relative path name be used as given above, but the particular version of the module will need to be given a name which reflects the particular module version. At APS the release number (such as 2-1) is used as the last component of the path name to the module, so that for example the Allen Bradley Scanner <supporttop> might be installed at /usr/local/iocapps/R3.14.0/bus/allenBradley/2-1. This makes it possible to install a new version of a <supporttop> application at any time but still ensure that only the application engineer in charge of a particular IOC can decide when to switch to using the new version. The APS Procedures section of this document describes this approach, although it does not use the classification structure described here as it was developed for earlier releases of EPICS.
The preferred method of distributing modules is to provide a tar file for each release, accessed through the module's web-site or ftp server. Module owners are also encouraged to read the Linux Software Release Practice HOWTO document which gives good advice on release procedures.
Any hardware record, device or driver support which was provided with release 3.13.1 of EPICS base but which is missing from the above list will be deleted. Should you need any such software you should check on Steve Lewis' Supported Hardware web page and approach the current maintainer directly, or ask on tech-talk. As a last resort you can always obtain the source code from release 3.13.1 and create your own support application for it.
A significant part of the work of a Module Owner (MO) is to maintain the code, fixing reported bugs or merging bug fixes from other users. However equally important or even more vital are the tasks associated with creating and maintaining documentation so the module can be used, and with packaging up releases and making the software easily available to other EPICS sites. It may be appropriate for some modules to divide the work between several people, some of whom might not be software developers (web-site maintenance for example).
Ideally copies of the documentation should be distributed with the software, but at the very least there should be a README file present which gives the URL for the module's web-site and the name of the Module Owner.
A template module web-page has been developed (using Netscape Composer, although any HTML editor can be used) which MOs may start from if they so wish. This will obviously need to be modified to suit particular circumstances by changing or removing parts as necessary (search for underscore characters in the HTML file to find all the parts that will need replacing). If you develop your own site, please try to ensure that all the above information can be accessed by the users somehow, although it does not have to be all on one page.
If you do not have access to a web-server or would prefer to maintain the web-site at a central location, APS will make an area of its web-site available to nominated MOs for module use. Requests for web-space and an account on the APS server should be made to Bill McDowell.
The recommended method is to provide a tar file for each documented release of the <supporttop>, accessible via the module's web-site or an ftp server. This is pretty much an industry-standard approach for obtaining software, and as long as there are no copyright problems in making the software available on a public server it should be the preferred method.
Unless there are particular reasons not to do so, try and keep older versions of the software available. This particularly applies where a particular version of EPICS base is required. MOs may be called upon to incorporate bug fixes into old module versions and generate new releases of these after an upgrade of EPICS base has required a significant change to the software. The release version number should indicate the relevant parentage.
We are looking at the possibility of providing a mirrored copy of the CVS repository outside the APS firewall, providing anonymous read-only access. This should make it easier for sites to obtain and install upgrades without compromising security for the code-base. Until the legal copyright issue has been resolved this would only serve the $CVSROOT/epics/modules area.
As changes occur to EPICS base, modifications may be needed to the <supporttop> applications to remain compatible with the new versions. The changes needed and any tools to help with this will be published by the base developers as soon as these have been confirmed, and any modifications thought to require significant effort should have been discussed on tech-talk or other forum beforehand. The MO will be responsible for ensuring that the required changes are applied and tested, and a new release created.
There may be several developers in the EPICS consortium with an interest in a particular module, and the MO is at liberty to distribute the workload associated with maintaining the module as she/he sees fit. Overall responsibility for the software and final authority for what should or should not be included in it will remain with the MO however.