aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorRickard Green <[email protected]>2010-02-16 01:24:37 +0000
committerErlang/OTP <[email protected]>2010-02-16 01:24:37 +0000
commit7aa2cb2e64cd404f8a9f388d85ab287ced95f139 (patch)
tree5bf6f7ecf5d6610db18b707436be0aa642083eea /README
parent924f3aaf2c4841eafb5ea3832e2c885eb54ac984 (diff)
downloadotp-7aa2cb2e64cd404f8a9f388d85ab287ced95f139.tar.gz
otp-7aa2cb2e64cd404f8a9f388d85ab287ced95f139.tar.bz2
otp-7aa2cb2e64cd404f8a9f388d85ab287ced95f139.zip
OTP-8449 Documentation improvements.
The most important "readme" files now use Markdown notation. HTML versions of these files are now also automatically generated and included in the HTML documentation. - Building and Installing Erlang/OTP - $ERL_TOP/INSTALL.md (previously known as $ERL_TOP/README). - Cross Compiling Erlang/OTP - $ERL_TOP/INSTALL-CROSS.md. - How to Build Erlang/OTP on Windows - $ERL_TOP/INSTALL-WIN32.md (previously known as $ERL_TOP/README.win32).
Diffstat (limited to 'README')
-rw-r--r--README562
1 files changed, 0 insertions, 562 deletions
diff --git a/README b/README
deleted file mode 100644
index 9622b2d676..0000000000
--- a/README
+++ /dev/null
@@ -1,562 +0,0 @@
-===========================================================================
- OpenSource Erlang/OTP
-===========================================================================
-
-Please read the whole file before attempting to build and install Erlang.
-You can find more information about Open Source Erlang at:
-
- http://www.erlang.org/
-
-The source code for Erlang/OTP can also be found in a Git repository:
-
- http://github.com/erlang/otp
-
-%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%
-
-Portability
------------
-
-Erlang/OTP should be possible to build from source on any Unix
-system, including Mac OS X.
-
-Instructions for building from source on Windows are in the file README.win32.
-Binary releases for Windows can be found at http://www.erlang.org/
-
-At Ericsson we have a "Daily Build and Test" that runs on:
-
- Operating system Versions
- -----------------------------------------------------------
- Solaris/Sparc32 8, 9, 10
- Solaris/Sparc64 10
- Solaris/x86 10
- Linux/Suse x86 9.4, 10.1
- Linux/Suse x86_64 10.0, 10.1, 11.0
- FreeBSD x86 7.1
- Mac OS X/Intel 10.4.11 (Tiger), 10.5.8 (Leopard)
- Windows XP SP3, 2003, Vista
-
-We have also done some testing on Mac OS 10.6.0 (Snow Leopard).
-
-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
-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.
-
-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.
-
-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:
- * http://www.freebsd.org/cgi/cvsweb.cgi/src/sys/kern/sys_pipe.c
- * http://lists.freebsd.org/pipermail/freebsd-arch/2007-September/006790.html
-
-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 isn't 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
-
-More information can be found at:
- * 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
-
-Required utilities
-------------------
-
-These are the tools you will need in order to unpack and build Erlang/OTP.
-
-Unpacking
-
- * GNU unzip, or a modern uncompress.
- * A TAR program that understands the GNU TAR format for long filenames (such
-as GNU TAR).
-
-Compiling
-
- * GNU make
- * 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.)
- * 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.7 of OpenSSL is required.
- * Sun Java jdk-1.5.0 or higher -- Optional but needed for building the
- Erlang/OTP application 'jinterface' and parts of 'ic' and 'orber'. 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.
-
-Installing
-
- * An 'install' program that can take multiple file names.
-
-How to build and install Erlang/OTP
------------------------------------
-
-If you are building in a Git repository, see
-
- http://wiki.github.com/erlang/otp
-
-The following instructions are for building using the source tar ball.
-
-Step 1: Start by unpacking the Erlang/OTP distribution file with your GNU
-compatible TAR program.
-
- $ gunzip -c otp_src_R13B03.tar.gz | tar xf -
- $ zcat otp_src_R13B03.tar.gz | tar xf -
-
-Step 2: Now cd into the base directory.
-
- $ cd otp_src_R13B03
-
-Step 3: On some platforms Perl may behave strangely if certain locales are
-set, so optionally you may need to set the LANG variable:
-
- # Bourne shell
- $ LANG=C; export LANG
-or
- # C-Shell
- $ setenv LANG C
-
-Step 4: Run the following commands to configure the build:
-
- $ ./configure [ options ]
-
-By default, Erlang/OTP will be installed in /usr/local/{bin,lib/erlang,man/man1}.
-To instead install in <BaseDir>/{bin,lib/erlang,man/man1}, 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.
-
-Step 5: Build the Erlang/OTP package.
-
- $ make
-
-Step 6: Install then Erlang/OTP package
-
- $ make install
-
-Let's go through them in some detail:
-
-Step 4 runs a configuration script 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;
-type "./configure --help" for details.
-
-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,man/man1};
-to keep the same structure but install in a different place, <Dir> say,
-use the --prefix argument like this:
-"./configure --prefix=<Dir>".
-
-This step will also configure any additional libraries unpacked in step 3
-(if you didn't add any of the extra libraries configure will issue a warning
-saying that there is no configuration information in lib; this warning can
-safely be ignored).
-
-You can also specify where the OpenSSL include and library files are
-located, or alternatively disable the use of SSL and Crypto.
-(The details can be found by typing './configure --help'.)
-
-Other options are:
-
- --enable-smp-support See the next section.
-
- --disable-smp-support See the next section.
-
- --disable-threads Disable support for threaded I/O;
- this option also disables building of the SMP
- emulator. (See the next section.)
-
- --enable-threads Enable support for threaded I/O.
- (This is the default if SMP support is enabled.
- See the next section.)
-
- --disable-hipe Disable HiPE (High-Performance Erlang).
- HiPE will automatically be enabled on supported
- platforms.
-
-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.
-
-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).
-
-Alternative installation procedures:
-* 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: 'make DESTDIR=<tmp install dir> install'
- The installation will be created in a location prefixed by $DESTDIR. It
- can, however, not be run from there. It needs to be moved into the correct
- location before it can be run. If DESTDIR have not been set but INSTALL_PREFIX
- has been set, DESTDIR will be set to INSTALL_PREFIX. Note that INSTALL_PREFIX
- in pre R13B04 was buggy and behaved as EXTRA_PREFIX (see below). There are
- lots of areas of use for an installation procedure using DESTDIR, e.g. when
- creating a package, cross compiling, etc. Here is an example where the
- installation should be located under /opt/local:
- $ ./configure --prefix=/opt/local
- $ make
- $ mkdir /tmp/erlang-build
- $ make DESTDIR=/tmp/erlang-build install
- $ cd /tmp/erlang-build/opt/local
- $ # gnu-tar is used in this example
- $ tar -zcf /home/me/my-erlang-build.tgz *
- $ su -
- Password: *****
- $ cd /opt/local
- $ tar -zxf /home/me/my-erlang-build.tgz
-* Test install using EXTRA_PREFIX. Note that EXTRA_PREFIX is similar to
- DESTDIR, but it does not have the same effect as DESTDIR. The EXTRA_PREFIX
- variable will prefix all installation paths, and the installation can and
- have to be run from there. That is, it can be useful if you want to try the
- system out, running test suites, etc, before doing the real install without
- EXTRA_PREFIX.
-* Install using the `release' target. Instead of doing `make install' you can
- creat the installation in whatever directory you like using the `release'
- target and run the `Install' script yourself. RELEASE_ROOT is used for
- specifying the directory where the installation should be created. This is
- what by default ends up under `/usr/local/lib/erlang' if you do the install
- using `make install'. All installation paths provided in the `configure'
- phase are ignored, as well as DESTDIR, and INSTALL_PREFIX. If you want links
- from a specific `bin' directory to the installation you have to set those up
- yourself. An example where Erlang/OTP should be located at /home/me/OTP:
- $ ./configure
- $ make
- $ make RELEASE_ROOT=/home/me/OTP release
- $ cd /home/me/OTP
- $ ./Install -minimal /home/me/OTP
- $ mkdir -p /home/me/bin
- $ cd /home/me/bin
- $ ln -s /home/me/OTP/bin/erl erl
- $ ln -s /home/me/OTP/bin/erlc erlc
- $ ln -s /home/me/OTP/bin/escript escript
- ...
- The `Install' script should currently be invoked as follows in the
- directory where it resides:
- `./Install [-cross] [-minimal|-sasl] <ERL_ROOT>'
- where:
- -minimal - Creates an installation that starts up a minimal amount
- of applications, i.e., only kernel and stdlib are started.
- The minimal system is normally enough.
- -sasl - Creates an installation that also starts up the sasl
- application.
- -cross - For cross compilation. Informs the install script that it
- is run on the build machine.
- <ERL_ROOT> - The absolute path to the Erlang installation to use at run
- time. This is often the same as the current working
- directory, but does not have to be. It can follow any other
- path through the file system to the same directory.
-
- If neither -minimal, nor -sasl is passed as argument you will be prompted.
-
-When doing `make install' and the default installation prefix is used, relative
-symbolic links will be created from /usr/local/bin to all public executables in
-the Erlang installation. The installation phase will try to create relative
-symbolic links as long as `--bindir' and the Erlang bin directory, located under
-`--libdir', both have `--exec-prefix' as prefix. Where `--exec-prefix'
-defaults to `--prefix'. `--prefix', `--exec-prefix', `--bindir', and `--libdir'
-are all arguments that can be passed to `configure'. One can however force
-relative, or absolute links by passing BINDIR_SYMLINKS=relative|absolute
-as arguments to make during the install phase. Note that such a request might
-cause a failure if the request cannot be satisfied.
-
-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.
-
-If you or your system has special requirements please read the
-Makefile for additional configuration information.
-
-Cross compiling Erlang/OTP
---------------------------
-The support for cross compiling Erlang/OTP is in its early stage of
-development, and should be considered as experimental. For more
-information see: $ERL_TOP/xcomp/README
-
-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, lcnt. These
-different beam types are useful for debugging and profiling purposes.
-
-
-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 doesn't
-automatically enable SMP support, the build is very likely to fail.
-
-Use "./configure --disable-smp-support" if you for some reason don't
-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'.
-
-How to install the Erlang/OTP documentation
--------------------------------------------
-
-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 <PrefixDir>/lib/erlang
- $ gunzip -c otp_html_R<XY>B-<Z>.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 <PrefixDir>/lib/erlang
- $gunzip -c otp_man_R<XY>B-<Z>.tar.gz | tar xf -
-
-
-GS (Graphic System)
--------------------
-
-GS now Tcl/Tk 8.4. It will be searched for when starting GS.
-
-Using HiPE
-----------
-
-HiPE supports the following system configurations:
-
-x86:
- All 32-bit and 64-bit mode processors should work.
-
- Linux:
- Fedora Core is supported.
- Both 32-bit and 64-bit modes are supported.
-
- NPTL glibc is strongly preferred, or a LinuxThreads
- glibc configured for "floating stacks". Old non-floating
- stacks glibcs have a fundamental problem that makes HiPE
- support and threads support mutually exclusive.
-
- Solaris:
- Solaris 10 (32-bit and 64-bit) and 9 (32-bit) are supported.
-
- The build requires a version of the GNU C compiler (gcc)
- that has been configured to use the GNU assembler (gas).
- Sun's x86 assembler is emphatically /not/ supported.
-
- 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.
-
-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.
-
-SPARC:
- All UltraSPARC processors running 32-bit user code should work.
-
- Solaris 9 and Linux (Aurora) are supported.
-
- On Solaris the build requires a gcc that has been configured to use Sun's
- assembler and linker. Using the GNU assembler but Sun's linker has been
- known to cause problems.
-
-ARM:
- ARMv5TE (i.e. XScale) processors should work. Both big-endian and
- little-endian modes are supported.
-
- Linux is supported.
-
-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
- SPARC: Linux
- ARM: Linux
-
-On other supported systems you need to "./configure --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
-shell:
-
- 1> c(Module, native).
-
-or
-
- 1> c(Module, [native|OtherOptions]).
-
-Using the erlc program, write like this:
-
- $ erlc +native Module.erl
-
-The native code will be placed into the beam file and automatically loaded
-when the beam file is loaded.
-
-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.
-
- 1> hipe:help_options().
-
-Mac OS X (Darwin)
------------------
-
-We test Mac OS X 10.4.11 (Tiger) and Mac OS X 10.5.x (Leopard) in our daily
-builds (but only on Intel processors).
-
-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.
-
-Universal 32bit binaries can be built on an Intel Mac using the
-'--enable-darwin-universal' configure option. There still may occur
-problems with certain applications using this option, but the base
-system should run smoothly.
-
-When building universal binaries on a PowerPC Mac (at least on Tiger),
-you must point out a suitable SDK that contains universal binaries.
-For instance, to build universal binaries for Tiger (10.4):
-
- $ CFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk" \
- LDFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk" \
- ./configure --enable-darwin-universal
-
-Also, if you run Leopard, but want to build for Tiger, you must do by setting the MACOSX_DEPLOYMENT_TARGET environmental variable.
-
- $ export MACOSX_DEPLOYMENT_TARGET=10.4
-
-Experimental support for 64bit x86 darwin binaries can be enabled
-using the '--enable-darwin-64bit' configure flag. The 64bit binaries are
-best built and run on Leopard, but most of the system also works on
-Tiger (Tiger's 64bit libraries are, however, limited; therefore e.g. odbc,
-crypto, ssl etc. are not supported in Tiger). 64bit PPC binaries are not
-supported and we have no plans to add such support (no machines to
-test on).
-
-Universal binaries and 64bit binaries are mutually exclusive options.
-
-Make and the variable "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.
-
-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.
-
-
-More Information
-----------------
-
-More information can be found at http://www.erlang.org/.