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