$Id$
----------------------------------------------------------------------------
3.12 EPICS BASE Notes and Build Instructions.
- By Matthew Needes
----------------------------------------------------------------------------
Notes:
1. Before you can build or really use EPICS, you must properly set the
environemnt variable HOST_ARCH. The epics/startup/HostArch script file
has been provided to set HOST_ARCH.
2. You must use GNU make (which is now THE supported make utility) for
the build, gnumake. Set your path so that a recent version (e.g.
V3.70) of gnumake is available.
----------------------------------------------------------------------------
Part 1 - Configuring and Building EPICS Base
----------------------------------------------------------------------------
1.1 To configure EPICS, edit the following files:
config/CONFIG_SITE - Build choices/HOST_ARCH/Vx location.
config/CONFIG_SITE.* - Location of X, etc.
config/CONFIG - For overriding specific variables.
1.2 To add a target architecture to EPICS:
cd base/config
cp CONFIG.mv167 CONFIG.YOUR_ARCH
edit CONFIG.YOUR_ARCH - For compiler flags / etc.
cp CONFIG.Vx.68k CONFIG.Vx.YOUR_ARCH_CLASS
cp CONFIG_SITE.Vx.68k CONFIG_SITE.Vx.YOUR_ARCH_CLASS
- ONLY IF you are adding a new architecture class,
see note in Appendix A.
edit CONFIG_BASE - Add architecture to list.
1.3 To build EPICS:
cd epics/base
gnumake - To build and install EPICS.
gnumake clean - To clean temporary object files. Top level
clean will remove all the O.ARCH dirs, not
only those specified in BUILD_ARCHS.
gnumake uninstall - Only available at the top level directory.
Cleans directories created by the install.
1.4 "Partial" build commands:
gnumake clean.sun4 - Cleans sun4 binaries in O.sun4 dirs only.
gnumake install.sun4 - Builds sun4 only.
gnumake install.mv167 - Builds mv167 only (a HOST_ARCH build must
be complete before this can be issued).
NOTES:
1. EPICS binaries and shellscripts are installed into the directory
$(INSTALL_LOCATION)/bin/ARCH.
2. EPICS libraries are installed into the $(INSTALL_LOCATION)/lib/ARCH
directory.
3. During a normal build (a "make" or "make install"), the "depends"
dependency will NOT be invoked. Only if "make depends" is run
explicitly, or a "make built_release" is performed will dependencies
be generated automatically.
4. Temporary objects are stored in src/DIR/O.ARCH, This allows objects
for multiple architectures to be maintained at the same time.
While developing source for EPICS, merely cd src/DIR/O.ARCH, and
invoke "make":
cd epics/base/src/db/O.mv167
make dbAccess.o
The above example instructs make to build dbAccess.o for the
mv167 target.
----------------------------------------------------------------------------
Part 2 --- Configuration Files in epics/base/config
----------------------------------------------------------------------------
CONFIG - This file is meant to be included in the low-level EPICS Makefiles.
It includes the other EPICS makefiles, and allows individual developers
and the EPICS system manager to override specific variables in the rest of
the configuration.
----------------------------------------------------------------------------
CONFIG_SITE - This file is meant to be changed only by the EPICS system
manager. It specifies:
HOST_ARCH: The system's host architecture (sun4/hp700/etc).
This now come from an environment variable.
CROSS_COMPILER_HOST_ARCHS: List of unix architectures with cross_compilers.
CROSS_COMPILER_TARGET_ARCHS: List of architectures to build epics for.
VX_DIR: Location of vxWorks.
STATIC_BUILD: Whether or not to build clients statically.
etc.
----------------------------------------------------------------------------
CONFIG.ARCH - This file defines a particular architecture. It
contains the following variables:
BUILD_TYPE: Unix / Vx
ARCH_CLASS: 68k / sun4 / hp700 / etc.
Architecture dependent build flags. The flag names / contents
depend on your architecture class.
----------------------------------------------------------------------------
----------------------------------------------------------------------------
CONFIG_SITE.ARCH - Contains site specific definitions pertaining to a
particular architecture. This file's primary usefulness is to
define site specific compile and link flags.
----------------------------------------------------------------------------
CONFIG_COMMON - Contains definitions describing the layout of base.
----------------------------------------------------------------------------
CONFIG_BASE - Defines what subdirectories get built by default under base.
----------------------------------------------------------------------------
RULES.Vx - Rules for building with VxWorks makefiles.
----------------------------------------------------------------------------
RULES.Unix - Rules for building with Unix makefiles.
----------------------------------------------------------------------------
RULES_TOP - Top level rules for building.
----------------------------------------------------------------------------
RULES_ARCHS
RULES_DIRS - Allows top-level type command syntax in low-level directories.
----------------------------------------------------------------------------
Table of files to change when building and adding architectures.
etc.
Filename SYS_MGR ADD_VX_ARCH ADD_UNIX_ARCH DEVELOPER
CONFIG m - - m
CONFIG_SITE m m m -
CONFIG_SITE_ENV m - - -
CONFIG.ARCH - c c -
CONFIG_SITE.ARCH - c c -
CONFIG.Vx.ARCH_CLASS - c* - -
RULES.Vx - - - -
RULES.Unix - - - -
CONFIG_BASE - - - -
CONFIG_COMMON - - - -
CONFIG_ENV - - - -
RULES_ARCHS - - - -
RULES_DIRS - - - -
RULES_TOP - - - -
m - Modify an existing file.
c - Create a new file.
* - Create an ARCH_CLASS file only if you are adding a
fundamentally new architecture, such as hp700 or
a SPARC VME board. If your board is 68k based,
you will not need to create CONFIG.Vx.68k,
since it already exists !
----------------------------------------------------------------------------
Part 3 --- Configuration File Inclusion Tree Examples
----------------------------------------------------------------------------
---------------------------- hkv2f example --------------------------------
(files are numbered in the order of their inclusion)
src/db/Makefile.Vx (An example EPICS makefile)
^ ^
| +--- 3. RULES.Vx
| Default rules.
+------- 2. CONFIG
^ ^ ^ ^
| | | |
| | | +- 1. CONFIG_SITE
| | | HOST_ARCH = sun4
| | | BUILD_ARCHS = $(HOST_ARCH) mv167 hkv2f
| | | VX_DIR = /vxworks
| | | More.
| | +--- 2. CONFIG_COMMON
| | General info about base.
| +----- 3. CONFIG.hkv2f
| ^ BUILD_TYPE = Vx
| | ARCH_CLASS = 68k
| | Arch Specific Compiler Flag Setup
| +--- a. CONFIG.Vx.68k
| Compiler/utility setup for ARCH_CLASS
+------- 4. CONFIG_SITE.hkv2f
Site Specific setup
---------------------------- sun4 example --------------------------------
(files are numbered in the order of their inclusion)
src/db/Makefile.Unix (An example EPICS makefile)
^ ^
| +--- 3. RULES.Unix
| Default rules.
+------- 2. CONFIG
^ ^ ^ ^
| | | |
| | | +- 1. CONFIG_SITE
| | | HOST_ARCH = sun4
| | | BUILD_ARCHS = $(HOST_ARCH) mv167 hkv2f
| | | VX_DIR = /vxworks
| | | More.
| | +--- 2. CONFIG_COMMON
| | General info about base.
| +----- 3. CONFIG.sun4
| BUILD_TYPE = Unix
| ARCH_CLASS = sun4
| Arch Specific Compiler Flag Setup
+------- 4. CONFIG_SITE.sun4
Directory locations
----------------------------------------------------------------------------
Part 4 --- EPICS makefile rules
----------------------------------------------------------------------------
Rules supported by lower level Makefiles:
depends - Generate include dependencies
build - Builds objects, using libraries from "build_libs"
install - Installs executables in bin/ARCH
clean - Cleans objects