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