4. Building Components

4.1. Locating Make Rules

Most directories in a <top> which contain human editable files also contain one or more Makefiles. A Makefile normally includes a file from <top>/config. Thus the Makefile "inherits" rules and definitions from config. The files in config may in turn include files from <base>/config or from some <supporttop>/config . This technique makes it possible to share make variables and even rules across applications.

gnumake can be executed in any subdirectory where a Makefile appears, which is almost every subdirectory. Executing gnumake in a particular directory usually causes it to descend into any subdirectories and run any Makefiles found there as well.

<top>

The most useful commands at the top level directory are:

gnumake: This rebuilds and installs everything which is not up to date.; NOTE: Executing gnumake without arguments is the same as gnumake install
gnumake clean: This can be used to save disk space by deleting the O.<arch> directories from the xxxApp areas, but does not remove any installed files from the bin, db, dbd etc. directories.
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 clean uninstall: This command removes everything created and installed by gnumake.
gnumake tar: This command makes a tar image of the entire <top> directory (excluding any CVS directories).

config

Starting with release 3.13.2 running gnumake in this directory creates the file CONFIG_APP_INCLUDE.

xxxApp

Two useful commands at this level are gnumake or gnumake rebuild, which are the same as issuing the same command in each subdirectory of xxxApp.

xxxsrc xxxSrc: Running the command gnumake (which is the same as executing gnumake install) builds and installs all out of date host and IOC components described by the files Makefile.Host and Makefile.Vx. The builds are performed in subdirectories O.<arch>.; It is possible to build for a single architecture via the command gnumake <arch>. For example, if your IOC uses an MVME167 CPU, then the build directory used is O.mv167, and the command is gnumake mv167.; Another useful command is gnumake clean which deletes the O.<arch> build directories created by make. .<arch> can be appended to invoke clean for a single architecture.; The command gnumake rebuild is the same as gnumake clean install.
xxxdb xxxDb: Executing gnumake in this directory generates and installs database instance files, template and substitution files from plain sources or CapFast schematics.

iocBoot

Executing gnumake here is the same as issuing gnumake in each subdirectory of iocBoot.

iocxxx: Executing gnumake in these directories creates their cdCommands files. See the section <top>/iocBoot/iocxxx/Makefile below for details.

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>: sun4, solaris, hp700, mv167, etc. - builds named architecture only.; host - builds for host architecture only.; cross - builds for vxWorks architecture(s) only.
<action>: clean, inc, install, build, rebuild, buildInstall, uninstall, or tar; NOTE: uninstall and tar can only be specified at <top>
<dir>: subdirectory name

4.3. Description of Makefiles

<top>/Makefile

This makefile performs a gnumake in the xxxApp and iocBoot subdirectories. In addition it allows the top level make options uninstall and tar as described in the previous section. There is seldom need to modify this file.

<top>/xxxApp/Makefile

This makefile just executes gnumake in each *src*, *Src* , *db* and *Db* subdirectory.

<top>/xxxApp/src/Makefile.Host

The following IOC related components can be built:

Breakpoint Tables

For each breakpoint table add the definition

BPTS += <table name>.dbd

Record Support

For each new record type, the following definition should be added to the makefile:

RECTYPES += <rectype>Record.h

and the associated record support file <rectype>Record.dbd must exist.

If a menuXXX.dbd file is present, then add the following definition:

MENUS += menu<name>.h

Expanded Database Definition File

Files containing database definition files are expanded by utility dbExpand and installed into <top>/dbd. The following variables control the process:

DBDEXPAND += xxxInclude.dbd
DBDNAME = xxxApp.dbd
USER_DBDFLAGS += -I <include path>
USER_DBDFLAGS += -S <macro substitutions>

DBDINSTALL += xxx.dbd

where the entries are:

DBDEXPAND: A list of files containing database definitions to be expanded.
DBDNAME: The name of the output file to contain the expanded definitions which will be installed into <top>/dbd.
USER_DBDFLAGS: Flags for dbExpand. Currently only an include path and macro substitution are supported.
DBDINSTALL: Installs the named files into <top>/dbd without expansion.

Makefile.Host has many facilities for building host components. Definitions given below containing <arch> can be used to provide settings for use when building for a specific host architecture, and the <arch> part of the name should be replaced by the architecture concerned, e.g. solaris, hp700 etc. If a _DEFAULT setting is given but a particular <arch> requires that the default not be used and the required setting is blank, the value "-nil-" should be assigned to the relevent <arch> variable definition.

Products to be built

PROD Product names (without execution suffix) to build and install (e.g. PROD=myprod)

SRCS Source files needed by every PROD (e.g. SRCS=a.c b.c c.c)

<prod>_SRCS Source files needed to build a specific PROD (e.g. myprod_SRCS=a.c b.c c.c)

PROD_<arch> os specific products to build and install

<prod>_SRCS_<arch> os specific source files to build a specific PROD

PROD_DEFAULT products to build and install for systems with no PROD_<arch> specified

<prod>_SRCS_DEFAULT source files needed to build a specific PROD for systems with no <prod>_SRCS_<arch> specified

Building libraries

LIBRARY Name of library to build. The name should NOT include a prefix or extension, e.g. specify Ca to build libCa.a on Unix, Ca.lib, CaObj.lib or Ca.dll on WIN32

LIBSRCS Source files for building LIBRARY (e.g. LIBSRCS=la.c lb.c lc.c)

LIBSRCS_<arch> os-specific library source files

LIBSRCS_DEFAULT Library source files for systems with no LIBSRCS_<arch> specified

SHARED_LIBRARIES Build shared libraries? Must be YES or NO

SHARED_LIBRARIES_<arch> Build shared libraries on <arch>? Must be YES or NO

SHARED_LIBRARIES_DEFAULT Build shared libraries for os systems with no SHARED_LIBRARIES_<arch> specified

SHRLIB_VERSION Shared library version number

Compiler flags

USR_CFLAGS C compiler flags for all systems

USR_CFLAGS_<arch> os-specific C compiler flags

USR_CFLAGS_DEFAULT C compiler flags for systems with no USR_CFLAGS_<arch> specified

<prod>_CFLAGS prod specific C compiler flags (e.g. xxxRecord_CFLAGS=-g)

USR_CXXFLAGS C++ compiler flags for all systems

USR_CXXFLAGS_<arch> os-specific C++ compiler flags

USR_CXXFLAGS_DEFAULT C++ compiler flags for systems with no USR_CXXFLAGS_<arch> specified

<prod>_CXXFLAGS prod specific C++ compiler flags

USR_CPPFLAGS C pre-processor flags (for all makefile compiles)

USR_CPPFLAGS_<arch> os specific cpp flags

USR_CPPFLAGS_DEFAULT cpp flags for systems with no USR_CPPFLAGS_<arch> specified

<prod>_CPPFLAGS prod specific C pre-processor flags (e.g. xxxRecord_CPPFLAGS=-DDEBUG)

USR_INCLUDES Directories to search for include files with -I prefix (e.g. -I$(EPICS_EXTENSIONS_INCLUDE))

<prod>_INCLUDES Directories to search for include files when building a specific product(e.g. -I$(MOTIF_INC))

Linker options

USR_LDFLAGS linker options (for all makefile links)

USR_LDFLAGS_<arch> os specific linker options (for all makefile links)

USR_LDFLAGS_DEFAULT linker options for systems with no USR_LDFLAGS_<arch> specified

<prod>_LDFLAGS prod specific ld flags

USR_LIBS load libraries (e.g. -lXt -lX11) (for all makefile links)

USR_LIBS_<arch> os specific load libraries (for all makefile links)

USR_LIBS_DEFAULT load libraries for systems with no USR_LIBS_<arch> specified

<prod>_LIBS prod specific ld libraries (e.g. probe_LIBS=X11 Xt)

PROD_LIBS libs needed to link every PROD for all systems

PROD_LIBS_<arch> os-specific libs needed to link every PROD

PROD_LIBS_DEFAULT libs needed to link every PROD for systems with no PROD_LIBS_<arch> specified

<lib>_DIR Directory to search for the specified lib. (For libs listed in PROD_LIBS, <prod>_LIBS and USR_LIBS)

SYS_PROD_LIBS system libs needed to link every PROD for all systems

SYS_PROD_LIBS_<arch> os-specific system libs needed to link every PROD

SYS_PROD_LIBS_DEFAULT system libs needed to link every PROD for systems with no SYS_PROD_LIBS_<arch> specified

<prod>_SYS_LIBS prod specific system ld libraries (e.g. m)

Header files to be installed

INC List of include files to install into $(INSTALL_DIR)/include

INC_<arch> os specific includes to installed under $(INSTALL_DIR)/include/os/<arch>

INC_DEFAULT include files to install where no INC_<arch> is specified

Perl, csh, tcl etc. script installation

SCRIPTS scripts to install for all systems

SCRIPTS_<arch> os-specific scripts to install

SCRIPTS_DEFAULT scripts to install for systems with no SCRIPTS_<arch> specified

TCLLIBNAME List of tcl scripts to install into $(INSTALL_DIR)/lib/<arch> (Unix hosts only)

TCLINDEX Name of tcl index file to create from TCLLIBNAME scripts

Test programs

TESTPROD Product names (without execution suffix) to build but not install. Built from source file having same name.

TESTPROD_SRCS List of source files needed to build every TESTPROD

Documentation

MAN1 MAN2 MAN3 etc. List of man files to be installed into relevent $(INSTALL_DIR)/man/man? subdirectory

DOCS List of text files to be installed into the $(INSTALL_DIR)/doc directory

HTMLS_DIR Hypertext directory to be created as $(INSTALL_DIR)/html/$(HTMLS_DIR)

HTMLS List of files 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 List of template files to be installed into $(TEMPLATE_DIR)

Options for other programs

YACCOPT yacc options

LEXOPT lex options

SNCFLAGS snc options

E2DB_FLAGS e2db options

SCH2EDIF_FLAGS sch2edif options

RANLIBFLAGS ranlib options

Miscellaneous settings

CMPLR C compiler selection, TRAD, ANSI or STRICT (default is STRICT)

INSTALL_LOCATION Location of install directory (default $(TOP))

USER_VPATH List of directories that gnumake should search for source files not in the current directory

HOST_WARN Are compiler warning messages desired (YES or NO) (default is NO)

HOST_OPT Is compiler optimization desired (default is NO optimization)

STATIC_BUILD Is static build desired (YES or NO) (default is NO)

Facilities for building Java programs

CLASSES Names of Java classes to be built and installed

TESTCLASSES Names of Java classes to be built

PACKAGE Names of Java package to be installed

JAR Name of Jar file to be built

JAR_INPUT Names of files to be included in JAR

MANIFEST Name of manifest file for JAR

Facilities for Windows 95/NT resource (.rc) files

RCS Resource files needed to build every PROD

<prod>_RCS Resource files needed to build a specific PROD

<prod>_RCS_<arch> os specific resource files to build a specific PROD

Products to be built
PROD	Product names (without execution suffix) to build and install (e.g. `PROD=myprod`)
SRCS	Source files needed by every PROD (e.g. `SRCS=a.c b.c c.c`)
<prod>_SRCS	Source files needed to build a specific PROD (e.g. `myprod_SRCS=a.c b.c c.c`)
PROD_<arch>	os specific products to build and install
<prod>_SRCS_<arch>	os specific source files to build a specific PROD
PROD_DEFAULT	products to build and install for systems with no PROD_<arch> specified
<prod>_SRCS_DEFAULT	source files needed to build a specific PROD for systems with no <prod>_SRCS_<arch> specified
Building libraries
LIBRARY	Name of library to build. The name should NOT include a prefix or extension, e.g. specify `Ca` to build `libCa.a` on Unix, `Ca.lib`, `CaObj.lib` or `Ca.dll` on WIN32
LIBSRCS	Source files for building LIBRARY (e.g. `LIBSRCS=la.c lb.c lc.c`)
LIBSRCS_<arch>	os-specific library source files
LIBSRCS_DEFAULT	Library source files for systems with no LIBSRCS_<arch> specified
SHARED_LIBRARIES	Build shared libraries? Must be `YES` or `NO`
SHARED_LIBRARIES_<arch>	Build shared libraries on <arch>? Must be `YES` or `NO`
SHARED_LIBRARIES_DEFAULT	Build shared libraries for os systems with no SHARED_LIBRARIES_<arch> specified
SHRLIB_VERSION	Shared library version number
Compiler flags
USR_CFLAGS	C compiler flags for all systems
USR_CFLAGS_<arch>	os-specific C compiler flags
USR_CFLAGS_DEFAULT	C compiler flags for systems with no USR_CFLAGS_<arch> specified
<prod>_CFLAGS	prod specific C compiler flags (e.g. `xxxRecord_CFLAGS=-g`)
USR_CXXFLAGS	C++ compiler flags for all systems
USR_CXXFLAGS_<arch>	os-specific C++ compiler flags
USR_CXXFLAGS_DEFAULT	C++ compiler flags for systems with no USR_CXXFLAGS_<arch> specified
<prod>_CXXFLAGS	prod specific C++ compiler flags
USR_CPPFLAGS	C pre-processor flags (for all makefile compiles)
USR_CPPFLAGS_<arch>	os specific cpp flags
USR_CPPFLAGS_DEFAULT	cpp flags for systems with no USR_CPPFLAGS_<arch> specified
<prod>_CPPFLAGS	prod specific C pre-processor flags (e.g. `xxxRecord_CPPFLAGS=-DDEBUG`)
USR_INCLUDES	Directories to search for include files with `-I` prefix (e.g. `-I$(EPICS_EXTENSIONS_INCLUDE)`)
<prod>_INCLUDES	Directories to search for include files when building a specific product(e.g. `-I$(MOTIF_INC)`)
Linker options
USR_LDFLAGS	linker options (for all makefile links)
USR_LDFLAGS_<arch>	os specific linker options (for all makefile links)
USR_LDFLAGS_DEFAULT	linker options for systems with no USR_LDFLAGS_<arch> specified
<prod>_LDFLAGS	prod specific ld flags
USR_LIBS	load libraries (e.g. `-lXt -lX11`) (for all makefile links)
USR_LIBS_<arch>	os specific load libraries (for all makefile links)
USR_LIBS_DEFAULT	load libraries for systems with no USR_LIBS_<arch> specified
<prod>_LIBS	prod specific ld libraries (e.g. `probe_LIBS=X11 Xt`)
PROD_LIBS	libs needed to link every PROD for all systems
PROD_LIBS_<arch>	os-specific libs needed to link every PROD
PROD_LIBS_DEFAULT	libs needed to link every PROD for systems with no PROD_LIBS_<arch> specified
<lib>_DIR	Directory to search for the specified lib. (For libs listed in PROD_LIBS, <prod>_LIBS and USR_LIBS)
SYS_PROD_LIBS	system libs needed to link every PROD for all systems
SYS_PROD_LIBS_<arch>	os-specific system libs needed to link every PROD
SYS_PROD_LIBS_DEFAULT	system libs needed to link every PROD for systems with no SYS_PROD_LIBS_<arch> specified
<prod>_SYS_LIBS	prod specific system ld libraries (e.g. `m`)
Header files to be installed
INC	List of include files to install into `$(INSTALL_DIR)/include`
INC_<arch>	os specific includes to installed under `$(INSTALL_DIR)/include/os/<arch>`
INC_DEFAULT	include files to install where no INC_<arch> is specified
Perl, csh, tcl etc. script installation
SCRIPTS	scripts to install for all systems
SCRIPTS_<arch>	os-specific scripts to install
SCRIPTS_DEFAULT	scripts to install for systems with no SCRIPTS_<arch> specified
TCLLIBNAME	List of tcl scripts to install into `$(INSTALL_DIR)/lib/<arch>` (Unix hosts only)
TCLINDEX	Name of tcl index file to create from TCLLIBNAME scripts
Test programs
TESTPROD	Product names (without execution suffix) to build but not install. Built from source file having same name.
TESTPROD_SRCS	List of source files needed to build every TESTPROD
Documentation
MAN1 MAN2 MAN3 etc.	List of man files to be installed into relevent `$(INSTALL_DIR)/man/man?` subdirectory
DOCS	List of text files to be installed into the `$(INSTALL_DIR)/doc` directory
HTMLS_DIR	Hypertext directory to be created as `$(INSTALL_DIR)/html/$(HTMLS_DIR)`
HTMLS	List of files 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	List of template files to be installed into `$(TEMPLATE_DIR)`
Options for other programs
YACCOPT	yacc options
LEXOPT	lex options
SNCFLAGS	snc options
E2DB_FLAGS	e2db options
SCH2EDIF_FLAGS	sch2edif options
RANLIBFLAGS	ranlib options
Miscellaneous settings
CMPLR	C compiler selection, `TRAD`, `ANSI` or `STRICT` (default is `STRICT`)
INSTALL_LOCATION	Location of install directory (default `$(TOP)`)
USER_VPATH	List of directories that gnumake should search for source files not in the current directory
HOST_WARN	Are compiler warning messages desired (`YES` or `NO`) (default is `NO`)
HOST_OPT	Is compiler optimization desired (default is `NO` optimization)
STATIC_BUILD	Is static build desired (`YES` or `NO`) (default is `NO`)
Facilities for building Java programs
CLASSES	Names of Java classes to be built and installed
TESTCLASSES	Names of Java classes to be built
PACKAGE	Names of Java package to be installed
JAR	Name of Jar file to be built
JAR_INPUT	Names of files to be included in JAR
MANIFEST	Name of manifest file for JAR
Facilities for Windows 95/NT resource (`.rc`) files
RCS	Resource files needed to build every PROD
<prod>_RCS	Resource files needed to build a specific PROD
<prod>_RCS_<arch>	os specific resource files to build a specific PROD

<top>/xxxApp/src/Makefile.Vx

Note that the rules for Makefile.Vx are older and subtly different to those for Makefile.Host. The following components can be built:

Record Support

For each new record type, the following definitions must be added to the makefile

LIBOBJS += <rectype>Record.o

and both source files <rectype>Record.c and <rectype>Record.dbd must exist.

Device, Driver, other C modules

For each such module, add a definition:

LIBOBJS += <name>.o

All such files will be combined into the library specified by LIBNAME. It is also possible to generate object files not placed in LIBNAME by using either of the definitions:

PROD += <name>.o
TARGETS += <name>.o

Both will cause the specified file to be generated, but PROD will also install the generated file into <top>/bin/<target_arch>.

Library files

A file containing all LIBOBJS is installed into <top>/bin/<arch> with the name specified by LIBNAME. For example:

LIBNAME = xxxLib

State Notation Programs

For each state notation program, add the definition:

LIBOBJS += <name>.o

The state notation programs must be called <name>.st .

Scripts, etc.

A definition of the form:

SCRIPTS += <name>

results in file <name> being installed from the src directory to the <top>/bin/<arch> directory.

iocCore and seq

In order to have iocCore and seq in the bin directory where the standard st.cmd file expects to find them, the following must appear:

INSTALLS += iocCore seq

NOTE: The above line only needs to appear in one application within each <ioctop>.

Other definitions:

USR_CFLAGS C compiler flags

<prod>_CFLAGS product specific C compiler flags

USR_CXXFLAGS C++ compiler flags

<prod>_CXXFLAGS product specific C++ compiler flags

CPPFLAGS cpp flags

<prod>_CPPFLAGS product specific cpp flags

USR_INCLUDES Include directory (e.g. -I$(EPICS_EXTENSIONS_BIN))

USR_LDFLAGS linker options

<prod>_LDFLAGS product specific ld flags

INC header files to install

BIN_INSTALLS Files in any directory to install to $(INSTALL_BIN)

YACCOPT yacc options

LEXOPT lex options

SNCFLAGS snc options

<prod>_SNCFLAGS product specific state notation language flags

VX_WARN Compiler warning messages desired (YES or NO) (default NO)

VX_OPT Is compiler optimization desired (YES or NO) (default is NO optimization)

INSTALL_LOCATION Installation directory (defaults to $(TOP))

<top>/xxxApp/xxxDb/Makefile.Host

This makefile creates and installs databases and related files.

Databases

Supported are:

Plain databases
- from dct/gdct/editor generated source files (*.db)
- from CapFast schematics (*.sch)
Template generated databases
- template database from dct/gdct/editor generated source file (*.template)
- template database from CapFast schematic (*.sch)
- substitutions file from editor generated source (*.substitutions)
- substitutions file generated by a script (e.g. querying a relational database)
Database optimization using the dbst tool (i.e. removing all fields with default values)

For template generated databases either the fully inflated database or the template and substitutions files may be installed (so the IOC may load the database using dbLoadRecords() or dbLoadTemplate() ).

For all these types of databases, the names of the files to install have to be specified. Make will figure out how to generate these files:

DB += xxx.db: Generates xxx.db depending on which source files exist. If xxx.db is template generated, the inflated database will be installed.
DB += xxx.template xxx.substitutions: Generates and installs these files, i.e. the database must be inflated on the IOC using dbLoadTemplate().

In order to record dependency information correctly all template files that are needed but not installed (i.e. those not listed in DB ), must be added to the USES_TEMPLATE variable:

USES_TEMPLATE += yyy.template
USES_TEMPLATE += $(SHARE)/installDb/zzz.template

If specified with a path (full or relative), the templates will be soft linked (UNIX) or copied (WIN) into the O.<arch> directory. After the first make run, template dependencies will be generated automatically.

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.

NOTE: 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.

Other definitions:

E2DB_FLAGS e2db options

SCH2EDIF_FLAGS sch2edif options

Related Files

Expanded Database Definition File

Files containing database definition files are expanded by utility dbExpand and installed into <top>/dbd. The following variables control the process:

DBDEXPAND += xxxInclude.dbd
DBDNAME = xxxApp.dbd
USER_DBDFLAGS += -I <include path>
USER_DBDFLAGS += -S <macro substitutions>

DBDINSTALL += xxx.dbd

where the entries are:

DBDEXPAND: A list of files containing database definitions to be expanded.
DBDNAME: The name of the output file to contain the expanded definitions which will be installed into <top>/dbd.
USER_DBDFLAGS: Flags for dbExpand. Currently only an include path and macro substitution are supported.
DBDINSTALL: Installs the named files into <top>/dbd without expansion.

Breakpoint Tables

For each breakpoint table add the following definition

BPTS += <table name>.dbd

<top>/iocBoot/Makefile

This executes gnumake in each iocxxx subdirectory.

<top>/iocBoot/iocxxx/Makefile

This makefile has a rule to generate the cdCommands file. Make sure that the definition:

ARCH = <arch>

refers to the correct architecture for your IOC processor.

Since cdCommands is generated, the user created and/or modified files can be independent of location, using the cdCommands definitions to provide path names where needed. See 3.2. Directory Structure: cdCommands for details.

Contents Previous Next