$Id$
----------------------------------------------------------------------------
3.13 EPICS BASE Notes and Build Instructions.
- By Matthew Needes
----------------------------------------------------------------------------
Notes:
1. Before you can build or use EPICS, the environemnt variable HOST_ARCH
must be set. 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.
3. You must have perl installed. See the README.Perl in this directory. The
config files no longer specify the perl full pathname. You now need the
perl executable in your search path.
4. You may need vendors C and C++ compilers in your search path. (Check
the definitions of ACC and CCC in CONFIG.Host.<host_arch> or gnu GCC
and G++ if ANSI=GCC and CPLUSPLUS=GCC are specified in CONFIG_SITE).
4. For building base you must have echo in your search path. For unix host
builds you must also have ar, cp, rm, mv, ranlib, and mkdir in your search
path and /bin/chmod must exist.
----------------------------------------------------------------------------
Part 1 - Configuring and Building EPICS Base
----------------------------------------------------------------------------
1.1 To configure EPICS, edit the following file:
config/CONFIG_SITE - Build choices/HOST_ARCH/Vx location.
config/CONFIG_SITE_ENV - For site-specific environment settings
For a specific host architecture you may want to edit the following file
config/CONFIG_SITE.Host.<arch> - Override Host build settings for a host arch
config/CONFIG_SITE.Vx.<arch> - Override Vx build settings for a host arch
config/CONFIG_SITE_HOST_ARCH.<arch> - Override build settings for a host arch
Optionally you may want to edit the following files
config/CONFIG_SITE.Host - Override Host build settings for all host archs.
config/CONFIG_SITE.Vx - Override Vx build settings for all host archs.
config/CONFIG - Override build settings for all host archs.
1.2 To add a target architecture to EPICS:
cd base/config
cp CONFIG.Vx.mv167 CONFIG.Vx.YOUR_ARCH
edit CONFIG.Vx.YOUR_ARCH - For compiler flags / etc.
edit CONFIG_SITE - Add architecture to CROSS_COMPILER_TARGET_ARCHS list.
1.3 To build EPICS:
cd epics/base
gnumake - To install include files, build and install EPICS.
(Same as "gnumake inc install")
gnumake all - Same as "gnumake"
gnumake clean - To clean temporary object files. Top level
clean will remove the O.ARCH dirs specified
in BUILD_ARCHS.
gnumake uninstall - Only available at the top level directory.
Cleans directories created by the install.
gnumake rebuild - Same as "gnumake clean all"
1.4 "Partial" build commands:
The complete set of targets now supported are:
action
arch
action.arch
dir
dir.action
dir.arch
dir.action.arch
where:
action can be clean, inc, install, depends, or build
action can also be uninstall or rebuild at top level only
dir is the name of a subdirectory.
arch can be host, cross, sun4, solaris, mv167, ...
Examples are:
gnumake inc - To install include files
gnumake install.host - To build and install EPICS for host arch.
gnumake install.cross - To build and install EPICS for Vx archs.
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.Host.ARCH - This file defines a particular host architecture. It
contains the following variables:
ARCH_CLASS: solaris / sun4 / hp700 / etc.
Host architecture OS vendor C and C++ complier variables.
Architecture dependent build flags. The flag names / contents
depend on your architecture class.
----------------------------------------------------------------------------
CONFIG_HOST_ARCH.ARCH - This file contains the following variable:
WIND_HOST_TYPE: sun4-solaris2 / sun4-sunos4 / x86-win32 / etc.
----------------------------------------------------------------------------
----------------------------------------------------------------------------
CONFIG.Vx.ARCH - This file defines a particular target architecture. It
contains the following variables:
ARCH_CLASS: 68k / sun4 / hp700 / etc.
Architecture dependent build flags. The flag names / contents
depend on your architecture class.
CMPLR_SUFFIX: Vx GNU cross compiler suffix definition.
----------------------------------------------------------------------------
----------------------------------------------------------------------------
CONFIG_SITE.BUILD_TYPE.ARCH - Contains site specific definitions pertaining to a
particular architecture and build type. This file's primary usefulness is to
define site specific compile and link flags.
----------------------------------------------------------------------------
CONFIG_COMMON - Contains definitions describing the layout of base
and definitions common to all builds.
----------------------------------------------------------------------------
CONFIG.Host.UnixCommon - Contains host definitions common to all Unix archs.
----------------------------------------------------------------------------
CONFIG_BASE - Defines what subdirectories get built by default under base.
----------------------------------------------------------------------------
CONFIG_BASE_VERSION - Defines the version of base.
----------------------------------------------------------------------------
CONFIG_ENV - EPICS Environment Parameter configuration file.
----------------------------------------------------------------------------
CONFIG_SITE_ENV - EPICS Environment Parameter Site configuration file
----------------------------------------------------------------------------
RULES.Vx - Rules for building with Makefile.Vx makefiles.
----------------------------------------------------------------------------
RULES.Host - Rules for building with Makefile.Host 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.Host.ARCH - c c -
CONFIG_HOST_ARCH.ARCH - c c -
CONFIG_SITE.Host.ARCH - - - -
CONFIG.Vx.ARCH - c c -
CONFIG_SITE.ARCH - c c -
CONFIG.Vx.ARCH_CLASS - c* - -
RULES.Vx - - - -
RULES.Host - - - -
CONFIG_BASE - - - -
CONFIG_BASE_VERSION - - - -
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)
^ ^
| +--- 2. RULES.Vx
| Default rules.
+----1. CONFIG_BASE
^
|
+ 1. CONFIG
^^^^^^^
||||||+- 1. CONFIG_COMMON
|||||| General info about base.
|||||+-- 2. CONFIG_BASE_VERSION
||||| Base version.
||||+--- 3. CONFIG_SITE
|||| HOST_ARCH = sun4
|||| CROSS_COMPILER_TARGET_ARCHS = mv167 hkv2f
|||| VX_DIR = /vxworks
|||| More.
|||+---- 4. CONFIG_HOST_ARCH.sun4
||| WIND_HOST_TYPE = sun4-sunos4
||+----- 5. CONFIG.Vx
|| Definitions for Vx builds
|+------ 6. CONFIG.Vx.hkv2f
| ARCH_CLASS = 68k
| Arch Specific Compiler Flag Setup
| Vx GNU cross compiler suffix
+------- 7. CONFIG_SITE.Vx.hkv2f
Site Specific setup
---------------------------- sun4 example --------------------------------
(files are numbered in the order of their inclusion)
src/db/Makefile.Unix (An example EPICS makefile)
^ ^
| +--- 2. RULES.Vx
| Default rules.
+----1. CONFIG_BASE
^
|
+ 1. CONFIG
^^^^^
|||||+- 1. CONFIG_COMMON
||||| General info about base.
||||+-- 2. CONFIG_BASE_VERSION
|||| Base version.
|||+--- 3. CONFIG_SITE
||| HOST_ARCH = sun4
||| CROSS_COMPILER_TARGET_ARCHS = mv167 hkv2f
||| VX_DIR = /vxworks
||| More.
||+---- 4. CONFIG_HOST_ARCH.sun4
|| WIND_HOST_TYPE = sun4-sunos4
|+----- 5. CONFIG.Host.sun4
| ARCH_CLASS = sun4
| Arch Specific Compiler Flag Setup
| Vx GNU cross compiler suffix
+------ 6. CONFIG_SITE.Host.sun4
Site Specific setup