Table of Contents 
Previous Chapter Chapter 3: Directory Structure
The EPICS tree consists of three top-level subdirectories: base, config and extensions. The base and config directories are distributed together in an EPICS release. Items within the extensions directory must be obtained separately.
- epics/
- base/
- config/
- extensions/
NOTE: The files in the epics/config directory are used for building both base and extension products.
The base sub-tree contains the parts of EPICS that are generally required by all installations. It contains the top-level makefile used to build EPICS, subdirectories for executables, libraries, source, ASCII files and more.
- epics/base/
- Makefile: EPICS top-level makefile.
- Makefile.subdirs: Recurses through subdirectories. Used by Makefile.
- README: Concise guide to building and developing EPICS code.
- bin/
- sun4/: atdb, snc, bld*, antelope, e_flex, more.
- hkv2f/: iocCore, vxWorks, recSup, seq, more.
- ...
- include/: EPICS header files.
- lib/
- sun4/: libca.a, libCom.a, libAs.a, more
- ...
- man/: Manual pages.
- rec/: Automatically generated header files, default.dctsdr, more
- rec.bak/: Old record header files from last run.
- src/: Contains source code and temporary objects.
- tools/: Shell scripts.
NOTES: Soft links to shell scripts are no longer maintained in each architecture's bin directory.
src Sub-Tree
The base/src directory contains a source sub-directory for each EPICS base Unix and vxWorks component.
- epics/base/src/
- as/: Channel access security
- ascii/: EPICS ASCII files.
- bld/: Utilities for building SDR files in epics/base/rec and application directories.
- ca/: Channel access client libraries.
- db/: Database routines.
- dbtools/: Libraries for loading ASCII database files.
- dct/: Curses tool for generating EPICS databases.
- dev/: Device support.
- devOpt/: Optional EPICS device support.
- dr/v: Driver support.
- iocCore/: Directory in which iocCore is built from.
- libCom/: UNIX/VxWorks common libraries.
- libCompat/: Compatibility libraries for various architectures.
- libVxWorks/: Various utilities for VxWorks IOCs.
- misc/: Miscellaneous.
- rec/: Record support.
- rsrv/: Channel access server libraries.
- sequencer/: State notation compiler and run-time support.
- toolsComm/: Tools for building EPICS, e.g.: e_flex and antelope.
- util/: Miscellaneous VxWorks and UNIX utilities.
Each source sub-directory contains source code, Makefiles and sub-directories for temporary objects. Here are the items you will see in a "typical" source directory:
- epics/base/src/XXX/
- Makefile: Invokes the build in this source directory for all architectures defined in CONFIG_SITE by default.
- Makefile.Unix: Makefile for UNIX software.
- Makefile.Vx: Makefile for VxWorks software.
- O.<ARCH>/: Automatically generated directories for temporary object storage. One directory for each architecture. (e.g: O.sun4 or O.mv167) An O.<ARCH> directory exists for each architecture being built in a particular source directory. O.<ARCH> and its initial contents are created when "gmake dirs" is invoked. Other dependencies such as "gmake install" will invoke "gmake dirs" for you if O.<ARCH> does not exist.
- .DEPENDS: Automatically generated Include file dependencies. Empty if "gmake depends" has not been invoked.
- Makefile@: Automatically generated symbolic link pointing to the build type Makefile (either ../Makefile.Unix or ../Makefile.Vx) corresponding to the current build type of this directories' target architecture.
- Target.Include: Automatically generated file included by makefiles to indicate the architecture of this directory. This is necessary because Makefiles cannot easily determine the target architecture simply by looking at the current directory.
- *.o: Temporary objects.
- *.a: Libraries.
- *.c: Automatically generated source (yacc/lex/etc.).
- *.h: Automatically generated header files (yacc/lex/etc.).
- *: Executable files.
- *.c: C source files.
- *.h: C header files.
- *.y: Yacc files.
- *.l: Lex files.
Notes: The O.* directories and contents are generated by the build.
Tools Sub-Tree
EPICS shellscripts are found in the base/tools subdirectory of the EPICS distribution. Of these scripts, only gmake, getrel and makesdr should be invoked directly.
- gmake: Executes gnumake with the flags no-print-directory and no-keep-going.
- getrel: Sets up EPICS application directories by creating soft links to EPICS and vxWorks releases.
- makesdr: Creates a custom database template (default.dctsdr) for an application directory. This command is optional because a default template will be used if this command is not invoked.
- MakeRelease: Creates a Tar image of an EPICS release.
- MakeDirs: Creates temporary object directories under an EPICS release for a particular architecture.
- GetVar: Gets make variable information from within a shell script.
- CheckArch: Determines if configuration files exist for this architecture.
- FindEpics: Determines where EPICS is located from within shell script. Many shell scripts invoke this shellscript first.
- Clean: Removes temporary objects from the O.ARCH directories under src. If Clean is called without any arguments all O.ARCH directories are removed.
- makeStatTbl: Creates the error symbol table.
- blderrSymTbl: Builds the error symbol table.
- SetOpVersion: Selects specific executable versions of EPICS extension programs that will be used on future command invocations.
The configuration directory contains a set of files containing variable and rule definitions used by makefiles to build both base and the extensions. Files with names containing the word "SITE" are meant to be edited by the EPICS system manager only. The CONFIG file may be edited by both individual developers as well as the system manager. However, only the system manager may commit changes to CONFIG.
NOTE: Individual developers should never edit any file except CONFIG.
- CONFIG - This file is indirectly included by EPICS low-level Makefiles. It allows individual developers and the EPICS system manager to override specific variables in the configuration. This file conditionally includes other EPICS configuration files depending on the architecture being built.
- CONFIG_SITE - This file contains top-level variables that control parts of the build. Only the EPICS system manager is permitted to edit this file. It specifies the following variables:
- HOST_ARCH: Your system's host architecture. This is the architecture that is used to build databases, run dm, etc. This may be set to sun4 or hp700, for example. Only one architecture is allowed on this list at a time. A list of valid choices is provided in a comment above this option.
- BUILD_ARCHS: List of all workstation and IOC architectures to be built for your local site. HOST_ARCH must be first on this list. A list of valid choices is provided.
- VX_DIR: The location of your VxWorks distribution.
- EPICS_BASE: Location of the official EPICS base release from which extensions will obtain base libraries, header files, etc.
- EPICS_EXTENSIONS: Location of the official EPICS extensions release from which extensions will obtain base libraries, header files, etc.
- ANSI: The C compiler you want for ANSI compilations. Choose the compiler from the list of uppercase options.
- STANDARD: The C compiler to use for old-style C compilation. This option exists because not all parts of EPICS may be compiled under ANSI C (yet). Choose the compiler from the list of available uppercase options.
- CPLUSPLUS: This variable is for future use. Ignore for now.
- STATIC_BUILD: YES/NO - Whether or not to build UNIX programs statically.
- UNIX_OPT: YES/NO - Whether or not to use the -O option when building UNIX objects.
- VX_OPT: YES/NO - Whether or not to use the -O option when building VxWorks objects.
- UNIX_WARN: YES/NO - NO suppresses warnings with the -w option, YES runs the compiler without additional warning flags.
- VX_WARN: YES/NO - Same as above, but for VxWorks.
NOTES: The VX_WARN and UNIX_WARN options are ignored during a STRICT compile. STRICT compilation automatically uses the most verbose warning flags available. Compile types such as STRICT are set in the low-level makefiles. See the "Build Internals" section for more information about compile types such as STRICT.
- CONFIG_SITE.Unix.ARCH - This file specifies where to find directories for various libraries such as X, MOTIF, WingZ, etc.. If you do not have a certain product, leave the line empty. These directories are used by the extension products. CONFIG_SITE.Unix.ARCH contains the following variables:
- CMPLR: STRICT/ANSI/OLD - Default to ANSI. For 3.12, set this to ANSI. In the future this option may be more useful.
- INSTALL_PRODUCT - Path to program used to install extension products
- SPECIAL_LANG: Special directory to search for SUN patch libraries.
The following are path variables for various products. If you do not have a certain product, leave its line empty.
- X11_LIB: Path to X11 libraries.
- X11_INC: Path to X11 header files.
- MOTIF: etc.
- OPENWIN:
- WINGZ:
- MATHEMATICA:
- XRTGRAPH
- QUESTWIN:
- IDL:
The remaining files in the config directory are described in the "Build Internals" portion of this document.
The extensions sub-tree contains parts of EPICS that are not generally required by all installations. An individual site usually has only a subset of all available extensions. A complete extensions sub-tree contains a top-level makefile that can be used to build all extensions.
- epics/extensions/
- Makefile: Extensions top-level makefile.
- bin/: Installed executables and scripts
- sun4/: AR, alh, cau, more.
- hkv2f/: ...
- ...
- include/: Installed header files used by multiple extensions.
- lib/ Installed libraries used by multiple extensions
- sun4/: libUnix.a, libLca.a, libdev.a, more
- ...
- man/: Installed manual page files.
- doc/: Installed documentation files.
- src/: Contains source and temporary objects.
- ...
src Sub-Tree
The extensions source tree contains all the source code, header files, scripts, man page files, makefiles, and all other files for EPICS extensions. Each extension directory contains all the required files for that extension.:
- epics/extensions/src/
- alh/: Alarm handler.
- ar/: Achiver and TCL/TK based data extraction tools.
- burt/: Backup and restore tool
- gdct/: Graphical Motif-based database editor
- opi/: OPI editor and run-time environment
- km/: Knob manager
- medm/: Motif-based OPI
- ...
Each extension subdirectory also contains Makefiles and directories for temporary objects. Here are the files you will see in a "typical" source directory:
- epics/extensions/src/XXX
- Makefile: Invokes the build in this source directory for all architectures defined in CONFIG_SITE by default.
- Makefile.Unix: Makefile for UNIX software.
- Makefile.Vx: Makefile for VxWorks software.
- O.*/: Directories for temporary object storage. One directory for each architecture. (e.g: O.sun4 or O.mv167)
- .DEPENDS: Automatically generated header file dependencies.
- Makefile@: Symbolic link to either ../Makefile.Unix or ../Makefile.Vx.
- Target.Include: File included by Makefile that contains the target architecture definition.
- *.o: Temporary objects.
- *.a: Libraries.
- *.c: Automatically generated source (yacc/lex/etc.).
- *.h: Automatically generated header files (yacc/lex/etc.).
- *: Executable files.
- *.c: C source files.
- *.h: C header files.
- *.doc: Documentation files.
- man*: Man page files.
- *.y: Yacc files.
- *.l: Lex files.
Notes: The O.* directories and contents are generated by the build.
Table of Contents 
Next Chapter