How To Port EPICS to a new OS/Architecture

This isn't a detailed list of tasks, but is intended to show the main stages needed to add a new build architecture to EPICS. If you make use of this and find there are hints you'd like to suggest, or steps missing please add them.

• Download a tarfile for the latest release of EPICS Base, or the snapshot from the R3.14 branch (not the trunk), and unpack it.
• If you're not already familiar with EPICS, at least skim chapter 4 of the IOC Application Developers Guide (hereafter known as the AppDevGuide; our build system is different to the usual "./configure && make" approach.
• Build your <base> on a linux-x86 or solaris-sparc system so you know what a fully built system actually looks and acts like. You can build multiple architectures simultaneously in the same tree, which makes for easier comparisons. On linux the build instructions should be as simple as

   export EPICS_HOST_ARCH=linux-x86
   cd <base>
   make

• On the new system system, setenv EPICS_HOST_ARCH to the name for your new architecture, which usually takes the form <osname>-<cpufamily>, for example solaris-sparc, linux-x86, windows-x86
• In the <base>/configure/os directory, create these files by copying and editing the files from an existing architecture:

   CONFIG.Common.<arch>
   CONFIG.<arch>.Common
   CONFIG_SITE.<arch>.Common

• • I would suggest looking at the darwin-ppc or linux-x86 versions to start with; for a Unix-like OS you should be able to make use of the UnixCommon and/or GnuCommon files to provide most of the definitions and rules.
  • If you have to cross-compile then there's more work you have to do and these instructions are probably not sufficient to get you there.
• Running 'make' in the <base>/configure directory should succeed and create an appropriate O.<arch> directory.
• Once you have created the new files for the build system, check out the <base>/src/libCom/osi/os subdirectories - these contain any code that has to be OS-specific; in many cases the posix and default directories may provide almost all of the implementation you need. Create a new directory named for your OS_CLASS to put any new files in.
  • You can run make inside the <base>/src/libCom directory to compile your new files. There are a number of tests in the <base>/src/libCom/test subdirectory (run make in here too first) that will check out some of the OSI implementations - try running these on Linux or Solaris as well as your new target OS to get a feel for what the correct output might be.
• Once libCom builds properly, try running 'make' in the <base> top level directory and see how far it gets. If you've done the libCom stuff right the rest of the software should compile without error.
• Keep tech-talk informed of your progress, and don't be afraid to ask questions here and post the errors and locations that you get stuck on, there are lots of people here who should be able to help.
• When you have base building without errors, follow the Chapter 2: Getting Started instructions in the AppDevGuide to create an IOC on the new architecture, and try running it.
• Change base/startup/EpicsHostArch and EpicsHostArch.pl for the new arch.
• Add base/documentation/README.<arch> if special instructions are needed.
• When this works, send a patch file with your changes to [email protected] and we'll incorporate your new architecture into the next release.