$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 base/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 specify the perl full pathname  as /usr/bin/perl for
   unix builds and C:\Perl\bin\perl for WIN95/NT builds. You can override
   these specifications with a CONFIG_SITE_HOST_ARCH.<host_arch> file. 

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 shell scripts 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