1Building and Installing Erlang/OTP 2================================== 3 4Introduction 5------------ 6 7This document describes how to build and install Erlang/OTP-%OTP-REL%. 8Erlang/OTP should be possible to build from source on any Unix/Linux system, 9including OS X. You are advised to read the whole document 10before attempting to build and install Erlang/OTP. 11 12The source code can be downloaded from the official site of Erlang/OTP or GitHub. 13* <http://www.erlang.org> 14* <https://github.com/erlang/otp> 15 16Required Utilities 17------------------ 18 19These are the tools you need in order to unpack and build Erlang/OTP. 20 21### Unpacking ### 22 23* GNU unzip, or a modern uncompress. 24* A TAR program that understands the GNU TAR format for long filenames. 25 26### Building ### 27 28* GNU `make` 29* Compiler -- GNU C Compiler, `gcc` or the C compiler frontend for LLVM, `clang`. 30* Perl 5 31* `ncurses`, `termcap`, or `termlib` -- The development headers and 32 libraries are needed, often known as `ncurses-devel`. Use 33 `--without-termcap` to build without any of these libraries. Note that 34 in this case only the old shell (without any line editing) can be used. 35* `sed` -- Stream Editor for basic text transformation. 36 37#### Building in Git #### 38 39Build the same way as when building the unpacked tar file. 40 41#### Building on OS X #### 42 43* Xcode -- Download and install via the Mac App Store. 44 Read about [Building on a Mac][] before proceeding. 45 46### Installing ### 47 48* An `install` program that can take multiple file names. 49 50 51Optional Utilities 52------------------ 53 54Some applications are automatically skipped if the dependencies aren't met. 55Here is a list of utilities needed for those applications. You will 56also find the utilities needed for building the documentation. 57 58### Building ### 59 60* OpenSSL -- The opensource toolkit for Secure Socket Layer 61 and Transport Layer Security. 62 Required for building the application `crypto`. 63 Further, `ssl` and `ssh` require a working crypto application and 64 will also be skipped if OpenSSL is missing. The `public_key` 65 application is available without `crypto`, but the functionality 66 will be very limited. 67 68 The development package of OpenSSL including the header files are needed as well 69 as the binary command program `openssl`. At least version 0.9.8 of OpenSSL is required. 70 Read more and download from <http://www.openssl.org>. 71* Oracle Java SE JDK -- The Java Development Kit (Standard Edition). 72 Required for building the application `jinterface`. 73 At least version 1.6.0 of the JDK is required. 74 75 Download from <http://www.oracle.com/technetwork/java/javase/downloads>. 76 We have also tested with IBM's JDK 1.6.0. 77* `flex` -- Headers and libraries are needed to build the flex 78 scanner for the `megaco` application on Unix/Linux. 79* wxWidgets -- Toolkit for GUI applications. 80 Required for building the `wx` application. At least 81 version 3.0 of wxWidgets is required. 82 83 Download from <http://sourceforge.net/projects/wxwindows/files/3.0.0/> 84 or get it from GitHub: <https://github.com/wxWidgets/wxWidgets> 85 86 Further instructions on wxWidgets, read [Building with wxErlang][]. 87 88 89 90### Building Documentation ### 91 92* `xsltproc` -- A command line XSLT processor. 93 94 A tool for applying XSLT stylesheets 95 to XML documents. Download xsltproc from 96 <http://xmlsoft.org/XSLT/xsltproc2.html>. 97 98* `fop` -- Apache FOP print formatter (requires Java). Can be downloaded 99 from <http://xmlgraphics.apache.org/fop>. 100 101 102 103How to Build and Install Erlang/OTP 104----------------------------------- 105 106The following instructions are for building [the released source tar ball][]. 107 108The variable `$ERL_TOP` will be mentioned a lot of times. It refers to 109the top directory in the source tree. More information about `$ERL_TOP` 110can be found in the [make and $ERL_TOP][] section below. 111 112### Unpacking ### 113 114Start by unpacking the Erlang/OTP distribution file with your GNU 115compatible TAR program. 116 117 $ tar -zxf otp_src_%OTP-VSN%.tar.gz # Assuming bash/sh 118 119Now change directory into the base directory and set the `$ERL_TOP` variable. 120 121 $ cd otp_src_%OTP-VSN% 122 $ export ERL_TOP=`pwd` # Assuming bash/sh 123 124### Configuring ### 125 126Run the following commands to configure the build: 127 128 $ ./configure [ options ] 129 130By default, Erlang/OTP release will be installed in `/usr/local/{bin,lib/erlang}`. 131If you for instance don't have the permission to install in the standard location, 132 you can install Erlang/OTP somewhere else. For example, to install in 133`/opt/erlang/%OTP-VSN%/{bin,lib/erlang}`, use the `--prefix=/opt/erlang/%OTP-VSN%` option. 134 135On some platforms Perl may behave strangely if certain locales are 136set. If you get errors when building, try setting the LANG variable: 137 138 $ export LANG=C # Assuming bash/sh 139 140 141### Building ### 142 143Build the Erlang/OTP release. 144 145 $ make 146 147 148### Testing ### 149 150Before installation you should test whether your build is working properly 151by running our smoke test. The smoke test is a subset of the complete Erlang/OTP test suites. 152First you will need to build and release the test suites. 153 154 $ make release_tests 155 156This creates an additional folder in `$ERL_TOP/release` called `tests`. 157Now, it's time to start the smoke test. 158 159 $ cd release/tests/test_server 160 $ $ERL_TOP/bin/erl -s ts install -s ts smoke_test batch -s init stop 161 162To verify that everything is ok you should open `$ERL_TOP/release/tests/test_server/index.html` 163in your web browser and make sure that there are zero failed test cases. 164 165> *NOTE*: On builds without `crypto`, `ssl` and `ssh` there is a failed test case 166> for undefined functions. Verify that the failed test case log only shows calls 167> to skipped applications. 168 169### Installing ### 170 171You are now ready to install the Erlang/OTP release! 172The following command will install the release on your system. 173 174 $ make install 175 176 177### Running ### 178 179You should now have a working release of Erlang/OTP! 180Jump to [System Principles][] for instructions on running Erlang/OTP. 181 182 183### How to Build the Documentation ### 184 185Make sure you're in the top directory in the source tree. 186 187 $ cd $ERL_TOP 188 189If you have just built Erlang/OTP in the current source tree, you have 190already ran `configure` and do not need to do this again; otherwise, run 191`configure`. 192 193 $ ./configure [Configure Args] 194 195When building the documentation you need a full Erlang/OTP-%OTP-VSN% system in 196the `$PATH`. 197 198 $ export PATH=$ERL_TOP/bin:$PATH # Assuming bash/sh 199 200For the FOP print formatter, two steps must be taken: 201 202* Adding the location of your installation of `fop` in `$FOP_HOME`. 203 204 $ export FOP_HOME=/path/to/fop/dir # Assuming bash/sh 205 206* Adding the `fop` script (in `$FOP_HOME`) to your `$PATH`, either by adding `$FOP_HOME` to `$PATH`, or by copying the `fop` script to a directory already in your `$PATH`. 207 208Build the documentation. 209 210 $ make docs 211 212It is possible to limit which types of documentation is build by passing the `DOC_TARGETS` 213environment variable to `make docs`. The currently available types are: `html`, `pdf`, `man` and 214`chunks`. Example: 215 216 $ make docs DOC_TARGETS=chunks 217 218#### Build Issues #### 219 220We have sometimes experienced problems with Oracle's `java` running out of 221memory when running `fop`. Increasing the amount of memory available 222as follows has in our case solved the problem. 223 224 $ export FOP_OPTS="-Xmx<Installed amount of RAM in MB>m" 225 226More information can be found at 227* <http://xmlgraphics.apache.org/fop/0.95/running.html#memory>. 228 229 230### How to Install the Documentation ### 231 232The documentation can be installed either using the `install-docs` target, 233or using the `release_docs` target. 234 235* If you have installed Erlang/OTP using the `install` target, install 236 the documentation using the `install-docs` target. Install locations 237 determined by `configure` will be used. `$DESTDIR` can be used the 238 same way as when doing `make install`. 239 240 $ make install-docs 241 242* If you have installed Erlang/OTP using the `release` target, install 243 the documentation using the `release_docs` target. You typically want 244 to use the same `RELEASE_ROOT` as when invoking `make release`. 245 246 $ make release_docs RELEASE_ROOT=<release dir> 247 248It is possible to limit which types of documentation is released using the same `DOC_TARGETS` 249environment variable as when building documentation. 250 251### Accessing the Documentation ### 252 253After installation you can access the documentation by 254 255* Reading man pages. Make sure that `erl` is referring to the 256 installed version. For example `/usr/local/bin/erl`. 257 Try viewing at the man page for Mnesia 258 259 $ erl -man mnesia 260 261* Browsing the html pages by loading the page `/usr/local/lib/erlang/doc/erlang/index.html` 262 or `<BaseDir>/lib/erlang/doc/erlang/index.html` if the prefix option has been used. 263 264* Read the embedded documentation by using the built-in shell functions `h/1,2,3` or 265 `ht/1,2,3`. 266 267### How to Install the Pre-formatted Documentation ### 268 269Pre-formatted [html documentation][] and [man pages][] can be downloaded from 270* <http://www.erlang.org/download.html>. 271 272Extract the html archive in the installation directory. 273 274 $ cd <ReleaseDir> 275 $ tar -zxf otp_html_%OTP-VSN%.tar.gz 276 277For `erl -man <page>` to work the Unix manual pages have to be 278installed in the same way, i.e. 279 280 $ cd <ReleaseDir> 281 $ tar -zxf otp_man_%OTP-VSN%.tar.gz 282 283Where `<ReleaseDir>` is 284 285* `<PrefixDir>/lib/erlang` if you have installed Erlang/OTP using 286 `make install`. 287* `$DESTDIR<PrefixDir>/lib/erlang` if you have installed Erlang/OTP 288 using `make install DESTDIR=<TmpInstallDir>`. 289* `RELEASE_ROOT` if you have installed using 290 `make release RELEASE_ROOT=<ReleaseDir>`. 291 292 293Advanced configuration and build of Erlang/OTP 294---------------------------------------------- 295 296If you want to tailor your Erlang/OTP build and installation, please read 297on for detailed information about the individual steps. 298 299### make and $ERL\_TOP ### 300 301All the makefiles in the entire directory tree use the environment 302variable `ERL_TOP` to find the absolute path of the installation. The 303`configure` script will figure this out and set it in the top level 304Makefile (which, when building, it will pass on). However, when 305developing it is sometimes convenient to be able to run make in a 306subdirectory. To do this you must set the `ERL_TOP` variable 307before you run make. 308 309For example, assume your GNU make program is called `make` and you 310want to rebuild the application `STDLIB`, then you could do: 311 312 $ cd lib/stdlib; env ERL_TOP=<Dir> make 313 314where `<Dir>` would be what you find `ERL_TOP` is set to in the top level 315Makefile. 316 317### otp\_build vs configure/make ### 318 319Building Erlang/OTP can be done either by using the `$ERL_TOP/otp_build` 320script, or by invoking `$ERL_TOP/configure` and `make` directly. Building using 321`otp_build` is easier since it involves fewer steps, but the `otp_build` build 322procedure is not as flexible as the `configure`/`make` build procedure. The binary 323releases for Windows that we deliver are built using `otp_build`. 324 325### Configuring ### 326 327The configure script is created by the GNU autoconf utility, which 328checks for system specific features and then creates a number of makefiles. 329 330The configure script allows you to customize a number of parameters; 331type `./configure --help` or `./configure --help=recursive` for details. 332`./configure --help=recursive` will give help for all `configure` scripts in 333all applications. 334 335One of the things you can specify is where Erlang/OTP should be installed. By 336default Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang}`. 337To keep the same structure but install in a different place, `<Dir>` say, 338use the `--prefix` argument like this: `./configure --prefix=<Dir>`. 339 340Some of the available `configure` options are: 341 342* `--prefix=PATH` - Specify installation prefix. 343* `--disable-parallel-configure` - Disable parallel execution of 344 `configure` scripts (parallel execution is enabled by default) 345* `--{enable,disable}-jit` - Force enabling or disabling of the JIT. 346* `--{enable,disable}-kernel-poll` - Kernel poll support (enabled by 347 default if possible) 348* `--enable-m64-build` - Build 64-bit binaries using the `-m64` flag to 349 `(g)cc` 350* `--enable-m32-build` - Build 32-bit binaries using the `-m32` flag to 351 `(g)cc` 352* `--{enable,disable}-pie` - Build position independent executable binaries. 353* `--with-assumed-cache-line-size=SIZE` - Set assumed cache-line size in 354 bytes. Default is 64. Valid values are powers of two between and 355 including 16 and 8192. The runtime system use this value in order to 356 try to avoid false sharing. A too large value wastes memory. A to 357 small value will increase the amount of false sharing. 358* `--{with,without}-termcap` - termcap (without implies that only the old 359 Erlang shell can be used) 360* `--with-javac=JAVAC` - Specify Java compiler to use 361* `--{with,without}-javac` - Java compiler (without implies that the 362 `jinterface` application won't be built) 363* `--{enable,disable}-builtin-zlib` - Use the built-in source for zlib. 364* `--{enable,disable}-dynamic-ssl-lib` - Enable or disable dynamic OpenSSL 365 libraries when linking the crypto NIF. By default dynamic linking is 366 done unless it does not work or is if it is a Windows system. 367* `--{with,without}-ssl` - OpenSSL (without implies that the `crypto`, 368 `ssh`, and `ssl` won't be built) 369* `--with-ssl=PATH` - Specify base location of OpenSSL include and lib 370 directories. 371* `--with-ssl-incl=PATH` - Specify base location of OpenSSL `include` 372 directory (if different than base location specified by --with-ssl=PATH). 373* `--with-ssl-zlib=PATH` - Path to static zlib library to link the 374 crypto NIF with. This zlib library is most often not necessary but 375 might be needed in order to link the NIF in some cases. 376* `--with-ssl-lib-subdir=RELATIVE_PATH` - Specify extra OpenSSL lib 377 sub-directory to search in (relative to base directory). 378* `--with-ssl-rpath=yes|no|PATHS` - Runtime library path for OpenSSL. 379 Default is `yes`, which equates to a number of standard locations. If 380 `no`, then no runtime library paths will be used. Anything else should be 381 a comma or colon separated list of paths. 382* `--with-libatomic_ops=PATH` - Use the `libatomic_ops` library for atomic 383 memory accesses. If `configure` should inform you about no native atomic 384 implementation available, you typically want to try using the 385 `libatomic_ops` library. It can be downloaded from 386 <https://github.com/ivmai/libatomic_ops/>. 387* `--disable-smp-require-native-atomics` - By default `configure` will 388 fail if an SMP runtime system is about to be built, and no implementation 389 for native atomic memory accesses can be found. If this happens, you are 390 encouraged to find a native atomic implementation that can be used, e.g., 391 using `libatomic_ops`, but by passing `--disable-smp-require-native-atomics` 392 you can build using a fallback implementation based on mutexes or spinlocks. 393 Performance of the SMP runtime system will however suffer immensely without 394 an implementation for native atomic memory accesses. 395* `--enable-static-{nifs,drivers}` - To allow usage of nifs and drivers on OSs 396 that do not support dynamic linking of libraries it is possible to statically 397 link nifs and drivers with the main Erlang VM binary. This is done by passing 398 a comma separated list to the archives that you want to statically link. e.g. 399 `--enable-static-nifs=/home/$USER/my_nif.a`. The path has to be absolute and the 400 name of the archive has to be the same as the module, i.e. `my_nif` in the 401 example above. This is also true for drivers, but then it is the driver name 402 that has to be the same as the filename. You also have to define 403 `STATIC_ERLANG_{NIF,DRIVER}` when compiling the .o files for the nif/driver. 404 If your nif/driver depends on some other dynamic library, you now have to link 405 that to the Erlang VM binary. This is easily achieved by passing `LIBS=-llibname` 406 to configure. 407* `--without-$app` - By default all applications in Erlang/OTP will be included 408 in a release. If this is not wanted it is possible to specify that Erlang/OTP 409 should be compiled without one or more applications, i.e. `--without-wx`. There is 410 no automatic dependency handling between applications. If you disable 411 an application that another application depends on, you also have to disable the 412 dependant application. 413* `--enable-gettimeofday-as-os-system-time` - Force usage of `gettimeofday()` for 414 OS system time. 415* `--enable-prefer-elapsed-monotonic-time-during-suspend` - Prefer an OS monotonic 416 time source with elapsed time during suspend. 417* `--disable-prefer-elapsed-monotonic-time-during-suspend` - Do not prefer an OS 418 monotonic time source with elapsed time during suspend. 419* `--with-clock-resolution=high|low` - Try to find clock sources for OS system 420 time, and OS monotonic time with higher or lower resolution than chosen by 421 default. Note that both alternatives may have a negative impact on the performance 422 and scalability compared to the default clock sources chosen. 423* `--disable-saved-compile-time` - Disable saving of compile date and time 424 in the emulator binary. 425 426If you or your system has special requirements please read the `Makefile` for 427additional configuration information. 428 429#### Important Variables Inspected by configure #### 430 431##### Compiler and Linker ##### 432 433* `CC` - C compiler. 434* `CFLAGS` - C compiler flags. Defaults to "-g -O2". If you set it, 435 these will be removed. 436* `STATIC_CFLAGS` - Static C compiler flags. 437* `CFLAG_RUNTIME_LIBRARY_PATH` - This flag should set runtime library 438 search path for the shared libraries. Note that this actually is a 439 linker flag, but it needs to be passed via the compiler. 440* `CPP` - C pre-processor. 441* `CPPFLAGS` - C pre-processor flags. 442* `CXX` - C++ compiler. 443* `CXXFLAGS` - C++ compiler flags. 444* `LD` - Linker. 445* `LDFLAGS` - Linker flags. 446* `LIBS` - Libraries. 447 448##### Dynamic Erlang Driver Linking ##### 449 450> *NOTE*: Either set all or none of the `DED_LD*` variables (with the exception 451> of `DED_LDFLAGS_CONFTEST`). 452 453* `DED_LD` - Linker for Dynamically loaded Erlang Drivers. 454* `DED_LDFLAGS` - Linker flags to use with `DED_LD`. 455* `DED_LDFLAGS_CONFTEST` - Linker flags to use with `DED_LD` in configure 456 link tests if `DED_LDFLAGS` cannot be used in such tests. If not set, 457 `DED_LDFLAGS` will be used in configure tests. 458* `DED_LD_FLAG_RUNTIME_LIBRARY_PATH` - This flag should set runtime library 459 search path for shared libraries when linking with `DED_LD`. 460 461##### Large File Support ##### 462 463> *NOTE*: Either set all or none of the `LFS_*` variables. 464 465* `LFS_CFLAGS` - Large file support C compiler flags. 466* `LFS_LDFLAGS` - Large file support linker flags. 467* `LFS_LIBS` - Large file support libraries. 468 469##### Other Tools ##### 470 471* `RANLIB` - `ranlib` archive index tool. 472* `AR` - `ar` archiving tool. 473* `GETCONF` - `getconf` system configuration inspection tool. `getconf` is 474 currently used for finding out large file support flags to use, and 475 on Linux systems for finding out if we have an NPTL thread library or 476 not. 477 478#### Updating configure Scripts #### 479 480Generated `configure` scripts are nowadays included in the git repository. 481 482If you modify any `configure.in` files or the `erts/aclocal.m4` file, you need 483to regenerate `configure` scripts before the changes will take effect. First 484ensure that you have GNU `autoconf` of version 2.69 in your path. Then execute 485`./otp_build update_configure [--no-commit]` in the `$ERL_TOP` directory. The 486`otp_build` script will verify that `autoconf` is of correct version and will 487refuse to update the `configure` scripts if it is of any other version. 488 489#### Atomic Memory Operations and the VM #### 490 491The VM with SMP support makes quite a heavy use of atomic memory operations. 492An implementation providing native atomic memory operations is therefore very 493important when building Erlang/OTP. By default the VM will refuse to build 494if native atomic memory operations are not available. 495 496Erlang/OTP itself provides implementations of native atomic memory operations 497that can be used when compiling with a `gcc` compatible compiler for 32/64-bit 498x86, 32/64-bit SPARC V9, 32-bit PowerPC, or 32-bit Tile. When compiling with 499a `gcc` compatible compiler for other architectures, the VM may be able to make 500use of native atomic operations using the `__atomic_*` builtins (may be 501available when using a `gcc` of at least version 4.7) and/or using the 502`__sync_*` builtins (may be available when using a `gcc` of at least version 5034.1). If only the `gcc`'s `__sync_*` builtins are available, the performance 504will suffer. Such a configuration should only be used as a last resort. When 505compiling on Windows using a MicroSoft Visual C++ compiler native atomic 506memory operations are provided by Windows APIs. 507 508Native atomic implementation in the order preferred: 5091. The implementation provided by Erlang/OTP. 5102. The API provided by Windows. 5113. The implementation based on the `gcc` `__atomic_*` builtins. 5124. If none of the above are available for your architecture/compiler, you 513 are recommended to build and install [libatomic_ops][] before building 514 Erlang/OTP. The `libatomic_ops` library provides native atomic memory 515 operations for a variety of architectures and compilers. When building 516 Erlang/OTP you need to inform the build system of where the 517 `libatomic_ops` library is installed using the 518 `--with-libatomic_ops=PATH` `configure` switch. 5195. As a last resort, the implementation solely based on the `gcc` 520 `__sync_*` builtins. This will however cause lots of expensive and 521 unnecessary memory barrier instructions to be issued. That is, 522 performance will suffer. The `configure` script will warn at the end 523 of its execution if it cannot find any other alternative than this. 524 525### Building ### 526 527Building Erlang/OTP on a relatively fast computer takes approximately 5285 minutes. To speed it up, you can utilize parallel make with the `-j<num_jobs>` option. 529 530 $ export MAKEFLAGS=-j8 # Assuming bash/sh 531 $ make 532 533If you've upgraded the source with a patch you may need to clean up from previous 534builds before the new build. 535Make sure to read the [Pre-built Source Release][] section below before doing a `make clean`. 536 537Other useful information can be found at our GitHub wiki: 538* <https://github.com/erlang/otp/wiki> 539 540#### Within Git #### 541 542Build the same way as when building the unpacked tar file. 543 544#### OS X (Darwin) #### 545 546Make sure that the command `hostname` returns a valid fully qualified host 547name (this is configured in `/etc/hostconfig`). Otherwise you might experience 548problems when running distributed systems. 549 550If you develop linked-in drivers (shared library) you need to link using 551`gcc` and the flags `-bundle -flat_namespace -undefined suppress`. You also 552include `-fno-common` in `CFLAGS` when compiling. Use `.so` as the library 553suffix. 554 555If you have Xcode 4.3, or later, you will also need to download 556"Command Line Tools" via the Downloads preference pane in Xcode. 557 558#### Building with wxErlang #### 559 560If you want to build the `wx` application, you will need to get wxWidgets-3.0 561(`wxWidgets-3.0.3.tar.bz2` from <https://github.com/wxWidgets/wxWidgets/releases/download/v3.0.3/wxWidgets-3.0.3.tar.bz2>) or get it from github with bug fixes: 562 563 $ git clone --branch WX_3_0_BRANCH git@github.com:wxWidgets/wxWidgets.git 564 565The wxWidgets-3.1 version should also work if 2.8 compatibility is enabled, 566add `--enable-compat28` to configure commands below. 567 568Configure and build wxWidgets (shared library on linux): 569 570 $ ./configure --prefix=/usr/local 571 $ make && sudo make install 572 $ export PATH=/usr/local/bin:$PATH 573 574Configure and build wxWidgets (static library on linux): 575 576 $ export CFLAGS=-fPIC 577 $ export CXXFLAGS=-fPIC 578 $ ./configure --prefix=/usr/local --disable-shared 579 $ make && sudo make install 580 $ export PATH=/usr/local/bin:$PATH 581 582Configure and build wxWidgets (on Mavericks - 10.9): 583 584 $ ./configure --with-cocoa --prefix=/usr/local 585 or without support for old versions and with static libs 586 $ ./configure --with-cocoa --prefix=/usr/local --with-macosx-version-min=10.9 --disable-shared 587 $ make 588 $ sudo make install 589 $ export PATH=/usr/local/bin:$PATH 590 591Check that you got the correct wx-config 592 593 $ which wx-config && wx-config --version-full 594 595Build Erlang/OTP 596 597 $ export PATH=/usr/local/bin:$PATH 598 $ cd $ERL_TOP 599 $ ./configure 600 $ make 601 $ sudo make install 602 603 604#### Pre-built Source Release #### 605 606The source release is delivered with a lot of platform independent 607build results already pre-built. If you want to remove these pre-built 608files, invoke `./otp_build remove_prebuilt_files` from the `$ERL_TOP` 609directory. After you have done this, you can build exactly the same way 610as before, but the build process will take a much longer time. 611 612> *WARNING*: Doing `make clean` in an arbitrary directory of the source 613> tree, may remove files needed for bootstrapping the build. 614> 615> Doing `./otp_build save_bootstrap` from the `$ERL_TOP` directory before 616> doing `make clean` will ensure that it will be possible to build after 617> doing `make clean`. `./otp_build save_bootstrap` will be invoked 618> automatically when `make` is invoked from `$ERL_TOP` with either the 619> `clean` target, or the default target. It is also automatically invoked 620> if `./otp_build remove_prebuilt_files` is invoked. 621> 622> If you need to verify the bootstrap beam files match the provided 623> source files, use `./otp_build update_primary` to create a new commit that 624> contains differences, if any exist. 625 626#### How to Build a Debug Enabled Erlang RunTime System #### 627 628After completing all the normal building steps described above a debug 629enabled runtime system can be built. To do this you have to change 630directory to `$ERL_TOP/erts/emulator` and execute: 631 632 $ (cd $ERL_TOP/erts/emulator && make debug) 633 634This will produce a beam.smp.debug executable. The 635file are installed along side with the normal (opt) version `beam.smp`. 636 637To start the debug enabled runtime system execute: 638 639 $ $ERL_TOP/bin/cerl -debug 640 641The debug enabled runtime system features lock violation checking, 642assert checking and various sanity checks to help a developer ensure 643correctness. Some of these features can be enabled on a normal beam 644using appropriate configure options. 645 646There are other types of runtime systems that can be built as well 647using the similar steps just described. 648 649 $ (cd $ERL_TOP/erts/emulator && make $TYPE) 650 651where `$TYPE` is `opt`, `gcov`, `gprof`, `debug`, `valgrind`, `asan` or `lcnt`. 652These different beam types are useful for debugging and profiling 653purposes. 654 655 656### Installing ### 657 658* Staged install using [DESTDIR][]. You can perform the install 659 phase in a temporary directory and later move the installation into 660 its correct location by use of the `DESTDIR` variable: 661 662 $ make DESTDIR=<tmp install dir> install 663 664 The installation will be created in a location prefixed by `$DESTDIR`. 665 It can, however, not be run from there. It needs to be moved into the 666 correct location before it can be run. If `DESTDIR` have not been set 667 but `INSTALL_PREFIX` has been set, `DESTDIR` will be set to 668 `INSTALL_PREFIX`. Note that `INSTALL_PREFIX` in pre R13B04 was buggy 669 and behaved as `EXTRA_PREFIX` (see below). There are lots of areas of 670 use for an installation procedure using `DESTDIR`, e.g. when creating 671 a package, cross compiling, etc. Here is an example where the 672 installation should be located under `/opt/local`: 673 674 $ ./configure --prefix=/opt/local 675 $ make 676 $ make DESTDIR=/tmp/erlang-build install 677 $ cd /tmp/erlang-build/opt/local 678 $ # gnu-tar is used in this example 679 $ tar -zcf /home/me/my-erlang-build.tgz * 680 $ su - 681 Password: ***** 682 $ cd /opt/local 683 $ tar -zxf /home/me/my-erlang-build.tgz 684 685* Install using the `release` target. Instead of doing `make install` you 686 can create the installation in whatever directory you like using the 687 `release` target and run the `Install` script yourself. `RELEASE_ROOT` 688 is used for specifying the directory where the installation should be 689 created. This is what by default ends up under `/usr/local/lib/erlang` 690 if you do the install using `make install`. All installation paths 691 provided in the `configure` phase are ignored, as well as `DESTDIR`, 692 and `INSTALL_PREFIX`. If you want links from a specific `bin` directory 693 to the installation you have to set those up yourself. An example where 694 Erlang/OTP should be located at `/home/me/OTP`: 695 696 $ ./configure 697 $ make 698 $ make RELEASE_ROOT=/home/me/OTP release 699 $ cd /home/me/OTP 700 $ ./Install -minimal /home/me/OTP 701 $ mkdir -p /home/me/bin 702 $ cd /home/me/bin 703 $ ln -s /home/me/OTP/bin/erl erl 704 $ ln -s /home/me/OTP/bin/erlc erlc 705 $ ln -s /home/me/OTP/bin/escript escript 706 ... 707 708 The `Install` script should currently be invoked as follows in the 709 directory where it resides (the top directory): 710 711 $ ./Install [-cross] [-minimal|-sasl] <ERL_ROOT> 712 713 where: 714 715 * `-minimal` Creates an installation that starts up a minimal amount 716 of applications, i.e., only `kernel` and `stdlib` are started. The 717 minimal system is normally enough, and is what `make install` uses. 718 * `-sasl` Creates an installation that also starts up the `sasl` 719 application. 720 * `-cross` For cross compilation. Informs the install script that it 721 is run on the build machine. 722 * `<ERL_ROOT>` - The absolute path to the Erlang installation to use 723 at run time. This is often the same as the current working directory, 724 but does not have to be. It can follow any other path through the 725 file system to the same directory. 726 727 If neither `-minimal`, nor `-sasl` is passed as argument you will be 728 prompted. 729 730* Test install using `EXTRA_PREFIX`. The content of the `EXTRA_PREFIX` 731 variable will prefix all installation paths when doing `make install`. 732 Note that `EXTRA_PREFIX` is similar to `DESTDIR`, but it does *not* have 733 the same effect as `DESTDIR`. The installation can and have to be run 734 from the location specified by `EXTRA_PREFIX`. That is, it can be useful 735 if you want to try the system out, running test suites, etc, before doing 736 the real install without `EXTRA_PREFIX`. 737 738#### Symbolic Links in --bindir #### 739 740When doing `make install` and the default installation prefix is used, 741relative symbolic links will be created from `/usr/local/bin` to all public 742Erlang/OTP executables in `/usr/local/lib/erlang/bin`. The installation phase 743will try to create relative symbolic links as long as `--bindir` and the 744Erlang bin directory, located under `--libdir`, both have `--exec-prefix` as 745prefix. Where `--exec-prefix` defaults to `--prefix`. `--prefix`, 746`--exec-prefix`, `--bindir`, and `--libdir` are all arguments that can be 747passed to `configure`. One can force relative, or absolute links by passing 748`BINDIR_SYMLINKS=relative|absolute` as arguments to `make` during the install 749phase. Note that such a request might cause a failure if the request cannot 750be satisfied. 751 752 753### Running ### 754 755 [$ERL_TOP/HOWTO/INSTALL-CROSS.md]: INSTALL-CROSS.md 756 [$ERL_TOP/HOWTO/INSTALL-WIN32.md]: INSTALL-WIN32.md 757 [DESTDIR]: http://www.gnu.org/prep/standards/html_node/DESTDIR.html 758 [Building in Git]: #Advanced-configuration-and-build-of-ErlangOTP_Building_Within-Git 759 [Advanced Configure]: #Advanced-configuration-and-build-of-ErlangOTP_Configuring 760 [Pre-built Source Release]: #Advanced-configuration-and-build-of-ErlangOTP_Building_Prebuilt-Source-Release 761 [make and $ERL_TOP]: #Advanced-configuration-and-build-of-ErlangOTP_make-and-ERLTOP 762 [html documentation]: http://www.erlang.org/download/otp_doc_html_%OTP-VSN%.tar.gz 763 [man pages]: http://www.erlang.org/download/otp_doc_man_%OTP-VSN%.tar.gz 764 [the released source tar ball]: http://www.erlang.org/download/otp_src_%OTP-VSN%.tar.gz 765 [System Principles]: system/system_principles:system_principles 766 [native build]: #How-to-Build-and-Install-ErlangOTP 767 [cross build]: INSTALL-CROSS.md 768 [Required Utilities]: #Required-Utilities 769 [Optional Utilities]: #Optional-Utilities 770 [Building on a Mac]: #Advanced-configuration-and-build-of-ErlangOTP_Building_OS-X-Darwin 771 [Building with wxErlang]: #Advanced-configuration-and-build-of-ErlangOTP_Building_Building-with-wxErlang 772 [libatomic_ops]: https://github.com/ivmai/libatomic_ops/ 773 774 775### Erlang/OTP test architectures ### 776 777 778Erlang/OTP are currently tested on the following hardware and Opererating systems. 779This is not an exhaustive list, but we try to keep it as up to date as possible. 780 781Architecture 782 783* x86, x86-64 784* Aarch32, Aarch64 785* powerpc, powerpc64le 786 787Operating System 788 789* Fedora 31 790* FreeBSD 791* macOS 10.4 - 11.2 792* MontaVista 4 793* NetBSD 794* OpenBSD 795* SLES 10, 11, 12 796* SunOS 5.11 797* Ubuntu 10.04 - 20.04 798* Windows 10, Windows Server 2019 799 800