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 (lower case m) as their syntax is defined by the makefile parser program "make".

Terms

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

An EPICS module is a library (.a or .so) that are 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 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.

<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

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>_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.

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.

PROD_IOC defines the resulting application name (the executable file name).

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

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 +=.

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

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

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

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

$(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.

DB_INSTALLS defines the databases from EPICS modules that are baked into your application.  This is additive, so use +=.

DB defines the databases from your application that are baked into your application.   This is additive, so use +=.