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 makefile parser program "make".

Terms

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

...

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.

...

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

...