$Id$

3.12 EPICS BASE release notes and build instructions.
	- By Matthew Needes

----------------------------------------------------------------------------
   Part 1 - Configuring and Building EPICS Base
----------------------------------------------------------------------------

1.1  To configure EPICS, edit the following files:

   ../config/CONFIG_BASE        - Build choices/HOST_ARCH/Vx location
   ../config/CONFIG.Unix.*	- For host directories/compilers/etc.
   ../config/CONFIG.Vx.*	- For target directories/compilers/etc.

1.2  To add a target architecture to EPICS:

   cd ../config
   cp CONFIG_ARCH.mv167 CONFIG_ARCH.YOUR_ARCH
   edit CONFIG_ARCH.YOUR_ARCH    - For compiler flags / etc.

   cp CONFIG_CLASS_vx.68k CONFIG_CLASS_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:

   make			- To build and install EPICS.
   make clean		- To clean temporary object files.

1.4  To create an EPICS release:

   edit include/version.h	- ONLY IF you need to change the EPICS
				    version number.
   tools/MakeRelease		- To create release file.
   tools/MakeRelease -b		- To create release file WITH BINARIES.

1.5  "Partial" build commands:

   make clean.sun4		- Cleans sun4 binaries in O.sun4 dirs only
   make install.sun4		- Builds sun4 only
   make install.mv167		- Builds mv167 only (a sun4 build must be
					complete before this can be
					issued)

NOTES:
   1. tools/MakeRelease will create tar files in the directory ABOVE
        base.  These tar files are then meant to be untarred at that level.
        The release will include the "config" directory.

   2. EPICS binaries are kept in the bin/ARCH and lib/ARCH directories. 
        EPICS shellscripts are kept in the tools directory.
   
   3. Temporary objects are stored in src/DIR/O.ARCH, so one can store
        objects for multiple architectures at the same time.  While
	developing source for EPICS, use aliases to facilitate building
	objects within these directories, e.g.:

		alias make167 "make -f Makefile.Vx T_A=mv167"
		make167 O.mv167/dbAccess.o

	This example instructs make to build dbAccess.o for the
	167 target using the Vx makefile.

----------------------------------------------------------------------------
   Part 2  ---  Configuration Files
----------------------------------------------------------------------------

Filename                   BUILD  ADD_VX_ARCH  ADD_UNIX_ARCH     XBS

CONFIG                       -         -             -            s
CONFIG_ARCH.ARCH             -         c             c            s
CONFIG_BASE                  m         m             m            s
CONFIG.Unix.ARCH_CLASS       m         -             c*           s
CONFIG.Vx.ARCH_CLASS         m         c*            -            s
CONFIG_COMMON                -         -             -            x
CONFIG_vx                    -         -             -            s
HRULES                       -         -             -            x
RULES                        -         -             -            x
RULES.Vx                     -         -             -            b
RULES.Unix                   -         -             -            b

     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_SITE_vx.68k,
             since it already exists !

     x -  File used in configuring EPICS extension products only.
     b -  File used in configuring EPICS base only.
     s -  File used for BOTH base and extensions.

----------------------------------------------------------------------------
   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
    |             Make Dependency Rules.
    |
    +------ 1. CONFIG_vx
                ^  ^  ^
                |  |  |
                |  |  +---- 1. CONFIG_BASE
                |  |                 HOST_ARCH = sun4
                |  |                 BUILD_ARCHS = $(HOST_ARCH) mv167 hkv2f
                |  |                 VX_DIR = /vxworks
                |  |                 Lots More.
                |  +------- 2. CONFIG_ARCH.hkv2f
                |                    BUILD_TYPE = Vx
                |                    ARCH_CLASS = 68k 
                |                    Arch Specific Compiler Flag Setup
                +---------- 3. CONFIG.Vx.68k
                                     Directory Setup
                                     Compiler/Utility Setup

----------------------------  sun4  example --------------------------------

 src/db/Makefile.Unix     (An example EPICS makefile)
    ^   ^
    |   +--- 2. RULES.Unix
    |             Make Dependency Rules.
    |
    +------- 1. CONFIG
                ^  ^  ^
                |  |  |
                |  |  +---- 1. CONFIG_BASE
                |  |                 HOST_ARCH = sun4
                |  |                 BUILD_ARCHS = $(HOST_ARCH) mv167 hkv2f
                |  |                 VX_DIR = /vxworks
                |  |                 Lots More.
                |  +------- 2. CONFIG_ARCH.sun4
                |                    BUILD_TYPE = Unix
                |                    ARCH_CLASS = sun4 
                |                    Arch Specific Compiler Flag Setup
                +---------- 3. CONFIG.Unix.sun4
                                     Directory Setup
                                     Compiler/Utility Setup

----------------------------------------------------------------------------
   Part 4  ---  EPICS dependencies
----------------------------------------------------------------------------

 Dependencies supported by lower level Makefiles:

    depends		- Generate include dependencies
    pre_build		- Build lex/yacc, miscellaneous
    build_libs		- Builds libraries for use in build dependency
    install_libs	- Install these libraries in lib/ARCH
    build		- Builds objects
    install		- Installs executables in bin/ARCH