# Build Facility¶

Janet Anderson is the author of this chapter.

## Overview¶

This chapter describes the EPICS build facility including directory structure, environment and system requirements, configuration files, Makefiles, and related build tools.

### <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. Different <top> areas can be on different releases of external software such as EPICS base releases.

A <top> directory has the following directory structure:

<top>/
Makefile
configure/
dir1/
dir2/
...

where configure is a directory containing build configuration files and a Makefile, where dir1, dir2, … are user created subdirectory trees with Makefiles and source files 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.

### Features¶

The principal features of the build system are:

• Requires a single Makefile in each directory of a <top> directory structure
• Supports both host os vendor’s native compiler and GNU compiler
• Supports building multiple types of software (libraries, executables, databases, java class files, etc.) stored in a single directory tree.
• Supports building EPICS base, extensions, and IOC applications.
• Supports multiple host and target operating system + architecture combinations.
• Allows builds for all hosts and targets within a single <top> source directory tree.
• Allows sharing of components such as special record/device/drivers across <top> areas.
• gnumake is the only command used to build a <top> area.

### 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 files 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 definition for $(INSTALL_LOCATION) is$(TOP) which is the root directory in the directory structure. Architecture dependant created files (e.g. object files) are stored in O.<arch> source subdirectories, and architecture independent created files 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 specific host/target combination you must have the proper host/target c/c++ cross compiler and target header files, 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/configure/ os directory must have the appropriate configure files.

## Build Requirements¶

### 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 filenames of the CONFIG.*.Common files in base/ configure/os show the currently supported EPICS_HOST_ARCH values. Examples are solaris-sparc, solaris-sparc-gnu, linux-x86, win32-x86, and cygwin-x86.

### Software Prerequisites¶

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

• Perl version 5.8 or greater
• GNU make, version 3.81 or greater
• C++ compiler (host operating system vendor’s compiler or GNU compiler)

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

• Tornado II or vxWorks 6.x or later, and one or more board support packages. Consult the vxWorks documentation for details.

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

• RTEMS development tools and libraries required to run EPICS IOC applications.

### Path requirements¶

You must have the perl executable in your path and you may need C and C++ compilers in your search path. Check definitions of CC and CCC in base/configure/os/CONFIG.<host>.<host> or the definitions for GCC and G++ if ANSI=GCC and CPLUSPLUS=GCC are specified in CONFIG_SITE. For building base you also must have echo in your search path. You can override the default settings by defining PERL, CC and CCC, GCC and G++, GNU_DIR … in the appropriate file (usually configure/os/CONFIG_SITE.$EPICS_HOST_ARCH.Common) #### 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. #### 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). ### 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. ### EPICS_HOST_ARCH environment variable¶ The startup directory in EPICS base contains a perl script, EpicsHostArch.pl, which can be used to define EPICS_HOST_ARCH. This script can be invoked with a command line parameter defining 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. ## Configuration Definitions¶ ### Site-specific EPICS Base Configuration¶ #### Site configuration¶ To configure EPICS base for your site, you may want to modify the default definitions in the following files: • configure/CONFIG_SITE Build choices. Specify target archs. • configure/CONFIG_SITE_ENV Environment variable defaults #### Host configuration¶ To configure each host system for your site, you may override the default definitions in the configure/os directory by adding a new file with override definitions. The new file should have the same name as the distribution file to be overridden except CONFIG in the name is changed to CONFIG_SITE. • configure/os/CONFIG_SITE.<host>.<host> - Host build settings • configure/os/CONFIG_SITE.<host>.Common - Host build settings for all target systems #### Target configuration¶ To configure each target system, you may override the default definitions in the configure/os directory by adding a new file with override definitions. The new file should have the same name as the distribution file to be overridden except CONFIG in the name is replaced by CONFIG_SITE. • configure/os/CONFIG_SITE.Common.<target> - Target cross settings • configure/os/CONFIG_SITE.<host>.<target> - Host-target settings • configure/os/CONFIG_SITE.Common.vxWorksCommon - vxWorks full paths #### R3.13 compatibility configuration¶ To configure EPICS base for building with R3.13 extensions and ioc applications, you must modify the default definitions in the base/config/CONFIG_SITE* files to agree with site definitions you made in base/configure and base/configure/os files.You must also modify the following tow macros in the base/configure/CONFIG_SITE file: • COMPAT_TOOLS_313 - Set to YES to build R3.13 extensions with this base. • COMPAT_313 - Set to YES to build R3.13 ioc applications and extensions with this base. ### Directory definitions¶ The configure files contain definitions 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 file. INSTALL_LOCATION_LIB =$(INSTALL_LOCATION)/lib
INSTALL_LOCATION_BIN      = $(INSTALL_LOCATION)/bin INSTALL_HOST_BIN =$(INSTALL_LOCATION_BIN)/$(EPICS_HOST_ARCH) INSTALL_HOST_LIB =$(INSTALL_LOCATION_LIB)/$(EPICS_HOST_ARCH) INSTALL_INCLUDE =$(INSTALL_LOCATION)/include
INSTALL_DOC               = $(INSTALL_LOCATION)/doc INSTALL_HTML =$(INSTALL_LOCATION)/html
INSTALL_TEMPLATES         = $(INSTALL_LOCATION)/templates INSTALL_DBD =$(INSTALL_LOCATION)/dbd
INSTALL_DB                = $(INSTALL_LOCATION)/db INSTALL_CONFIG =$(INSTALL_LOCATION)/configure
INSTALL_JAVA              = $(INSTALL_LOCATION)/javalib INSTALL_LIB =$(INSTALL_LOCATION_LIB)/$(T_A) INSTALL_SHRLIB =$(INSTALL_LOCATION_LIB)/$(T_A) INSTALL_TCLLIB =$(INSTALL_LOCATION_LIB)/$(T_A) INSTALL_BIN =$(INSTALL_LOCATION_BIN)/$(T_A) ### Extension and Application Specific Configuration¶ The base/configure directory contains files with the default build definitions and site specific build definitions. The extensions/configure directory contains extension specific build definitions (e.g. location of X11 and Motif libraries) and “include <filename>” lines for the base/configure files. Likewise, the <application>/configure directory contains application specific build definitions and includes for the application source files. Build definitions such as CROSS_COMPILER_TARGET_ARCHS can be overridden in an extension or application by placing an override definition in the <top>/configure/CONFIG_SITE file. ### RELEASE file¶ Every <top>/configure directory contains a RELEASE file. RELEASE contains a user specified list of other <top> directory structures containing files needed by the current <top>, and may also include other files to take those definitions from elsewhere. The macros defined in the RELEASE file (or its includes) may reference other defined macros, but cannot rely on environment variables to provide definitions. When make is executed, macro definitions for include, bin, and library directories are automatically generated for each external <top> definition given in the RELEASE file. Also generated are include statements for any existing RULES_BUILD files, cfg/RULES* files, and cfg/CONFIG* files from each external <top> listed in the RELEASE file. For example, if configure/RELEASE contains the definition CAMAC = /home/epics/modules/bus/camac then the generated macros will be: CAMAC_HOST_BIN = /home/epics/modules/bus/camac/bin/$(EPICS_HOST_ARCH)
CAMAC_HOST_LIB = /home/epics/modules/bus/camac/lib/$(EPICS_HOST_ARCH CAMAC_BIN = /home/epics/modules/bus/camac/bin/$(T_A)

### OS Class specific definitions¶

Definitions in a Makefile will apply to the host system (the platform on which make is executed) and each system defined by CROSS_COMPILER_TARGET_ARCHS.

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

Each system has an OS_CLASS definition in its configure/os/CONFIG.Common.<arch> file. A few examples are:

• For vxWorks-* targets <osclass> is vxWorks.
• For RTEMS-* targets <osclass> is RTEMS.
• For solaris-* targets <osclass> is solaris.
• For win32-* targets <osclass> is WIN32.
• For linux-* targets <osclass> is Linux.
• For darwin-* targets <osclass> is Darwin.
• For aix-* targets <osclass> is AIX.

For example the following Makefile lines specify that product aaa should be created for all systems. Product bbb should be created for systems that do not have OS_CLASS defined as solaris.

PROD = aaa
PROD_solaris = -nil-
PROD_DEFAULT = bbb

### Specifying T_A specific definitions¶

It is possible for the user to limit the systems for which a particular definition applies to specific target systems.

For example the following Makefile 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

PROD_IOC = aaa
VX_PROD_vxWorks-68040 = bbb
VX_PROD_vxWorks-ppc603 = bbb
PROD_IOC += VX_PROD_$(T_A) ### Host and Ioc targets¶ Build creates two type of makefile targets: Host and Ioc. Host targets are executables, object files, libraries, and scripts which are not part of iocCore. Ioc targets are components of ioc libraries, executables, object files, or iocsh scripts which will be run on an ioc. Each supported target system has a VALID_BUILDS definition which specifies the type of makefile targets it can support. This definition appears in configure/os/CONFIG.Common.<arch> or configure/os/CONFIG.<arch>.<arch> files. • For vxWorks systems VALID_BUILDS is set to “Ioc”. • For Unix type systems, VALID_BUILDS is set to “Host Ioc”. • For RTEMS systems, VALID_BUILDS is set to “Ioc”. • For WIN32 systems, VALID_BUILDS is set to “Host Ioc”. In a Makefile it is possible to limit the systems for which a particular PROD, TESTPROD, LIBRARY, SCRIPTS, and OBJS is built. For example the following Makefile 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. PROD_HOST = aaa PROD_IOC = bbb PROD = ccc These definitions can be further limited by specifying an appended underscore “_” followed by an osclass or DEFAULT specification. ### User specific override definitions¶ User specific override definitions are allowed in user created files in the user’s <home>/configure subdirectory. These override definitions will be used for builds in all <top> directory structures. The files must have the following names. <home>/configure/CONFIG_USER <home>/configure/CONFIG_USER.<epics_host_arch> <home>/configure/CONFIG_USER.Common.<targetarch> <home>/configure/CONFIG_USER.<epics_host_arch>.<targetarch> ## Makefiles¶ ### Name¶ The name of the makefile in each directory must be Makefile. ### Included Files¶ Makefiles normally include files from <top>/configure. Thus the makefile “inherits” rules and definitions from configure. The files in <top>/configure may in turn include files from another <top>/configure. This technique makes it possible to share make variables and even rules across <top> directories. ### Contents of Makefiles¶ #### Makefiles in directories containing subdirectories¶ A Makefile in this type of directory must define where <top> is relative to this directory, include <top>/configure files, and specify the subdirectories in the desired order of make execution. Running gnumake in a directory with the following Makefile lines will cause gnumake to be executed in <dir1> first and then <dir2>. The build rules do not allow a Makefile to specify both subdirectories and components to be built. TOP=../.. include$(TOP)/configure/CONFIG
DIRS += <dir1> <dir2>
include $(TOP)/configure/RULES_DIRS #### Makefiles in directories where components are to be built¶ A Makefile in this type of directory must define where <top> is relative to this directory, include <top> configure files, and specify the target component definitions. Optionally it may contain user defined rules. Running gnumake in a directory with this type of Makefile will cause gnumake to create an O.<arch> subdirectory and then execute gnumake to build the defined components in this subdirectory. It contains the following lines: TOP=../../.. include$(TOP)/configure/CONFIG
<component definition lines>
include $(TOP)/configure/RULES <optional rules definitions> ### Simple Makefile examples¶ Create an IOC type library named asIoc from the source file asDbLib.c and install it into the$(INSTALL_LOCATION)/lib/<arch> directory.

TOP=../../..
include $(TOP)/configure/CONFIG LIBRARY_IOC += asIoc asIoc_SRCS += asDbLib.c include$(TOP)/configure/RULES

For each Host type target architecture, create an executable named catest from the catest1.c and catest2.c source files linking with the existing EPICS base ca and Com libraries, and then install the catest executable into the $(INSTALL_LOCATION)/bin/<arch> directory. TOP=../../.. include$(TOP)/configure/CONFIG
PROD_HOST = catest
catest_SRCS += catest1.c catest2.c
catest_LIBS = ca Com
include $(TOP)/configure/RULES ## Make¶ ### 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. ### 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. The most frequently used make commands are: gnumake This rebuilds and installs everything that is not up to date. NOTE: Executing gnumake without arguments is the same as “gnumake install” gnumake help This command can be executed from the <top> directory only. This command prints a page describing the most frequently used make commands. gnumake install This rebuilds and installs everything that is not up to date. gnumake all This is the same as “gnumake install”. gnumake buildInstall This is the same as “gnumake install”. gnumake<arch> This rebuilds and installs everything that is not up to date first for the host arch and then (if different) for the specified target arch. NOTE: This is the same as “gnumake install.<arch>” gnumake clean This can be used to save disk space by deleting the O.<arch> directories that gnumake will create, but does not remove any installed files from the bin, db, dbd etc. directories. “gnumake clean.<arch>” can be invoked to clean a single architecture. gnumake archclean This command will remove the current build’s O.<arch> directories but not O.Common directory. gnumake realclean This command will remove ALL the O.<arch> subdirectories (even those created by a gnumake from another EPICS_HOST_ARCH). gnumake rebuild This is the same as “gnumake clean install”. If you are unsure about the state of the generated files in an application, just execute “gnumake rebuild”. gnumake uninstall This command can be executed from the <top> directory only. It will remove everything installed by gnumake in the include, lib, bin, db, dbd, etc. directories. gnumake realuninstall This command can be executed from the <top> directory only. It will remove all the install directories, include, lib, bin, db, dbd, etc. gnumake distclean This command can be executed from the <top> directory only. It is the same as issuing both the realclean and realuninstall commands. gnumake cvsclean This command can be executed from the <top> directory only. It removes cvs .#* files in the make directory tree. ### Make targets¶ The following is a summary of targets that can be specified for gnumake: • <action> • <arch> • <action>.<arch> • <dir> • <dir>.<action> • <dir>.<arch> • <dir>.<action>.<arch> where: • <arch> is an architecture such as solaris-sparc, vxWorks-68040, win32-x86, etc. • <action> is help, clean, realclean, distclean, inc, install, build, rebuild, buildInstall, realuninstall, or uninstall NOTE: help, uninstall, distclean, cvsclean, and realuninstall can only be specified at <top>. NOTE: realclean cannot be specified inside an O.<arch> subdirectory. <dir> is subdirectory name NOTE: You can build using your os vendor’s 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 Makefiles must be explicit in defining which architectures a component should be built for. ### Header file dependencies¶ All product, test product, and library source files which appear in one of the source file definitions (e.g. SRCS, PROD_SRCS, LIB_SRCS, <prodname>_SRCS) will have their header file dependencies automatically generated and included as part of the Makefile. ## Makefile definitions¶ The following components can be defined in a Makefile: ### Source file directories¶ Normally all product, test product, and library source files reside in the same directory as the Makefile. OS specific source files are allowed and should reside in subdirectories os/<os_class> or os/posix or os/default. The build rules also allow source files to reside in subdirectories of the current Makefile directory (src directory). For each subdirectory <dir> containing source files add the SRC_DIRS definition. SRC_DIRS += <dir> where <dir> is a relative path definition. An example of SRC_DIRS is SRC_DIRS += ../dir1 ../dir2 The directory search order for the above definition is . ../os/$(OS_CLASS) ../os/posix ../os/default
../dir1/os/$(OS_CLASS) ../dir1/os/posix ../dir1/os/default ../dir2/os/$(OS_CLASS) ../dir2/os/posix ../dir2/os/default
..
../dir1 ../dir2

where the build directory O.<arch> is . and the src directory is …

### Posix C source code¶

The epics base config files assume posix source code and define POSIX to be YES as the default. Individual Makefiles can override this by setting POSIX to NO. Source code files may have the suffix .c, .cc, .cpp, or .C.

### Breakpoint Tables¶

For each breakpoint table dbd file, bpt<table name>.dbd, to be created from an existing bpt<table name>.data file, add the definition

DBD += bpt<table name>.dbd

to the Makefile. The following Makefile will create a bptTypeJdegC.dbd file from an existing bptTypeJdegC.data file using the EPICS base utility program makeBpt and install the new dbd file into the $(INSTALL_LOCATION)/dbd directory. TOP=../../.. include$(TOP)/configure/CONFIG
DBD += bptTypeJdegC.dbd
include $(TOP)/configure/RULES ### Record Type Definitions¶ For each new record type, the following definition should be added to the makefile: DBDINC += <rectype>Record A <rectype>Record.h header file will be created from an existing <rectype>Record.dbd file using the EPICS base utility program dbToRecordTypeH. This header will be installed into the$(INSTALL_LOCATION)/include directory and the dbd file will be installed into the $(INSTALL_LOCATION)/dbd directory. The following Makefile will create xxxRecord.h from an existing xxxRecord.dbd file, install xxxRecord.h into$(INSTALL_LOCATION)/include, and install xxxRecord.dbd into $(INSTALL_LOCATION)/dbd. TOP=../../.. include$(TOP)/configure/CONFIG
DBDINC += xxxRecord
include $(TOP)/configure/RULES ### Expanded Database Definition Files¶ Database definition include files named <name>Include.dbd containing includes for other database definition files can be expanded by the EPICS base utility program dbExpand into a created <name>.dbd file and the <name>.dbd file installed into$(INSTALL_LOCATION)/dbd. The following variables control the process:

DBD += <name>.dbd
USR_DBDFLAGS += -I <include path>
USR_DBDFLAGS += -S <macro substitutions>
<name>_DBD += <file1>.dbd <file2>.dbd ...

where

DBD += <name>.dbd

is the name of the output dbd file to contain the expanded definitions. It is created by expanding an existing or build created <name>Include.dbd file and then copied into $(INSTALL_LOCATION)/dbd. An example of a file to be expanded is exampleInclude.dbd containing the following lines include "base.dbd" include "xxxRecord.dbd" device(xxx,CONSTANT,devXxxSoft,"SoftChannel") USR_DBDFLAGS defines optional flags 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 specified in the configure/RELEASE file. A database definition include file named <name>Include.dbd containing includes for other database definition files can be created from a <name>_DBD definition. The lines DBD += <name>.dbd <name>_DBD += <file1>.dbd <file2>.dbd ... will create an expanded dbd file <name>.dbd by first creating a <name>Include.dbd. For each filename in the <name>_DBD definition, the created <name>Include.dbd will contain an include statement for that filename. Then the expanded DBD file is generated from the created <name>Include.dbd file and installed into$(INSTALL_LOCATION)/ dbd.

The following Makefile will create an expanded dbd file named example.dbd from an existing exampleInclude.dbd file and then install example.dbd into the $(INSTALL_LOCATION)/dbd directory. TOP=../../.. include$(TOP)/configure/CONFIG
DBD += exampleApp.dbd
include $(TOP)/configure/RULES The following Makefile will create an exampleInclude.dbd file from the example_DBD definition then expand it to create an expanded dbd file, example.dbd, and install example.dbd into the$(INSTALL_LOCATION)/dbd directory.

TOP=../../..
include $(TOP)/configure/CONFIG DBD += example.dbd example_DBD += base.dbd xxxRecord.dbd xxxSupport.dbd include$(TOP)/configure/RULES

The created exampleInclude.dbd file will contain the following lines

include "base.dbd"
include "xxxRecord.dbd"
include "xxxSupport.dbd"

### Registering Support Routines for Expanded Database Definition Files¶

A source file 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 file.

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

<prodname>_SRCS += <name>_registerRecordDeviceDriver.cpp

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

variable(mySubDebug)
function(mySubInit)
function(mySubProcess)

The following line installs the existing named dbd files into $(INSTALL_LOCATION)/dbd without expansion. DBD += <name>.dbd ### DBD install files¶ Definitions of the form: DBD_INSTALLS += <name> result in files being installed to the$(INSTALL_LOCATION/dbd directory. The file <name> can appear with or without a directory prefix. If the file has a directory prefix e.g. $(APPNAME)/dbd/, it is copied from the specified location. If a directory prefix is not present, make will look in the current source directory for the file. ### Database Files¶ For most databases just the name of the database has to be specified. Make will figure out how to generate the file: DB += xxx.db generates xxx.db depending on which source files exist and installs it into$(INSTALL_LOCATION)/db.

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

<name>_TEMPLATE = <template file name>

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

If a <name> substitutions file contains “file” references to other input files, these referenced files 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 redefine MSI as the full path name to the msi binary in a RELEASE file or Makefile. An example MSI definition is

MSI = /usr/local/epics/extensions/bin/${EPICS_HOST_ARCH}/msi Template files <name>.template, and db files, <name>.db, will be created from an edf file <name>.edf and an <name>.edf file will be created from a <name>.sch file. Template and substitution files can be installed. DB += xxx.template xxx.substitutions generates and installs these files. If one or more xxx.substitutions files 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 prefix of the substitution file name to be generated as its argument. If (and only if) there are script generated substitutions files, the prefix of any inflated database’s name may not equal the prefix of the name of any template used within the directory. ### DB install files¶ Definitions of the form: DB_INSTALLS += <name> result in files being installed to the$(INSTALL_LOCATION/db directory. The file <name> can appear with or without a directory prefix. If the file has a directory prefix e.g. $(APPNAME)/db/, it is copied from the specified location. If a directory prefix is not present, make will look in the current source directory for the file. ### 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 files containing code for the library. An object or source file name can appear with or without a directory prefix. If the file name has a directory prefix e.g. $(EPICS_BASE_BIN), it is taken from the specified location. If a directory prefix is not present, make will first look in the source directories for a file with the specified name and next try to create the file using existing configure rules. A library filename prefix may be prepended to the library name when the file is created. For Unix type systems and vxWorks the library prefix is lib and there is no prefix for WIN32. Also a library suffix appropriate for the library type and target arch (e.g. .a, .so, .lib, .dll) will be appended to the filename when the file is created. vxWorks and RTEMS Note: Only archive libraries are created. Shared libraries Note: Shared libraries can be built for any or all HOST type architectures. The definition of SHARED_LIBRARIES (YES/NO) in base/configure/CONFIG_SITE determines whether shared or archive libraries will be built. When SHARED_LIBRARIES is YES, both archive and shared libraries are built. This definition can be overridden for a specific arch in an configure/os/CONFIG_SITE.<arch>.Common file.,The default definition for SHARED_LIBRARIES in the EPICS base distribution file is YES for all host systems. win32 Note: An object library file is created when SHARED_LIBRARIES=NO, <name>.lib which is installed into$(INSTALL_LOCATION)/lib/<arch>. Two library files 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 file <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 files are different for shared and nonshared builds. #### Specifying the library name.¶ Any of the following can be specified: LIBRARY += <name> A library will be created for every target arch. LIBRARY_<osclass> += <name> Library <name> will be created for all archs of the specified osclass. LIBRARY_DEFAULT += <name> Library <name> will be created for any arch that does not have a LIBRARY_<osclass> definition LIBRARY_IOC += <name> Library <name> will be created for IOC type archs. LIBRARY_IOC_<osclass> += <name> Library <name> will be created for all IOC type archs of the specified osclass. LIBRARY_IOC_DEFAULT += <name> Library <name> will be created for any IOC type arch that does not have a LIBRARY_IOC_<osclass> definition LIBRARY_HOST += <name> Library <name> will be created for HOST type archs. LIBRARY_HOST_<osclass> += <name> Library <name> will be created for all HOST type archs of the specified osclass. LIBRARY_HOST_DEFAULT += <name> Library <name> will be created for any HOST type arch that does not have a LIBRARY_HOST_<osclass> definition #### Specifying library source file names¶ Source file names, which must have a suffix, are defined as follows: SRCS += <name> Source files will be used for all defined libraries and products. SRCS_<osclass> += <name> Source files will be used for all defined libraries and products for all archs of the specified osclass. SRCS_DEFAULT += <name> Source files will be used for all defined libraries and products for any arch that does not have a SRCS_<osclass> definition LIBSRCS and LIB_SRCS have the same meaning. LIBSRCS is deprecated, but retained for R3.13 compatibility. LIBSRCS += <name> Source files will be used for all defined libraries. LIBSRCS_<osclass> += <name> Source files will be used for all defined libraries for all archs of the specified osclass. LIBSRCS_DEFAULT += <name> Source files will be used for all defined libraries for any arch that does not have a LIBSRCS_<osclass> definition USR_SRCS += <name> Source files will be used for all defined products and libraries. USR_SRCS_<osclass> += <name> Source files will be used for all defined products and libraries for all archs of the specified osclass. USR_SRCS_DEFAULT += <name> Source files will be used for all defined products and libraries for any arch that does not have a USR_SRCS_<osclass> definition LIB_SRCS += <name> Source files will be used for all libraries. LIB_SRCS_<osclass> += <name> Source files will be used for all defined libraries for all archs of the specified osclass. LIB_SRCS_DEFAULT += <name> Source files will be used for all defined libraries for any arch that does not have a LIB_SRCS_<osclass> definition <libname>_SRCS += <name> Source files will be used for the named library. <libname>_SRCS_<osclass> += <name> Source files will be used for named library for all archs of the specified osclass. <libname>_SRCS_DEFAULT += <name> Source files will be used for named library for any arch that does not have a <libname>_SRCS_<osclass> definition #### Specifying library object file names¶ Library object file names should only be specified for object files which will not be built in the current directory. For object files built in the current directory, library source file names should be specified. See Specifying Library Source File Names above. Object files which have filename with a “.o” or “.obj” suffix are defined as follows and can be specified without the suffix but should have the directory prefix USR_OBJS += <name> Object files will be used in builds of all products and libraries USR_OBJS_<osclass> += <name> Object files will be used in builds of all products and libraries for archs with the specified osclass. USR_OBJS_DEFAULT += <name> Object files will be used in builds of all products and libraries for archs without a USR_OBJS_<osclass> definition specified. LIB_OBJS += <name> Object files will be used in builds of all libraries. LIB_OBJS_<osclass> += <name> Object files will be used in builds of all libraries for archs of the specified osclass. LIB_OBJS_DEFAULT += <name> Object files will be used in builds of all libraries for archs without a LIB_OBJS_<osclass> definition specified. <libname>_OBJS += <name> Object files will be used for all builds of the named library) <libname>_OBJS_<osclass> += <name> Object files will be used in builds of the library for archs with the specified osclass. <libname>_OBJS_DEFAULT += <name> Object files will be used in builds of the library for archs without a <libname>_OBJS_<osclass> definition specified. Combined object files, from R3.13 built modules and applications which have file names that do not include a “.o” or “.obj” suffix (e.g. xyzLib) are defined as follows: USR_OBJLIBS += <name> Combined object files will be used in builds of all libraries and products. USR_OBJLIBS_<osclass> += <name> Combined object files will be used in builds of all libraries and products for archs of the specified osclass. USR_OBJLIBS_DEFAULT += <name> Combined object files will be used in builds of all libraries and products for archs without a USR_OBJLIBS_<osclass> definition specified. LIB_OBJLIBS += <name> Combined object files will be used in builds of all libraries. LIB_OBJLIBS_<osclass> += <name> Combined object files will be used in builds of all libraries for archs of the specified osclass. LIB_OBJLIBS_DEFAULT += <name> Combined object files will be used in builds of all libraries for archs without a LIB_OBJLIBS_<osclass> definition specified. <libname>_OBJLIBS += <name> Combined object files will be used for all builds of the named library. <libname>_OBJLIBS_<osclass> += <name> Combined object files will be used in builds of the library for archs with the specified osclass. <libname>_OBJLIBS_DEFAULT += <name> Combined object files will be used in builds of the library for archs without a <libname>_OBJLIBS_<osclass> definition specified. <libname>_LDOBJS += <name> Combined object files will be used for all builds of the named library. (deprecated) <libname>_LDOBJS_<osclass> += <name> Combined object files will be used in builds of the library for archs with the specified osclass. (deprecated) <libname>_LDOBJS_DEFAULT += <name> Combined object files will be used in builds of the library for archs without a <libname>_LDOBJS_<osclass> definition specified. (deprecated) #### LIBOBJS definitions¶ Previous versions of epics (3.13 and before) accepted definitions like: LIBOBJS +=$<support>_BIN)/xxx.o

These are gathered together in files such as baseLIBOBJS. To use such definitions include the lines:

-include ../baseLIBOBJS <libname>_OBJS += $(LIBOBJS) Note: vxWorks applications created by makeBaseApp.pl from 3.14 Base releases no longer have a file named baseLIBOBJS. Base record and device support now exists in archive libraries. #### Specifying dependant libraries to be linked when creating a library¶ For each library name specified which is not a system library nor a library from an EPICS top defined in the configure/ RELEASE file, a <name>_DIR definition must be present in the Makefile to specify the location of the library. Library names, which must not have a directory and “lib” prefix nor a suffix, are defined as follows: LIB_LIBS += <name> Libraries to be used when linking all defined libraries. LIB_LIBS_<osclass> += <name> Libraries to be used or all archs of the specified osclass when linking all defined libraries. LIB_LIBS_DEFAULT += <name> Libraries to be used for any arch that does not have a LIB_LIBS_<osclass> definition when linking all defined libraries. USR_LIBS += <name> Libraries to be used when linking all defined products and libraries. USR_LIBS_<osclass> += <name> Libraries to be used or all archs of the specified osclasswhen linking all defined products and libraries. USR_LIBS_DEFAULT += <name> Libraries to be used for any arch that does not have a USR_LIBS_<osclass> definition when linking all defined products and libraries. <libname>_LIBS += <name> Libraries to be used for linking the named library. <libname>_LIBS_<osclass> += <name> Libraries will be used for all archs of the specified osclass for linking named library. <libname>_LIBS_DEFAULT += <name> Libraries to be used for any arch that does not have a <libname>_LIBS_<osclass> definition when linking named library. <libname>_SYS_LIBS += <name> System libraries to be used for linking the named library. <libname>_SYS_LIBS_<osclass> += <name> System libraries will be used for all archs of the specified osclass for linking named library. <libname>_SYS_LIBS_DEFAULT += <name> System libraries to be used for any arch that does not have a <libname>_LIBS_<osclass> definition when linking named library. #### The order of dependant libraries¶ Dependant library names appear in the following order on a library link line: 1. <libname>_LIBS 2. <libname>_LIBS_<osclass> or <libname>_LIBS_DEFAULT 3. LIB_LIBS 4. LIB_LIBS_<osclass> or LIB_LIBS_DEFAULT 5. USR_LIBS 6. USR_LIBS_<osclass> or USR_LIBS_DEFAULT 7. <libname>_SYS_LIBS 8. <libname>_SYS_LIBS_<osclass> or <libname>_SYS_LIBS_DEFAULT 9. LIB_SYS_LIBS 10. LIB_SYS_LIBS_<osclass> or LIB_SYS_LIBS_DEFAULT 11. USR_SYS_LIBS 12. USR_SYS_LIBS_<osclass> or USR_SYS_LIBS_DEFAULT #### Specifying library DLL file 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 specified (without directory prefix and without “.dll” suffix) as follows: DLL_LIBS += <name> These DLLs will be used for all libraries. <libname>_DLL_LIBS += <name> These DLLs will be used for the named library. Each <name> must have a corresponding <name>_DIR definition specifying its directory location. #### Specifying shared library version number¶ A library version number can be specified when creating a shared library as follows: SHRLIB_VERSION = <version> 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. #### Library example:¶ LIBRARY_vxWorks += vxWorksOnly LIBRARY_IOC += iocOnly LIBRARY_HOST += hostOnly LIBRARY += all vxWorksOnly_OBJS +=$(LINAC_BIN)/vxOnly1
vxWorksOnly_SRCS += vxOnly2.c
iocOnly_OBJS += $(LINAC_BIN)/iocOnly1 iocOnly_SRCS += iocOnly2.cpp hostOnly_OBJS +=$(LINAC_BIN)/host1

### Object Files¶

It is possible to generate and install object files by using definitions:

OBJS += <name>
OBJS_<osclass> += <name>
OBJS_DEFAULT += <name>
OBJS_IOC += <name>
OBJS_IOC_<osclass> += <name>
OBJS_IOC_DEFAULT += <name>
OBJS_HOST += <name>
OBJS_HOST_<osclass> += <name>
OBJS_HOST_DEFAULT += <name>

These will cause the specified file to be generated from an existing source file for the appropriate target arch and installed into $(INSTALL_LOCATION)/bin/<arch>. The following Makefile will create the abc object file for all target architectures, the def object file for all target archs except vxWorks, and the xyz object file only for the vxWorks target architecture and install them into the appropriate$(INSTALL_LOCATION)/bin/<arch> directory.

TOP=../../..
include $(TOP)/configure/CONFIG OBJS += abc OBJS_vxWorks += xyz OBJS_DEFAULT += def include$(TOP)/configure/RULES

### State Notation Programs¶

A state notation program file can be specified as a source file in any SRC definition. For example:

<prodname>_SRCS += <name>.stt

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

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

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

### Scripts, etc.¶

Any of the following can be specified:

SCRIPTS += <name>

A script will be installed from the src directory to the $(INSTALL_LOCATION)/bin/<arch> directories. SCRIPTS_<osclass> += <name> Script <name> will be installed for all archs of the specified osclass. SCRIPTS_DEFAULT += <name> Script <name> will be installed for any arch that does not have a SCRIPTS_<osclass> definition SCRIPTS_IOC += <name> Script <name> will be installed for IOC type archs. SCRIPTS_IOC_<osclass> += <name> Script <name> will be installed for all IOC type archs of the specified osclass. SCRIPTS_IOC_DEFAULT += <name> Script <name> will be installed for any IOC type arch that does not have a SCRIPTS_IOC_<osclass> definition SCRIPTS_HOST += <name> Script <name> will be installed for HOST type archs. SCRIPTS_HOST_<osclass> += <name> Script <name> will be installed for all HOST type archs of the specified osclass. SCRIPTS_HOST_DEFAULT += <name> Script <name> will be installed for any HOST type arch that does not have a SCRIPTS_HOST_<osclass> definition Definitions of the form: SCRIPTS_<osclass> += <name1> SCRIPTS_DEFAULT += <name2> results in the <name1> script being installed from the src directory to the$(INSTALL_LOCATION)/bin/<arch> directories for all target archs of the specified os class <osclass> and the <name2> script installed into the $(INSTALL_LOCATION)/bin/<arch> directories of all other target archs. ### Include files¶ A definition of the form: INC += <name>.h results in file <name>.h being installed or created and installed to the$(INSTALL_LOCATION)/include directory.

Definitions of the form:

INC_DEFAULT += <name>.h
INC_<osclass> += <name>.h

results in file <name>.h being installed or created and installed into the appropriate $(INSTALL_LOCATION)/include/os/<osclass> directory. ### Html and Doc files¶ A definition of the form: HTMLS_DIR = <dirname> HTMLS += <name> results in file <name> being installed from the src directory to the$(INSTALL_LOCATION)/html/<dirname> directory.

A definition of the form:

DOCS += <name>

### Lex and yacc¶

If a <name>.c source file specified in a Makefile definition is not found in the source directory, gnumake will try to build it from <name>.y and <name>_lex.l files in the source directory. Lex converts a <name>.l Lex code file to a lex.yy.c file which the build rules renames to <name>.c. Yacc converts a <name>.y yacc code file to a y.tab.c file, which the build rules renames to <name>.c. Optionally yacc can create a y.tab.h file which the build rules renames to <name>.h.

### 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 files containing code for the product. An object or source file name can appear with or without a directory prefix. Object files should contain a directory prefix. If the file has a directory prefix e.g.$(EPICS_BASE_BIN), the file is taken from the specified location. If a directory prefix is not present, make will look in the source directories for a file with the specified name or try build it using existing rules. An executable filename suffix appropriate for the target arch (e.g. .exe) may be appended to the filename when the file is created.

PROD specifications in the Makefile for vxWorks target architectures create a combined object file with library references resolved and a corresponding .munch file.

PROD_HOST += <name>
<name>_SRC += <srcname>.c

results in the executable <name> being built for each HOST architecture, <arch>, from a <srcname>.c file. Then <name> is installed into the $(INSTALL_LOCATION)/bin/<arch> directory. #### Specifying the product name.¶ Any of the following can be specified: PROD += <name> Product <name> will be created for every target arch. PROD_<osclass> += <name> Product <name> will be created for all archs of the specified osclass. PROD_DEFAULT += <name> Product <name> will be created for any arch that does not have a PROD_<osclass> definition PROD_IOC += <name> Product <name> will be created for IOC type archs. PROD_IOC_<osclass> += <name> Product <name> will be created for all IOC type archs of the specified osclass. PROD_IOC_DEFAULT += <name> Product <name> will be created for any IOC type arch that does not have a PROD_IOC_<osclass> definition PROD_HOST += <name> Product <name> will be created for HOST type archs. PROD_HOST_<osclass> += <name> Product <name> will be created for all HOST type archs of the specified osclass. PROD_HOST_DEFAULT += <name> Product <name> will be created for any HOST type arch that does not have a PROD_HOST_<osclass> definition #### Specifying product object file names¶ Object files which have filenames with a “.o” or “.obj” suffix are defined as follows and can be specified without the suffix but should have the directory prefix USR_OBJS += <name> Object files will be used in builds of all products and libraries USR_OBJS_<osclass> += <name> Object files will be used in builds of all products and libraries for archs with the specified osclass. USR_OBJS_DEFAULT += <name> Object files will be used in builds of all products and libraries for archs without a USR_OBJS_<osclass> definition specified. PROD_OBJS += <name> Object files will be used in builds of all products PROD_OBJS_<osclass> += <name> Object files will be used in builds of all products for archs with the specified osclass. PROD_OBJS_DEFAULT += <name> Object files will be used in builds of all products for archs without a PROD_OBJS_<osclass> definition specified. <prodname>_OBJS += <name> Object files will be used for all builds of the named product <prodname>_OBJS_<osclass> += <name> Object files will be used in builds of the named product for archs with the specified osclass. <prodname>_OBJS_DEFAULT += <name> Object files will be used in builds of the named product for archs without a <prodname>_OBJS_<osclass> definition specified. Combined object files, from R3.13 built modules and applications which have file names that do not include a “.o” or “.obj” suffix (e.g. xyzLib) are defined as follows: USR_OBJLIBS += <name> Combined object files will be used in builds of all libraries and products. USR_OBJLIBS_<osclass> += <name> Combined object files will be used in builds of all libraries and products for archs of the specified osclass. USR_OBJLIBS_DEFAULT += <name> Combined object files will be used in builds of all libraries and products for archs without a USR_OBJLIBS_<osclass> definition specified. PROD_OBJLIBS += <name> Combined object files will be used in builds of all products. PROD_OBJLIBS_<osclass> += <name> Combined object files will be used in builds of all products for archs of the specified osclass. PROD_OBJLIBS_DEFAULT += <name> Combined object files will be used in builds of all products for archs without a PROD_OBJLIBS_<osclass> definition specified. <prodname>_OBJLIBS += <name> Combined object files will be used for all builds of the named product. <prodname>_OBJLIBS_<osclass> += <name> Combined object files will be used in builds of the named product for archs with the specified osclass. <prodname>_OBJLIBS_DEFAULT += <name> Combined object files will be used in builds of the named product for archs without a <prodname>_OBJLIBS_<osclass> definition specified. <prodname>_LDOBJS += <name> Object files will be used for all builds of the named product. (deprecated) <prodname>_LDOBJS_<osclass> += <name> Object files will be used in builds of the name product for archs with the specified osclass. (deprecated) <prodname>_LDOBJS_DEFAULT += <name> Object files will be used in builds of the product for archs without a <prodname>_LDOBJS_<osclass> definition specified. (deprecated) #### Specifying product source file names¶ Source file names, which must have a suffix, are defined as follows: SRCS += <name> Source files will be used for all defined libraries and products. SRCS_<osclass> += <name> Source files will be used for all defined libraries and products for all archs of the specified osclass. SRCS_DEFAULT += <name> Source files will be used for all defined libraries and products for any arch that does not have a SRCS_<osclass> definition USR_SRCS += <name> Source files will be used for all products and libraries. USR_SRCS_<osclass> += <name> Source files will be used for all defined products and libraries for all archs of the specified osclass. USR_SRCS_DEFAULT += <name> Source files will be used for all defined products and libraries for any arch that does not have a USR_SRCS_<osclass> definition PROD_SRCS += <name> Source files will be used for all products. PROD_SRCS_<osclass> += <name> Source files will be used for all defined products for all archs of the specified osclass. PROD_SRCS_DEFAULT += <name> Source files will be used for all defined products for any arch that does not have a PROD_SRCS_<osclass> definition <prodname>_SRCS += <name> Source file will be used for the named product. <prodname>_SRCS_<osclass> += <name> Source files will be used for named product for all archs of the specified osclass. <prodname>_SRCS_DEFAULT += <name> Source files will be used for named product for any arch that does not have a <prodname>_SRCS_<osclass> definition #### Specifying libraries to be linked when creating the product¶ For each library name specified which is not a system library nor a library from EPICS_BASE, a <name>_DIR definition must be present in the Makefile to specify the location of the library. Library names, which must not have a directory and “lib” prefix nor a suffix, are defined as follows: PROD_LIBS += <name> Libraries to be used when linking all defined products. PROD_LIBS_<osclass> += <name> Libraries to be used or all archs of the specified osclass when linking all defined products. PROD_LIBS_DEFAULT += <name> Libraries to be used for any arch that does not have a PROD_LIBS_<osclass> definition when linking all defined products. USR_LIBS += <name> Libraries to be used when linking all defined products. USR_LIBS_<osclass> += <name> Libraries to be used or all archs of the specified osclasswhen linking all defined products. USR_LIBS_DEFAULT += <name> Libraries to be used for any arch that does not have a USR_LIBS_<osclass> definition when linking all defined products. <prodname>_LIBS += <name> Libraries to be used for linking the named product. <prodname>_LIBS_<osclass> += <name> Libraries will be used for all archs of the specified osclass for linking named product. <prodname>_LIBS_DEFAULT += <name> Libraries to be used for any arch that does not have a <prodname>_LIBS_<osclass> definition when linking named product. SYS_PROD_LIBS += <name> System libraries to be used when linking all defined products. SYS_PROD_LIBS_<osclass> += <name> System libraries to be used for all archs of the specified osclass when linking all defined products. SYS_PROD_LIBS_DEFAULT += <name> System libraries to be used for any arch that does not have a PROD_LIBS_<osclass> definition when linking all defined products. <prodname>_SYS_LIBS += <name> System libraries to be used for linking the named product. <prodname>_SYS_LIBS_<osclass> += <name> System libraries will be used for all archs of the specified osclass for linking named product. <prodname>_SYS_LIBS_DEFAULT += <name> System libraries to be used for any arch that does not have a <prodname>_LIBS_<osclass> definition when linking named product. #### The order of dependant libraries¶ Dependant library names appear in the following order on a product link line: 1. <prodname>_LIBS 2. <prodname>_LIBS_<osclass> or <prodname>_LIBS_DEFAULT 3. PROD_LIBS 4. PROD_LIBS_<osclass> or PROD_LIBS_DEFAULT 5. USR_LIBS 6. USR_LIBS_<osclass> or USR_LIBS_DEFAULT 7. <prodname>_SYS_LIBS 8. <prodname>_SYS_LIBS_<osclass> or <prodname>_SYS_LIBS_DEFAULT 9. PROD_SYS_LIBS 10. PROD_SYS_LIBS_<osclass> or PROD_SYS_LIBS_DEFAULT 11. USR_SYS_LIBS 12. USR_SYS_LIBS_<osclass> or USR_SYS_LIBS_DEFAULT #### Specifying product version number¶ On WIN32 only a product version number can be specified as follows: PROD_VERSION += <version> This results in “/version:$(PROD_VERSION)” link option.

A header can be generated which defines a single string macro with an automatically generated identifier. The default is the ISO 8601 formatted time of the build. A revision id is used if a supported version control system is present. This will typically be used to make an automatically updated source version number visible at runtime (eg. with a stringin record).

To enable this the variable GENVERSION must be set with the desired name of the generated header. By default this variable is empty and no header will be generated. If specified, this variable must be set before configure/RULES is included.

It is also necessary to add an explicit dependency for each source file which includes the generated header.

An Makefile which generates a version header named “myversion.h” included by “devVersionString.c” would have the following.

TOP=../..
include $(TOP)/configure/CONFIG # ... define PROD or LIBRARY names sometarget sometarget_SRCS = devVersionString.c GENVERSION = myversion.h include$(TOP)/configure/RULES
# for each source file
devVersionString$(DEP):$(GENVERSION)

The optional variables GENVERSIONMACRO and GENVERSIONDEFAULT give the name of the C macro which will be defined in the generated header, and its default value if no version control system is being used. To avoid conflicts, the macro name must be changed from its default MODULEVERSION if the version header is to be installed.

#### 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 definition of STATIC_BUILD (YES/NO) in base/configure/ 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 definition for STATIC_BUILD in the EPICS base CONFIG_SITE distribution file is NO. A STATIC_BUILD definition in a Makefile will override the definition 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.

### Java class files¶

Java class files can be created by the javac tool into $(INSTALL_JAVA) or into the O.Common subdirectory, by specifying the name of the java class file in the Makefile. Command line options for the javac tool can be specified. The configuration files set the java c option “-sourcepath .:..:../..”. Any of the following can be specified: JAVA += <name>.java The <name>.java file will be used to create the <name>.class file in the$(INSTALL_JAVA) directory.

TESTJAVA += <name>.java

The <name>.java files will be used to create the <name>.class file in the O.Common subdirectory.

USR_JAVACFLAGS += <name>

The javac option <name> will be used on the javac command lines.

In this example, three class files are created in $(INSTALL_LOCATION)/javalib/mytest. The javac depreciation flag is used to list the description of each use or override of a deprecated member or class. JAVA = mytest/one.java JAVA = mytest/two.java JAVA = mytest/three.java USR_JAVACFLAGS = -deprecation #### Example 2¶ In this example, the test.class file is created in the O.Common subdirectory. TESTJAVA = test.java ### Java jar file¶ A single java jar file 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 files to be included in the created jar file. The jar input file names must appear with a directory prefix. Any of the following can be specified: JAR += <name> The <name> jar file will be created and installed into the$(INSTALL_JAVA) directory.

JAR_INPUT += <name>

Names of images, audio files and classes files to be included in the jar file.

JAR_MANIFEST += <name>

The preexisting manifest file will be used for the created jar file.

JAR_PACKAGES += <name>

Names of java packages to be installed and added to the created jar file.

#### Example 1¶

In this example, all the class files created by the current Makefile’s “JAVA+=” definitions, are placed into a file named mytest1.jar. A manifest file will be automatically generated for the jar.

Note: $(INSTALL_CLASSES) is set to$(addprefix $(INSTALL_JAVA)/,$(CLASSES)) in the EPICS base configure files.

JAR = mytest1.jar
JAR_INPUT = $(INSTALL_CLASSES) #### Example 2¶ In this example, three class files are created and placed into a new jar archive file named mytest2.jar. An existing manifest file, mytest2.mf is put into the new jar file. JAR = mytest2.jar JAR_INPUT =$(INSTALL_JAVA)/mytest/one.class
JAR_INPUT = $(INSTALL_JAVA)/mytest/two.class JAR_INPUT =$(INSTALL_JAVA)/mytest/three.class
JAR_MANIFEST = mytest2.mf

### Java native method C header files¶

A C header files 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 file to be created. The name of the java class file used to generate the header is derived from the name of the header file. Underscores (_) are used as a header file name delimiter. Command line options for the javah tool can be specified.

Any of the following can be specified:

JAVAINC += <name>.h

The <name>.h header file will be created in the O.Common subdirectory.

USR_JAVAHFLAGS += <name>

The javah option <name> will be used on the javah tool command line.

#### 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 file$(INSTALL_JAVA)/xx/yy/zz.class)). The option “-old” will tell javah to create old JDK1.0 style header files.

JAVAINC = xx_yy_zz.h USR_JAVAHFLAGS = -old

### User Created CONFIG* and RULES* files¶

Module developers can now create new CONFIG and RULES* files ia a <top> application source directory. These new CONFIG* or RULES* files will be installed into the directory $(INSTALL_LOCATION)/cfg by including lines like the following Makefile line: CFG += CONFIG_MY1 RULES_MY1 The build will install the new files 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 definitions and rules in them are available for use by later src directory Makefiles in the same module or by other modules with a RELEASE line pointing to the TOP of this module. ### User Created File Types¶ Module developers can now define a new type of file, e.g. ABC, so that files of type ABC will be installed into a directory defined by INSTALL_ABC. This is done by creating a new CONFIG_<name> file, e.g. CONFIG_ABC, with the following lines: FILE_TYPE += ABC INSTALL_ABC =$(INSTALL_LOCATION)/abc

The INSTALL_ABC directory should be a subdirectory of $(INSTALL_LOCATION). The file type ABC should be target architecture independent (alh files, medm files, edm files. Optional rules necessary for files of type ABC should be put in a RULES_ABC file. The module developer installs new CONFIG_ABC and RULES_ABC files for the new file type into the directory$(INSTALL_LOCATION)/cfg by including the following Makefile line:

CFG += CONFIG_ABC RULES_ABC

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

ABC += <filename1> <filename2> <filename3>

Since the files in $(INSTALL_LOCATION)/cfg directory are now included by the base config files, the ABC += definition lines are available for use by later src directory Makefiles in the same module or by other modules with a RELEASE line pointing to the TOP of this module. ### Assemblies¶ A single output file is generated from assembling specified snippet files. Snippet file names start with numbers and are sorted when the snippets are concatenated: first by the number, then alphabetical by the remaining part of the name. (This mechanism is conceptually similar to the Linux convention of collecting configuration file snippets in *.d directories.) Snippets with file names not starting with a number or ending in ‘~’ are ignored. The specified 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: • D - Default. Snippet is treated as a default, which is replaced (overwritten) by any other snippet with the same number. • R - Replace. Snippet is replacing (overwriting) already processed snippets with the same number. Specification of the target file is different for architecture dependent or independent files. COMMON_ASSEMBLIES += st.cmd ASSEMBLIES += mytool.rc Snippet files are configured specifically (relative or absolute path) or as patterns (searched relative to all source directories). mytool.rc_SNIPPETS += ../rc.d/10_head ../rc.d/20_init st.cmd_PATTERN += st.cmd.d/* #### Macros¶ The following macros can be used in snippets, and will be replaced by the current value when assembling is done. • _DATETIME_ Date and time of the build • _USERNAME_ Name of the user running the build • _HOST_ Name of the host on which the build is run • _OUTPUTFILE_ Name of the generated file • _SNIPPETFILE_ Name of the current snippet #### Example¶ This mechanism can be used to create an IOC startup file from snippets in a global and an application specific directory, allowing applications to add commands to different phases of the IOC startup by dropping appropriately numbered snippets into the directory. Given the following directories and snippets: /global/st.cmd.d: (G=GLOBAL) D10_init 20_environment 30_drivers D40_settings 70_start-ioc ../st.cmd.d: (L=LOCAL) D10_init 40_settings 40_settings~ 30_another-driver R70_start-my-ioc And the following Makefile declaration: SCRIPTS +=$(COMMON_DIR)/st.cmd
COMMON_ASSEMBLIES += st.cmd

## Configuration Files¶

### Base Configure Directory¶

The base/configure directory has the following directory structure:

base/
configure/
os/
tools/

### Base Configure File Descriptions¶

The configure files contain definitions and make rules to be included in the various makefiles.

CONFIG.CrossCommon

Definitions for all hosts and all targets for a cross build (host different than target).

CONFIG.gnuCommon

Definitions for all hosts and all targets for builds using the gnu compiler.

Definitions which setup the variables that have <osclass> and DEFAULT options.

CONFIG_APP_INCLUDE

Definitions to generate include, bin, lib, perl module, db, and dbd directory definitions for RELEASE <top>s.

CONFIG_BASE

EPICS base specific definitions.

CONFIG_BASE_VERSION

Definitions for the version number of EPICS base. This file is used for creating epicsVersion.h which is installed into base/include.

CONFIG_COMMON

Definitions common to all builds.

CONFIG_ENV

Default definitions of the EPICS environment variables. This file is used for creating envData.c which is included in the Com library.

CONFIG_FILE_TYPE

Definitions to allow user created file types.

CONFIG_SITE

File in which you add to or modify make variables in EPICS base. A definition commonly overridden is CROSS_COMPILER_TARGET_ARCHS

CONFIG_SITE_ENV

Defaults for site specific definitions of EPICS environment variables. This file is used for creating envData.c which is included in the Com library.

CONFIG

Include statements for all the other configure files. You can override any definitions in other CONFIG* files by placing override definitions at the end of this file.

RELEASE

Specifies the location of external products such as Tornado II and external <tops> such as EPICS base.

RULES

This file just includes the appropriate rules configuration file.

RULES.Db

Rules for building and installing database and database definition files. Databases generated from templates and/or CapFast schematics are supported.

RULES.ioc

Rules which allow building in the iocBoot/<iocname> directory of a makeBaseApp created ioc application.

RULES_ARCHS

Definitions and rules which allow building the make target for each target architecture.

RULES_BUILD

Build rules for the Makefiles

RULES_DIRS

Definitions and rules which allow building the make targets in each subdirectory. This file is included by Makefiles in directories with subdirectories to be built.

RULES_EXPAND

Definitions and rules to use expandVars.pl to expand @VAR@ variables in a file.

RULES_FILE_TYPE

Definitions and rules to allow user created CONFIG* and RULES* files and rules to allow user created file types.

RULES_JAVA Definitions and rules which allow building java class files and java jar files. RULES_TARGET

Makefile code to create target specific dependency lines for libraries and product targets.

RULES_TOP

Rules specific to a <top> level directory e.g. uninstall and tar. It also includes the RULES_DIRS file.

Makefile Definitions to allow creation of CONFIG_APP_INCLUDE and installation of the CONFIG* files into the $(INSTALL_LOCATION) directory. ### Base configure/os File Descriptions¶ The configure/os directory contains os specific make definitions. The naming convention for the files in this directory is CONFIG.<host>.<target> where <host> is either the arch for a specific host system or Common for all supported host systems and <target> is either the arch for a specific target system or Common for all supported target systems. For example, the file CONFIG.Common.vxWorks-pentium will contain make definitions 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 files have the same make definitions these common definitions can be moved to a new file which is then included in each host or target file. An example of this is all Unix hosts which have common definitions in a CONFIG.UnixCommon.Common file and all vxWorks targets with definitions in CONFIG.Common.vxWorksCommon. The base/configure/os directory contains the following os-arch specific definitions CONFIG.<host>.<target> Specific host-target build definitions CONFIG.Common.<target> Specific target definitions for all hosts CONFIG.<host>.Common Specific host definitions for all targets CONFIG.UnixCommon.Common Definitions for Unix hosts and all targets CONFIG.<host>.vxWorksCommon Specific host definitions for all vx targets CONFIG_COMPAT R3.13 arch compatibility definitions CONFIG_SITE.<host>.<target> Site specific host-target definitions CONFIG_SITE.Common.<target> Site specific target definitions for all hosts CONFIG_SITE.<host>.Common Site specific host definitions for all targets ### 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: convertRelease.pl This Perl script does consistency checks for the external <top> definitions in the RELEASE file. This script also creates envPaths, cdCommands, and dllPath.bat files for vxWorks and other IOCs. cvsclean.pl This perl script finds and deletes cvs .#* files in all directories of the directory tree. dos2unix.pl This perl script converts text file in DOS CR/LF format to unix ISO format. expandVars.pl This perl tool expands @VAR@ variables while copying a file. filterWarnings.pl This is a perl script that filters compiler warning output (for HP-UX). fullpathname.pl This perl script returns the fullpathname of a file. installEpics.pl This is a Perl script that installs build created files into the install directories. makeDbDepends.pl This perl script searches .substitutions and .template files for entries to create a DEPENDS file. makeIncludeDbd.pl This perl script creates an include dbd file from file names makeMakefile.pl This is a perl script that creates a Makefile in the created O.<arch> directories. makeTestfile.pl This perl script generates a file$target.t which executes a real test program in the same directory.
mkmf.pl
This perl script generates include file dependencies for targets from source file include statements.
munch.pl
This is a perl script that creates a ctdt.c file for vxWorks target arch builds which lists the c++ static constructors and destructors. See munching in the vxWorks documentation for more information.
replaceVAR.pl
This is a perl script that changes VAR(xxx) style macros in CapFast generated databases into the \$(xxx) notation used in EPICS databases.
useManifestTool.pl
This tools uses MS Visual C++ compiler version number to determine if we want to use the Manifest Tool (status=1) or not (status=0).

## Build Documentation Files¶

### Base Documentation Directory¶

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

### Base Documentation File Descriptions¶

The files currently in the base/documentation directory are:

Instructions for setup and building epics base
Microsoft WIN32 specific instructions
NI cpu030 specific instructions

HPUX 11 (hpux-parisc) specific instructions
Cris architecture specific instructions
Tru64Unix/Alpha specific instructions
Installation notes for Mac OS X (Darwin)
BuildingR3.13AppsWithR3.14.html
Describes how to modify a R3.13 vxWorks application so that it builds with release R3.14.1.
ConvertingR3.13AppsToR3.14.html
Describes how to convert a R3.13 vxWorks application so that it contains a R3.14 configure directory and R3.14 Makefiles and builds with R3.14.1.
ConvertingR3.14.0alpha2AppsTobeta1.html
Describes how to modify a R3.14.0alpha1 application so that it builds with release R3.14.0beta1.
ConvertingR3.14.0beta1AppsTobeta2.html
Describes how to modify a R3.14.0beta1 application so that it builds with release R3.14.0beta2.
ConvertingR3.14.0beta2AppsToR3.14.1.html
Describes how to modify a R3.14.0beta2 application so that it builds with release R3.14.1.
ConvertingR3.14.*AppsToR3.14.*.html
Describes how to modify a R3.14.* application so that it builds with next release after R3.14.*.
BuildingR3.13ExtensionsWithR3.14.html
Describes how to modify a R3.13 extension so that it builds with release R3.14.1.
RELEASE_NOTES.html
Describes changes in the R3.14.1 release
KnownProblems.html
List of known problems in EPICS base R3.14.1.
ReleaseChecklist.html
Checklist of things that must be done when creating a new release of EPICS Base.

## Startup Files¶

### Base Startup Directory¶

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

### Base Startup File Descriptions¶

The scripts currently in the base/startup directory are:

EpicsHostArch
c shell script to set EPICS_HOST_ARCH environment variable
EpicsHostArch.pl
perl script to set EPICS_HOST_ARCH environment variable
Site.profile
Unix bourne shell script to set path and environment variables
Site.cshrc
Unix c shell script to set path and environment variables
cygwin.bat
WIN32 bat file to set path and environment variables for building with cygwin gcc/g++ compilers
win32.bat
WIN32 bat file to set path and environment variables for building with MS Visual C++ compilers