1 # Installation Instructions {#install}
3 ## EPICS Base Release 7.0.5
9 - [What is EPICS base?](#0_0_1)
10 - [What is new in this release?](#0_0_2)
12 - [Supported platforms](#0_0_4)
13 - [Supported compilers](#0_0_5)
14 - [Software requirements](#0_0_6)
15 - [Documentation](#0_0_8)
16 - [Directory Structure](#0_0_10)
17 - [Build related components](#0_0_11)
18 - [Building EPICS base (Unix and Win32)](#0_0_12)
19 - [Example application and extension](#0_0_13)
20 - [Multiple host platforms](#0_0_14)
24 ### <span id="0_0_1">What is EPICS base?</span>
26 The Experimental Physics and Industrial Control Systems (EPICS) is an
27 extensible set of software components and tools with which application
28 developers can create a control system. This control system can be
29 used to control accelerators, detectors, telescopes, or other
30 scientific experimental equipment. EPICS base is the set of core
31 software, i.e. the components of EPICS without which EPICS would not
32 function. EPICS base allows an arbitrary number of target systems,
33 IOCs (input/output controllers), and host systems, OPIs (operator
34 interfaces) of various types.
36 ### <span id="0_0_2">What is new in this release?</span>
38 Please check the `RELEASE_NOTES` file in the distribution for
39 description of changes and release migration details.
41 ### <span id="0_0_3">Copyright Licenses</span>
43 Please review the LICENSE file included in the distribution for legal
46 ### <span id="0_0_4">Supported platforms</span>
48 The list of platforms supported by this version of EPICS base is given
49 in the `configure/CONFIG_SITE` file. If you are trying to build EPICS
50 Base on an unlisted host or for a different target machine you must
51 have the proper host/target cross compiler and header files, and you
52 will have to create and add the appropriate new configure files to the
53 base/configure/os/directory. You can start by copying existing
54 configuration files in the configure/os directory and then make
55 changes for your new platforms.
57 ### <span id="0_0_5">Supported compilers</span>
59 This version of EPICS base has been built and tested using the host
60 vendor's C and C++ compilers, as well as the GNU gcc and g++
61 compilers. The GNU cross-compilers work for all cross-compiled
62 targets. You may need the C and C++ compilers to be in your search
63 path to do EPICS builds; check the definitions of CC and CCC in
64 `base/configure/os/CONFIG.<host>.<host>` if you have problems.
66 ### <span id="0_0_6">Software requirements</span>
69 You must use GNU make, gnumake, for any EPICS builds. Set your path so
70 that a gnumake version 4.1 or later is available.
73 You must have Perl version 5.10 or later installed. The EPICS
74 configuration files do not specify the perl full pathname, so the perl
75 executable must be found through your normal search path.
77 **Unzip and tar (Winzip on WIN32 systems)**
78 You must have tools available to unzip and untar the EPICS base
82 EPICS supports IOCs running on embedded platforms such as VxWorks and
83 RTEMS built using a cross-compiler, and also supports soft IOCs
84 running as processes on the host platform.
87 You must have vxWorks 6.8 or later installed if any of your target
88 systems are vxWorks systems; the C++ compiler from older versions cannot
89 compile recently developed code. The vxWorks installation provides the
90 cross-compiler and header files needed to build for these targets. The
91 absolute path to and the version number of the vxWorks installation
92 must be set in the `base/configure/os/CONFIG_SITE.Common.vxWorksCommon`
93 file or in one of its target-specific overrides.
95 Consult the [vxWorks 6.x](https://epics.anl.gov/base/vxWorks6.php) EPICS
96 web pages about and the vxWorks documentation for information about
97 configuring your vxWorks operating system for use with EPICS.
100 For RTEMS targets, you need RTEMS core and toolset version 4.9.x or
101 4.10.x (4.11 or 5.x are not yet supported).
103 **GNU readline or Tecla library**
104 GNU readline and Tecla libraries can be used by the IOC shell to
105 provide command line editing and command line history recall and edit.
106 GNU readline (or Tecla library) must be installed on your target
107 system when `COMMANDLINE_LIBRARY` is set to READLINE (or TECLA) for
108 that target. EPICS (EPICS shell) is the default specified in
109 `CONFIG_COMMON`. A READLINE override is defined for linux-x86 in the
110 EPICS distribution. Comment out `COMMANDLINE_LIBRARY=READLINE` in
111 `configure/os/CONFIG_SITE.Common.linux-x86` if readline is not
112 installed on linux-x86. Command-line editing and history will then be
113 those supplied by the os. On vxWorks the ledLib command-line input
114 library is used instead.
116 ### <span id="0_0_8">Documentation</span>
118 EPICS documentation is available through the [EPICS
119 website](https://epics.anl.gov/) at Argonne.
121 Release specific documentation can also be found in the
122 base/documentation directory of the distribution.
124 ### <span id="0_0_10">Directory Structure</span>
126 #### Distribution directory structure:
129 base Root directory of the base distribution
130 base/configure Operating system independent build config files
131 base/configure/os Operating system dependent build config files
132 base/documentation Distribution documentation
133 base/src Source code in various subdirectories
134 base/startup Scripts for setting up path and environment
137 #### Install directories created by the build:
140 bin Installed scripts and executables in subdirs
141 cfg Installed build configuration files
142 db Installed data bases
143 dbd Installed data base definitions
144 doc Installed documentation files
145 html Installed html documentation
146 include Installed header files
147 include/os Installed os specific header files in subdirs
148 include/compiler Installed compiler-specific header files
149 lib Installed libraries in arch subdirectories
150 lib/perl Installed perl modules
151 templates Installed templates
154 ### <span id="0_0_11">Build related components</span>
156 #### base/documentation directory - contains setup, build, and install documents
159 README.md Instructions for setup and building epics base
160 README.darwin.html Installation notes for Mac OS X (Darwin)
161 RELEASE_NOTES.html Notes on release changes
162 KnownProblems.html List of known problems and workarounds
165 #### base/startup directory - contains scripts to set environment and path
168 EpicsHostArch Shell script to set EPICS_HOST_ARCH env variable
169 unix.csh C shell script to set path and env variables
170 unix.sh Bourne shell script to set path and env variables
171 win32.bat Bat file example to configure win32-x86 target
172 windows.bat Bat file example to configure windows-x64 target
175 #### base/configure directory - contains build definitions and rules
178 CONFIG Includes configure files and allows variable overrides
179 CONFIG.CrossCommon Cross build definitions
180 CONFIG.gnuCommon Gnu compiler build definitions for all archs
181 CONFIG_ADDONS Definitions for <osclass> and DEFAULT options
183 CONFIG_BASE EPICS base tool and location definitions
184 CONFIG_BASE_VERSION Definitions for EPICS base version number
185 CONFIG_COMMON Definitions common to all builds
186 CONFIG_ENV Definitions of EPICS environment variables
188 CONFIG_SITE Site specific make definitions
189 CONFIG_SITE_ENV Site defaults for EPICS environment variables
190 MAKEFILE Installs CONFIG* RULES* creates
191 RELEASE Location of external products
192 RULES Includes appropriate rules file
193 RULES.Db Rules for database and database definition files
194 RULES.ioc Rules for application iocBoot/ioc* directory
195 RULES_ARCHS Definitions and rules for building architectures
196 RULES_BUILD Build and install rules and definitions
197 RULES_DIRS Definitions and rules for building subdirectories
201 RULES_TOP Rules specific to a <top> dir (uninstall and tar)
202 Sample.Makefile Sample makefile with comments
205 #### base/configure/os directory - contains os-arch specific definitions
208 CONFIG.<host>.<target> Specific host-target build definitions
209 CONFIG.Common.<target> Specific target definitions for all hosts
210 CONFIG.<host>.Common Specific host definitions for all targets
211 CONFIG.UnixCommon.Common Definitions for Unix hosts and all targets
212 CONFIG.Common.UnixCommon Definitions for Unix targets and all hosts
213 CONFIG.Common.vxWorksCommon Specific host definitions for all vx targets
214 CONFIG_SITE.<host>.<target> Site specific host-target definitions
215 CONFIG_SITE.Common.<target> Site specific target defs for all hosts
216 CONFIG_SITE.<host>.Common Site specific host defs for all targets
219 ### <span id="0_0_12">Building EPICS base (Unix and Win32)</span>
223 Unzip and untar the distribution file. Use WinZip on Windows
226 #### Set environment variables
228 Files in the base/startup directory have been provided to help set
229 required path and other environment variables.
232 Before you can build or use this EPICS base, the environment variable
233 `EPICS_HOST_ARCH` must be defined. A perl script EpicsHostArch.pl in
234 the base/startup directory has been provided to help set
235 `EPICS_HOST_ARCH.` You should have `EPICS_HOST_ARCH` set to your
236 host operating system followed by a dash and then your host
237 architecture, e.g. linux-x86_64. If you are not using the OS
238 vendor's c/c++ compiler for host builds, you will need another dash
239 followed by the alternate compiler name (e.g. "-gnu" for GNU c/c++
240 compilers on a solaris host or "-mingw" for MinGW c/c++ compilers on
241 Windows). See `configure/CONFIG_SITE` for a list of supported
242 `EPICS_HOST_ARCH` values.
245 As already mentioned, you must have the perl executable and you may
246 need C and C++ compilers in your search path. For building base you
247 also must have echo in your search path. For Unix host builds you
248 also need ln, cpp, cp, rm, mv, and mkdir in your search path and
249 /bin/chmod must exist. On some Unix systems you may also need ar and
250 ranlib in your path, and the C compiler may require as and ld in
251 your path. On solaris systems you need uname in your path.
254 EPICS shared libraries and executables normally contain the full
255 path to any libraries they require. However, if you move the EPICS
256 files or directories from their build-time location then in order
257 for the shared libraries to be found at runtime `LD_LIBRARY_PATH`
258 must include the full pathname to
259 `$(INSTALL_LOCATION)/lib/$(EPICS_HOST_ARCH)` when invoking
260 executables, or some equivalent OS-specific mechanism (such as
261 /etc/ld.so.conf on Linux) must be used. Shared libraries are now
262 built by default on all Unix type hosts.
264 #### Do site-specific build configuration
266 **Site configuration**
267 To configure EPICS, you may want to modify the default definitions
268 in the following files:
271 configure/CONFIG_SITE Build choices. Specify target archs.
272 configure/CONFIG_SITE_ENV Environment variable defaults
273 configure/RELEASE TORNADO2 full path location
276 **Host configuration**
277 To configure each host system, you may override the default
278 definitions by adding a new file in the configure/os directory with
279 override definitions. The new file should have the same name as the
280 distribution file to be overridden except with CONFIG in the name
281 changed to `CONFIG_SITE`.
284 configure/os/CONFIG.<host>.<host> Host build settings
285 configure/os/CONFIG.<host>.Common Host common build settings
288 **Target configuration**
289 To configure each target system, you may override the default
290 definitions by adding a new file in the configure/os directory with
291 override definitions. The new file should have the same name as the
292 distribution file to be overridden except with CONFIG in the name
293 replaced by `CONFIG_SITE`. This step is necessary even if the host
294 system is the only target system.
297 configure/os/CONFIG.Common.<target> Target common settings
298 configure/os/CONFIG.<host>.<target> Host-target settings
301 #### Build EPICS base
303 After configuring the build you should be able to build EPICS base
304 by issuing the following commands in the distribution's root
308 gnumake clean uninstall
312 The command "gnumake clean uninstall" will remove all files and
313 directories generated by a previous build. The command "gnumake"
314 will build and install everything for the configured host and
317 It is recommended that you do a "gnumake clean uninstall" at the
318 root directory of an EPICS directory structure before each complete
319 rebuild to ensure that all components will be rebuilt.
321 ### <span id="0_0_13">Example application and extension</span>
323 A perl tool, makeBaseApp.pl is included in the distribution file. This
324 script will create a sample application that can be built and then
325 executed to try out this release of base.
327 Instructions for building and executing the EPICS example application
328 can be found in the section "Example Application" of Chapter 2,
329 "Getting Started", in the "EPICS Application Developer's Guide".
330 The "Example IOC Application" section briefly explains how to
331 create and build an example application in a user created <top>
332 directory. It also explains how to run the example application on a
333 vxWorks ioc or as a process on the host system. By running the example
334 application as a host-based IOC, you will be able to quickly implement
335 a complete EPICS system and be able to run channel access clients on
338 A perl script, makeBaseExt.pl, is included in the distribution file.
339 This script will create a sample extension that can be built and
340 executed. The makeBaseApp.pl and makeBaseExt.pl scripts are installed
341 into the install location `bin/<hostarch>` directory during the base
344 ### <span id="0_0_14">Multiple host platforms</span>
346 You can build using a single EPICS directory structure on multiple
347 host systems and for multiple cross target systems. The intermediate
348 and binary files generated by the build will be created in separate
349 subdirectories and installed into the appropriate separate host/target
350 install directories. EPICS executables and perl scripts are installed
351 into the `$(INSTALL_LOCATION)/bin/<arch>` directories. Libraries are
352 installed into $`(INSTALL_LOCATION)/lib/<arch>`. The default
353 definition for `$(INSTALL_LOCATION)` is `$(TOP)` which is the root
354 directory in the distribution directory structure, base. Created
355 object files are stored in `O.<arch>` source subdirectories, This
356 allows objects for multiple cross target architectures to be
357 maintained at the same time. To build EPICS base for a specific
358 host/target combination you must have the proper host/target C/C++
359 cross compiler and target header files and the base/configure/os
360 directory must have the appropriate configure files.
