Table of Contents Previous Chapter Chapter 6: Developer Interface

Chapter 6: Developer Interface

1. Introduction

This chapter explains how to create and use a private master EPICS directory tree for developing EPICS base and extension software. The CVS source/release system makes it convenient to develop for base and for individual extension products or for a combination.

2. Creating Private Directory Structure

Checkout `config'

   cvs checkout epics/config
This will checkout the configuration files used by both base and extensions. config must be checked out for any development work on base and/or extensions. It creates a subtree named epics/config in whatever directory the cvs checkout command is issued.

Please note that the only configuration file a developer should ever modify is the file <epics>/config/CONFIG. You can add definitions to the end of this file to override definitions contained in other config files.

Checkout `base'

Checkout base only if you wish to develop base products. Although it is possible to checkout only portions of base, it is easier, until you have experience building base products, to check out the entire base tree. This can be done with the commands:

  cd <to directory just above the epics created in previous step>
  cvs checkout epics/base
  cd epics/base
  gmake
This will checkout and build the entire EPICS base.

Checkout `extensions'

Other than the EPICS system manager, you will probably never want to checkout the entire set of extension products. Instead you will only want to check out an individual product for development. If the product relies on other products, the other products will be automatically referenced from your site official base and official extensions areas. If you want to change these referenced locations, you can add definitions for EPICS_BASE and/or EPICS_EXTENSIONS to the end of your <epics>/config/CONFIG file.

For example, to checkout an extension product, issue the commands:

  cd <to directory just above epics>
  cvs checkout epics/extensions/src/<product>
  cd epics/extensions/src/<product>
  gmake
This will check out and build <product>.

3. Using CVS Commands

Committing a New Version

Perform the following steps:

  cd <epics>/extensions/src/<product>
Or

  cd <epics>/base/src/<product>
Modify the files as desired.

  cvs commit
You will be asked to supply a comment for the cvs log when you commit modified files.

Other Useful CVS commands

The following are helpful cvs commands:

  cvs add        Adds a new file/directory to the repository
  cvs diff        Runs diffs between revisions
  cvs help        Prints list of cvs commands
  cvs log        Prints out information for files
  cvs status        Prints status info on the files
  cvs remove        Removes an entry from the repository
  cvs update        Brings work tree in sync with repository
  cvs commit        Checks files into the respository
See the CVS document Version Management with CVS by Per Cederquist and the cvs man page for details.

4. Using EPICS Makefiles

This section describes how an EPICS developer uses EPICS Makefiles. A basic knowledge of CVS operation is assumed.

Makefile Commands

Each src/xxx directory contains two types of Makefiles, a single high-level Makefile and one or more low-level Makefiles, one for each architecture type to be built (e.g.: Vx or Unix).

While developing code for a particular architecture, a developer can use either of two different methods. The developer may opt to use a higher-level approach and invoke gmake in a src/xxx directory (e.g.: <epics>/base/src/db), or use a lower-level approach and invoke gmake in an architecture-specific object directory (e.g.: <epics>/base/src/db/O.sun4). The higher level Makefile will generate all targets for single or multiple architectures. The low-level Makefile in the O.<ARCH> directory can only generate targets for a single architecture, however it is capable of generating a single object target.

The following make commands are available in EPICS Makefiles:

The default command is install, i.e.

  gmake
is the same as

  gmake install
The makefiles in the src/XXX directories also support the single architecture "command.arch" syntax. For example, to build and install software for the mv167 architecture, type "gmake install.mv167".

The makefiles in the O.<arch> directories can be used to build a single target. These makefiles do NOT support the single architecture syntax "target.arch" because a single architecture is the default.

For example to build dbAccess.o in $EPICS/base/src/db/O.mv167, execute:

  cd O.mv167
  gmake dbAccess.o
Notes:

5. Creating High-level Makefiles

Each src/XXX source directory must contain a high-level Makefile which has the following lines:

  # Relative pathname to the top of the EPICS tree (required).
  EPICS = ../../..
  # Include file containing EPICS definitions (required).
  # Include $(EPICS)/config/CONFIG_BASE  - for base products.
  # Include $(EPICS)/config/CONFIG_EXTENSTIONS - for extension products.
  include $(EPICS)config/CONFIG_BASE
  # Include file containing EPICS rules for architectures (required).
  include $(EPICS)/config/RULES_ARCHS

6. Creating Low-level Makefiles

A low-level makefile must exist for each build type supported in a particular source directory. For example, the db directory performs both Unix and VxWorks compilation. Therefore it contains a makefiles for both build types: Makefile.Unix and Makefile.Vx.

Low-level Makefile Structure

Each low-level Makefile is made up of four parts.

Preamble

The Makefile "preamble" contains relative pathnames to the top of EPICS. Every pathname is specified relative to the O.<ARCH> directory, as that is where gmake is being invoked.

  # Relative pathname to the top of the epics tree (required)
  EPICS = ../../../..
  # Include file that sets the EPICS target architecture (required)
  include Target.include
  # Include file containing EPICS definitions (required)
  #  $(EPICS)/config/CONFIG_BASE    - For base products.
  #  $(EPICS)/config/CONFIG_EXTENSIONS  - For extension products.
  include $(EPICS)/config/CONFIG_BASE

Options Section

The options section allows options to be specified for the various utilities in the build. The following options are supported:

  # "Compile type" option, used only for Unix builds. (optional) !  If this option
  # is left out, an ANSI compile is chosen by default.
  # OLD - Select old-style compilation for this directory.Avoid this when possible.
  # STRICT - ANSI compilation with pedantic warning flags.  Use this when possible.
  CMPLR = OLD
  # C / C++ / loader flags / loader libraries / depending libraries
  # VxWorks compiles only support USR_CFLAGS and USR_LDFLAGS.
  USR_CFLAGS = -D_NO_PROTO -UvxWorks
  USR_CCFLAGS =
  USR_LDFLAGS = 
  USR_LDLIBS = -lDb -lCom -lm
  DEPLIBS = 
  # Lex/Yacc option flags, with typical settings.
  YACCOPT = -d -v
  LEXOPT = -l

Product Definition Section

This section specifies the sources, objects, libraries and library dependencies that will be used to compile targets in this directory.

  # Source files.  Include targets, but without the ../.
  SRCS.c = ../snc_main.c ../parse.c ../phase2.c snc.c snx_lex.c   ...
  # Object files.  All object files are created in the current directory.  Do not
  # include objects that are parts of libraries on this line.  Leave this
  # blank if only libraries are being built in this directory.
  OBJS = snc_main.o parse.o phase2.o snc.o snc_lex.o   ...
  # Library object files.These are objects that make up the principal library being
  # built in this directory.  Leave this out if no libraries are being built.
  LIBOBJS = obj1.o obj2.o obj3.o   ...
  # Library name. Leave this out if no libraries are to be installed
  LIBNAME = libname.a
  # Products.Objects specified in $(OBJS) are linked together to create this 
  # target. Leave this out if no products are to be installed
  PROD = prod1 prod2  
  # Targets to be built but not installed. Leave this out if none are to be built.
  TARGETS = target1 target2 
  # Include files. Leave this out if no include files are to be installed.
  INC = include1.h include2.h
  # Document files. Leave this out if no document files are to be installed.
  DOCS = doc1 doc2 doc3
  # Man pages files. Leave this out if no man pages are to be installed.
  MAN1 = mana.1 manb.1 manc.1
  # Scripts to be installed. Leave this out if no scripts are to be installed.
  SCRIPTS =  script1 script2 script3

Rules Section

This section specifies the rules that will be used to build the targets in this directory.

  # Include the default rules file (required).
  include $(EPICS)/config/RULES.Unix
  #  Add rules for objects not easily built with the default rules file, e.g.:
  tsTest: tsSubr.o
    $(LINK.c) -o $@ tsSubr.o -lCom -lm -s
  #  Add the "clean::" double colon rule.  This rule should remove all temporary 
  #  files in the O.<ARCH> directory except those with .o and .a extensions.  These 
  # files are automatically removed by the default rules file.
  clean::
    rm -f snc snc_lex.c snc.c
Default rules are provided for lex and yacc generated C files. As with objects, these temporary files are generated in the O.<ARCH> directories. If left alone, yacc will create y.tab.c and optionally, y.tab.h. However, the default rules will rename these files automatically so that yacc may be used again in the same directory. For example, if you have a yacc file foo.y, the default rules will create foo.c, and optionally, foo.h. This renaming also occurs for lex generated files.

Therefore, to use the default rules, all files in the same directory must have different basenames. For example, three files named dbLoadTemplate.y, dbLoadTemplate.l, and dbLoadTemplate.c will confuse the default Make rules. This is not an absolute restriction, as you may override the default rules as you see fit. However, we suggest using the default rules since they result in simpler Makefiles.

C files generated by lex are often included directly into C files generated by yacc. When this is the case, extra dependency must be created manually in your Makefile, for example:

  # Extra rule since atdb_lex.c is included in atdb_yacc.c
  atdb_yacc.o: atdb_lex.c
NOTE: It is recommended that you use the EPICS supplied version of lex (elex) and yacc (antelope). To do this, put the following two definitions in your Makefile:

  LEX = $(ELEX)
  YACC = $(EYACC)

7. Modifying The CONFIG File

The epics/config/CONFIG file may be edited by developers or the EPICS system manager in order to override specific variables in the configuration. Configuration files other than CONFIG and the "SITE" files are not meant to be modified at all. CONFIG provides a convenient place to put all variable overrides.

Say, for example, a developer wishes to turn on compiler warnings that were disabled by the EPICS system manager for the build. The developer would then add the following definitions at the end of the CONFIG file:

  VX_WARN=YES
  UNIX_WARN=YES
Notes: Only the EPICS system manager is allowed to commit this file into the local CVS repository.

8. Developing EPICS Base at a Remote Site

With the help of CVS, EPICS base can easily be developed by remote sites. This is because CVS allows each file to be edited by more than one person at a time, and merges parallel changes when the source code is finally checked in. To develop EPICS base at a remote site:

  1. Checkout a copy of EPICS base and config from the CVS repository at the master site. Important: Note time and date of this operation.
        cvs checkout base config
  2. Create an EPICS release.
        cd $EPICS/base
    gmake release
Or obtain an official EPICS release from the EPICS repository site.

  1. Move this release to the remote site. Make changes to it, possibly with the aid of a local CVS repository. Note files and directories that have been modified, or use the Unix "find" command to perform this operation automatically.
  2. Create a new EPICS release and send it back to the master site.
  3. Check out the version of EPICS current at the date and time you obtained it.
        cvs checkout -D "DATE" base config
    Or checkout the release of EPICS you obtained from the repository site using its tag:
        cvs checkout -t "EPICS_R3_12" base config
  4. Copy all files that were modified at the remote site onto this version.
  5. Update these new files either individually or at the top-level, using
          "cvs update -A".
  6. Fix conflicts and then commit changes with "cvs commit".

9. Developing New Extensions

Creating a New Extension

To create a new extension within an extensions development tree perform the following steps:

  cd <epics>/extensions/src
  mkdir <newext>
  cvs add <newext>
  cd <newext>
Create and test the <newext> files and Makefiles. Put the cvs keyword $Log$ someplace in each source file.

  cvs add <filename>
The add command is issued for each file to be placed under cvs control. Don't forget the Makefiles.

  cd <epics>/config
NOTE: You may not have file permission for the next step. In this case you will have to ask your EPICS system manager to perform this step.

Add your new extension directory to the directory list in the CONFIG_EXTENSIONS file. These directories are used for an extension top-level build.

  cvs commit CONFIG_EXTENSIONS
You will be asked to supply a comment for the cvs log when you commit modified files.

Importing an Existing Product

In the source directory where the product currently exists execute:

  cvs import -m "Imported files" epics/extensions/src/<prod> <prod>_R0 <prod>_R0
WARNING: Make sure you have a a clean directory structure before invoking import because it recursively descends all directories from where it is invoked.

If the source files were previously maintained via SCCS, it is best to import a version obtained via the sccs get command. If the SCCS keywords such as %W% and %G% were used then the file will contain a record of the SCCS version that was converted to CVS.

Perform the following steps:

  cd <to directory just above epics>
  cvs checkout epics/extensions/src/<prod>
  cd epics/extensions/src/<prod>
  gmake
Create and test necessary Makefiles and then use the add command for each Makefile as follows:

  cvs add <filename>
Create a .cvsignore file if desired.

  cvs add .cvsignore
Add the cvs keyword $Log$ to each source file. If a Modification log was manually maintained previously just add the $Log$ after the last log entry.

  cvs commit
You will be asked to supply a comment for the cvs log when you commit modified files.

  cd <epics>/config
Add your new extension directory to the directory list in the CONFIG_EXTENSIONS file. These directories are used for an extension top-level build.

  cvs commit CONFIG_EXTENSIONS
You will be asked to supply a comment for the cvs log when you commit modified files.
Table of Contents Next Chapter