aboutsummaryrefslogtreecommitdiffstats
path: root/INSTALL.md
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL.md')
-rw-r--r--INSTALL.md295
1 files changed, 162 insertions, 133 deletions
diff --git a/INSTALL.md b/INSTALL.md
index 452b0ff252..526df8de93 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,8 +1,12 @@
Building and Installing Erlang/OTP
==================================
-Please read the whole file before attempting to build and install Erlang/OTP.
-You can find more information about Open Source Erlang/OTP at:
+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:
<http://www.erlang.org/>
@@ -10,24 +14,22 @@ The source code for Erlang/OTP can also be found in a Git repository:
<http://github.com/erlang/otp>
-Portability
------------
-
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/INSTALL-CROSS.md`] [1]
+* cross compile Erlang/OTP, see the [$ERL_TOP/INSTALL-CROSS.md][]
document.
-* build Erlang/OTP on Windows, see the [`$ERL_TOP/INSTALL-WIN32.md`] [2]
+* build Erlang/OTP on Windows, see the [$ERL_TOP/INSTALL-WIN32.md][]
document.
Binary releases for Windows can be found at
<http://www.erlang.org/download.html>.
-However, 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.
+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.
Daily Build and Test
--------------------
@@ -44,9 +46,9 @@ At Ericsson we have a "Daily Build and Test" that runs on:
* x86
* SuSE Linux/GNU 10.0, 10.1
* x86
- * x86_64
+ * x86\_64
* SuSE Linux/GNU 11.0
- * x86_64
+ * x86\_64
* Gentoo Linux/GNU 1.12.11.1
* x86
* MontaVista Linux/GNU 4.0.1
@@ -60,15 +62,15 @@ At Ericsson we have a "Daily Build and Test" that runs on:
We also have the following "Daily Cross Builds":
-* SuSE Linux/GNU 10.1 x86 -> SuSE Linux/GNU 10.1 x86_64
-* SuSE Linux/GNU 10.1 x86_64 -> Linux/GNU TILEPro64
+* SuSE Linux/GNU 10.1 x86 -> SuSE Linux/GNU 10.1 x86\_64
+* SuSE Linux/GNU 10.1 x86\_64 -> Linux/GNU TILEPro64
and the following "Daily Cross Build Tests":
-* SuSE Linux/GNU 10.1 x86_64
+* SuSE Linux/GNU 10.1 x86\_64
-Versions Known *not* to Work
-----------------------------
+Versions Known NOT to Work
+--------------------------
* 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
@@ -118,14 +120,15 @@ These are the tools you will need in order to unpack and build Erlang/OTP.
### Building ###
-* GNU make
-* GNU C compiler
+* GNU `make`
+* `gcc` -- GNU C compiler
* Perl 5
-* GNU m4 -- If hipe (native code) support is enabled.
-* ncurses (or 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. Only the old shell (without any line
- editing) can be used.)
+* 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
@@ -140,23 +143,21 @@ These are the tools you will need in order to unpack and build Erlang/OTP.
* `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
+* `flex` -- Optional, headers and libraries are needed to build the `flex`
scanner for the `megaco` application on Unix/Linux.
-If you are building in a Git working directory you also have to have a GNU
-`autoconf` of at least version 2.59. Autoconf is however not needed if you
-build an unmodified version of the released source.
-
#### Building Documentation ####
* `xsltproc` -- XSLT processor. A tool for applying XSLT stylesheets
to XML documents. Can be downloaded from
<http://xmlsoft.org/XSLT/xsltproc2.html>.
-* `fop` -- Apache FOP print formatter (requires Java). Can be downloaded from
- <http://xmlgraphics.apache.org/fop>.
-* `Markdown.pl` -- Optional. This is a `perl` script that generates an
- HTML version of a document written in Markdown notation. Can be
- downloaded at <http://daringfireball.net/projects/markdown>.
+* `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 ###
@@ -165,12 +166,12 @@ build an unmodified version of the released source.
How to Build and Install Erlang/OTP
-----------------------------------
-The following instructions are for building using the source tar ball.
+The following instructions are for building [the released source tar ball][].
The variable `$ERL_TOP` will be mentioned a lot of times. It refers to
the top directory in the source tree. More information about `$ERL_TOP`
-can be found in the "`make` and `$ERL_TOP`" section below. If you are
-building in git you probably want to take a look at the "Building in Git"
+can be found in the [make and $ERL_TOP][] section below. If you are
+building in git you probably want to take a look at the [Building in Git][]
section below before proceeding.
### Unpacking ###
@@ -178,13 +179,16 @@ section below before proceeding.
Step 1: Start by unpacking the Erlang/OTP distribution file with your GNU
compatible TAR program.
- $ gunzip -c otp_src_R13B04.tar.gz | tar xf -
- $ zcat otp_src_R13B04.tar.gz | tar xf -
+ $ gunzip -c otp_src_%OTP-REL%.tar.gz | tar xf -
+
+alternatively:
+
+ $ zcat otp_src_%OTP-REL%.tar.gz | tar xf -
Step 2: Now cd into the base directory (`$ERL_TOP`).
- $ cd otp_src_R13B04
+ $ cd otp_src_%OTP-REL%
### Configuring ###
@@ -208,8 +212,8 @@ To instead install in `<BaseDir>/{bin,lib/erlang}`, use the
`--prefix=<BaseDir>` option.
If you upgraded the source with some patch you may need to clean up
-from previous builds before the new build. Do a `make clean`; see
-"Caveats" below.
+from previous builds before the new build. Before doing a `make clean`,
+be sure to read the [Pre-built Source Release][] section below.
### Building ###
@@ -237,46 +241,65 @@ type `./configure --help` or `./configure --help=recursive` for details.
`./configure --help=recursive` will give help for all `configure` scripts in
all applications.
-One of the things you can specify is where Erlang/OTP should be installed: by
-default Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang}`;
-to keep the same structure but install in a different place, `<Dir>` say,
+One of the things you can specify is where Erlang/OTP should be installed. By
+default Erlang/OTP will be installed in `/usr/local/{bin,lib/erlang}`.
+To keep the same structure but install in a different place, `<Dir>` say,
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
+* `--prefix=PATH` - Specify installation prefix.
+* `--{enable,disable}-threads` - Thread support (enabled by default if
possible)
- * `--{enable,disable}-smp-support`: SMP support (enabled by default if
+* `--{enable,disable}-smp-support` - SMP support (enabled by default if
possible)
- * `--{enable,disable}-kernel-poll`: Kernel poll support (enabled by default
- if possible)
- * `--{enable,disable}-hipe`: HiPE support (enabled by default on supported
+* `--{enable,disable}-kernel-poll` - Kernel poll support (enabled by
+ default if possible)
+* `--{enable,disable}-hipe` - HiPE support (enabled by default on supported
platforms)
- * `--enable-darwin-universal`: Build universal binaries on darwin i386.
- * `--enable-darwin-64bit`: Build 64bit binaries on darwin
- * `--enable-m64-build`: Build 64bit binaries using the -m64 flag to (g)cc
- * `--enable-m32-build`: Build 32bit binaries using the -m32 flag to (g)cc
- * `--{with,without}-termcap`: termcap (without implies that only the old
+* `--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,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
- * `--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)
-
-If you or your system has special requirements please read the
-Makefile for additional configuration information.
+* `--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
+* `--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)
+* `--enable-ethread-pre-pentium4-compatibility` - Enable compatibility with
+ x86 processors before pentium 4 (back to 486) in the ethread library. If
+ not passed the ethread library (part of the runtime system) will use
+ instructions that first appeared on the pentium 4 processor when building
+ for x86. This option will be automatically enabled if required on the
+ build machine.
+* `--with-libatomic_ops=PATH` - Use the `libatomic_ops` library for atomic
+ 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/>.
+
+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.
+up Erlang/OTP and give you a prompt:
+
+ $ bin/erl
+ Erlang %OTP-REL% (erts-%ERTS-VSN%) [source] [smp:4:4] [rq:4] [async-threads:0] [kernel-poll:false]
+
+ Eshell V%ERTS-VSN% (abort with ^G)
+ 1> _
#### Installing ####
@@ -286,7 +309,7 @@ without having to do step 5 again).
##### Alternative Installation Procedures #####
-* Staged install using [`DESTDIR`] [3]. You can perform the install
+* Staged install using [DESTDIR][]. You can perform the install
phase in a temporary directory and later move the installation into
its correct location by use of the `DESTDIR` variable:
@@ -366,7 +389,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
@@ -380,10 +403,28 @@ 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.
+
+> *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. This since you need to generate the
+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
@@ -394,32 +435,13 @@ 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 that running `./otp_build autoconf` is **not** needed when building an
-unmodified version the released source.
+> *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>
-Pre-built Source Tree
----------------------
-
-The source tree 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.
-
-*NOTE*: 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.
-
-`make` and `$ERL_TOP`
----------------------
+### 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
@@ -437,8 +459,10 @@ want to rebuild the application `STDLIB`, then you could do:
where `<Dir>` would be what you find `ERL_TOP` is set to in the top level
Makefile.
-How to Build the Erlang/OTP Documentation
------------------------------------------
+The Erlang/OTP Documentation
+----------------------------
+
+### How to Build the Documentation ###
$ cd $ERL_TOP
@@ -448,19 +472,10 @@ already ran `configure` and do not need to do this again; otherwise, run
$ ./configure [Configure Args]
-When building the documentation you need a full Erlang/OTP-R13B04 system in
+When building the documentation you need a full Erlang/OTP-%OTP-REL% system in
the `$PATH`.
- $ export PATH=<Erlang/OTP-R13B04 bin dir>:$PATH # Assuming bash/sh
-
-This document as well as some other documents have been written using
-Markdown notation. HTML versions of these documents are created and included
-in the HTML documentation if the environment variable `MD2HTML` is set to a
-command that generates HTML on `stdout` for a Markdown document passed as
-argument. This is a last minute hack, which will be handled in a better way
-in the future. We currently set `MD2HTML` as follows.
-
- $ export MD2HTML="perl <path to script>/Markdown.pl --html4tags"
+ $ export PATH=<Erlang/OTP-%OTP-REL% bin dir>:$PATH # Assuming bash/sh
Build the documentation.
@@ -478,13 +493,13 @@ or using the `release_docs` target.
* 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`.
+ to use the same `RELEASE_ROOT` as when invoking `make release`.
$ make release_docs RELEASE_ROOT=<release dir>
-### Build Issues ###
+#### Build Issues ####
-We have sometimes experienced problems with suns `java` running out of
+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.
@@ -493,23 +508,22 @@ as follows has in our case solved the problem.
More information can be found at
<http://xmlgraphics.apache.org/fop/0.95/running.html#memory>.
-How to Install the Pre-formatted Erlang/OTP Documentation
----------------------------------------------------------
+### How to Install the Pre-formatted Documentation ###
-Pre-formatted documentation can be downloaded at
+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_R13B04.tar.gz | tar xf -
+ $ 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_R13B04.tar.gz | tar xf -
+ $ gunzip -c otp_man_%OTP-REL%.tar.gz | tar xf -
Where `<ReleaseDir>` is
@@ -620,7 +634,7 @@ To add hipe options, write like this from the Erlang shell:
1> c(Module, [native,{hipe,HipeOptions}|MoreOptions]).
-Use hipe:help_options/0 to print out the available options.
+Use `hipe:help_options/0` to print out the available options.
1> hipe:help_options().
@@ -702,6 +716,7 @@ purposes.
Authors
-------
+
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.
@@ -709,30 +724,44 @@ not in the individual source files.
Copyright and License
---------------------
-> %CopyrightBegin%
->
-> Copyright Ericsson AB 1998-2010. 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
-> compliance with the License. You should have received a copy of the
-> Erlang Public License along with this software. If not, it can be
-> retrieved online at http://www.erlang.org/.
->
-> Software distributed under the License is distributed on an "AS IS"
-> basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
-> the License for the specific language governing rights and limitations
-> under the License.
->
-> %CopyrightEnd%
+%CopyrightBegin%
+
+Copyright Ericsson AB 1998-2011. 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
+compliance with the License. You should have received a copy of the
+Erlang Public License along with this software. If not, it can be
+retrieved online at http://www.erlang.org/.
+
+Software distributed under the License is distributed on an "AS IS"
+basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+the License for the specific language governing rights and limitations
+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/README.md.txt` document.
+
+
+ [$ERL_TOP/INSTALL-CROSS.md]: INSTALL-CROSS
+ [$ERL_TOP/INSTALL-WIN32.md]: INSTALL-WIN32
+ [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
- [1]: INSTALL-CROSS.html "$ERL_TOP/INSTALL-CROSS.md"
- [2]: INSTALL-WIN32.html "$ERL_TOP/INSTALL-WIN32.md"
- [3]: http://www.gnu.org/prep/standards/html_node/DESTDIR.html "DESTDIR"
+ [?TOC]: true