1 # Installation Instructions {#install}
3 ## EPICS Base Release 7.0.x
9 - [What is EPICS base?](#what-is-epics-base?)
10 - [What is
new in
this release?](#what-is-
new-in-
this-release?)
11 - [Copyright](#copyright)
12 - [Supported platforms](#supported-platforms)
13 - [Supported compilers](#supported-compilers)
14 - [Software requirements](#software-requirements)
15 - [Host system storage requirements](#host-system-storage-requirements)
16 - [Documentation](#documentation)
17 - [Directory Structure](#directory-structure)
18 - [Site-specific build configuration](#site-specific-build-configuration)
19 - [Building EPICS base](#building-epics-base)
20 - [Example application and extension](#example-application-and-extension)
21 - [Multiple host platforms](#multiple-host-platforms)
25 ### What is EPICS base?
27 The Experimental Physics and Industrial Control Systems (EPICS) is an
28 extensible set of software components and tools with which application
29 developers can create a control system. This control system can be
30 used to control accelerators, detectors, telescopes, or other
31 scientific experimental equipment. EPICS base is the set of core
32 software, i.e. the components of EPICS without which EPICS would not
33 function. EPICS base allows an arbitrary number of target systems,
34 IOCs (input/output controllers), and host systems, OPIs (
operator
35 interfaces) of various types.
37 ### What is new in this release?
39 Please check the `documentation/RELEASE_NOTES.md` file
for
40 description of changes and release migration details.
44 Please review the `LICENSE` file included in the distribution
for
47 ### Supported platforms
49 The list of platforms supported by
this version of EPICS base is given
50 in the `configure/CONFIG_SITE` file. If you are trying to build EPICS
51 Base on an unlisted host or
for a different target machine you must
52 have the proper host/target cross compiler and header files, and you
53 will have to create and add the appropriate
new configure files to the
54 base/configure/os/directory. You can start by copying existing
55 configuration files in the configure/os directory and then make
56 changes
for your
new platforms.
58 ### Supported compilers
60 This version of EPICS base has been built and tested
using the host
61 vendor
's C and C++ compilers, as well as the GNU gcc and g++
62 compilers. The GNU cross-compilers work for all cross-compiled
63 targets. You may need the C and C++ compilers to be in your search
64 path to do EPICS builds; check the definitions of CC and CCC in
65 `base/configure/os/CONFIG.<host>.<host>` if you have problems.
67 ### Software requirements
71 You must use the GNU version of `make` for EPICS builds. Set your path
72 so that version 4.1 or later is available. The macOS version of `make`
73 is older but does still work.
77 You must have Perl version 5.10.1 or later installed. The EPICS
78 configuration files do not specify the perl full pathname, so the perl
79 executable must be found through your normal search path.
81 #### Unzip and tar (Winzip on WIN32 systems)
83 You must have tools available to unzip and untar the EPICS base
88 EPICS supports IOCs running on embedded platforms such as VxWorks and
89 RTEMS built using a cross-compiler, and also supports soft IOCs
90 running as processes on the host platform.
94 You must have vxWorks 6.8 or later installed if any of your target
95 systems are vxWorks systems; the C++ compiler from older versions cannot
96 compile recently developed code. The vxWorks installation provides the
97 cross-compiler and header files needed to build for these targets. The
98 absolute path to and the version number of the vxWorks installation
99 must be set in the `base/configure/os/CONFIG_SITE.Common.vxWorksCommon`
100 file or in one of its target-specific overrides.
102 Consult the [vxWorks 6.x](https://epics.anl.gov/base/vxWorks6.php) EPICS
103 web pages about and the vxWorks documentation for information about
104 configuring your vxWorks operating system for use with EPICS.
108 For RTEMS targets, you need RTEMS core and toolset version 4.9.x or
109 4.10.x. RTEMS 5 is experimental in EPICS 7.0.6.
111 #### Command Line Editing
113 GNU readline and other similar libraries can be used by the IOC shell
114 to provide command line editing and command line history recall. The
115 GNU readline development package (or Apple's emulator on macOS) must
116 be installed
for a target when its build configuration variable
117 `COMMANDLINE_LIBRARY` is set to `READLINE`. The
default specified in
118 `CONFIG_COMMON` is `EPICS`, but most linux target builds can detect
if
119 readline is available and will then use it. RTEMS targets may be
120 configured to use `LIBTECLA`
if available, and on vxWorks the OS
's
121 ledLib line-editing library is normally used.
123 ### Host system storage requirements
125 The compressed tar file is approximately 3 MB in size. The
126 distribution source tree takes up approximately 21 MB. A 64-bit host
127 architecture may need around 610 MB to compile, while cross-compiled
128 targets are somewhat smaller.
132 EPICS documentation is available through the [EPICS website](https://epics.anl.gov/) at Argonne.
134 Release specific documentation can also be found in the
135 `base/documentation` directory of the distribution.
137 ### Directory Structure
139 #### Distribution directory structure
142 base Root directory of the distribution
143 base/configure Build rules and OS-independent config files
144 base/configure/os OS-dependent build config files
145 base/documentation Distribution documentation
146 base/src Source code in various subdirectories
147 base/startup Scripts for setting up path and environment
150 #### Directories created by the build
152 These are created in the root directory of the installation (`base`
153 above) or under the directory pointed to by the `INSTALL_LOCATION`
154 configuration variable if that has been set.
157 bin Installed scripts and executables in subdirs
158 cfg Installed build configuration files
159 db Installed database files
160 dbd Installed database definition files
161 html Installed html documentation
162 include Installed header files
163 include/os Installed OS-specific header files in subdirs
164 include/compiler Installed compiler-specific header files
165 lib Installed libraries in arch subdirectories
166 lib/perl Installed perl modules
167 templates Installed templates
170 #### `base/documentation` Directory
172 This contains documents on how to setup, build, and install EPICS.
176 RELEASE_NOTES.md Notes on release changes
177 KnownProblems.html List of known problems and workarounds
180 #### `base/startup` Directory
182 This contains several example scripts that show how to set up the
183 build environment and PATH for using EPICS. Sites would usually copy and/or modify these files as appropriate for their environment; they are not used by the build system at all.
186 EpicsHostArch Shell script to set EPICS_HOST_ARCH env variable
187 unix.csh C shell script to set path and env variables
188 unix.sh Bourne shell script to set path and env variables
189 win32.bat Bat file example to configure win32-x86 target
190 windows.bat Bat file example to configure windows-x64 target
193 #### `base/configure` directory
195 This contains build-system files providing definitions and rules
196 required by GNU Make to build EPICS. Users should only need to modify the `CONFIG_SITE` files to configure the EPICS build.
199 CONFIG Main entry point for building EPICS
200 CONFIG.CrossCommon Cross build definitions
201 CONFIG.gnuCommon Gnu compiler build definitions for all archs
202 CONFIG_ADDONS Definitions for <osclass> and DEFAULT options
204 CONFIG_BASE EPICS base tool and location definitions
205 CONFIG_BASE_VERSION Definitions for EPICS base version number
206 CONFIG_COMMON Definitions common to all builds
207 CONFIG_ENV Definitions of EPICS environment variables
209 CONFIG_SITE Site specific make definitions
210 CONFIG_SITE_ENV Site defaults for EPICS environment variables
211 MAKEFILE Installs CONFIG* RULES* creates
212 RELEASE Location of external products
213 RULES Includes appropriate rules file
214 RULES.Db Rules for database and database definition files
215 RULES.ioc Rules for application iocBoot/ioc* directory
216 RULES_ARCHS Definitions and rules for building architectures
217 RULES_BUILD Build and install rules and definitions
218 RULES_DIRS Definitions and rules for building subdirectories
222 RULES_TOP Rules specific to a <top> dir only
223 Sample.Makefile Sample makefile with comments
226 #### `base/configure/os` Directory
228 Files in here provide definitions that are shared by or specific to particular host and/or target architectures. Users should only need to modify the `CONFIG_SITE` files in this directory to configure the EPICS build.
231 CONFIG.<host>.<target> Definitions for a specific host-target combination
232 CONFIG.Common.<target> Definitions for a specific target, any host
233 CONFIG.<host>.Common Definitions for a specific host, any target
234 CONFIG.UnixCommon.Common Definitions for Unix hosts, any target
235 CONFIG.Common.UnixCommon Definitions for Unix targets, any host
236 CONFIG.Common.RTEMS Definitions for all RTEMS targets, any host
237 CONFIG.Common.vxWorksCommon Definitions for all vxWorks targets, any host
238 CONFIG_SITE.<host>.<target> Local settings for a specific host-target combination
239 CONFIG_SITE.Common.<target> Local settings for a specific target, any host
240 CONFIG_SITE.<host>.Common Local settings for a specific host, any target
241 CONFIG_SITE.Common.RTEMS Local settings for all RTEMS targets, any host
242 CONFIG_SITE.Common.vxWorksCommon Local settings for all vxWorks targets, any host
245 ### Building EPICS base
249 Unzip and untar the distribution file. Use WinZip on Windows
252 #### Set environment variables
254 Files in the base/startup directory have been provided to help set
255 required path and other environment variables.
257 * **`EPICS_HOST_ARCH`**
259 Some host builds of EPICS require that the environment variable
260 `EPICS_HOST_ARCH` be defined. The perl script `EpicsHostArch.pl` in the
261 `base/startup` directory prints the value which the build will use if
262 the variable is not set before the build starts. Architecture names
263 start with the operating system followed by a dash and the host CPU
264 architecture, e.g. `linux-x86_64`. Some architecture names have another
265 dash followed by another keyword, for example when building for Windows
266 but using the MinGW compiler the name must be `windows-x64-mingw`. See
267 `configure/CONFIG_SITE` for a list of supported host architecture names.
270 As already mentioned, you must have the `perl` executable and you may
271 need C and C++ compilers in your search path. When building base you
272 must have `echo` in your search path. For Unix host builds you will
273 also need `cp`, `rm`, `mv`, and `mkdir` in your search path. Some Unix
274 systems may also need `ar` and `ranlib`, and the C/C++ compilers may
275 require `as` and `ld` in your path. On Solaris systems you need
276 `uname` in your path.
278 * **`LD_LIBRARY_PATH`**
279 EPICS shared libraries and executables normally contain the full path
280 to any libraries they require, so setting this variable is not usually
281 necessary. However, if you move the EPICS installation to a new
282 location after building it then in order for the shared libraries to
283 be found at runtime it may need to be set, or some equivalent
284 OS-specific mechanism such as `/etc/ld.so.conf` on Linux must be used.
285 Shared libraries are now built by default on all Unix type hosts.
287 ### Site-specific build configuration
289 #### Site configuration
291 To configure EPICS, you may want to modify some values set in the
296 configure/CONFIG_SITE Build settings. Specify target archs.
297 configure/CONFIG_SITE_ENV Environment variable defaults
300 #### Host configuration
302 To configure each host system, you can override the default
303 definitions by adding a new settings file (or editing an existing
304 settings file) in the `configure/os` directory with your override
305 definitions. The settings file has the same name as the definitions
306 file to be overridden except with `CONFIG` in the name changed to
310 configure/os/CONFIG.<host>.<host> Host self-build definitions
311 configure/os/CONFIG.<host>.Common Host common build definitions
312 configure/os/CONFIG_SITE.<host>.<host> Host self-build overrides
313 configure/os/CONFIG_SITE.<host>.Common Host common build overrides
316 #### Target configuration
318 To configure each target system, you may override the default
319 definitions by adding a new settings file (or editing an existing
320 settings file) in the `configure/os` directory with your override
321 definitions. The settings file has the same name as the definitions
322 file to be overridden except with `CONFIG` in the name changed to
326 configure/os/CONFIG.Common.<target> Target common definitions
327 configure/os/CONFIG.<host>.<target> Host-target definitions
328 configure/os/CONFIG_SITE.Common.<target> Target common overrides
329 configure/os/CONFIG_SITE.<host>.<target> Host-target overrides
332 #### Build EPICS base
334 After configuring the build you should be able to build EPICS base
335 by issuing the following commands in the distribution's root
343 The command `make distclean` will
remove all files and
344 directories generated by a previous build. The command `make`
345 will build and install everything
for the configured host and
348 It is recommended that you
do a `make distclean` at the
349 root directory of an EPICS directory structure before each complete
350 rebuild to ensure that all components will be rebuilt.
352 In some cases GNU Make may have been installed as `gmake` or
353 `gnumake`, in which
case the above commands will have to be adjusted
356 ### Example application and extension
358 A perl tool `makeBaseApp.pl` and several
template applications are
359 included in the distribution. This script instantiates the selected
360 template into an empty directory to provide an example application
361 that can be built and then executed to
try out
this release of base.
363 Instructions
for building and executing the EPICS example application
364 can be found in the section
"Example Application" of Chapter 2,
365 "Getting Started", in the
"EPICS Application Developer's Guide".
366 The
"Example IOC Application" section briefly explains how to
367 create and build an example application in a user created <top>
368 directory. It also explains how to run the example application on a
369 vxWorks ioc or as a process on the host system. By running the example
370 application as a host-based IOC, you will be able to quickly implement
371 a complete EPICS system and be able to run channel access clients on
374 Another perl script `makeBaseExt.pl` is also included in the
375 distribution file
for creating an extensions tree and sample
376 application that can also be built and executed. Both these scripts
377 are installed into the install location `bin/<hostarch>` directory
378 during the base build.
380 ### Multiple host platforms
382 You can build
using a single EPICS directory structure on multiple
383 host systems and
for multiple cross target systems. The intermediate
384 and binary files generated by the build will be created in separate
385 subdirectories and installed into the appropriate separate host/target
388 EPICS executables and perl scripts are installed into the
389 `$(INSTALL_LOCATION)/bin/<arch>` directories. Libraries are installed
390 into `$(INSTALL_LOCATION)/lib/<arch>`. The
default definition
for
391 `$(INSTALL_LOCATION)` is `$(TOP)` which is the root directory in the
392 distribution directory structure, `base`. Intermediate
object files
393 are stored in `O.<arch>` source subdirectories during the build
394 process, to allow objects
for multiple cross target architectures
395 to be maintained at the same time.
397 To build EPICS base
for a specific
398 host/target combination you must have the proper host/target C/C++
399 cross compiler and target header files and the base/configure/os
400 directory must have the appropriate configure files.
1.8.5
