# How to Work with the EPICS Repository¶

This document aims to show to software developers how to get the current EPICS Base code, modify it and publish the changes.

## Organization of the EPICS Git Repository¶

The main EPICS repository is hosted on Launchpad. The source code repository is at https://git.launchpad.net/epics-base.

A mirror of the repository is available on Github: https://github.com/epics-base/epics-base.git Depending on your location one or the the other may be faster.

All current and past EPICS Base versions are in the same repository on different branches.

### EPICS 7¶

The current development branch is “core/master”. However this branch only acts as a kind of envelope. The actual EPICS 7 code is divided into modules each of which lives on a separate branch.

git clone --recursive https://git.launchpad.net/epics-base
cd epics-base
git submodule update --remote


This requires at least git version 1.8. Older git versions may need a different procedure. If git clone --recursive is not supported, do this instead:

git clone https://git.launchpad.net/epics-base
cd epics-base
git submodule update --init --reference .


If git submodule update --remote is not supported, look up the branches of each module in the .gitmodule file, then go into each module directory and check out the relevant branch manually.

### Older EPICS Versions¶

There is a separate branch for each of the older EPICS Base versions: 3.13, 3.14, 3.15, and 3.16. (However there is no 3.12 branch.)

Use these to check out the latest developments of one of the older versions, for example to fix a bug in one of those versions.

git clone --branch 3.14 https://git.launchpad.net/epics-base


### Specific Releases¶

Individual releases as well as pre-releases and release candidates are tagged like R3.16.1, R7.0.1-pre or R7.0.1-rc1. First clone the relevant branch, then check out the tag, e.g.:

git clone --branch 3.14 https://git.launchpad.net/epics-base
cd epics-base
git co R3.14.8


## Making Changes¶

Changes should always be made against the head of the relevant branch, not against the release tags.

For bug fixes check out the branch where the bug appears first. The fix will be merged into newer EPICS versions by the core developer team.

For new features better announce your idea on the core-talk@aps.anl.gov mailing list and ask which branch is most appropriate. For revolutionary new features it is probably the EPICS 7 master branch respectively the branch of the submodule as referenced in the .gitmodule file.

For each change create a new branch with a meaningful name.

git checkout -b branch-name


Then start working on your change. Don’t forget to write a test!

### Maintaining Compatibility¶

Build and test your changes on as many systems as possible. Important operating systems are Linux, Windows, OS X, vxWorks and RTEMS.

Keep in mind that in particular vxWorks 5 uses old compiler versions. Do not break working systems with dependencies on new compiler versions. This means for example C++ 11 features.

EPICS up to 3.15 works with vxWorks 5.5 which uses gcc 3.3.2 with a quite old C++ implementation and EPICS 3.16 works with vxWorks 6.3 using gcc 3.4.4. Do not break that!

### Testing¶

All new features must come with automated tests to prove their functionality. This also helps to find out if future changes break existing features.

There are several “test” directories. Choose the one appropriate for the test. Keep in mind that some tests may run before all parts of Base are built. Details vary depending on the EPICS Base version.

EPICS Base comes with a testing framework which allows to run IOCs, set and read/compare values and more.

To add a test, you will typically create a xxxTest.c and probably some records in a xxxTest.db file. (Choose a suitable name.) Also you need to edit the Makefile in the test directory as well as a file with a name like “epicsRun*Tests.c” to include your new test.

Here is a basic example of a test code (xxxTest.c):

#include "dbAccess.h"
#include "dbUnitTest.h"
#include "testMain.h"
MAIN(xxxTest) {
epicsUInt32 value;

/* Announce how many test will be done, see comments below. */
testPlan(total_number_of_tests);

testdbPrepare();

/* "dbTestIoc" or "recTestIoc" may be suitable. */
recTestIoc_registerRecordDeviceDriver(pdbbase);

/* start up IOC */
testIocInitOk();

* (This does not count as a test.)
*/
testDiag("##### This text goes to the test log #####");

/* Set values and check for success. Counts as 1 test.
* Make sure that DBF type matches your variable
*/
testdbPutFieldOk("record.FIELD", DBF_ULONG, value);

/* Get value and compare with expected result. Counts as 1 test.
* Make sure that DBF type matches your variable
*/
testdbGetFieldEqual("record.FIELD", DBF_ULONG, value);

/* Do some arbitrary test. Counts as 1 test. */
testOk(condition, formatstring, ...);

/* The same without your own message. Counts as 1 test. */
testOk1(condition);

/* Finish */
testIocShutdownOk();
testdbCleanup();
return testDone();
}


Your test should run (and succeed) when you execute

make runtests


## Merging Your Work into EPICS Base¶

When done with your development, do not push it to the main repository (You probably do not have permission to do so anyway). Instead push it to your personal repository on Launchpad.

If you do not have a Launchpad account yet, got to https://launchpad.net/ and click on “register”. With a Launchpad account comes the possibility to have personal repositories. You will use these to push your changes. Don’t forget to upload your public (not private!) ssh key (found in \$HOME/.ssh/id_rsa.pub or similar) in order to be able to push to your repository using ssh.

git remote add launchpad git+ssh://username@git.launchpad.net/~username/epics-base