diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 399 |
1 files changed, 203 insertions, 196 deletions
@@ -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 ------------------------------------- @@ -63,126 +59,105 @@ 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. +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. 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 ----------------------------------- -If you are building in a Git reposistory, see +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. +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). @@ -266,6 +243,41 @@ if './otp_build remove_prebuilt_files' is invoked. If you or your system has special requirements please read the Makefile for additional configuration information. + +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) -------------------------------------------- @@ -294,14 +306,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 +321,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]). - -Use - - hipe:help_options(). + 1> c(Module, [native,{hipe,HipeOptions}|MoreOptions]). -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 +429,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 + $ 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 +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 - -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 +447,6 @@ test on). Universal binaries and 64bit binaries are mutually exclusive options. - Make and the variable "ERL_TOP" ------------------------------- @@ -453,12 +461,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 +476,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/. |