$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