EPICS Application Developer’s Guide

This chapter describes the EPICS build facility including directory structure, environment and system requirements, conﬁguration ﬁles, Makeﬁles, and related build tools.

4.1.1 <top> Directory structure

EPICS software can be divided into multiple <top> areas. Examples of <top> areas are EPICS base itself, EPICS extensions, and simple or complicated IOC applications. Each <top> may be maintained separately. Diﬀerent <top> areas can be on diﬀerent releases of external software such as EPICS base releases.

where configure is a directory containing build conﬁguration ﬁles and a Makefile, where dir1, dir2, ... are user created subdirectory trees with Makefiles and source ﬁles to be built. Because the build rules allow make commands like “make install.vxWorks-68040”, subdirectory names within a <top> directory structure may not contain a period “.” character.

4.1.2 Install Directories

Files generated during the build are installed into subdirectories of an installation directory which defaults to $(TOP), the <top> directory. For base, extensions, and IOC applications, the default value can be changed in the
configure/CONFIG_SITE ﬁle. The installation directory for the EPICS components is controlled by the deﬁnition of the INSTALL_LOCATION variable.

Due to a side-eﬀect of the build rules, the parent of the installation directory ($(INSTALL_LOCATION)/..) should not contain directories with the same names as the subdirectories listed below.

The following subdirectories may exist in the installation directory. They are created by the build and contain the installed build components.

4.1.3 Elements of build system

4.1.4 Features

4.1.5 Multiple host and target systems

You can build on multiple host systems and for multiple cross target systems using a single EPICS directory structure. The intermediate and binary ﬁles generated by the build will be created in separate O.* subdirectories and installed into the appropriate separate host or target install directories. EPICS executables and scripts are installed into the $(INSTALL_LOCATION)/bin/<arch> directories. Libraries are installed into $(INSTALL_LOCATION)/lib/<arch>. The default deﬁnition for $(INSTALL_LOCATION) is $(TOP) which is the root directory in the directory structure. Architecture dependant created ﬁles (e.g. object ﬁles) are stored in O.<arch> source subdirectories, and architecture independent created ﬁles are stored in O.Common source subdirectories. This allows objects for multiple cross target architectures to be maintained at the same time.

To build EPICS base for a speciﬁc host/target combination you must have the proper host/target c/c++ cross compiler and target header ﬁles, CROSS_COMPILER_HOST_ARCHS must empty or include the host architecture in its list value, the CROSS_COMPILER_TARGET_ARCHS variable must include the target to be cross-compiled, and the base/conﬁgure/ os directory must have the appropriate conﬁgure ﬁles.

4.2 Build Requirements

4.2.1 Host Environment Variable

Only one environment variable, EPICS_HOST_ARCH, is required to build EPICS <top> areas. This variable should be set to be your workstation’s operating system - architecture combination to use the os vendor’s c/c++ compiler for native builds or set to the operating system - architecture - alternate compiler combination to use an alternate compiler for native builds if an alternate compiler is supported on your system. The ﬁlenames of the CONFIG.⋆.Common ﬁles in base/ conﬁgure/os show the currently supported EPICS_HOST_ARCH values. Examples are solaris-sparc, solaris-sparc-gnu, linux-x86, win32-x86, and cygwin-x86.

4.2.2 Software Prerequisites

Before you can build EPICS components your host system must have the following software installed:

If you will be building EPICS components for vxWorks targets you will also need:

4.2.3 Path requirements

You must have the perl executable in your path and you may need C and C++ compilers in your search path. Check deﬁnitions of CC and CCC in base/configure/os/CONFIG.<host>.<host> or the deﬁnitions for GCC and G++ if ANSI=GCC and CPLUSPLUS=GCC are speciﬁed in CONFIG_SITE. For building base you also must have echo in your search path. You can override the default settings by deﬁning PERL, CC and CCC, GCC and G++, GNU_DIR ... in the appropriate ﬁle (usually configure/os/CONFIG_SITE.$EPICS_HOST_ARCH.Common)

4.2.3.1 Unix path

For Unix host builds you also need touch, cpp, cp, rm, mv, and mkdir in your search path and /bin/chmod must exist. On some Unix systems you may also need ar and ranlib in your path, and the c compiler may require ld in your path.

4.2.3.2 Win32 PATH

On WIN32 systems, building shared libraries is the default setting and you will need to add fullpathname to $(INSTALL_LOCATION)/bin/$(EPICS_HOST_ARCH) to your path so the shared libraries, dlls, can be found during the build.. Building shared libraries is determined by the value of the macro SHARED_LIBRARIES in CONFIG_SITE or os/CONFIG.Common.<host> (either YES or NO).

4.2.4 Directory names

Because the build rules allow make commands like “make <dir>.<action>,<arch>”, subdirectory names within a <top> directory structure may not contain a period”.” character.

4.2.5 EPICS_HOST_ARCH environment variable

The startup directory in EPICS base contains a perl script, EpicsHostArch.pl, which can be used to deﬁne EPICS_HOST_ARCH. This script can be invoked with a command line parameter deﬁning the alternate compiler (e.g. if invoking EpicsHostArch.pl yields solaris-sparc, then invoking EpicsHostArch.pl gnu will yield solaris-sparc-gnu).

The startup directory also contains scripts to help users set the path and other environment variables.

4.3 Conﬁguration Deﬁnitions

4.3.1 Site-speciﬁc EPICS Base Conﬁguration

4.3.1.1 Site conﬁguration

To conﬁgure EPICS base for your site, you may want to modify the default deﬁnitions in the following ﬁles:

4.3.1.2 Host conﬁguration

To conﬁgure each host system for your site, you may override the default deﬁnitions in the configure/os directory by adding a new ﬁle with override deﬁnitions. The new ﬁle should have the same name as the distribution ﬁle to be overridden except CONFIG in the name is changed to CONFIG_SITE.

4.3.1.3 Target conﬁguration

To conﬁgure each target system, you may override the default deﬁnitions in the configure/os directory by adding a new ﬁle with override deﬁnitions. The new ﬁle should have the same name as the distribution ﬁle to be overridden except CONFIG in the name is replaced by CONFIG_SITE.

4.3.1.4 R3.13 compatibility conﬁguration

To conﬁgure EPICS base for building with R3.13 extensions and ioc applications, you must modify the default deﬁnitions in the base/conﬁg/CONFIG_SITE* ﬁles to agree with site deﬁnitions you made in base/conﬁgure and base/conﬁgure/os ﬁles.You must also modify the following tow macros in the base/conﬁgure/CONFIG_SITE ﬁle:

4.3.2 Directory deﬁnitions

The conﬁgure ﬁles contain deﬁnitions for locations in which to install various components. These are all relative to INSTALL_LOCATION. The default value for INSTALL_LOCATION is $(TOP), and $(T_A) is the current build’s target architecture. The default value for INSTALL_LOCATION can be overridden in the configure/CONFIG_SITE ﬁle.

4.3.3 Extension and Application Speciﬁc Conﬁguration

The base/configure directory contains ﬁles with the default build deﬁnitions and site speciﬁc build deﬁnitions. The extensions/configure directory contains extension speciﬁc build deﬁnitions (e.g. location of X11 and Motif libraries) and “include <filename>” lines for the base/configure ﬁles. Likewise, the <application>/configure directory contains application speciﬁc build deﬁnitions and includes for the application source ﬁles. Build deﬁnitions such as
CROSS_COMPILER_TARGET_ARCHS can be overridden in an extension or application by placing an override deﬁnition in the <top>/configure/CONFIG_SITE ﬁle.

4.3.4 RELEASE ﬁle

Every <top>/configure directory contains a RELEASE ﬁle. RELEASE contains a user speciﬁed list of other <top> directory structures containing ﬁles needed by the current <top>, and may also include other ﬁles to take those deﬁnitions from elsewhere. The macros deﬁned in the RELEASE ﬁle (or its includes) may reference other deﬁned macros, but cannot rely on environment variables to provide deﬁnitions.

When make is executed, macro deﬁnitions for include, bin, and library directories are automatically generated for each external <top> deﬁnition given in the RELEASE ﬁle. Also generated are include statements for any existing RULES_BUILD ﬁles, cfg/RULES* ﬁles, and cfg/CONFIG* ﬁles from each external <top> listed in the RELEASE ﬁle.

RELEASE_DBDFLAGS will appear on the command lines for the dbToRecordTypeH, mkmf.pl, and dbExpand tools, and RELEASE_INCLUDES will appear on compiler command lines. CAMAC_LIB and CAMAC_BIN can be used in a Makeﬁle to deﬁne the location of needed scripts, executables, object ﬁles, libraries or other ﬁles.

Deﬁnitions in conﬁgure/RELEASE can be overridden for a speciﬁc host and target architectures by providing the appropriate ﬁle or ﬁles containing overriding deﬁnitions.

For <top> directory structures created by makeBaseApp.pl, an EPICS base perl script, convertRelease.pl can perform consistency checks for the external <top> deﬁnitions in the RELEASE ﬁle and its includes as part of the <top> level build. Consistancy checks are controlled by value of CHECK_RELEASE which is deﬁned in <top>/conﬁgure/ CONFIG_SITE. CHECK_RELEASE can be set to YES, NO or WARN, and if YES (the default value), consistency checks will be performed. If CHECK_RELEASE is set to WARN the build will continue even if conﬂicts are found.

4.3.5 Modifying conﬁgure/RELEASE* ﬁles

You should always do a gnumake clean uninstall in the <top> directory BEFORE adding, changing, or removing any deﬁnitions in the conﬁgure/RELEASE* ﬁles and then a gnumake at the top level AFTER making the changes.

The ﬁle <top>/configure/RELEASE contains deﬁnitions for components obtained from outside <top>. If you want to link to a new release of anything deﬁned in the ﬁle do the following:

All deﬁnitions in <top>/configure/RELEASE must result in complete path deﬁnitions, i.e. relative path names are not permitted. If your site could have multiple releases of base and other support <top> components installed at once, these path deﬁnitions should contain a release number as one of the components. However as the RELEASE ﬁle is read by gnumake, it is permissible to use macro substitutions to deﬁne these pathnames, for example:

4.3.6 OS Class speciﬁc deﬁnitions

Deﬁnitions in a Makeﬁle will apply to the host system (the platform on which make is executed) and each system deﬁned by CROSS_COMPILER_TARGET_ARCHS.

It is possible to limit the architectures for which a particular deﬁnition is used. Most Makeﬁle deﬁnition names can be speciﬁed with an appended underscore “_” followed by an osclass name. If an _<osclass> is not speciﬁed, then the deﬁnition applies to the host and all CROSS_COMPILER_TARGET_ARCHS systems. If an _<osclass> is speciﬁed, then the deﬁnition applies only to systems with the speciﬁed os class. A Makeﬁle deﬁnition can also have an appended _DEFAULT speciﬁcation. If _DEFAULT is appended, then the Makeﬁle deﬁnition will apply to all systems that do not have an _<osclass> speciﬁcation for that deﬁnition. If a _DEFAULT deﬁnition exists but should not apply to a particular system OS Class, the value “-nil-” should be speciﬁed in the relevant Makeﬁle deﬁnition.

Each system has an OS_CLASS deﬁnition in its configure/os/CONFIG.Common.<arch> ﬁle. A few examples are:

For example the following Makeﬁle lines specify that product aaa should be created for all systems. Product bbb should be created for systems that do not have OS_CLASS deﬁned as solaris.

4.3.7 Specifying T_A speciﬁc deﬁnitions

It is possible for the user to limit the systems for which a particular deﬁnition applies to speciﬁc target systems.

For example the following Makeﬁle lines specify that product aaa should be created for all target architecture which allow IOC type products and product bbb should be created only for the vxWorks-68040 and vxWorks-ppc603 targets. Remember T_A is the build’s current target architecture. so PROD_IOC has the bbb value only when the current built target architecture is vwWorks-68040 or vxWorks-ppc603

4.3.8 Host and Ioc targets

Build creates two type of makeﬁle targets: Host and Ioc. Host targets are executables, object ﬁles, libraries, and scripts which are not part of iocCore. Ioc targets are components of ioc libraries, executables, object ﬁles, or iocsh scripts which will be run on an ioc.

Each supported target system has a VALID_BUILDS deﬁnition which speciﬁes the type of makeﬁle targets it can support. This deﬁnition appears in configure/os/CONFIG.Common.<arch> or configure/os/CONFIG.<arch>.<arch> ﬁles.

In a Makeﬁle it is possible to limit the systems for which a particular PROD, TESTPROD, LIBRARY, SCRIPTS, and OBJS is built. For example the following Makeﬁle lines specify that product aaa should be created for systems that support Host type builds. Product bbb should be created for systems that support Ioc type builds. Product ccc should be created for all target systems.

These deﬁnitions can be further limited by specifying an appended underscore “_” followed by an osclass or DEFAULT speciﬁcation.

4.3.9 User speciﬁc override deﬁnitions

User speciﬁc override deﬁnitions are allowed in user created ﬁles in the user’s <home>/configure subdirectory. These override deﬁnitions will be used for builds in all <top> directory structures. The ﬁles must have the following names.

4.4 Makeﬁles

4.4.1 Name

4.4.2 Included Files

Makeﬁles normally include ﬁles from <top>/configure. Thus the makeﬁle “inherits” rules and deﬁnitions from conﬁgure. The ﬁles in <top>/configure may in turn include ﬁles from another <top>/configure. This technique makes it possible to share make variables and even rules across <top> directories.

4.4.3 Contents of Makeﬁles

4.4.3.1 Makeﬁles in directories containing subdirectories

A Makeﬁle in this type of directory must deﬁne where <top> is relative to this directory, include <top>/configure ﬁles, and specify the subdirectories in the desired order of make execution. Running gnumake in a directory with the following Makeﬁle lines will cause gnumake to be executed in <dir1> ﬁrst and then <dir2>. The build rules do not allow a Makeﬁle to specify both subdirectories and components to be built.

4.4.3.2 Makeﬁles in directories where components are to be built

A Makeﬁle in this type of directory must deﬁne where <top> is relative to this directory, include <top> conﬁgure ﬁles, and specify the target component deﬁnitions. Optionally it may contain user deﬁned rules. Running gnumake in a directory with this type of Makeﬁle will cause gnumake to create an O.<arch> subdirectory and then execute gnumake to build the deﬁned components in this subdirectory. It contains the following lines:

4.4.4 Simple Makeﬁle examples

Create an IOC type library named asIoc from the source ﬁle asDbLib.c and install it into the $(INSTALL_LOCATION)/lib/<arch> directory.

For each Host type target architecture, create an executable named catest from the catest1.c and catest2.c source ﬁles linking with the existing EPICS base ca and Com libraries, and then install the catest executable into the $(INSTALL_LOCATION)/bin/<arch> directory.

4.5 Make

4.5.1 Make vs. gnumake

EPICS provides an extensive set of make rules. These rules only work with the GNU version of make, gnumake, which is supplied by the Free Software Foundation. Thus, on most Unix systems, the native make will not work. On some systems, e.g. Linux, GNU make may be the default. This manual always uses gnumake in the examples.

4.5.2 Frequently used Make commands

NOTE: It is possible to invoke the following commands for a single target architecture by appending <arch> to the target in the command.

4.5.3 Make targets

Note: You can build using your os vendors’ native compiler and also build using a supported alternate compiler in the same directory structure because the executables and libraries will be created and installed into separate directories (e.g bin/solaris-sparc and bin/solaris-sparc-gnu). You can do this by changing your EPICS_HOST_ARCH, environment variable between builds or by setting EPICS_HOST_ARCH on the gnumake command line.

The build system ensures the host architecture is up to date before building a cross-compiled target, thus Makeﬁles must be explicit in deﬁning which architectures a component should be built for.

4.5.4 Header ﬁle dependencies

All product, test product, and library source ﬁles which appear in one of the source ﬁle deﬁnitions (e.g. SRCS, PROD_SRCS, LIB_SRCS, <prodname>_SRCS) will have their header ﬁle dependencies automatically generated and included as part of the Makeﬁle.

4.6 Makeﬁle deﬁnitions

4.6.1 Source ﬁle directories

Normally all product, test product, and library source ﬁles reside in the same directory as the Makeﬁle. OS speciﬁc source ﬁles are allowed and should reside in subdirectories os/<os_class> or os/posix or os/default.

The build rules also allow source ﬁles to reside in subdirectories of the current Makeﬁle directory (src directory). For each subdirectory <dir> containing source ﬁles add the SRC_DIRS deﬁnition.

4.6.2 Posix C source code

The epics base conﬁg ﬁles assume posix source code and deﬁne POSIX to be YES as the default. Individual Makeﬁles can override this by setting POSIX to NO. Source code ﬁles may have the suﬃx .c, .cc, .cpp, or .C.

4.6.3 Breakpoint Tables

For each breakpoint table dbd ﬁle, bpt<table name>.dbd, to be created from an existing bpt<table name>.data ﬁle, add the deﬁnition

to the Makeﬁle. The following Makeﬁle will create a bptTypeJdegC.dbd ﬁle from an existing bptTypeJdegC.data ﬁle using the EPICS base utility program makeBpt and install the new dbd ﬁle into the $(INSTALL_LOCATION)/dbd directory.

4.6.4 Record Type Deﬁnitions

For each new record type, the following deﬁnition should be added to the makeﬁle:

A <rectype>Record.h header ﬁle will be created from an existing <rectype>Record.dbd ﬁle using the EPICS base utility program dbToRecordTypeH. This header will be installed into the $(INSTALL_LOCATION)/include directory and the dbd ﬁle will be installed into the $(INSTALL_LOCATION)/dbd directory.

The following Makeﬁle will create xxxRecord.h from an existing xxxRecord.dbd ﬁle, install xxxRecord.h into $(INSTALL_LOCATION)/include, and install xxxRecord.dbd into $(INSTALL_LOCATION)/dbd.

4.6.5 Menus

The header ﬁle, menu<name>.h will be created from the existing menu<name>.dbd ﬁle using the EPICS base utility program dbToMenuH and installed into the $(INSTALL_LOCATION)/include directory and the menu dbd ﬁle will be installed into $(INSTALL_LOCATION)/dbd.

The following Makeﬁle will create a menuConvert.h ﬁle from an existing menuConvert.dbd ﬁle and install menuConvert.h into $(INSTALL_LOCATION)/include and menuConvert.dbd into $(INSTALL_LOCATION)/dbd.

4.6.6 Expanded Database Deﬁnition Files

Database deﬁnition include ﬁles named <name>Include.dbd containing includes for other database deﬁnition ﬁles can be expanded by the EPICS base utility program dbExpand into a created <name>.dbd ﬁle and the <name>.dbd ﬁle installed into $(INSTALL_LOCATION)/dbd. The following variables control the process:

is the name of the output dbd ﬁle to contain the expanded deﬁnitions. It is created by expanding an existing or build created <name>Include.dbd ﬁle and then copied into $(INSTALL_LOCATION)/dbd.

An example of a ﬁle to be expanded is exampleInclude.dbd containing the following lines

USR_DBDFLAGS deﬁnes optional ﬂags for dbExpand. Currently only an include path (-I <path>) and macro substitution (-S <substitution>) are supported. The include paths for EPICS base/dbd, and other <top>/dbd directories will automatically be added during the build if the <top> names are speciﬁed in the conﬁgure/RELEASE ﬁle.

A database deﬁnition include ﬁle named <name>Include.dbd containing includes for other database deﬁnition ﬁles can be created from a <name>_DBD deﬁnition. The lines

will create an expanded dbd ﬁle <name>.dbd by ﬁrst creating a <name>Include.dbd. For each ﬁlename in the <name>_DBD deﬁnition, the created <name>Include.dbd will contain an include statement for that ﬁlename. Then the expanded DBD ﬁle is generated from the created <name>Include.dbd ﬁle and installed into $(INSTALL_LOCATION)/ dbd.

The following Makeﬁle will create an expanded dbd ﬁle named example.dbd from an existing exampleInclude.dbd ﬁle and then install example.dbd into the $(INSTALL_LOCATION)/dbd directory.

The following Makeﬁle will create an exampleInclude.dbd ﬁle from the example_DBD deﬁnition then expand it to create an expanded dbd ﬁle, example.dbd, and install example.dbd into the $(INSTALL_LOCATION)/dbd directory.

4.6.7 Registering Support Routines for Expanded Database Deﬁnition Files

A source ﬁle which registers simple static variables and record/device/driver support routines with iocsh can be created. The list of variables and routines to register is obtained from lines in an existing dbd ﬁle.

The following line in a Makeﬁle will result in <name>_registerRecordDeviceDriver.cpp being created, compiled, and linked into <prodname>. It requires that the ﬁle <name>.dbd exist or can be created using other make rules.

An example of registering the variable mySubDebug and the routines mySubInit and mySubProcess is <name>.dbd containg the following lines

4.6.8 Database Deﬁnition Files

The following line installs the existing named dbd ﬁles into $(INSTALL_LOCATION)/dbd without expansion.

4.6.9 DBD install ﬁles

result in ﬁles being installed to the $(INSTALL_LOCATION/dbd directory. The ﬁle <name> can appear with or without a directory preﬁx. If the ﬁle has a directory preﬁx e.g. $(APPNAME)/dbd/, it is copied from the speciﬁed location. If a directory preﬁx is not present, make will look in the current source directory for the ﬁle.

4.6.10 Database Files

For most databases just the name of the database has to be speciﬁed. Make will ﬁgure out how to generate the ﬁle:

generates xxx.db depending on which source ﬁles exist and installs it into $(INSTALL_LOCATION)/db.

A <name>.db database ﬁle will be created from an optional <name>.template ﬁle and/or an optional <name>.substitutions ﬁle, If the substitution ﬁle exists but the template ﬁle is not named <name>.template, the template ﬁle name can be speciﬁed as

A ⋆<nn>.db database ﬁle will be created from a *.template and a ⋆<nn>.substitutions ﬁle, (where nn is an optional index number).

If a <name> substitutions ﬁle contains “ﬁle” references to other input ﬁles, these referenced ﬁles are made dependencies of the created <name>.db by the makeDbDepends.pl perl tool.

The Macro Substitutions and Include tool, msi, will be used to generate the database, and msi must either be in your path or you must redeﬁne MSI as the full path name to the msi binary in a RELEASE ﬁle or Makeﬁle. An example MSI deﬁnition is

Template ﬁles <name>.template, and db ﬁles, <name>.db, will be created from an edf ﬁle <name>.edf and an <name>.edf ﬁle will be created from a <name>.sch ﬁle.

generates and installs these ﬁles. If one or more xxx.substitutions ﬁles are to be created by script, the script name must be placed in the CREATESUBSTITUTIONS variable (e.g. CREATESUBSTITUTIONS=mySubst.pl). This script will be executed by gnumake with the preﬁx of the substitution ﬁle name to be generated as its argument. If (and only if) there are script generated substitutions ﬁles, the preﬁx of any inﬂated database’s name may not equal the preﬁx of the name of any template used within the directory.

4.6.11 DB install ﬁles

result in ﬁles being installed to the $(INSTALL_LOCATION/db directory. The ﬁle <name> can appear with or without a directory preﬁx. If the ﬁle has a directory preﬁx e.g. $(APPNAME)/db/, it is copied from the speciﬁed location. If a directory preﬁx is not present, make will look in the current source directory for the ﬁle.

4.6.12 Compile and link command options

4.6.12.1 Options for all compile/link commands.

4.6.12.2 Options for a target speciﬁc compile/link command.

4.6.13 Libraries

A library is created and installed into $(INSTALL_LOCATION)/lib/<arch> by specifying its name and the name of the object and/or source ﬁles containing code for the library. An object or source ﬁle name can appear with or without a directory preﬁx. If the ﬁle name has a directory preﬁx e.g. $(EPICS_BASE_BIN), it is taken from the speciﬁed location. If a directory preﬁx is not present, make will ﬁrst look in the source directories for a ﬁle with the speciﬁed name and next try to create the ﬁle using existing conﬁgure rules. A library ﬁlename preﬁx may be prepended to the library name when the ﬁle is created. For Unix type systems and vxWorks the library preﬁx is lib and there is no preﬁx for WIN32. Also a library suﬃx appropriate for the library type and target arch (e.g. .a, .so, .lib, .dll) will be appended to the ﬁlename when the ﬁle is created.

Shared libraries Note: Shared libraries can be built for any or all HOST type architectures. The deﬁnition of SHARED_LIBRARIES (YES/NO) in base/conﬁgure/CONFIG_SITE determines whether shared or archive libraries will be built. When SHARED_LIBRARIES is YES, both archive and shared libraries are built. This deﬁnition can be overridden for a speciﬁc arch in an configure/os/CONFIG_SITE.<arch>.Common ﬁle.,The default deﬁnition for SHARED_LIBRARIES in the EPICS base distribution ﬁle is YES for all host systems.

win32 Note: An object library ﬁle is created when SHARED_LIBRARIES=NO, <name>.lib which is installed into $(INSTALL_LOCATION)/lib/<arch>. Two library ﬁles are created when SHARED_LIBRARIES=YES, <name>.lib, an import library for DLLs, which is installed into $(INSTALL_LOCATION)/lib/<arch>, and <name>.dll which is installed into $(INSTALL_LOCATION)/bin/<arch>. (Warning: The ﬁle <name>.lib will only be created by the build if there are exported symbols from the library.) If SHARED_LIBRARIES=YES, the directory
$(INSTALL_LOCATION)/bin/<arch> must be in the user’s path during builds to allow invoking executables which were linked with shared libraries. NOTE: the <name>.lib ﬁles are diﬀerent for shared and nonshared builds.

4.6.13.1 Specifying the library name.

4.6.13.2 Specifying library source ﬁle names

LIBSRCS and LIB_SRCS have the same meaning. LIBSRCS is deprecated, but retained for R3.13 compatibility.

4.6.13.3 Specifying library object ﬁle names

Library object ﬁle names should only be speciﬁed for object ﬁles which will not be built in the current directory. For object ﬁles built in the current directory, library source ﬁle names should be speciﬁed. See Specifying Library Source File Names above.

Object ﬁles which have ﬁlename with a “.o” or “.obj” suﬃx are deﬁned as follows and can be speciﬁed without the suﬃx but should have the directory preﬁx

Combined object ﬁles, from R3.13 built modules and applications which have ﬁle names that do not include a “.o” or ”.obj” suﬃx (e.g. xyzLib) are deﬁned as follows:

4.6.13.4 LIBOBJS deﬁnitions

4.6.13.5 Specifying dependant libraries to be linked when creating a library

For each library name speciﬁed which is not a system library nor a library from an EPICS top deﬁned in the conﬁgure/ RELEASE ﬁle, a <name>_DIR deﬁnition must be present in the Makeﬁle to specify the location of the library.

Library names, which must not have a directory and “lib” preﬁx nor a suﬃx, are deﬁned as follows:

4.6.13.6 The order of dependant libraries

4.6.13.7 Specifying library DLL ﬁle names (deprecated)

WIN32 libraries require all external references to be resolved, so if a library contains references to items in other DLL libraries, these DLL library names must be speciﬁed (without directory preﬁx and without “.dll” suﬃx) as follows:

4.6.13.8 Specifying shared library version number

A library version number can be speciﬁed when creating a shared library as follows:

On WIN32 this results in /version:$(SHRLIB_VERSION) link option. On Unix type hosts .$(SHRLIB_VERSION) is appended to the shared library name and a symbolic link is created for the unversioned library name.
$(EPICS_VERSION).$(EPICS_REVISION) is the default value for SHRLIB_VERSION.

4.6.13.9 Library example:

If the architectures deﬁned in <top>/configure are solaris-sparc and vxWorks-68040 and LINAC is deﬁned in the <top>/configure/RELEASE ﬁle, then the following libraries will be created:

4.6.14 Loadable libraries

Loadable libraries are regular libraries which are not required to have all symbols resolved during the build. The intent is to create dynamic plugins so no archive library is created. Source ﬁle, object ﬁles, and dependant libraries are speciﬁed in exactly the same way as for regular libraries.

4.6.15 Combined object libraries (VxWorks only)

Combined object libraries are regular combined object ﬁles which have been created by linking together multiple object ﬁles. OBJLIB speciﬁcations in the Makeﬁle create a combined object ﬁle and a corresponding munch ﬁle for vxWorks target architectures only. Combined object libraries have a Library.o suﬃx. It is possible to generate and install combined object libraries by using deﬁnitions:

These deﬁnitions result in the combined object ﬁle <name>Library.o and its corresponding <name>Library.munch munch ﬁle being built for each vxWorks architecture from source/object ﬁles in the OBJLIB_SRCS/OBJLIB_OBJS deﬁnitions. The combined object ﬁle and the munch ﬁle are installed into the $(INSTALL_LOCATION)/bin/<arch> directory.

4.6.16 Object Files

These will cause the speciﬁed ﬁle to be generated from an existing source ﬁle for the appropriate target arch and installed into $(INSTALL_LOCATION)/bin/<arch>.

The following Makeﬁle will create the abc object ﬁle for all target architectures, the def object ﬁle for all target archs except vxWorks, and the xyz object ﬁle only for the vxWorks target architecture and install them into the appropriate $(INSTALL_LOCATION)/bin/<arch> directory.

4.6.17 State Notation Programs

A state notation program ﬁle can be speciﬁed as a source ﬁle in any SRC deﬁnition. For example:

The state notation compiler snc will generate the ﬁle <name>.c from the state notation program ﬁle <name>.stt. This C ﬁle is compiled and the resulting object ﬁle is linked into the <prodname> product.

A state notation source ﬁle must have the extension .st or .stt. The .st ﬁle is passed through the C preprocessor before it is processed by snc.

If you have state notation language source ﬁles (.stt and .st ﬁles), the module seq must be built and SNCSEQ deﬁned in the RELEASE ﬁle. If the state notation language source ﬁles require c preprocessing before conversion to c source (.st ﬁles), gcc must be in your path.

4.6.18 Scripts, etc.

results in the <name1> script being installed from the src directory to the $(INSTALL_LOCATION)/bin/<arch> directories for all target archs of the speciﬁed os class <osclass> and the <name2> script installed into the $(INSTALL_LOCATION)/bin/<arch> directories of all other target archs.

4.6.19 Include ﬁles

results in ﬁle <name>.h being installed or created and installed to the $(INSTALL_LOCATION)/include directory.

results in ﬁle <name>.h being installed or created and installed into the appropriate $(INSTALL_LOCATION)/include/os/<osclass> directory.

4.6.20 Html and Doc ﬁles

results in ﬁle <name> being installed from the src directory to the $(INSTALL_LOCATION)/html/<dirname> directory.

results in ﬁle <name> being installed from the src directory to the $(INSTALL_LOCATION)/doc directory.

4.6.21 Templates

results in the ﬁle <name> being installed from the src directory to the $(INSTALL_LOCATION)/templates/<dirname> directory. If a directory structure of template ﬁles is to be installed, the template ﬁle names may include a directory preﬁx.

4.6.22 Lex and yac

If a <name>.c source ﬁle speciﬁed in a Makeﬁle deﬁnition is not found in the source directory, gnumake will try to build it from <name>.y and <name>_lex.l ﬁles in the source directory. Lex converts a <name>.l Lex code ﬁle to a lex.yy.c ﬁle which the build rules renames to <name>.c. Yacc converts a <name>.y yacc code ﬁle to a y.tab.c ﬁle, which the build rules renames to <name>.c. Optionally yacc can create a y.tab.h ﬁle which the build rules renames to <name>.h.

4.6.23 Products

A product executable is created for each <arch> and installed into $(INSTALL_LOCATION)/bin/<arch> by specifying its name and the name of either the object or source ﬁles containing code for the product. An object or source ﬁle name can appear with or without a directory preﬁx. Object ﬁles should contain a directory preﬁx. If the ﬁle has a directory preﬁx e.g. $(EPICS_BASE_BIN), the ﬁle is taken from the speciﬁed location. If a directory preﬁx is not present, make will look in the source directories for a ﬁle with the speciﬁed name or try build it using existing rules. An executable ﬁlename suﬃx appropriate for the target arch (e.g. .exe) may be appended to the ﬁlename when the ﬁle is created.

PROD speciﬁcations in the Makeﬁle for vxWorks target architectures create a combined object ﬁle with library references resolved and a corresponding .munch ﬁle.

results in the executable <name> being built for each HOST architecture, <arch>, from a <srcname>.c ﬁle. Then <name> is installed into the $(INSTALL_LOCATION)/bin/<arch> directory.

4.6.23.1 Specifying the product name.

4.6.23.2 Specifying product object ﬁle names

Object ﬁles which have ﬁlenames with a “.o” or “.obj” suﬃx are deﬁned as follows and can be speciﬁed without the suﬃx but should have the directory preﬁx

4.6.23.3 Specifying product source ﬁle names

4.6.23.4 Specifying libraries to be linked when creating the product

For each library name speciﬁed which is not a system library nor a library from EPICS_BASE, a <name>_DIR deﬁnition must be present in the Makeﬁle to specify the location of the library.

Library names, which must not have a directory and “lib” preﬁx nor a suﬃx, are deﬁned as follows:

4.6.23.5 The order of dependant libraries

4.6.23.6 Specifying product version number

4.6.23.7 Product static builds

Product executables can be linked with either archive versions or shared versions of EPICS libraries. Shared versions of system libraries will always be used in product linking. The deﬁnition of STATIC_BUILD (YES/NO) in base/conﬁgure/ CONFIG_SITE determines which EPICS libraries to use. When STATIC_BUILD is NO, shared libraries will be used. (SHARED_LIBRARIES must be set to YES.) The default deﬁnition for STATIC_BUILD in the EPICS base CONFIG_SITE distribution ﬁle is NO. A STATIC_BUILD deﬁnition in a Makeﬁle will override the deﬁnition in CONFIG_SITE.Static builds may not be possible on all systems. For static builds, all nonsystem libraries must have an archive version, and this may not be true form all libraries.

4.6.24 Test Products

Test products are product executables that are created but not installed into $(INSTALL_LOCATION)/bin/<arch> directories. Test product libraries, source, and object ﬁles are speciﬁed in exactly the same way as regular products.

4.6.25 Test Scripts

Test scripts are perl scripts whose names end in .t that get executed to satisfy the runtests make target. They are run by the perl Test::Harness library, and should send output to stdout following the Test Anything Protocol. Any of the following can be speciﬁed, although only TESTSCRIPTS_HOST is currently useful:

If a name in one of the above variables matches a regular executable program name (normally generated as a test product) with “.t” appended, a suitable perl script will be generated that will execute that program directly; this makes it simple to run programs that use the epicsUnitTest routines in libCom. A test script written in Perl with a name ending .plt will be copied into the O.<arch> directory with the ending changed to .t; such scripts will usually use the perl Test::Simple or Test::More libraries.

4.6.26 Miscellaneous Targets

results in the ﬁle <name> being built in the O.<arch> directory from existing rules and ﬁles in the source directory. These target ﬁles are not installed.

4.6.27 Installing Other Binaries

will result in the named ﬁles being installed to the appropriate $(INSTALL_LOCATION)/bin/<arch> directory. The ﬁle <name> can appear with or without a directory preﬁx. If the ﬁle has a directory preﬁx e.g. $(EPICS_BASE_BIN), it is copied from the speciﬁed location. If a directory preﬁx is not present, make will look in the source directory for the ﬁle.

4.6.28 Installing Other Libraries

result in ﬁles being installed to the appropriate $(INSTALL_LOCATION)/lib/<arch> directory. The ﬁle <name> can appear with or without a directory preﬁx. If the ﬁle has a directory preﬁx e.g. $(EPICS_BASE_LIB), it is copied from the speciﬁed location. If a directory preﬁx is not present, make will look in the source directory for the ﬁle.

4.6.29 Win32 resource ﬁles

RCS += <name> Resource deﬁnition script ﬁles for all products and libraries.
RCS_<osclass> += <name>

PROD_RCS += <name> Resource deﬁnition script ﬁles for all products.
PROD_RCS_<osclass> += <name>
PROD_RCS_DEFAULT += <name>

LIB_RCS += <name> Resource deﬁnition script ﬁles for all libraries.
LIB_RCS_<osclass> += <name>
LIB_RCS_DEFAULT += <name>

<name>_RCS += <name> Resource deﬁnition script ﬁles for speciﬁed product or library.
<name>_RCS_<osclass> += <name>
<name>_RCS_DEFAULT += <name>

result in resource ﬁles (*.res ﬁles) being created from the speciﬁed *.rc resource deﬁnition script ﬁles and linked into the prods and/or libraries.

4.6.30 TCL libraries

result in the speciﬁed tcl ﬁles being installed to the $(INSTALL_LOCATION)/lib/<arch> directory.

4.6.31 Java class ﬁles

Java class ﬁles can be created by the javac tool into $(INSTALL_JAVA) or into the O.Common subdirectory, by specifying the name of the java class ﬁle in the Makeﬁle. Command line options for the javac tool can be speciﬁed. The conﬁguration ﬁles set the java c option “-sourcepath .:..:../..”.

4.6.31.1 Example 1

In this example, three class ﬁles are created in $(INSTALL_LOCATION)/javalib/mytest. The javac depreciation ﬂag is used to list the description of each use or override of a deprecated member or class.

4.6.31.2 Example 2

4.6.32 Java jar ﬁle

A single java jar ﬁle can be created using the java jar tool and installed into $(INSTALL_JAVA)
(i.e. $(INSTALL_LOCATION)/javalib) by specifying its name, and the names of its input ﬁles to be included in the created jar ﬁle. The jar input ﬁle names must appear with a directory preﬁx.

4.6.32.1 Example 1

In this example, all the class ﬁles created by the current Makeﬁle’s “JAVA+=” deﬁnitions, are placed into a ﬁle named mytest1.jar. A manifest ﬁle will be automatically generated for the jar.

Note: $(INSTALL_CLASSES) is set to $(addpreﬁx $(INSTALL_JAVA)/,$(CLASSES)) in the EPICS base conﬁgure ﬁles.

4.6.32.2 Example 2

In this example, three class ﬁles are created and placed into a new jar archive ﬁle named mytest2.jar. An existing manifest ﬁle, mytest2.mf is put into the new jar ﬁle.

4.6.33 Java native method C header ﬁles

A C header ﬁles for use with java native methods will be created by the javah tool in the O.Common subdirectory by specifying the name of the header ﬁle to be created. The name of the java class ﬁle used to generate the header is derived from the name of the header ﬁle. Underscores (_) are used as a header ﬁle name delimiter. Command line options for the javah tool can be speciﬁed.

4.6.33.1 Example

In this example, the C header xx_yy_zz.h will be created in the $(COMMON_DIR) subdirectory from the class xx.yy.zz (i.e. the java class ﬁle $(INSTALL_JAVA)/xx/yy/zz.class)). The option “-old” will tell javah to create old JDK1.0 style header ﬁles.

4.6.34 User Created CONFIG* and RULES* ﬁles

Module developers can now create new CONFIG and RULES* ﬁles ia a <top> application source directory. These new CONFIG* or RULES* ﬁles will be installed into the directory $(INSTALL_LOCATION)/cfg by including lines like the following Makeﬁle line:

The build will install the new ﬁles CONFIG_MY1 and RULES_MY1 into the $(INSTALL_LOCATION)/cfg directory.

Files in a $(INSTALL_LOCATION)/cfg directory are now included during a build by so that the deﬁnitions and rules in them are available for use by later src directory Makeﬁles in the same module or by other modules with a RELEASE line pointing to the TOP of this module.

4.6.35 User Created File Types

Module developers can now deﬁne a new type of ﬁle, e.g. ABC, so that ﬁles of type ABC will be installed into a directory deﬁned by INSTALL_ABC. This is done by creating a new CONFIG_<name> ﬁle, e.g. CONFIG_ABC, with the following lines:

The INSTALL_ABC directory should be a subdirectory of $(INSTALL_LOCATION). The ﬁle type ABC should be target architecture independent (alh ﬁles, medm ﬁles, edm ﬁles.

Optional rules necessary for ﬁles of type ABC should be put in a RULES_ABC ﬁle.

The module developer installs new CONFIG_ABC and RULES_ABC ﬁles for the new ﬁle type into the directory $(INSTALL_LOCATION)/cfg by including the following Makeﬁle line:

Files of type ABC are installed into INSTALL_ABC directory by adding a line like the following to a Makeﬁle.

Since the ﬁles in $(INSTALL_LOCATION)/cfg directory are now included by the base conﬁg ﬁles, the ABC += deﬁnition lines are available for use by later src directory Makeﬁles in the same module or by other modules with a RELEASE line pointing to the TOP of this module.

4.6.36 Assemblies

A single output ﬁle is generated from assembling speciﬁed snippet ﬁles. Snippet ﬁle names start with numbers and are sorted when the snippets are concatenated: ﬁrst by the number, then alphabetical by the remaining part of the name. (This mechanism is conceptually similar to the Linux convention of collecting conﬁguration ﬁle snippets in *.d directories.)

Snippets with ﬁle names not starting with a number or ending in ’~’ are ignored. The speciﬁed snippets are processed in the order they appear on the command line. Multiple snippets with the same number are concatenated. ”Commands” (tags in the snippet name) can be used to control the treatment of snippets with the same number:

Speciﬁcation of the target ﬁle is diﬀerent for architecture dependent or independent ﬁles.

Snippet ﬁles are conﬁgured speciﬁcally (relative or absolute path) or as patterns (searched relative to all source directories).

4.6.36.1 Macros

The following macros can be used in snippets, and will be replaced by the current value when assembling is done.

4.6.36.2 Example

This mechanism can be used to create an IOC startup ﬁle from snippets in a global and an application speciﬁc directory, allowing applications to add commands to diﬀerent phases of the IOC startup by dropping appropriately numbered snippets into the directory.

4.7 Table of Makeﬁle deﬁnitions

Deﬁnitions given below containing <osclass> are used when building for target archs of a speciﬁc osclass, and the <osclass> part of the name should be replaced by the desired osclass, e.g. solaris, vxWorks, etc. If a _DEFAULT setting is given but a particular <osclass> requires that the default not apply and there are no items in the deﬁnition that apply for that <osclass>, the value “-nil-” should be speciﬁed in the relevant Makeﬁle deﬁnition.

Build Option	Description

Products to be built (host type archs only)

PROD	products (names without execution suﬃx) to build and install. Specify xyz to build executable xyz on Unix and xyz.exe on WIN32
PROD_<osclass>	os class speciﬁc products to build and install for <osclass> archs only
PROD_DEFAULT	products to build and install for archs with no PROD_<osclass> speciﬁed
PROD_IOC	products to build and install for ioc type archs
PROD_IOC_<osclass>	os speciﬁc products to build and install for ioc type archs
PROD_IOC_DEFAULT	products to build and install for ioc type arch systems with no PROD_IOC_<osclass> speciﬁed
PROD_HOST	products to build and install for host type archs.
PROD_HOST_<osclass>	os class speciﬁc products to build and install for <osclass> type archs
PROD_HOST_DEFAULT	products to build and install for arch with no PROD_HOST_<osclass> speciﬁed
Test products to be built

TESTPROD	test products (names without execution suﬃx) to build but not install
TESTPROD_<osclass>	os class speciﬁc test products to build but not install
TESTPROD_DEFAULT	test products to build but not install for archs with no TESTPROD_<osclass> speciﬁed
TESTPROD_IOC	test products to build and install for ioc type archs
TESTPROD_IOC_<osclass>	os speciﬁc test products to build and install for ioc type archs
TESTPROD_IOC_DEFAULT	test products to build and install for ioc type arch systems with no TESTPROD_IOC_<osclass> speciﬁed
TESTPROD_HOST	testproducts to build and install for host type archs.
TESTPROD_HOST_<osclass>	os class speciﬁc testproducts to build and install for <osclass> type archs

TESTPROD_HOST_DEFAULT	test products to build and install for arch with no TESTPROD_HOST_<osclass> speciﬁed
Test scripts to be built

TESTSCRIPTS	test scripts (names with .t suﬃx) to build but not install
TESTSCRIPTS_<osclass>	os class speciﬁc test scripts to build but not install
TESTSCRIPTS_DEFAULT	test scripts to build but not install for archs with no TESTSCRIPTS_<osclass> speciﬁed
TESTSCRIPTS_IOC	test scripts to build and install for ioc type archs
TESTSCRIPTS_IOC_<osclass>	os speciﬁc test scripts to build and install for ioc type archs
TESTSCRIPTS_IOC_DEFAULT	test scripts to build and install for ioc type arch systems with no TESTSCRIPTS_IOC_<osclass> speciﬁed
TESTSCRIPTS_HOST	test scripts to build and install for host type archs.
TESTSCRIPTS_HOST_<osclass>	os class speciﬁc testscripts to build and install for <osclass> type archs
TESTSCRIPTS_HOST_DEFAULT	test scripts to build and install for arch with no TESTSCRIPTS_HOST_<osclass> speciﬁed
Libraries to be built

LIBRARY	name of library to build and install. The name should NOT include a preﬁx or extension e.g. specify Ca to build libCa.a on Unix, Ca.lib or Ca.dll on WIN32
LIBRARY_<osclass>	os speciﬁc libraries to build and install
LIBRARY_DEFAULT	libraries to build and install for archs with no LIBRARY_<osclass> speciﬁed
LIBRARY_IOC	name of library to build and install for ioc type archs. The name should NOT include a preﬁx or extension e.g. specify Ca to build libCa.a on Unix, Ca.lib or Ca.dll on WIN32
LIBRARY_IOC_<osclass>	os speciﬁc libraries to build and install for ioc type archs
LIBRARY_IOC_DEFAULT	libraries to build and install for ioc type arch systems with no LIBRARY_IOC_<osclass> speciﬁed
LIBRARY_HOST	name of library to build and install for host type archs. The name should NOT include a preﬁx or extension, e.g. specify Ca to build libCa.a on Unix, Ca.lib or Ca.dll on WIN32
LIBRARY_HOST_<osclass>	os class speciﬁc libraries to build and install for host type archs

LIBRARY_HOST_DEFAULT	libraries to build and install for host type arch systems with no LIBRARY_HOST_<osclass> speciﬁed
SHARED_LIBRARIES	build shared libraries? Must be YES or NO
SHRLIB_VERSION	shared library version number
Loadable libraries to be built

LOADABLE_LIBRARY	name of loadable library to build and install. The name should NOT include a preﬁx or extension e.g. specify Ca to build libCa.so on Unix and Ca.dll on WIN32
LOADABLE_LIBRARY_<osclass>	os speciﬁc loadable libraries to build and install
LOADABLE_LIBRARY_DEFAULT	loadable libraries to build and install for archs with no LOADABLE_LIBRARY_<osclass> speciﬁed
LOADABLE_LIBRARY_HOST	name of loadable library to build and install for host type archs. The name should NOT include a preﬁx or extension, e.g. specify test to build libtest.so on Unix and test.dll on WIN32
LOADABLE_LIBRARY_HOST_<osclass>	os class speciﬁc loadable libraries to build and install for host type archs
LOADABLE_LIBRARY_HOST_DEFAULT	loadable libraries to build and install for host type arch systems with no LOADABLE_LIBRARY_HOST_<osclass> speciﬁed
Combined object ﬁles (vxWorks only)

OBJLIB	name of a combined object ﬁle library and corresponding munch ﬁle to build and install. The name will have a Library suﬃx appended
OBJLIB_vxWorks	same as OBJLIB
OBJLIB_SRCS	source ﬁles to build the OBJLIB
OBJLIB_OBJS	object ﬁles to include in OBJLIB
Product and library source ﬁles

SRCS	source ﬁles to build all PRODs and LIBRARYs
SRCS_<osclass>	osclass speciﬁc source ﬁles to build all PRODs and LIBRARYs
SRCS_DEFAULT	source ﬁle to build all PRODs and LIBRARYs for archs with no SRCS_<osclass> speciﬁed
USR_SRCS	source ﬁles to build all PRODs and LIBRARYs

USR_SRCS_<osclass>	osclass speciﬁc source ﬁles to build all PRODs and LIBRARYs
USR_SRCS_DEFAULT	source ﬁle to build all PRODs and LIBRARYs for archs with no SRCS_<osclass> speciﬁed
PROD_SRCS	source ﬁles to build all PRODs
PROD_SRCS_<osclass>	osclass speciﬁc source ﬁles to build all PRODs
PROD_SRCS_DEFAULT	source ﬁles needed to build PRODs for archs with no SRCS_<osclass> speciﬁed
LIB_SRCS	source ﬁles for building LIBRARY (e.g. LIB_SRCS=la.c lb.c lc.c)
LIB_SRCS_<osclass>	os-speciﬁc library source ﬁles
LIB_SRCS_DEFAULT	library source ﬁles for archs with no LIB_SRCS_<osclass> speciﬁed
LIBSRCS	source ﬁles for building LIBRARY (deprecated)
LIBSRCS_<osclass>	os-speciﬁc library source ﬁles (deprecated)
LIBSRCS_DEFAULT	library source ﬁles for archs with no LIBSRCS_<osclass> speciﬁed (deprecated)
<name>_SRCS	source ﬁles to build a speciﬁc PROD or LIBRARY
<name>_SRCS_<osclass>	os speciﬁc source ﬁles to build a speciﬁc PROD or LIBRARY
<name>_SRCS_DEFAULT	source ﬁles needed to build a speciﬁc PROD or LIBRARY for archs with no <prod>_SRCS_<osclass> speciﬁed
Product and library object ﬁles

USR_OBJS	object ﬁles, speciﬁed without suﬃx, to build all PRODs and LIBRARYs
USR_OBJS_<osclass>	osclass speciﬁc object ﬁles, speciﬁed without suﬃx, to build all PRODs and LIBRARYs
USR_OBJS_DEFAULT	object ﬁles, speciﬁed without suﬃx, needed to build PRODs and LIBRARYs for archs with no OBJS_<osclass> speciﬁed
PROD_OBJS	object ﬁles, speciﬁed without suﬃx, to build all PRODs
PROD_OBJS_<osclass>	osclass speciﬁc object ﬁles, speciﬁed without suﬃx, to build all PRODs

PROD_OBJS_DEFAULT	object ﬁles, speciﬁed without suﬃx, needed to build PRODs for archs with no OBJS_<osclass> speciﬁed
LIB_OBJS	object ﬁles, speciﬁed without suﬃx, for building all LIBRARYs (e.g. LIB_OBJS+=$(AB_BIN)/la $(AB_BIN)/lb)
LIB_OBJS_<osclass>	os-speciﬁc library object ﬁles, specify without suﬃx,
LIB_OBJS_DEFAULT	library object ﬁles, speciﬁed without suﬃx, for archs with no LIB_OBJS_<osclass> speciﬁed
<name>_OBJS	object ﬁles, speciﬁed without suﬃx, to build a speciﬁc PROD or LIBRARY
<name>_OBJS_<osclass>	os speciﬁc object ﬁles, speciﬁed without suﬃx, to build a speciﬁc PROD or LI\|BRARY
<name>_OBJS_DEFAULT	object ﬁles, without suﬃx, needed to build a speciﬁc PROD or LIBRARY for archs with no <prod>_OBJS_<osclass> speciﬁed
Product and library R3.13 combined object ﬁles

USR_OBJLIBS	combined object ﬁles with ﬁlenames that do not have a suﬃx, needed for building all PRODs and LIBRARYs (e.g. USR_OBJLIBS+=$(XYZ_BIN)/xyzLib)
USR_OBJLIBS_<osclass>	os-speciﬁc combined object ﬁles with ﬁlenames that do not have a suﬃx for building all PRODs and LIBRARYs
USR_OBJLIBS_DEFAULT	combined object ﬁles with ﬁlenames that do not have a suﬃx, for archs with no USR_OBJLIBS_<osclass> speciﬁed for building all PRODs and LIBRARYs
PROD_OBJLIBS	combined object ﬁles with ﬁlenames that do not have a suﬃx, needed for building all PRODs (e.g. PROD_OBJLIBS+=$(XYZ_BIN)/xyzLib)
PROD_OBJLIBS_<osclass>	os-speciﬁc combined object ﬁles with ﬁlenames that do not have a suﬃx for building all PRODs
PROD_OBJLIBS_DEFAULT	combined object ﬁles with ﬁlenames that do not have a suﬃx, for archs with no PROD_OBJLIBS_<osclass> speciﬁed for building all PRODs
LIB_OBJLIBS	combined object ﬁles with ﬁlenames that do not have a suﬃx, needed for building all LIBRARYs (e.g. LIB_OBJLIBS+=$(XYZ_BIN)/xyzLib)
LIB_OBJLIBS_<osclass>	os-speciﬁc combined object ﬁles with ﬁlenames that do not have a suﬃx for building all LIBRARYs
LIB_OBJLIBS_DEFAULT	combined object ﬁles with ﬁlenames that do not have a suﬃx, for archs with no LIB_OBJLIBS_<osclass> speciﬁed for building all LIBRARYs
<name>_OBJLIBS	combined object ﬁles with ﬁlenames that do not have a suﬃx, needed to build a speciﬁc PROD or LIBRARY
<name>_OBJLIBS_<osclass>	os speciﬁc combined object ﬁles with ﬁlenames that do not have a suﬃx, to build a speciﬁc PROD or LI\|BRARY
<name>_OBJLIBS_DEFAULT	combined object ﬁles with ﬁlenames that do not have a suﬃx, needed to build a speciﬁc PROD or LIBRARY for archs with no <name>_OBJLIBS_<osclass> speciﬁed

<name>_LDOBJS	combined object ﬁles with ﬁlenames that do not have a suﬃx, needed to build a speciﬁc PROD or LIBRARY (deprecated)
<name>_LDOBJS_<osclass>	os speciﬁc combined object ﬁles with ﬁlenames that do not have a suﬃx, to build a speciﬁc PROD or LI\|BRARY (deprecated)
<name>_LDOBJS_DEFAULT	combined object ﬁles with ﬁlenames that do not have a suﬃx, needed to build a speciﬁc PROD or LIBRARY for archs with no <name>_LDOBJS_<osclass> speciﬁed (deprecated)
Product and library dependant libraries

<name>_DIR	directory to search for the speciﬁed lib. (For libs listed in all PROD_LIBS, LIB_LIBS, <name>_LIBS and USR_LIBS listed below)System libraries do not need a <name>_dir deﬁnition.
USR_LIBS	load libraries (e.g. Xt X11) for all products and libraries
USR_LIBS_<osclass>	os speciﬁc load libraries for all makeﬁle links
USR_LIBS_DEFAULT	load libraries for systems with no USR_LIBS_<osclass> speciﬁed libs
<name>_LIBS	named prod or library speciﬁc ld libraries (e.g. probe_LIBS=X11 Xt)
<name>_LIBS_<osclass>	os-speciﬁc libs needed to link named prod or library
<name>_LIBS_DEFAULT	libs needed to link named prod or library for systems with no <name>_LIBS_<osclass> speciﬁed
PROD_LIBS	libs needed to link every PROD
PROD_LIBS_<osclass>	os-speciﬁc libs needed to link every PROD
PROD_LIBS_DEFAULT	libs needed to link every PROD for archs with no PROD_LIBS_<osclass> speciﬁed
LIB_LIBS	libraries to be linked with every library being created
LIB_LIBS_<osclass>	os class speciﬁc libraries to be linked with every library being created
LIB_LIBS_DEFAULT	libraries to be linked with every library being created for archs with no LIB_LIBS_<osclass> speciﬁed
USR_SYS_LIBS	system libraries (e.g. Xt X11) for all products and libraries
USR_SYS_LIBS_<osclass>	os class speciﬁc system libraries for all makeﬁle links
USR_SYS_LIBS_DEFAULT	system libraries for archs with no USR_SYS_LIBS_<osclass> speciﬁed

<name>_SYS_LIBS	named prod or library speciﬁc system ld libraries
<name>_SYS_LIBS_<osclass>	os class speciﬁc system libs needed to link named prod or library
<name>_SYS_LIBS_DEFAULT	system libs needed to link named prod or library for systems with no <name>_SYS_LIBS_<osclass> speciﬁed
PROD_SYS_LIBS	system libs needed to link every PROD
PROD_SYS_LIBS_<osclass>	os class speciﬁc system libs needed to link every PROD
PROD_SYS_LIBS_DEFAULT	system libs needed to link every PROD for archs with no PROD_SYS_LIBS_<osclass> speciﬁed
LIB_SYS_LIBS	system libraries to be linked with every library being created
LIB_SYS_LIBS_<osclass>	os class speciﬁc system libraries to be linked with every library being created
LIB_SYS_LIBS_DEFAULT	system libraries to be linked with every library being created for archs with no LIB_SYS_LIBS_<osclass> speciﬁed
SYS_PROD_LIBS	system libs needed to link every PROD for all systems (deprecated)
SYS_PROD_LIBS_<osclass>	os class speciﬁc system libs needed to link every PROD (deprecated)
SYS_PROD_LIBS_DEFAULT	system libs needed to link every PROD for systems with no SYS_PROD_LIBS_<osclass> speciﬁed (deprecated)
Compiler ﬂags

USR_CFLAGS	C compiler ﬂags for all systems
USR_CFLAGS_<T_A>	target architecture speciﬁc C compiler ﬂags
USR_CFLAGS_<osclass>	os class speciﬁc C compiler ﬂags
USR_CFLAGS_DEFAULT	C compiler ﬂags for archs with no USR_CFLAGS_<osclass> speciﬁed
<name>_CFLAGS	ﬁle speciﬁc C compiler ﬂags (e.g. xxxRecord_CFLAGS=-g)
<name>_CFLAGS_<T_A>	ﬁle speciﬁc C compiler ﬂags for a speciﬁc target architecture
<name>_CFLAGS_<osclass>	ﬁle speciﬁc C compiler ﬂags for a speciﬁc os class

USR_CXXFLAGS	C++ compiler ﬂags for all systems (e.g. xyxMain_CFLAGS=-DSDDS)
USR_CXXFLAGS_<T_A>	target architecture speciﬁc C++ compiler ﬂags
USR_CXXFLAGS_<osclass>	os-speciﬁc C++ compiler ﬂags
USR_CXXFLAGS_DEFAULT	C++ compiler ﬂags for systems with no USR_CXXFLAGS_<osclass> speciﬁed
<name>_CXXFLAGS	ﬁle speciﬁc C++ compiler ﬂags
<name>_CXXFLAGS_<T_A>	ﬁle speciﬁc C++ compiler ﬂags for a speciﬁc target architecture
<name>_CXXFLAGS_<osclass>	ﬁle speciﬁc C++ compiler ﬂags for a speciﬁc osclass
USR_CPPFLAGS	C pre-processor ﬂags (for all makeﬁle compiles)
USR_CPPFLAGS_<T_A>	target architecture speciﬁc cpp ﬂags
USR_CPPFLAGS_<osclass>	os speciﬁc cpp ﬂags
USR_CPPFLAGS_DEFAULT	cpp ﬂags for systems with no USR_CPPFLAGS_<osclass> speciﬁed
<name>_CPPFLAGS	ﬁle speciﬁc C pre-processor ﬂags(e.g. xxxRecord_CPPFLAGS=-DDEBUG)
<name>_CPPFLAGS_<T_A>	ﬁle speciﬁc cpp ﬂags for a speciﬁc target architecture
<name>_CPPFLAGS_<osclass>	ﬁle speciﬁc cpp ﬂags for a speciﬁc os class
USR_INCLUDES	directories, with -I preﬁx, to search for include ﬁles(e.g. -I$(EPICS_EXTENSIONS_INCLUDE))
USR_INCLUDES_<osclass>	directories, with -I preﬁx, to search for include ﬁles for a speciﬁc os class
USR_INCLUDES_DEFAULT	directories, with -I preﬁx, to search for include ﬁles for systems with no <name>_INCLUDES_<osclass> speciﬁed
<name>_INCLUDES	directories, with -I preﬁx, to search for include ﬁles when building a speciﬁc object ﬁle (e.g. -I$(MOTIF_INC))
<name>_INCLUDES_<T_A>	ﬁle speciﬁc directories, with -I preﬁx, to search for include ﬁles for a speciﬁc target architecture
<name>_INCLUDES_<osclass>	ﬁle speciﬁc directories, with -I preﬁx, to search for include ﬁles for a speciﬁc os class

HOST_WARN	Are compiler warning messages desired for host type builds? (YES or NO) (default is YES)
CROSS_WARN	C cross-compiler warning messages desired (YES or NO) (default YES)
HOST_OPT	Is host build compiler optimization desired (default is NO optimization)
CROSS_OPT	Is cross-compiler optimization desired (YES or NO) (default is NO optimization)
CMPLR	C compiler selection, TRAD, ANSI or STRICT (default is STRICT)
CXXCMPLR	C++ compiler selection, NORMAL or STRICT (default is STRICT)
Linker options

USR_LDFLAGS	linker options (for all makeﬁle links)
USR_LDFLAGS_<osclass>	os speciﬁc linker options (for all makeﬁle links)
USR_LDFLAGS_DEFAULT	linker options for systems with no USR_LDFLAGS_<osclass> speciﬁed
PROD_LDFLAGS	prod linker options
PROD_LDFLAGS_<osclass>	os speciﬁc prod linker options
PROD_LDFLAGS_DEFAULT	prod linker options for systems with no PROD_LDFLAGS_<osclass> speciﬁed
LIB_LDFLAGS	library linker options
LIB_LDFLAGS_<osclass>	os speciﬁc library linker options
LIB_LDFLAGS_DEFAULT	library linker options for systems with no LIB_LDFLAGS_<osclass> speciﬁed
<name>_LDFLAGS	prod or library speciﬁc linker options
<name>_LDFLAGS_<osclass>	prod or library speciﬁc linker ﬂags for a speciﬁc os class
<name>_LDFLAGS_DEFAULT	linker options for systems with no <name>_LDFLAGS_<osclass> speciﬁed
STATIC_BUILD	Is static build desired (YES or NO) (default is NO). On win32 if STATIC_BUILD=YES then set SHARED_LIBRARIES=NO)

Header ﬁles to be installed

INC	list of include ﬁles to install into $(INSTALL_DIR)/include
INC_<osclass>	os speciﬁc includes to installed under $(INSTALL_DIR)/include/os/<osclass>
INC_DEFAULT	include ﬁles to install where no INC_<osclass> is speciﬁed
Perl, csh, tcl etc. script installation

SCRIPTS	scripts to install for all systems
SCRIPTS_<osclass>	os-speciﬁc scripts to install
SCRIPTS_DEFAULT	scripts to install for systems with no SCRIPTS_<osclass> speciﬁed
SCRIPTS_IOC	scripts to install for ioc type archs.
SCRIPTS_IOC_<osclass>	os speciﬁc scripts to install for ioc type archs
SCRIPTS_IOC_DEFAULT	scripts to install for ioc type arch systems with no SCRIPTS_IOC_<osclass> speciﬁed
SCRIPTS_HOST	scripts to install for host type archs. T
SCRIPTS_HOST_<osclass>	os class speciﬁc scripts to install for host type archs
SCRIPTS_HOST_DEFAULT	scripts to install for host type arch systems with no OBJS_HOST_<osclass> speciﬁed
TCLLIBNAME	list of tcl scripts to install into $(INSTALL_DIR)/lib/<osclass> (Unix hosts only)
TCLINDEX	name of tcl index ﬁle to create from TCLLIBNAME scripts
Object ﬁles	The names in the following OBJS deﬁnitions should NOT include a suﬃx (.o or.obj).

OBJS	object ﬁles to build and install for all system.
OBJS_<osclass>	os-speciﬁc object ﬁles to build and install.
OBJS_DEFAULT	object ﬁles to build and install for systems with no OBJS_<osclass> speciﬁed.

OBJS_IOC	object ﬁles to build and install for ioc type archs.
OBJS_IOC_<osclass>	os speciﬁc object ﬁles to build and install for ioc type archs
OBJS_IOC_DEFAULT	object ﬁles to build and install for ioc type arch systems with no OBJS_IOC_<osclass> speciﬁed
OBJS_HOST	object ﬁles to build and install for host type archs. T
OBJS_HOST_<osclass>	os class speciﬁc object ﬁles to build and install for host type archs
OBJS_HOST_DEFAULT	object ﬁles to build and install for host type arch systems with no OBJS_HOST_<osclass> speciﬁed
Documentation

DOCS	text ﬁles to be installed into the $(INSTALL_DIR)/doc directory
HTMLS_DIR	name install Hypertext directory name i.e. $(INSTALL_DIR)/html/$(HTMLS_DIR)
HTMLS	hypertext ﬁles to be installed into the $(INSTALL_DIR)/html/$(HTMLS_DIR) directory
TEMPLATES_DIR	template directory to be created as $(INSTALL_DIR)/templates/$(TEMPLATE_DIR)
TEMPLATES	template ﬁles to be installed into $(TEMPLATE_DIR)
Database Deﬁnition ﬁles

DBD	database deﬁnition ﬁles to be installed or created and installed into $(INSTALL_DBD).
DBDINC	names, without suﬃx, of menus or record database deﬁnitions and headers to be installed or created and installed.
USR_DBDFLAGS	optional ﬂags for dbExpand. Currently only include path (-I <path>) and macro substitution (-S <substitution>) are supported.
DBD_INSTALLS	ﬁles from speciﬁed directory to install into $(INSTALL_DBD) (e.g. DBD_INSTALLS = $(APPNAME)/dbd/test.dbd
Database Files

DB	database ﬁles to be installed or created and installed into $(INSTALL_DB).
DB_INSTALLS	ﬁles from speciﬁed directory to install into $(INSTALL_DB) (e.g. DB_INSTALLS = $(APPNAME)/db/test.db

USR_DBFLAGS	optional ﬂags for msi (EPICS Macro Substitution Tool)
Options for other programs

YACCOPT	yacc options
LEXOPT	lex options
SNCFLAGS	state notation language, snc, options
<name>_SNCFLAGS	product speciﬁc state notation language options
E2DB_FLAGS	e2db options
SCH2EDIF_FLAGS	sch2edif options
RANLIBFLAGS	ranlib options
USR_ARFLAGS	ar options
Facilities for building Java programs

JAVA	names of Java source ﬁles to be built and installed
TESTJAVA	names of Java source ﬁles to be built
JAVAINC	names of C header ﬁle to be created in O.Common subdirectory
JAR	name of Jar ﬁle to be built
JAR_INPUT	names of ﬁles to be included in JAR
JAR_MANIFEST	name of manifest ﬁle for JAR
USR_JAVACFLAGS	javac tool options
USR_JAVAHFLAGS	javah tool options
Facilities for Windows 95/NT resource ( .rc) ﬁles


RCS	resource ﬁles (<name>.rc) needed to build every PROD and LIBRARY
RCS_<osclass>	resource ﬁles (<name>.rc) needed to build every PROD and LIBRARY for ioc type archs
RCS_DEFAULT	resource ﬁles needed to build every PROD and LIBRARY for ioc type arch systems with no RCS_<osclass> speciﬁed
<name>_RCS	resource ﬁles needed to build a speciﬁc PROD or LIBRARY
<name>_RCS_<osclass>	os speciﬁc resource ﬁles to build a speciﬁc PROD or LIBRARY
<name>_RCS_DEFAULT	resource ﬁles needed to build a speciﬁc PROD or LIBRARY for ioc type arch systems with no RCS_<osclass> speciﬁed
Assemblies

ASSEMBLIES	names of ﬁles to be assembled from snippets
COMMON_ASSEMBLIES	names of arch-independent ﬁles to be assembled from snippets
<name>_SNIPPETS	snippet ﬁles needed to build a speciﬁc assembly
<name>_PATTERN	patterns for snippet ﬁles (searched from all source directories) needed to build a speciﬁc assembly
Other deﬁnitions:

USR_VPATH	list of directories
BIN_INSTALLS	ﬁles from speciﬁed directories to be installed into $(INSTALL_BIN) (e.g. BIN_INSTALLS = $(EPICS_BASE_BIN)/aiRecord$(OBJ))
BIN_INSTALLS_<osclass>	os class speciﬁc ﬁles from speciﬁed directories to be installed into $(INSTALL_BIN)
BIN_INSTALLS_DEFAULT	ﬁles from speciﬁed directories to be installed into $(INSTALL_BIN) for target archs with no BIN_INSTALLS_<osclass> speciﬁed
LIB_INSTALLS	ﬁles from speciﬁed directories to be installed into $(INSTALL_LIB)
LIB_INSTALLS_<osclass>	os class speciﬁc ﬁles from speciﬁed directories to be installed into $(INSTALL_LIB)
LIB_INSTALLS_DEFAULT	ﬁles from speciﬁed directories to be installed into $(INSTALL_LIB) for target archs with no LIB_INSTALLS_<osclass> speciﬁed
TARGETS	ﬁles to create but not install

INSTALL_LOCATION	installation directory (defaults to $(TOP))

4.8 Conﬁguration Files

4.8.1 Base Conﬁgure Directory

4.8.2 Base Conﬁgure File Descriptions

The conﬁgure ﬁles contain deﬁnitions and make rules to be included in the various makeﬁles.

4.8.3 Base conﬁgure/os File Descriptions

The conﬁgure/os directory contains os speciﬁc make deﬁnitions. The naming convention for the ﬁles in this directory is CONFIG.<host>.<target> where <host> is either the arch for a speciﬁc host system or Common for all supported host systems and <target> is either the arch for a speciﬁc target system or Common for all supported target systems.

For example, the ﬁle CONFIG.Common.vxWorks-pentium will contain make deﬁnitions to be used for builds on all host systems when building for a vxWorks-pentium target system.

Also, if a group of host or target ﬁles have the same make deﬁnitions these common deﬁnitions can be moved to a new ﬁle which is then included in each host or target ﬁle. An example of this is all Unix hosts which have common deﬁnitions in a CONFIG.UnixCommon.Common ﬁle and all vxWorks targets with deﬁnitions in CONFIG.Common.vxWorksCommon.

The base/conﬁgure/os directory contains the following os-arch speciﬁc deﬁnitions

4.8.4 Base src/tools File Descriptions

The src/tools directory contains Perl script tools used for the build. The are installed by the build into
$(INSTALL_LOCATION)/bin/$(T_A) for Host type target archs. The tools currently in this directory are:

4.9 Build Documentation Files

4.9.1 Base Documentation Directory

The base/documentation directory contains README ﬁles to help users setup and build epics/base.

4.9.2 Base Documentation File Descriptions

4.10 Startup Files

4.10.1 Base Startup Directory

The base/startup directory contains scripts to help users set the required environment variables and path. The appropriate startup ﬁles should be executed before any EPICS builds.

Source	Snippet	Comment

L	10_init	L default resets the G default
G	20_environment
L	30_another-driver	implicit addition, alphabetical sorting
G	30_drivers
L	40_settings	replacing a default, ignoring backup ﬁle
L	70_start-my-ioc	explicit replace

Chapter 4Build Facility

4.1 Overview