$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 (as make) before any system supplied makes. ---------------------------------------------------------------------------- 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 epics/config cp CONFIG_ARCH.mv167 CONFIG_ARCH.YOUR_ARCH edit CONFIG_ARCH.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. Clean will remove files from ALL O.ARCH dirs, not only those specified in BUILD_ARCHS. 1.4 To create an EPICS release: edit base/include/version.h - ONLY IF you need to change the EPICS version number. gnumake release - Will create Tar file gnumake built_release - Will create Tar file, after generating dependencies, INCLUDING BINARIES. 1.5 "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. base/MakeRelease will create tar files in the directory ABOVE base. These tar files are then meant to be untarred at that level. This release will include the "epics/config" directory. 2. EPICS binaries and shellscripts are installed into the bin/ARCH and lib/ARCH directories. 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/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). BUILD_ARCHS: List of architectures to be built. VX_DIR: Location of vxWorks. STATIC_BUILD: Whether or not to build clients statically. etc. ---------------------------------------------------------------------------- CONFIG_ARCH.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.BUILD_TYPE.ARCH_CLASS - Contains definitions of where to find things, like X11 / Motif, etc. ---------------------------------------------------------------------------- CONFIG.BUILD_TYPE.ARCH_CLASS - Contains definitions pertaining to a particular architecture class. This file's primary usefulness is to define compile and link flags. ---------------------------------------------------------------------------- CONFIG_COMMON - Contains definitions describing the layout of base. ---------------------------------------------------------------------------- CONFIG_BASE CONFIG_EXTENSIONS - Defines what subdirectories get built by default under base and extensions. ---------------------------------------------------------------------------- RULES.Vx - Rules for building with VxWorks makefiles. ---------------------------------------------------------------------------- RULES.Unix - Rules for building with Unix makefiles. ---------------------------------------------------------------------------- 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_ARCH.ARCH - c c - CONFIG_SITE.Unix.ARCH_CLASS m - c* - CONFIG_SITE.Vx.ARCH_CLASS m c* - - CONFIG.Unix.ARCH_CLASS - - c* - CONFIG.Vx.ARCH_CLASS - c* - - RULES.Vx - - - - RULES.Unix - - - - CONFIG_BASE - - - - CONFIG_EXTENSIONS - - - - CONFIG_COMMON - - - - RULES_ARCHS - - - - RULES_DIRS - - - - 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_ARCH.hkv2f | | | BUILD_TYPE = Vx | | | ARCH_CLASS = 68k | | | Arch Specific Compiler Flag Setup | | +------- 4. CONFIG_SITE.Vx.68k | | Directory locations | +--------- 5. CONFIG.Vx.68k | Compiler/utility setup for ARCH_CLASS +---------- 1. Target.include T_A definition (target architecture) ---------------------------- 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_ARCH.sun4 | | | BUILD_TYPE = Unix | | | ARCH_CLASS = sun4 | | | Arch Specific Compiler Flag Setup | | +------- 4. CONFIG_SITE.Unix.sun4 | | Directory locations | +--------- 5. CONFIG.Unix.sun4 | Compiler/utility setup for ARCH_CLASS +---------- 1. Target.include T_A definition (target architecture) ---------------------------------------------------------------------------- Part 4 --- EPICS dependencies ---------------------------------------------------------------------------- Dependencies 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