The purpose of this page is to create a quick reference for all the macro (and variable) definitions we find in the EPICS build environment.  Often times, the names of the macros do not give much of a clue of their purpose, and sometimes the names are misleading. 

Makefiles typically have the name "Makefile" but in EPICS they can have just about any name.  For example, RELEASE or CONFIG or RULES.  I still call them Makefiles makefiles (lower case m) as their syntax is defined by the Makefile parser program "make".makefile parser program "make".

Links

• EPICS App Dev Guide / Build Facility

Terms

An EPICS application is an application that is linked with EPICS libraries.

An EPICS module is a library (.a or .so) that is specifically designed for the EPICS environment.  Typically modules are statically linked to the EPICS application.

A package is a standard OS (e.g. Linux) library (.a or .so) that is linked with an EPICS application.  An example is boost or an XML parsing library.

Top level directory

Your top level directory must have a Makefile.

DIRS defines which directories should be entered.  Each directory should have a Makefile which is read by make.  DIRS can be used in Makefiles located in directories other than the top level, but I am not sure which.  The path of the directory you add is relative to the current directory.

<dir_name>_DEPEND_DIRS I'm not sure what this is.  This might define the order in which directories are entered by make.

configure directory

CONFIG_SITE

Your configure directory can have a CONFIG_SITE makefile.  In it we define information about packages that are linked with the application.

CHECK_RELEASE is set to YES, NO, or WARN.  It defines whether to enforce the version dependencies between modules.  Module X might depend on version 5 of module Z, and module Y might depend on version 6 of module Z.  Should such a situation be flagged by make?

CROSS_COMPILER_TARGET_ARCHS defines the architectures to be built beyond the architecture of the machine you are building on.  You should not list an architecture like rhel6-x86_64 here.  You should list architectures like linuxRT-x86_64 as you can't build natively on such architectures at SLAC.

SHARED_LIBRARIES I am not sure what this defines.

STATIC_BUILD defines if packages should be statically linked with the application.  Typically this is YES.

We also need to define information about the packages we want to link with.  This information is used in other makefiles, for example your application's Makefile.  Defining these do not themselves cause a link to occur.

<package_name>_PACKAGE_NAME is not required but we use it just to make defining the other macros easier.  It defines the directory name for the package behind $PACKAGE_SITE_TOP.

<package_name>_VERSION is not required but we use it to make changing package versions easier.  It defines the directory behind the package name directory.

<package_name>_TOP defines where the top directory of the package exists.  This directory should contain a build and src directory.

<package_name>_LIB defines where the library file (.a or .so) exists.  This is probably behind an architecture directory. 

<package_name>_INCLUDE defines where the library's header files (.h) exist.  This is probably behind an architecture directory, but I don't know why as header files should be consistent across architectures.  Maybe when we build the packages, we copy header files to the architecture directory just for completeness.

RELEASE

In the RELEASE makefile we define the module dependencies for our application.

<module>_VERSION is not required but we use it to make changing module versions easier.  It defines the directory behind the $EPICS_MODULES/<module> directory.

<module> defines the include (.h) and library (.a and .so) search directories.  "include" and "lib/<arch>" are appended to what this macro is defined to be.  Yes, this is confusing.

EPICS_BASE defines the version of the EPICS base library behind the directory $EPICS_SITE_TOP/base you want to link your application with.

Application

src Directory

If you're building an app (not a module, not a library), your app will have a Makefile in its src directory.

...

DBD defines the database definition made for and baked into your app.

<app_name>_DBD defines the database definitions that get baked into your app.  This is additive, so use +=.

USR_INCLUDES defines the include directories to search for the header files that your app needs, like include directories for libraries you want to bake in.  For some reason, -I (dash eye) is not automatically prepended, so you need to preface the directory with -I, e.g. -I$(MY_LIB_INCLUDE).  Also, since you are adding include directories, you need to use +=.

USR_LIBS defines the libraries that are baked into your application.  This is additive, so use +=.

USR_LIBS_<operating_system> e.g. USR_LIBS_Linux defines the libraries that are baked into your application when the target OS is <operating_system>, e.g. USR_LIBS_Linux.  This is additive, so use +=.

<lib>_DIR defines the directory in which the library (.a or .so) will be found.

USR_LIBS $(PROD_IOC)_DBD defines the libraries database definitions that are get baked into your applicationapp.  This is additive, so use +=.

<app_name>$(PROD_IOC)_SRCS I'm not sure what this is.

<app_name>$(PROD_IOC)_SRCS_DEFAULT defines the source files for your application.  This is additive, so use +=.

<app_name>$(PROD_IOC)_LIBS defines the EPICS modules (not libraries) that are baked into your application.

Db Directory

If you're building an app (not a module, not a library), your app will have a Makefile in its Db directory.

...