aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-30 06:06:48 +0000
committerErlang/OTP <[email protected]>2009-11-30 06:06:48 +0000
commit9d6440bf3be15db070371b4c74cc59cacf33eea4 (patch)
tree4f2eb91fc31bbf9a54f0f82343e22819fb5feb53
parent6448c56ecc7c6584a983c5173fd0748068820698 (diff)
parentb261bf348f61469bb1ff0691e96d8ee63ea91545 (diff)
downloadotp-9d6440bf3be15db070371b4c74cc59cacf33eea4.tar.gz
otp-9d6440bf3be15db070371b4c74cc59cacf33eea4.tar.bz2
otp-9d6440bf3be15db070371b4c74cc59cacf33eea4.zip
Merge branch 'ng/readme' into ccase/r13b04_dev
* ng/readme: Clean up formatting issues in the README
-rw-r--r--README360
1 files changed, 166 insertions, 194 deletions
diff --git a/README b/README
index 50280169a0..fa430e7aab 100644
--- a/README
+++ b/README
@@ -2,16 +2,14 @@
OpenSource Erlang/OTP
===========================================================================
-
Please read the whole file before attempting to build and install Erlang.
-You can find more information about OpenSource Erlang at
+You can find more information about Open Source Erlang at:
- http://www.erlang.org/
+ http://www.erlang.org/
-The source code for Erlang/OTP can also be found in a Git
-repository at
+The source code for Erlang/OTP can also be found in a Git repository:
- http://github.com/erlang/otp
+ http://github.com/erlang/otp
%CopyrightBegin%
@@ -30,7 +28,6 @@ under the License.
%CopyrightEnd%
-
Portability
-----------
@@ -47,15 +44,14 @@ At Ericsson we have a "Daily Build and Test" that runs on:
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
+ 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
+ Windows XP SP3, 2003, Vista
We have also done some testing on Mac OS 10.6.0 (Snow Leopard).
-
Versions known *not* to work
-------------------------------------
@@ -70,86 +66,66 @@ 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. 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
-NetBSD and DragonFlyBSD probably have or have had the same bug.
+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:
+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
-* 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
+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.
-
+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
-----------------------------------
@@ -158,31 +134,30 @@ If you are building in a Git reposistory, see
http://wiki.github.com/erlang/otp
-The following instructions are for building using the
-source tar ball.
+The following instructions are for building using the source tar ball.
-Start by unpacking the Erlang/OTP distribution file with your
-GNU compatible TAR
+Step 1: Start by unpacking the Erlang/OTP distribution file with your GNU
+compatible TAR program.
- 1) gunzip -c otp_src_R13B03.tar.gz | tar xf -
- 1) zcat otp_src_R13B03.tar.gz | tar xf -
+ $ gunzip -c otp_src_R13B03.tar.gz | tar xf -
+ $ zcat otp_src_R13B03.tar.gz | tar xf -
-Now cd into the base directory
+Step 2: Now cd into the base directory.
- 2) cd otp_src_R13B03
+ $ cd otp_src_R13B03
-On some platforms Perl may behave strangely if certain locales are set,
-so optionally you may need to set the LANG variable:
+Step 3: On some platforms Perl may behave strangely if certain locales are
+set, so optionally you may need to set the LANG variable:
- 3a) LANG=C; export LANG #Bourne shell
+ # Bourne shell
+ $ LANG=C; export LANG
or
- 3b) setenv LANG C #C-shell
+ # C-Shell
+ $ setenv LANG C
-Run the following commands
+Step 4: Run the following commands to configure the build:
- 4a) ./configure [ options ]
-or
- 4b) ./configure --prefix=<BaseDir> [ other options ]
+ $ ./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>
@@ -192,14 +167,18 @@ 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.
- 5) make
- 6) make install
+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.
+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.
@@ -221,30 +200,28 @@ located, or alternatively disable the use of SSL and Crypto.
Other options are:
- --enable-smp-support See the next section.
+ --enable-smp-support See the next section.
+
+ --disable-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.)
- --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.)
- --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.
-
+ --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 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 (if you change your
+Step 6 is optional. It installs Erlang/OTP (if you change your
mind about where you wish to install you can rerun step 4, without
having to do step 5 again).
@@ -294,14 +271,14 @@ 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 -
+ $ 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 -
+ $ cd <PrefixDir>/lib/erlang
+ $gunzip -c otp_man_R<XY>B-<Z>.tar.gz | tar xf -
GS (Graphic System)
@@ -309,110 +286,107 @@ 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.
-
- The following systems are supported:
-
- 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.
+ 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.
+ 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 Mac OSX 10.4 are supported.
SPARC:
- All UltraSPARC processors running 32-bit user code should work.
+ All UltraSPARC processors running 32-bit user code should work.
+
+ Solaris 9 and Linux (Aurora) are supported.
- 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.
- 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.
+ ARMv5TE (i.e. XScale) processors should work. Both big-endian and
+ little-endian modes are supported.
- Linux is 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".
+ 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:
+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:
- c(Module, native).
+ 1> c(Module, native).
or
- c(Module, [native|OtherOptions]).
+ 1> c(Module, [native|OtherOptions]).
Using the erlc program, write like this:
- erlc +native Module.erl
+ $ erlc +native Module.erl
-The native code will be placed into the beam file and automatically
-loaded when the beam file is loaded.
+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:
- c(Module, [native,{hipe,HipeOptions}|MoreOptions]).
+ 1> c(Module, [native,{hipe,HipeOptions}|MoreOptions]).
-Use
-
- hipe:help_options().
-
-to print out the available options.
+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).
+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").
+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
+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
+'--enable-darwin-universal' configure option. There still may occur
problems with certain applications using this option, but the base
system should run smoothly.
@@ -420,16 +394,16 @@ 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
+ $ CFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk" \
+ LDFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk" \
+ ./configure --enable-darwin-universal
-export MACOSX_DEPLOYMENT_TARGET=10.4
+Also, if you run Leopard, but want to build for Tiger, you must do by setting the MACOSX_DEPLOYMENT_TARGET environmental variable.
-before running the above configure command.
+ $ 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
+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
@@ -438,7 +412,6 @@ test on).
Universal binaries and 64bit binaries are mutually exclusive options.
-
Make and the variable "ERL_TOP"
-------------------------------
@@ -453,12 +426,11 @@ 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
+ $ 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,
@@ -469,4 +441,4 @@ not in the individual source files.
More Information
----------------
-More information can be found at http://www.erlang.org.
+More information can be found at http://www.erlang.org/.