Skip to content
Snippets Groups Projects
user avatar
Janet B. Anderson authored
22b550ed
History
$Id$

----------------------------------------------------------------------------
3.13 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 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 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.
   gnumake rebuild     - Same as "gnumake clean uninstall 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.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