From 7aa2cb2e64cd404f8a9f388d85ab287ced95f139 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Tue, 16 Feb 2010 01:24:37 +0000 Subject: 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). --- README | 562 ----------------------------------------------------------------- 1 file changed, 562 deletions(-) delete mode 100644 README (limited to 'README') 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 /{bin,lib/erlang,man/man1}, use the --prefix= -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, say, -use the --prefix argument like this: -"./configure --prefix=". - -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= 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] ' - 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. - - 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 /lib/erlang - $ gunzip -c otp_html_RB-.tar.gz | tar xf - - -For "erl -man " to work the Unix manual pages have to be -installed in the same way, i.e. - - $ cd /lib/erlang - $gunzip -c otp_man_RB-.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= make - -where 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/. -- cgit v1.2.3