diff options
Diffstat (limited to 'HOWTO/INSTALL.md')
| -rw-r--r-- | HOWTO/INSTALL.md | 971 |
1 files changed, 507 insertions, 464 deletions
diff --git a/HOWTO/INSTALL.md b/HOWTO/INSTALL.md index 3dde37bfec..5b3a09df2b 100644 --- a/HOWTO/INSTALL.md +++ b/HOWTO/INSTALL.md @@ -4,174 +4,109 @@ Building and Installing Erlang/OTP Introduction ------------ -This document describes how to build and install Erlang/OTP-%OTP-REL%. You -are advised to read the whole document before attempting to build and install -Erlang/OTP. You can find more information about Open Source Erlang/OTP at: +This document describes how to build and install Erlang/OTP-%OTP-REL%. +Erlang/OTP should be possible to build from source on any Unix/Linux system, +including OS X. You are advised to read the whole document +before attempting to build and install Erlang/OTP. - <http://www.erlang.org/> +The source code can be downloaded from the official site of Erlang/OTP or GitHub. +* <http://www.erlang.org> +* <https://github.com/erlang/otp> -The source code for Erlang/OTP can also be found in a Git repository: - - <http://github.com/erlang/otp> - -Erlang/OTP should be possible to build from source on any Unix system, -including Mac OS X. This document describes how to native compile Erlang/OTP -on Unix. For detailed instructions on how to - -* cross compile Erlang/OTP, see the [$ERL_TOP/HOWTO/INSTALL-CROSS.md][] - document. - -* build Erlang/OTP on Windows, see the [$ERL_TOP/HOWTO/INSTALL-WIN32.md][] - document. - - Binary releases for Windows can be found at - <http://www.erlang.org/download.html>. +Required Utilities +------------------ -Before reading the above mentioned documents you are in any case advised to -read this document first, since it covers building Erlang/OTP in general as -well as other important information. +These are the tools you need in order to unpack and build Erlang/OTP. -Daily Build and Test --------------------- -At Ericsson we have a "Daily Build and Test" that runs on: +> *WARNING*: Please have a look at the [Known platform issues][] chapter +> before you start. -* Solaris 8, 9 - * Sparc32 - * Sparc64 -* Solaris 10 - * Sparc32 - * Sparc64 - * x86 -* SuSE Linux/GNU 9.4, 10.1 - * x86 -* SuSE Linux/GNU 10.0, 10.1, 11.0 - * x86 - * x86\_64 -* openSuSE 11.4 (Celadon) - * x86\_64 (valgrind) -* Fedora 7 - * PowerPC -* Fedora 14 - * x86\_64 -* Gentoo Linux/GNU 1.12.11.1 - * x86 -* Ubuntu Linux/GNU 7.04, 10.04, 10.10, 11.0 - * x86\_64 -* MontaVista Linux/GNU 4.0.1 - * PowerPC -* FreeBSD 8.2 - * x86 -* OpenBSD 5.0 - * x86\_64 -* Mac OS X 10.5.8 (Leopard), 10.7.3 (Lion), 10.9 (Mavericks) - * x86 -* Windows XP SP3, 2003, Vista, 7 - * x86 -* Windows 7 - * x86\_64 +### Unpacking ### -We also have the following "Daily Cross Builds": +* GNU unzip, or a modern uncompress. +* A TAR program that understands the GNU TAR format for long filenames. -* SuSE Linux/GNU 10.1 x86 -> SuSE Linux/GNU 10.1 x86\_64 -* SuSE Linux/GNU 10.1 x86\_64 -> Linux/GNU TILEPro64 +### Building ### -and the following "Daily Cross Build Tests": +* GNU `make` +* Compiler -- GNU C Compiler, `gcc` or the C compiler frontend for LLVM, `clang`. +* Perl 5 +* GNU `m4` -- If HiPE (native code) support is enabled. HiPE can be + disabled using `--disable-hipe` +* `ncurses`, `termcap`, or `termlib` -- The development headers and + libraries are needed, often known as `ncurses-devel`. Use + `--without-termcap` to build without any of these libraries. Note that + in this case only the old shell (without any line editing) can be used. +* `sed` -- Stream Editor for basic text transformation. -* SuSE Linux/GNU 10.1 x86\_64 +#### Building in Git #### -Versions Known NOT to Work --------------------------- +* GNU `autoconf` of at least version 2.59. Note that `autoconf` is not + needed when building an unmodified version of the released source. -* Suse linux 9.1 is shipped with a patched GCC version 3.3.3, having the - rpm named `gcc-3.3.3-41`. That version has a serious optimization bug - that makes it unusable for building the Erlang emulator. Please - upgrade GCC to a newer version before building on Suse 9.1. Suse Linux - Enterprise edition 9 (SLES9) has `gcc-3.3.3-43` and is not affected. +#### Building on OS X #### -* `gcc-4.3.0` has a serious optimizer bug. It produces an Erlang emulator - that will crash immediately. The bug is supposed to be fixed in - `gcc-4.3.1`. +* Xcode -- Download and install via the Mac App Store. + Read about [Building on a Mac][] before proceeding. -* FreeBSD had a bug which caused `kqueue`/`poll`/`select` to fail to detect - that a `writev()` on a pipe has been made. This bug should have been fixed - in FreeBSD 6.3 and FreeBSD 7.0. NetBSD and DragonFlyBSD probably have or - have had the same bug. More information can be found at: +### Installing ### - * <http://www.freebsd.org/cgi/cvsweb.cgi/src/sys/kern/sys_pipe.c> - * <http://lists.freebsd.org/pipermail/freebsd-arch/2007-September/006790.html> +* An `install` program that can take multiple file names. -* `getcwd()` on Solaris 9 can cause an emulator crash. If you have - async-threads enabled you can increase the stack size of the - async-threads as a temporary workaround. See the `+a` command-line - argument in the documentation of `erl(1)`. Without async-threads the - emulator is not as vulnerable to this bug, but if you hit it without - async-threads the only workaround available is to enable async-threads - and increase the stack size of the async-threads. Sun has however - released patches that fixes the issue: - > Problem Description: 6448300 large mnttab can cause stack overrun - > during Solaris 9 getcwd +Optional Utilities +------------------ - More information can be found at: +Some applications are automatically skipped if the dependencies aren't met. +Here is a list of utilities needed for those applications. You will +also find the utilities needed for building the documentation. - * <http://sunsolve.sun.com/search/document.do?assetkey=1-21-112874-40-1&searchclause=6448300> - * <http://sunsolve.sun.com/search/document.do?assetkey=1-21-114432-29-1&searchclause=6448300> +### Building ### -Required Utilities ------------------- +* OpenSSL -- The opensource toolkit for Secure Socket Layer + and Transport Layer Security. + Required for building the application `crypto`. + Further, `ssl` and `ssh` require a working crypto application and + will also be skipped if OpenSSL is missing. The `public_key` + application will available without `crypto`, but the functionality + will be very limited. + + The development package of OpenSSL including the header files are needed as well + as the binary command program `openssl`. At least version 0.9.8 of OpenSSL is required. + Read more and download from <http://www.openssl.org>. +* Oracle Java SE JDK -- The Java Development Kit (Standard Edition). + Required for building the application `jinterface` and parts of `ic` and `orber`. + At least version 1.5.0 of the JDK is required. + + Download from <http://www.oracle.com/technetwork/java/javase/downloads>. + We have also tested with IBM's JDK 1.5.0. +* X Windows -- Development headers and libraries are needed + to build the Erlang/OTP application `gs` on Unix/Linux. +* `flex` -- Headers and libraries are needed to build the flex + scanner for the `megaco` application on Unix/Linux. +* wxWidgets -- Toolkit for GUI applications. + Required for building the `wx` application. At least + version 3.0 of wxWidgets is required. -These are the tools you will need in order to unpack and build Erlang/OTP. + Download from <http://sourceforge.net/projects/wxwindows/files/3.0.0/> + or get it from GitHub: <https://github.com/wxWidgets/wxWidgets> -### Unpacking ### + Further instructions on wxWidgets, read [Building with wxErlang][]. -* GNU unzip, or a modern uncompress. -* A TAR program that understands the GNU TAR format for long filenames - (such as GNU TAR). -### Building ### -* GNU `make` -* `gcc` -- GNU C compiler -* Perl 5 -* GNU `m4` -- If HiPE (native code) support is enabled. HiPE can be - disabled using `--disable-hipe` -* `ncurses`, `termcap`, or `termlib` -- The development headers and - libraries are needed, often known as `ncurses-devel`. Use - `--without-termcap` to build without any of these libraries. Note that - in this case only the old shell (without any line editing) can be used. -* OpenSSL -- Optional, but needed for building the Erlang/OTP applications - `ssl` and `crypto`. You need the "development package" of OpenSSL, i.e. - including the header files. For building the application `ssl` the OpenSSL - binary command program `openssl` is also needed. At least version 0.9.8 - of OpenSSL is required. Can be downloaded from <http://www.openssl.org>. -* Sun Java jdk-1.5.0 or higher -- Optional but needed for building the - Erlang/OTP application `jinterface` and parts of `ic` and `orber`. Can - be downloaded from <http://java.sun.com>. We have also tested IBM's - JDK 1.5.0. -* X Windows -- Optional, but development headers and libraries are needed - to build the Erlang/OTP application `gs` on Unix/Linux. -* `sed` -- There seem to be some problems with some of the `sed` version on - Solaris. Make sure `/bin/sed` or `/usr/bin/sed` is used on the Solaris - platform. -* `flex` -- Optional, headers and libraries are needed to build the `flex` - scanner for the `megaco` application on Unix/Linux. +### Building Documentation ### -#### Building Documentation #### +* `xsltproc` -- A command line XSLT processor. -* `xsltproc` -- XSLT processor. A tool for applying XSLT stylesheets - to XML documents. Can be downloaded from + A tool for applying XSLT stylesheets + to XML documents. Download xsltproc from <http://xmlsoft.org/XSLT/xsltproc2.html>. + * `fop` -- Apache FOP print formatter (requires Java). Can be downloaded from <http://xmlgraphics.apache.org/fop>. -#### Building in Git #### -* GNU `autoconf` of at least version 2.59. Note that `autoconf` is not - needed when building an unmodified version of the released source. - -### Installing ### - -* An `install` program that can take multiple file names. How to Build and Install Erlang/OTP ----------------------------------- @@ -186,65 +121,205 @@ section below before proceeding. ### Unpacking ### -Step 1: Start by unpacking the Erlang/OTP distribution file with your GNU +Start by unpacking the Erlang/OTP distribution file with your GNU compatible TAR program. - $ gunzip -c otp_src_%OTP-REL%.tar.gz | tar xf - + $ tar -zxf otp_src_%OTP-VSN%.tar.gz # Assuming bash/sh -alternatively: +Now change directory into the base directory and set the `$ERL_TOP` variable. - $ zcat otp_src_%OTP-REL%.tar.gz | tar xf - + $ cd otp_src_%OTP-VSN% + $ export ERL_TOP=`pwd` # Assuming bash/sh +### Configuring ### -Step 2: Now cd into the base directory (`$ERL_TOP`). +Run the following commands to configure the build: - $ cd otp_src_%OTP-REL% + $ ./configure [ options ] -### Configuring ### +> *NOTE*: If you are building Erlang/OTP from git you will need to run `./otp_build autoconf` to generate +> the configure scripts. -Step 3: On some platforms Perl may behave strangely if certain locales are -set, so optionally you may need to set the LANG variable: +By default, Erlang/OTP release will be installed in `/usr/local/{bin,lib/erlang}`. +If you for instance don't have the permission to install in the standard location, + you can install Erlang/OTP somewhere else. For example, to install in +`/opt/erlang/%OTP-VSN%/{bin,lib/erlang}`, use the `--prefix=/opt/erlang/%OTP-VSN%` option. - # Bourne shell - $ LANG=C; export LANG +On some platforms Perl may behave strangely if certain locales are +set. If you get errors when building, try setting the LANG variable: -or + $ export LANG=C # Assuming bash/sh - # C-Shell - $ setenv LANG C -Step 4: Run the following commands to configure the build: +### Building ### - $ ./configure [ options ] +Build the Erlang/OTP release. -If you are building it from git you will need to run `autoconf` to generate configure file. -By default, Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang}`. -To instead install in `<BaseDir>/{bin,lib/erlang}`, use the -`--prefix=<BaseDir>` option. + $ make -If you upgraded the source with some patch you may need to clean up -from previous builds before the new build. Before doing a `make clean`, -be sure to read the [Pre-built Source Release][] section below. -### Building ### +### Testing ### -Step 5: Build the Erlang/OTP package. +Before installation you should test whether your build is working properly +by running our smoke test. The smoke test is a subset of the complete Erlang/OTP test suites. +First you will need to build and release the test suites. - $ make + $ make release_tests + +This creates an additional folder in `$ERL_TOP/release` called `tests`. +Now, it's time to start the smoke test. + + $ cd release/tests/test_server + $ $ERL_TOP/bin/erl -s ts install -s ts smoke_test batch -s init stop + +To verify that everything is ok you should open `$ERL_TOP/release/tests/test_server/index.html` +in your web browser and make sure that there are zero failed test cases. + +> *NOTE*: On builds without `crypto`, `ssl` and `ssh` there is a failed test case +> for undefined functions. Verify that the failed test case log only shows calls +> to skipped applications. ### Installing ### -Step 6: Install then Erlang/OTP package +You are now ready to install the Erlang/OTP release! +The following command will install the release on your system. $ make install -### A Closer Look at the individual Steps ### -Let us go through them in some detail. +### Running ### + +You should now have a working release of Erlang/OTP! +Jump to [System Principles][] for instructions on running Erlang/OTP. + + +### How to Build the Documentation ### + +Make sure you're in the top directory in the source tree. + + $ cd $ERL_TOP + +If you have just built Erlang/OTP in the current source tree, you have +already ran `configure` and do not need to do this again; otherwise, run +`configure`. + + $ ./configure [Configure Args] + +When building the documentation you need a full Erlang/OTP-%OTP-VSN% system in +the `$PATH`. + + $ export PATH=$ERL_TOP/bin:$PATH # Assuming bash/sh + +Build the documentation. + + $ make docs + +#### Build Issues #### + +We have sometimes experienced problems with Oracle's `java` running out of +memory when running `fop`. Increasing the amount of memory available +as follows has in our case solved the problem. + + $ export FOP_OPTS="-Xmx<Installed amount of RAM in MB>m" + +More information can be found at +* <http://xmlgraphics.apache.org/fop/0.95/running.html#memory>. + + +### How to Install the Documentation ### + +The documentation can be installed either using the `install-docs` target, +or using the `release_docs` target. + +* If you have installed Erlang/OTP using the `install` target, install + the documentation using the `install-docs` target. Install locations + determined by `configure` will be used. `$DESTDIR` can be used the + same way as when doing `make install`. + + $ make install-docs + +* If you have installed Erlang/OTP using the `release` target, install + the documentation using the `release_docs` target. You typically want + to use the same `RELEASE_ROOT` as when invoking `make release`. + + $ make release_docs RELEASE_ROOT=<release dir> + + +### Accessing the Documentation ### + +After installation you can access the documentation by + +* Reading man pages. Make sure that `erl` is referring to the + installed version. For example `/usr/local/bin/erl`. + Try viewing at the man page for Mnesia + + $ erl -man mnesia -#### Configuring #### +* Browsing the html pages by loading the page `/usr/local/lib/erlang/doc/erlang/index.html` + or `<BaseDir>/lib/erlang/doc/erlang/index.html` if the prefix option has been used. -Step 4 runs a configuration script created by the GNU autoconf utility, which + +### How to Install the Pre-formatted Documentation ### + +Pre-formatted [html documentation][] and [man pages][] can be downloaded from +* <http://www.erlang.org/download.html>. + +Extract the html archive in the installation directory. + + $ cd <ReleaseDir> + $ tar -zxf otp_html_%OTP-VSN%.tar.gz + +For `erl -man <page>` to work the Unix manual pages have to be +installed in the same way, i.e. + + $ cd <ReleaseDir> + $ tar -zxf otp_man_%OTP-VSN%.tar.gz + +Where `<ReleaseDir>` is + +* `<PrefixDir>/lib/erlang` if you have installed Erlang/OTP using + `make install`. +* `$DESTDIR<PrefixDir>/lib/erlang` if you have installed Erlang/OTP + using `make install DESTDIR=<TmpInstallDir>`. +* `RELEASE_ROOT` if you have installed using + `make release RELEASE_ROOT=<ReleaseDir>`. + + +Advanced configuration and build of Erlang/OTP +---------------------------------------------- + +If you want to tailor your Erlang/OTP build and installation, please read +on for detailed information about the individual steps. + +### make and $ERL\_TOP ### + +All the makefiles in the entire directory tree use the environment +variable `ERL_TOP` to find the absolute path of the installation. The +`configure` script will figure this out and set it in the top level +Makefile (which, when building, it will pass on). However, when +developing it is sometimes convenient to be able to run make in a +subdirectory. To do this you must set the `ERL_TOP` variable +before you run make. + +For example, assume your GNU make program is called `make` and you +want to rebuild the application `STDLIB`, then you could do: + + $ cd lib/stdlib; env ERL_TOP=<Dir> make + +where `<Dir>` would be what you find `ERL_TOP` is set to in the top level +Makefile. + +### otp\_build vs configure/make ### + +Building Erlang/OTP can be done either by using the `$ERL_TOP/otp_build` +script, or by invoking `$ERL_TOP/configure` and `make` directly. Building using +`otp_build` is easier since it involves fewer steps, but the `otp_build` build +procedure is not as flexible as the `configure`/`make` build procedure. The binary +releases for Windows that we deliver are built using `otp_build`. + +### Configuring ### + +The configure script is created by the GNU autoconf utility, which checks for system specific features and then creates a number of makefiles. The configure script allows you to customize a number of parameters; @@ -260,27 +335,37 @@ use the `--prefix` argument like this: `./configure --prefix=<Dir>`. Some of the available `configure` options are: * `--prefix=PATH` - Specify installation prefix. -* `--{enable,disable}-threads` - Thread support (enabled by default if - possible) + +* `--{enable,disable}-threads` - Thread support. This is enabled by default if possible. * `--{enable,disable}-smp-support` - SMP support (enabled by default if - possible) + a usable POSIX thread library or native Windows threads is found) * `--{enable,disable}-kernel-poll` - Kernel poll support (enabled by default if possible) * `--{enable,disable}-hipe` - HiPE support (enabled by default on supported platforms) +* `--{enable,disable}-fp-exceptions` - Floating point exceptions (an + optimization for floating point operations). The default differs + depending on operating system and hardware platform. Note that by + enabling this you might get a seemingly working system that sometimes + fail on floating point operations. * `--enable-darwin-universal` - Build universal binaries on darwin i386. * `--enable-darwin-64bit` - Build 64-bit binaries on darwin * `--enable-m64-build` - Build 64-bit binaries using the `-m64` flag to `(g)cc` * `--enable-m32-build` - Build 32-bit binaries using the `-m32` flag to `(g)cc` +* `--with-assumed-cache-line-size=SIZE` - Set assumed cache-line size in + bytes. Default is 64. Valid values are powers of two between and + including 16 and 8192. The runtime system use this value in order to + try to avoid false sharing. A too large value wastes memory. A to + small value will increase the amount of false sharing. * `--{with,without}-termcap` - termcap (without implies that only the old Erlang shell can be used) * `--with-javac=JAVAC` - Specify Java compiler to use * `--{with,without}-javac` - Java compiler (without implies that the `jinterface` application won't be built) * `--{enable,disable}-dynamic-ssl-lib` - Dynamic OpenSSL libraries -* `--{enable,disable}-shared-zlib` - Shared zlib library +* `--{enable,disable}-builtin-zlib` - Use the built-in source for zlib. * `--with-ssl=PATH` - Specify location of OpenSSL include and lib * `--{with,without}-ssl` - OpenSSL (without implies that the `crypto`, `ssh`, and `ssl` won't be built) @@ -288,7 +373,7 @@ Some of the available `configure` options are: memory accesses. If `configure` should inform you about no native atomic implementation available, you typically want to try using the `libatomic_ops` library. It can be downloaded from - <http://www.hpl.hp.com/research/linux/atomic_ops/>. + <https://github.com/ivmai/libatomic_ops/>. * `--disable-smp-require-native-atomics` - By default `configure` will fail if an SMP runtime system is about to be built, and no implementation for native atomic memory accesses can be found. If this happens, you are @@ -297,36 +382,165 @@ Some of the available `configure` options are: you can build using a fallback implementation based on mutexes or spinlocks. Performance of the SMP runtime system will however suffer immensely without an implementation for native atomic memory accesses. +* `--enable-static-{nifs,drivers}` - To allow usage of nifs and drivers on OSs + that do not support dynamic linking of libraries it is possible to statically + link nifs and drivers with the main Erlang VM binary. This is done by passing + a comma seperated list to the archives that you want to statically link. e.g. + `--enable-static-nifs=/home/$USER/my_nif.a`. The path has to be absolute and the + name of the archive has to be the same as the module, i.e. `my_nif` in the + example above. This is also true for drivers, but then it is the driver name + that has to be the same as the filename. You also have to define + `STATIC_ERLANG_{NIF,DRIVER}` when compiling the .o files for the nif/driver. + If your nif/driver depends on some other dynamic library, you now have to link + that to the Erlang VM binary. This is easily achived by passing `LIBS=-llibname` + to configure. * `--without-$app` - By default all applications in Erlang/OTP will be included in a release. If this is not wanted it is possible to specify that Erlang/OTP - should be compiled without that applications, i.e. `--without-wx`. There is - no automatic dependency handling inbetween applications. So if you disable - an application that another depends on, you also have to disable the + should be compiled without one or more applications, i.e. `--without-wx`. There is + no automatic dependency handling between applications. If you disable + an application that another application depends on, you also have to disable the dependant application. +* `--enable-dirty-schedulers` - Enable the **experimental** dirty schedulers + functionality. Note that the dirty schedulers functionality is experimental, + and **not supported**. This functionality **will** be subject to backward + incompatible changes. Note that you should **not** enable the dirty scheduler + functionality on production systems. It is only provided for testing. If you or your system has special requirements please read the `Makefile` for additional configuration information. -#### Building #### -Step 5 builds the Erlang/OTP system. On a fast computer, this will take about -5 minutes. After completion of this step, you should have a working -Erlang/OTP system which you can try by typing `bin/erl`. This should start -up Erlang/OTP and give you a prompt: +### Building ### - $ bin/erl - Erlang %OTP-REL% (erts-%ERTS-VSN%) [source] [smp:4:4] [rq:4] [async-threads:0] [kernel-poll:false] +Building Erlang/OTP on a relatively fast computer takes approximately +5 minutes. To speed it up, you can utilize parallel make with the `-j<num_jobs>` option. - Eshell V%ERTS-VSN% (abort with ^G) - 1> _ + $ export MAKEFLAGS=-j8 # Assuming bash/sh + $ make -#### Installing #### +If you've upgraded the source with a patch you may need to clean up from previous +builds before the new build. +Make sure to read the [Pre-built Source Release][] section below before doing a `make clean`. -Step 6 is optional. It installs Erlang/OTP at a standardized location (if you -change your mind about where you wish to install you can rerun step 4, -without having to do step 5 again). +#### Within Git #### -##### Alternative Installation Procedures ##### +When building in a Git working directory you also have to have a GNU `autoconf` +of at least version 2.59 on your system, because you need to generate the +`configure` scripts before you can start building. + +The `configure` scripts are generated by invoking `./otp_build autoconf` in +the `$ERL_TOP` directory. The `configure` scripts also have to be regenerated +when a `configure.in` or `aclocal.m4` file has been modified. Note that when +checking out a branch a `configure.in` or `aclocal.m4` file may change +content, and you may therefore have to regenerate the `configure` scripts +when checking out a branch. Regenerated `configure` scripts imply that you +have to run `configure` and build again. + +> *NOTE*: Running `./otp_build autoconf` is **not** needed when building +> an unmodified version of the released source. + +Other useful information can be found at our GitHub wiki: +* <http://wiki.github.com/erlang/otp> + +#### OS X (Darwin) #### + +Make sure that the command `hostname` returns a valid fully qualified host +name (this is configured in `/etc/hostconfig`). Otherwise you might experience +problems when running distributed systems. + +If you develop linked-in drivers (shared library) you need to link using +`gcc` and the flags `-bundle -flat_namespace -undefined suppress`. You also +include `-fno-common` in `CFLAGS` when compiling. Use `.so` as the library +suffix. + +If you have Xcode 4.3, or later, you will also need to download +"Command Line Tools" via the Downloads preference pane in Xcode. + +#### Building with wxErlang #### + +If you want to build the `wx` application, you will need to get wxWidgets-3.0 +(`wxWidgets-3.0.0.tar.bz2` from <http://sourceforge.net/projects/wxwindows/files/3.0.0/>) or get it from github with bug fixes: + + $ git clone --branch WX_3_0_branch [email protected]:wxWidgets/wxWidgets.git + +Be aware that the wxWidgets-3.0 is a new release of wxWidgets, it is not as +mature as the old releases and the OS X port still lags behind the other ports. + +Configure and build wxWidgets (on Mavericks - 10.9): + + $ ./configure --with-cocoa --prefix=/usr/local + or without support for old versions and with static libs + $ ./configure --with-cocoa --prefix=/usr/local --with-macosx-version-min=10.9 --disable-shared + $ make + $ sudo make install + $ export PATH=/usr/local/bin:$PATH + +Check that you got the correct wx-config + + $ which wx-config && wx-config --version-full + +Build Erlang/OTP + + $ export PATH=/usr/local/bin:$PATH + $ cd $ERL_TOP + $ ./configure + $ make + $ sudo make install + + +#### Pre-built Source Release #### + +The source release is delivered with a lot of platform independent +build results already pre-built. If you want to remove these pre-built +files, invoke `./otp_build remove_prebuilt_files` from the `$ERL_TOP` +directory. After you have done this, you can build exactly the same way +as before, but the build process will take a much longer time. + +> *WARNING*: Doing `make clean` in an arbitrary directory of the source +> tree, may remove files needed for bootstrapping the build. +> +> Doing `./otp_build save_bootstrap` from the `$ERL_TOP` directory before +> doing `make clean` will ensure that it will be possible to build after +> doing `make clean`. `./otp_build save_bootstrap` will be invoked +> automatically when `make` is invoked from `$ERL_TOP` with either the +> `clean` target, or the default target. It is also automatically invoked +> if `./otp_build remove_prebuilt_files` is invoked. + +#### How to Build a Debug Enabled Erlang RunTime System #### + +After completing all the normal building steps described above a debug +enabled runtime system can be built. To do this you have to change +directory to `$ERL_TOP/erts/emulator`. + +In this directory execute: + + $ make debug FLAVOR=$FLAVOR + +where `$FLAVOR` is either `plain` or `smp`. The flavor options will +produce a beam.debug and beam.smp.debug executable respectively. The +files are installed along side with the normal (opt) versions `beam.smp` +and `beam`. + +To start the debug enabled runtime system execute: + + $ $ERL_TOP/bin/cerl -debug + +The debug enabled runtime system features lock violation checking, +assert checking and various sanity checks to help a developer ensure +correctness. Some of these features can be enabled on a normal beam +using appropriate configure options. + +There are other types of runtime systems that can be built as well +using the similar steps just described. + + $ make $TYPE FLAVOR=$FLAVOR + +where `$TYPE` is `opt`, `gcov`, `gprof`, `debug`, `valgrind`, or `lcnt`. +These different beam types are useful for debugging and profiling +purposes. + + +### Installing ### * Staged install using [DESTDIR][]. You can perform the install phase in a temporary directory and later move the installation into @@ -408,7 +622,7 @@ without having to do step 5 again). if you want to try the system out, running test suites, etc, before doing the real install without `EXTRA_PREFIX`. -### Symbolic Links in --bindir ### +#### Symbolic Links in --bindir #### When doing `make install` and the default installation prefix is used, relative symbolic links will be created from `/usr/local/bin` to all public @@ -422,166 +636,10 @@ passed to `configure`. One can force relative, or absolute links by passing phase. Note that such a request might cause a failure if the request cannot be satisfied. -### Pre-built Source Release ### -The source release is delivered with a lot of platform independent -build results already pre-built. If you want to remove these pre-built -files, invoke `./otp_build remove_prebuilt_files` from the `$ERL_TOP` -directory. After you have done this, you can build exactly the same way -as before, but the build process will take a much longer time. +### Running ### -> *WARNING*: Doing `make clean` in an arbitrary directory of the source -> tree, may remove files needed for bootstrapping the build. -> -> Doing `./otp_build save_bootstrap` from the `$ERL_TOP` directory before -> doing `make clean` will ensure that it will be possible to build after -> doing `make clean`. `./otp_build save_bootstrap` will be invoked -> automatically when `make` is invoked from `$ERL_TOP` with either the -> `clean` target, or the default target. It is also automatically invoked -> if `./otp_build remove_prebuilt_files` is invoked. - -### Building in Git ### - -When building in a Git working directory you also have to have a GNU `autoconf` -of at least version 2.59 on your system, because you need to generate the -`configure` scripts before you can start building. - -The `configure` scripts are generated by invoking `./otp_build autoconf` in -the `$ERL_TOP` directory. The `configure` scripts also have to be regenerated -when a `configure.in` or `aclocal.m4` file has been modified. Note that when -checking out a branch a `configure.in` or `aclocal.m4` file may change -content, and you may therefore have to regenerate the `configure` scripts -when checking out a branch. Regenerated `configure` scripts imply that you -have to run `configure` and build again. - -> *NOTE*: Running `./otp_build autoconf` is **not** needed when building -> an unmodified version of the released source. - -Other useful information can be found at our github wiki: -<http://wiki.github.com/erlang/otp> - -### make and $ERL\_TOP ### - -All the makefiles in the entire directory tree use the environment -variable `ERL_TOP` to find the absolute path of the installation. The -`configure` script will figure this out and set it in the top level -Makefile (which, when building, it will pass on). However, when -developing it is sometimes convenient to be able to run make in a -subdirectory. To do this you must set the `ERL_TOP` variable -before you run make. - -For example, assume your GNU make program is called `make` and you -want to rebuild the application `STDLIB`, then you could do: - - $ cd lib/stdlib; env ERL_TOP=<Dir> make - -where `<Dir>` would be what you find `ERL_TOP` is set to in the top level -Makefile. - -The Erlang/OTP Documentation ----------------------------- - -### How to Build the Documentation ### - - $ cd $ERL_TOP - -If you have just built Erlang/OTP in the current source tree, you have -already ran `configure` and do not need to do this again; otherwise, run -`configure`. - - $ ./configure [Configure Args] - -When building the documentation you need a full Erlang/OTP-%OTP-REL% system in -the `$PATH`. - - $ export PATH=<Erlang/OTP-%OTP-REL% bin dir>:$PATH # Assuming bash/sh - -Build the documentation. - - $ make docs - -The documentation can be installed either using the `install-docs` target, -or using the `release_docs` target. - -* If you have installed Erlang/OTP using the `install` target, install - the documentation using the `install-docs` target. Install locations - determined by `configure` will be used. `$DESTDIR` can be used the - same way as when doing `make install`. - - $ make install-docs - -* If you have installed Erlang/OTP using the `release` target, install - the documentation using the `release_docs` target. You typically want - to use the same `RELEASE_ROOT` as when invoking `make release`. - - $ make release_docs RELEASE_ROOT=<release dir> - -#### Build Issues #### - -We have sometimes experienced problems with Sun's `java` running out of -memory when running `fop`. Increasing the amount of memory available -as follows has in our case solved the problem. - - $ export FOP_OPTS="-Xmx<Installed amount of RAM in MB>m" - -More information can be found at -<http://xmlgraphics.apache.org/fop/0.95/running.html#memory>. - -### How to Install the Pre-formatted Documentation ### - -Pre-formatted [html documentation][] and [man pages][] can be downloaded at -<http://www.erlang.org/download.html>. - -For some graphical tools to find the on-line help you have to install -the HTML documentation on top of the installed OTP applications, i.e. - - $ cd <ReleaseDir> - $ gunzip -c otp_html_%OTP-REL%.tar.gz | tar xf - - -For `erl -man <page>` to work the Unix manual pages have to be -installed in the same way, i.e. - - $ cd <ReleaseDir> - $ gunzip -c otp_man_%OTP-REL%.tar.gz | tar xf - - -Where `<ReleaseDir>` is - -* `<PrefixDir>/lib/erlang` if you have installed Erlang/OTP using - `make install`. -* `$DESTDIR<PrefixDir>/lib/erlang` if you have installed Erlang/OTP - using `make install DESTDIR=<TmpInstallDir>`. -* `RELEASE_ROOT` if you have installed using - `make release RELEASE_ROOT=<ReleaseDir>`. - -Support for SMP (Symmetric Multi Processing) --------------------------------------------- - -An emulator with SMP support will be built by default on most platforms -if a usable POSIX thread library or native Windows threads is found. - -You can force building of an SMP emulator, by using -`./configure --enable-smp-support`. However, if configure does not -automatically enable SMP support, the build is very likely to fail. - -Use `./configure --disable-smp-support` if you for some reason do not -want to have the emulator with SMP support built. - -If SMP support is enabled, support for threaded I/O will also be turned on -(also in the emulator without SMP support). - -The `erl` command will automatically start the SMP emulator if the -computer has more than one logical processor. You can force a start -of the emulator with SMP support by passing `-smp enable` as -command line arguments to erl, and you can force a start of the -emulator without SMP support by passing `-smp disable`. - -GS (Graphic System) -------------------- - -GS now Tcl/Tk 8.4. It will be searched for when starting GS. - -Using HiPE ----------- +#### Using HiPE #### HiPE supports the following system configurations: @@ -602,12 +660,12 @@ HiPE supports the following system configurations: * FreeBSD: FreeBSD 6.1 and 6.2 in 32-bit and 64-bit modes should work. - * MacOSX/Darwin: Darwin 9.8.0 in 32-bit mode should work. + * OS X/Darwin: Darwin 9.8.0 in 32-bit mode should work. * PowerPC: All 32-bit 6xx/7xx(G3)/74xx(G4) processors should work. 32-bit mode on 970 (G5) and POWER5 processors should work. - * Linux (Yellow Dog) and Mac OSX 10.4 are supported. + * Linux (Yellow Dog) and OS X 10.4 are supported. * SPARC: All UltraSPARC processors running 32-bit user code should work. @@ -626,11 +684,11 @@ HiPE is automatically enabled on the following systems: * x86 in 32-bit mode: Linux, Solaris, FreeBSD * x86 in 64-bit mode: Linux, Solaris, FreeBSD -* PowerPC: Linux, MacOSX +* PowerPC: Linux, Mac OSX * SPARC: Linux * ARM: Linux -On other supported systems you need to `./configure --enable-hipe`. +On other supported systems, see [Advanced Configure][] on how to enable HiPE. If you are running on a platform supporting HiPE and if you have not disabled HiPE, you can compile a module into native code like this from the Erlang @@ -642,7 +700,7 @@ or 1> c(Module, [native|OtherOptions]). -Using the erlc program, write like this: +Using the erlc program, write like this $ erlc +native Module.erl @@ -657,115 +715,102 @@ Use `hipe:help_options/0` to print out the available options. 1> hipe:help_options(). -Mac OS X (Darwin) ------------------ - -Make sure that the command `hostname` returns a valid fully qualified host -name (this is configured in `/etc/hostconfig`). - -If you develop linked-in drivers (shared library) you need to link using -`gcc` and the flags `-bundle -flat_namespace -undefined suppress`. You also -include `-fno-common` in `CFLAGS` when compiling. Use `.so` as the library -suffix. - -Use the `--enable-darwin-64bit` configure flag to build a 64-bit -binaries on Mac OS X. - -Building a fast Erlang VM on Mac OS Lion ----------------------------------------- - -Starting with Xcode 4.2, Apple no longer includes a "real" `gcc` -compiler (not based on the LLVM). Building with `llvm-gcc` or `clang` -will work, but the performance of the Erlang run-time system will not -be the best possible. - -Note that if you have `gcc-4.2` installed and included in `PATH` -(from a previous version of Xcode), `configure` will automatically -make sure that `gcc-4.2` will be used to compile `beam_emu.c` -(the source file most in need of `gcc`). - -If you don't have `gcc-4.2.` and want to build a run-time system with -the best possible performance, do like this: +#### Running with GS #### -Install Xcode from the AppStore if it is not already installed. +The `gs` application requires the GUI toolkit Tcl/Tk to run. At least +version 8.4 is required. -If you have Xcode 4.3, or later, you will also need to download -"Command Line Tools" via the Downloads preference pane in Xcode. - -Some tools may still be lacking or out-of-date, we recommend using -[Homebrew](https://github.com/mxcl/homebrew/wiki/installation) or -Macports to update those tools. - -Install MacPorts (<http://www.macports.org/>). Then: - - $ sudo port selfupdate - $ sudo port install gcc45 +universal - -### Building with wxErlang ### - -If you want to build the `wx` application, you will need to get wxWidgets-3.0 (or later) -(`wxWidgets-3.0.0.tar.bz2` from <http://sourceforge.net/projects/wxwindows/files/3.0.0/>) -or get it from github: - $ git clone [email protected]:wxWidgets/wxWidgets.git - -Be aware that the wxWidgets-3.0 is a new release of wxWidgets, it is not as matured -as the old releases and the MacOsX port still lags behind the other ports. - -Configure and build wxWidgets: - - $ ./configure --with-cocoa --prefix=/usr/local - % Optional version and static libs: --with-macosx-version-min=10.9 --disable-shared - $ make - $ sudo make install - $ export PATH=/usr/local/bin:$PATH +Known platform issues +--------------------- -Check that you got the correct wx-config +* Suse linux 9.1 is shipped with a patched GCC version 3.3.3, having the + rpm named `gcc-3.3.3-41`. That version has a serious optimization bug + that makes it unusable for building the Erlang emulator. Please + upgrade GCC to a newer version before building on Suse 9.1. Suse Linux + Enterprise edition 9 (SLES9) has `gcc-3.3.3-43` and is not affected. - $ which wx-config +* `gcc-4.3.0` has a serious optimizer bug. It produces an Erlang emulator + that will crash immediately. The bug is supposed to be fixed in + `gcc-4.3.1`. -### Finish up ### +* FreeBSD had a bug which caused `kqueue`/`poll`/`select` to fail to detect + that a `writev()` on a pipe has been made. This bug should have been fixed + in FreeBSD 6.3 and FreeBSD 7.0. NetBSD and DragonFlyBSD probably have or + have had the same bug. More information can be found at: -Build Erlang + * <http://www.freebsd.org/cgi/cvsweb.cgi/src/sys/kern/sys_pipe.c> + * <http://lists.freebsd.org/pipermail/freebsd-arch/2007-September/006790.html> - $ export PATH=/usr/local/bin:$PATH - $ cd $ERL_TOP - $ ./configure --enable-shared-zlib - $ make - $ sudo make install +* `getcwd()` on Solaris 9 can cause an emulator crash. If you have + async-threads enabled you can increase the stack size of the + async-threads as a temporary workaround. See the `+a` command-line + argument in the documentation of `erl(1)`. Without async-threads the + emulator is not as vulnerable to this bug, but if you hit it without + async-threads the only workaround available is to enable async-threads + and increase the stack size of the async-threads. Oracle has however + released patches that fixes the issue: -How to Build a Debug Enabled Erlang RunTime System --------------------------------------------------- + > Problem Description: 6448300 large mnttab can cause stack overrun + > during Solaris 9 getcwd -After completing all the normal building steps described above a debug -enabled runtime system can be built. To do this you have to change -directory to `$ERL_TOP/erts/emulator`. + More information can be found at: + * <https://getupdates.oracle.com/readme/112874-40> + * <https://getupdates.oracle.com/readme/114432-29> -In this directory execute: +* `sed` on Solaris seem to have some problems. For example on + Solaris 8, the BSD `sed` and XPG4 `sed` should be avoided. + Make sure `/bin/sed` or `/usr/bin/sed` is used on the Solaris + platform. - $ make debug FLAVOR=$FLAVOR -where `$FLAVOR` is either `plain` or `smp`. The flavor options will -produce a beam.debug and beam.smp.debug executable respectively. The -files are installed along side with the normal (opt) versions `beam.smp` -and `beam`. +Daily Build and Test +-------------------- +At Ericsson we have a "Daily Build and Test" that runs on: -To start the debug enabled runtime system execute: +* Solaris 8, 9 + * Sparc32 + * Sparc64 +* Solaris 10 + * Sparc32 + * Sparc64 + * x86 +* SuSE Linux/GNU 9.4, 10.1 + * x86 +* SuSE Linux/GNU 10.0, 10.1, 11.0 + * x86 + * x86\_64 +* openSuSE 11.4 (Celadon) + * x86\_64 (valgrind) +* Fedora 7 + * PowerPC +* Fedora 16 + * x86\_64 +* Gentoo Linux/GNU 1.12.11.1 + * x86 +* Ubuntu Linux/GNU 7.04, 10.04, 10.10, 11.04, 12.04 + * x86\_64 +* MontaVista Linux/GNU 4.0.1 + * PowerPC +* FreeBSD 10.0 + * x86 +* OpenBSD 5.4 + * x86\_64 +* OS X 10.5.8 (Leopard), 10.7.5 (Lion), 10.9.1 (Mavericks) + * x86 +* Windows XP SP3, 2003, Vista, 7 + * x86 +* Windows 7 + * x86\_64 - $ $ERL_TOP/bin/cerl -debug +We also have the following "Daily Cross Builds": -The debug enabled runtime system features lock violation checking, -assert checking and various sanity checks to help a developer ensure -correctness. Some of these features can be enabled on a normal beam -using appropriate configure options. +* SuSE Linux/GNU 10.1 x86 -> SuSE Linux/GNU 10.1 x86\_64 +* SuSE Linux/GNU 10.1 x86\_64 -> Linux/GNU TILEPro64 -There are other types of runtime systems that can be built as well -using the similar steps just described. +and the following "Daily Cross Build Tests": - $ make $TYPE FLAVOR=$FLAVOR +* SuSE Linux/GNU 10.1 x86\_64 -where `$TYPE` is `opt`, `gcov`, `gprof`, `debug`, `valgrind`, or `lcnt`. -These different beam types are useful for debugging and profiling -purposes. Authors ------- @@ -774,12 +819,13 @@ Authors are mostly listed in the application's `AUTHORS` files, that is `$ERL_TOP/lib/*/AUTHORS` and `$ERL_TOP/erts/AUTHORS`, not in the individual source files. + Copyright and License --------------------- %CopyrightBegin% -Copyright Ericsson AB 1998-2013. All Rights Reserved. +Copyright Ericsson AB 1998-2014. All Rights Reserved. The contents of this file are subject to the Erlang Public License, Version 1.1, (the "License"); you may not use this file except in @@ -794,28 +840,25 @@ under the License. %CopyrightEnd% -More Information ----------------- - -More information can be found at <http://www.erlang.org>. - -Modifying This Document ------------------------ -Before modifying this document you need to have a look at the -[$ERL_TOP/HOWTO/MARKDOWN.md][] document. [$ERL_TOP/HOWTO/INSTALL-CROSS.md]: INSTALL-CROSS.md [$ERL_TOP/HOWTO/INSTALL-WIN32.md]: INSTALL-WIN32.md [DESTDIR]: http://www.gnu.org/prep/standards/html_node/DESTDIR.html - [Building in Git]: #How-to-Build-and-Install-ErlangOTP_Building-in-Git - [Pre-built Source Release]: #How-to-Build-and-Install-ErlangOTP_Prebuilt-Source-Release - [make and $ERL_TOP]: #How-to-Build-and-Install-ErlangOTP_make-and-ERLTOP - [html documentation]: http://www.erlang.org/download/otp_doc_html_%OTP-REL%.tar.gz - [man pages]: http://www.erlang.org/download/otp_doc_man_%OTP-REL%.tar.gz - [the released source tar ball]: http://www.erlang.org/download/otp_src_%OTP-REL%.tar.gz - [$ERL_TOP/HOWTO/MARKDOWN.md]: MARKDOWN.md - - [?TOC]: true + [Building in Git]: #Advanced-configuration-and-build-of-ErlangOTP_Building_Within-Git + [Advanced Configure]: #Advanced-configuration-and-build-of-ErlangOTP_Configuring + [Pre-built Source Release]: #Advanced-configuration-and-build-of-ErlangOTP_Building_Prebuilt-Source-Release + [make and $ERL_TOP]: #Advanced-configuration-and-build-of-ErlangOTP_make-and-ERLTOP + [html documentation]: http://www.erlang.org/download/otp_doc_html_%OTP-VSN%.tar.gz + [man pages]: http://www.erlang.org/download/otp_doc_man_%OTP-VSN%.tar.gz + [the released source tar ball]: http://www.erlang.org/download/otp_src_%OTP-VSN%.tar.gz + [System Principles]: ../system_principles/system_principles + [Known platform issues]: #Known-platform-issues + [native build]: #How-to-Build-and-Install-ErlangOTP + [cross build]: INSTALL-CROSS.md + [Required Utilities]: #Required-Utilities + [Optional Utilities]: #Optional-Utilities + [Building on a Mac]: #Advanced-configuration-and-build-of-ErlangOTP_Building_OS-X-Darwin + [Building with wxErlang]: #Advanced-configuration-and-build-of-ErlangOTP_Building_Building-with-wxErlang |