From 4ba364c5df2c574974fb3ec10fe03f2e6ad4f92f Mon Sep 17 00:00:00 2001 From: Rick Reed Date: Fri, 16 Mar 2012 15:40:16 -0700 Subject: Fix missing accounting for outbound distribution bytes. --- erts/emulator/beam/dist.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/erts/emulator/beam/dist.c b/erts/emulator/beam/dist.c index 300c2b708f..5db68f6d45 100644 --- a/erts/emulator/beam/dist.c +++ b/erts/emulator/beam/dist.c @@ -1969,6 +1969,7 @@ erts_dist_command(Port *prt, int reds_limit) bw(foq.first->extp, size); #endif reds += ERTS_PORT_REDS_DIST_CMD_DATA(size); + erts_smp_atomic_add_nob(&erts_bytes_out, size); fob = foq.first; obufsize += size_obuf(fob); foq.first = foq.first->next; @@ -2052,6 +2053,7 @@ erts_dist_command(Port *prt, int reds_limit) bw(oq.first->extp, size); #endif reds += ERTS_PORT_REDS_DIST_CMD_DATA(size); + erts_smp_atomic_add_nob(&erts_bytes_out, size); fob = oq.first; obufsize += size_obuf(fob); oq.first = oq.first->next; -- cgit v1.2.3 From 6bb1cd1c9595413cdfd9a8875520e1c85e446833 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Wed, 23 May 2012 16:44:25 +0200 Subject: Move README and INSTALL to HOWTO folder --- .gitignore | 1 + HOWTO/BOOTSTRAP.md | 61 ++ HOWTO/DTRACE.md | 394 +++++++++++ HOWTO/INSTALL-CROSS.md | 556 +++++++++++++++ HOWTO/INSTALL-WIN32.md | 1047 +++++++++++++++++++++++++++++ HOWTO/INSTALL.md | 839 +++++++++++++++++++++++ HOWTO/MARKDOWN.md | 266 ++++++++ HOWTO/SYSTEMTAP.md | 75 +++ INSTALL-CROSS.md | 1 - INSTALL-WIN32.md | 1046 ---------------------------- INSTALL.md | 838 ----------------------- README.bootstrap | 61 -- README.dtrace.md | 393 ----------- README.md | 3 +- README.md.txt | 266 -------- README.systemtap.md | 72 -- TAR.include | 8 +- erts/emulator/beam/erlang_dtrace.d | 6 +- lib/runtime_tools/doc/src/dyntrace.xml | 2 +- make/emd2exml.in | 16 +- system/doc/installation_guide/Makefile | 8 +- system/doc/installation_guide/part.xml | 4 +- system/doc/installation_guide/xmlfiles.mk | 3 +- xcomp/README.md | 556 +-------------- 24 files changed, 3273 insertions(+), 3249 deletions(-) create mode 100644 HOWTO/BOOTSTRAP.md create mode 100644 HOWTO/DTRACE.md create mode 100644 HOWTO/INSTALL-CROSS.md create mode 100644 HOWTO/INSTALL-WIN32.md create mode 100644 HOWTO/INSTALL.md create mode 100644 HOWTO/MARKDOWN.md create mode 100644 HOWTO/SYSTEMTAP.md delete mode 120000 INSTALL-CROSS.md delete mode 100644 INSTALL-WIN32.md delete mode 100644 INSTALL.md delete mode 100644 README.bootstrap delete mode 100644 README.dtrace.md delete mode 100644 README.md.txt delete mode 100644 README.systemtap.md mode change 100644 => 120000 xcomp/README.md diff --git a/.gitignore b/.gitignore index 0986bb6e4c..e64cc9ec81 100644 --- a/.gitignore +++ b/.gitignore @@ -335,6 +335,7 @@ JAVADOC-GENERATED /system/doc/installation_guide/INSTALL.xml /system/doc/installation_guide/INSTALL-CROSS.xml /system/doc/installation_guide/INSTALL-WIN32.xml +/system/doc/installation_guide/MARKDOWN.xml # test_server diff --git a/HOWTO/BOOTSTRAP.md b/HOWTO/BOOTSTRAP.md new file mode 100644 index 0000000000..59e31165cf --- /dev/null +++ b/HOWTO/BOOTSTRAP.md @@ -0,0 +1,61 @@ +Notes about prebuilt beam files under version control +===================================================== + +This information applies mostly to developers, some parts only +to developers of the main branch i.e. Ericsson and HiPE personel. + +There are two types of derived code under version control, namely: + +primary bootstrap - Resides in the `$ERL_TOP/bootstrap/{lib,bin}` directories. +preloaded code - Resides in the `$ERL_TOP/erts/preloaded` directory. + +Primary bootstrap +----------------- + +The two types of version controlled code are fundamentally +different. The primary bootstrap is code compiled from source files in +the lib/{kernel,stdlib,compiler} (and header files from +lib/orber/include. They are checked in in the version control system +to make it possible to build directly from the code base tree without +the need for an earlier version of the compiler. When a new version of +OTP is released, these files are updated manually (or rather, by using +the `$ERL_TOP/otp_build` script) and checked in. The files can also be +updated due to changes in the compiler during the development +process. The primary bootstrap is always updated as a separate +deliberate process, never during a normal development build. + +If a prebuilt open source version of erlang is used, the directory +bootstrap initially does not contain any beam files, the directory is +instead populated by copying beam files from the +`$ERL_TOP/lib/{kernel,stdlib,compiler}/ebin` directories. This +construction is to save space in the distribution, but the result +would be the same. Open source developers need not provide patches for +the precompiled beam files in the primary bootstrap, the bootstrap +update is always performed by the main developers. + +Preloaded code +-------------- + +The directory `$ERL_TOP/preloaded` contains both src and ebin +subdirectories. The preloaded code is compiled into the virtual +machine and always present. When compiling the virtual machine, those +beam files need to be present and they are considered a part of the +virtual machine rather than a part of the kernel application. When +preloaded files are to be updated, the source code is built using a +special Makefile in the `$ERL_TOP/preloaded/src` directory, which +creates beam files in the same directory. When they seem to compile +successfully, they can be used in an emulator build by being copied +to the ebin directory. `otp_build update_preloaded` can be used to +ease the process (there are also similar targets in the +`$ERL_TOP/preloaded/src/Makefile`). + +In prebuilt open source distributions, these beam files are also +present, but to update them one might need to change permission on the +`$ERL_TOP/preloaded/ebin` directory, then build and then manually copy +the beam files from the source directory to ../ebin. If patches are +created that involve the source files used to build preloaded code, +always note this specially as the preloaded/ebin directory needs +updating, or provide the new derived files in the patch or as complete +binaries. + +/Patrik, OTP diff --git a/HOWTO/DTRACE.md b/HOWTO/DTRACE.md new file mode 100644 index 0000000000..1d495b0eaf --- /dev/null +++ b/HOWTO/DTRACE.md @@ -0,0 +1,394 @@ +DTrace and Erlang/OTP +===================== + +History +------- + +The first implementation of DTrace probes for the Erlang virtual +machine was presented at the [2008 Erlang User Conference] [1]. That +work, based on the Erlang/OTP R12 release, was discontinued due to +what appears to be miscommunication with the original developers. + +Several users have created Erlang port drivers, linked-in drivers, or +NIFs that allow Erlang code to try to activate a probe, +e.g. `foo_module:dtrace_probe("message goes here!")`. + +Goals +----- + +1. Annotate as much of the Erlang VM as is practical. + * The initial goal is to trace file I/O operations. +2. Support all platforms that implement DTrace: OS X, Solaris, + and (I hope) FreeBSD and NetBSD. +3. To the extent that it's practical, support SystemTap on Linux + via DTrace provider compatibility. +4. Allow Erlang code to supply annotations. + +Supported platforms +------------------- + +* OS X 10.6.x / Snow Leopard. It should also work for 10.7 / Lion, + but I haven't personally tested it. +* Solaris 10. I have done limited testing on Solaris 11 and + OpenIndiana release 151a, and both appear to work. +* FreeBSD 9.0, though please see the "FreeBSD 9.0 Release Notes" + section below! +* Linux via SystemTap compatibility. Please see + [$ERL_TOP/HOWTO/SYSTEMTAP.md][] for more details. + +Just add the `--with-dynamic-trace=dtrace` option to your command when you +run the `configure` script. If you are using systemtap, the configure option +is `--with-dynamic-trace=systemtap` + +Status +------ + +As of R15B01, the dynamic trace code is included in the main OTP distribution, +although it's considered experimental. The main development of the dtrace code +still happens outside of Ericsson, but there is no need to fetch a patched +version of OTP to get the basic funtionality. + +Implementation summary +---------------------- + +So far, most effort has been focused on the `efile_drv.c` code, +which implements most file I/O on behalf of the Erlang virtual +machine. This driver also presents a big challenge: its use of an I/O +worker pool (enabled by using the `erl +A 8` flag, for example) makes +it much more difficult to trace I/O activity because each of the +following may be executed in a different Pthread: + +* I/O initiation (Erlang code) +* I/O proxy process handling, e.g. read/write when file is not opened + in `raw` mode, operations executed by the code & file server processes. + (Erlang code) +* `efile_drv` command setup (C code) +* `efile_drv` command execution (C code) +* `efile_drv` status return (C code) + +**TODO: keep this description up-to-date.** + +Example output from `lib/dtrace/examples/efile_drv.d` while executing +`file:rename("old-name", "new-name")`: + + efile_drv enter tag={3,84} user tag some-user-tag | RENAME (12) | args: old-name new-name , 0 0 (port #Port<0.59>) + async I/O worker tag={3,83} | RENAME (12) | efile_drv-int_entry + async I/O worker tag={3,83} | RENAME (12) | efile_drv-int_return + efile_drv return tag={3,83} user tag | RENAME (12) | errno 2 + +... where the following key can help decipher the output: + +* `{3,83}` is the Erlang scheduler thread number (3) and operation + counter number (83) assigned to this I/O operation. Together, + these two numbers form a unique ID for the I/O operation. +* `12` is the command number for the rename operation. See the + definition for `FILE_RENAME` in the source code file `efile_drv.c` + or the `BEGIN` section of the D script `lib/dtrace/examples/efile_drv.d`. +* `old-name` and `new-name` are the two string arguments for the + source and destination of the `rename(2)` system call. + The two integer arguments are unused; the simple formatting code + prints the arguments anyway, 0 and 0. +* The worker pool code was called on behalf of Erlang port `#Port<0.59>`. +* The system call failed with a POSIX errno value of 2: `ENOENT`, + because the path `old-name` does not exist. +* The `efile_drv-int_entry` and `efile_drv_int_return` probes are + provided in case the user is + interested in measuring only the latency of code executed by + `efile_drv` asynchronous functions by I/O worker pool threads + and the OS system call that they encapsulate. + +So, where does the `some-user-tag` string come from? + +At the moment, the user tag comes from code like the following: + + put(dtrace_utag, "some-user-tag"), + file:rename("old-name", "new-name"). + +This method of tagging I/O at the Erlang level is subject to change. + +Example DTrace probe specification +---------------------------------- + + /** + * Fired when a message is sent from one local process to another. + * + * NOTE: The 'size' parameter is in machine-dependent words and + * that the actual size of any binary terms in the message + * are not included. + * + * @param sender the PID (string form) of the sender + * @param receiver the PID (string form) of the receiver + * @param size the size of the message being delivered (words) + * @param token_label for the sender's sequential trace token + * @param token_previous count for the sender's sequential trace token + * @param token_current count for the sender's sequential trace token + */ + probe message__send(char *sender, char *receiver, uint32_t size, + int token_label, int token_previous, int token_current); + + /** + * Fired when a message is sent from a local process to a remote process. + * + * NOTE: The 'size' parameter is in machine-dependent words and + * that the actual size of any binary terms in the message + * are not included. + * + * @param sender the PID (string form) of the sender + * @param node_name the Erlang node name (string form) of the receiver + * @param receiver the PID/name (string form) of the receiver + * @param size the size of the message being delivered (words) + * @param token_label for the sender's sequential trace token + * @param token_previous count for the sender's sequential trace token + * @param token_current count for the sender's sequential trace token + */ + probe message__send__remote(char *sender, char *node_name, char *receiver, + uint32_t size, + int token_label, int token_previous, int token_current); + + /** + * Fired when a message is queued to a local process. This probe + * will not fire if the sender's pid == receiver's pid. + * + * NOTE: The 'size' parameter is in machine-dependent words and + * that the actual size of any binary terms in the message + * are not included. + * + * @param receiver the PID (string form) of the receiver + * @param size the size of the message being delivered (words) + * @param queue_len length of the queue of the receiving process + * @param token_label for the sender's sequential trace token + * @param token_previous count for the sender's sequential trace token + * @param token_current count for the sender's sequential trace token + */ + probe message__queued(char *receiver, uint32_t size, uint32_t queue_len, + int token_label, int token_previous, int token_current); + + /** + * Fired when a message is 'receive'd by a local process and removed + * from its mailbox. + * + * NOTE: The 'size' parameter is in machine-dependent words and + * that the actual size of any binary terms in the message + * are not included. + * + * @param receiver the PID (string form) of the receiver + * @param size the size of the message being delivered (words) + * @param queue_len length of the queue of the receiving process + * @param token_label for the sender's sequential trace token + * @param token_previous count for the sender's sequential trace token + * @param token_current count for the sender's sequential trace token + */ + probe message__receive(char *receiver, uint32_t size, uint32_t queue_len, + int token_label, int token_previous, int token_current); + + /* ... */ + + /* Async driver pool */ + + /** + * Show the post-add length of the async driver thread pool member's queue. + * + * NOTE: The port name is not available: additional lock(s) must + * be acquired in order to get the port name safely in an SMP + * environment. The same is true for the aio__pool_get probe. + * + * @param port the Port (string form) + * @param new queue length + */ + probe aio_pool__add(char *, int); + + /** + * Show the post-get length of the async driver thread pool member's queue. + * + * @param port the Port (string form) + * @param new queue length + */ + probe aio_pool__get(char *, int); + + /* Probes for efile_drv.c */ + + /** + * Entry into the efile_drv.c file I/O driver + * + * For a list of command numbers used by this driver, see the section + * "Guide to probe arguments" in ../../../README.md. That section + * also contains explanation of the various integer and string + * arguments that may be present when any particular probe fires. + * + * TODO: Adding the port string, args[10], is a pain. Making that + * port string available to all the other efile_drv.c probes + * will be more pain. Is the pain worth it? If yes, then + * add them everywhere else and grit our teeth. If no, then + * rip it out. + * + * @param thread-id number of the scheduler Pthread arg0 + * @param tag number: {thread-id, tag} uniquely names a driver operation + * @param user-tag string arg2 + * @param command number arg3 + * @param string argument 1 arg4 + * @param string argument 2 arg5 + * @param integer argument 1 arg6 + * @param integer argument 2 arg7 + * @param integer argument 3 arg8 + * @param integer argument 4 arg9 + * @param port the port ID of the busy port args[10] + */ + probe efile_drv__entry(int, int, char *, int, char *, char *, + int64_t, int64_t, int64_t, int64_t, char *); + + /** + * Entry into the driver's internal work function. Computation here + * is performed by a async worker pool Pthread. + * + * @param thread-id number + * @param tag number + * @param command number + */ + probe efile_drv__int_entry(int, int, int); + + /** + * Return from the driver's internal work function. + * + * @param thread-id number + * @param tag number + * @param command number + */ + probe efile_drv__int_return(int, int, int); + + /** + * Return from the efile_drv.c file I/O driver + * + * @param thread-id number arg0 + * @param tag number arg1 + * @param user-tag string arg2 + * @param command number arg3 + * @param Success? 1 is success, 0 is failure arg4 + * @param If failure, the errno of the error. arg5 + */ + probe efile_drv__return(int, int, char *, int, int, int); + +Guide to efile_drv.c probe arguments +------------------------------------ + + /* Driver op code: used by efile_drv-entry arg3 */ + /* used by efile_drv-int_entry arg3 */ + /* used by efile_drv-int_return arg3 */ + /* used by efile_drv-return arg3 */ + + #define FILE_OPEN 1 (probe arg3) + probe arg6 = C driver dt_i1 = flags; + probe arg4 = C driver dt_s1 = path; + + #define FILE_READ 2 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + probe arg7 = C driver dt_i2 = flags; + probe arg8 = C driver dt_i3 = size; + + #define FILE_LSEEK 3 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + probe arg7 = C driver dt_i2 = offset; + probe arg8 = C driver dt_i3 = origin; + + #define FILE_WRITE 4 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + probe arg7 = C driver dt_i2 = flags; + probe arg8 = C driver dt_i3 = size; + + #define FILE_FSTAT 5 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + + #define FILE_PWD 6 (probe arg3) + none + + #define FILE_READDIR 7 (probe arg3) + probe arg4 = C driver dt_s1 = path; + + #define FILE_CHDIR 8 (probe arg3) + probe arg4 = C driver dt_s1 = path; + + #define FILE_FSYNC 9 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + + #define FILE_MKDIR 10 (probe arg3) + probe arg4 = C driver dt_s1 = path; + + #define FILE_DELETE 11 (probe arg3) + probe arg4 = C driver dt_s1 = path; + + #define FILE_RENAME 12 (probe arg3) + probe arg4 = C driver dt_s1 = old_name; + probe arg5 = C driver dt_s2 = new_name; + + #define FILE_RMDIR 13 (probe arg3) + probe arg4 = C driver dt_s1 = path; + + #define FILE_TRUNCATE 14 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + probe arg7 = C driver dt_i2 = flags; + + #define FILE_READ_FILE 15 (probe arg3) + probe arg4 = C driver dt_s1 = path; + + #define FILE_WRITE_INFO 16 (probe arg3) + probe arg6 = C driver dt_i1 = mode; + probe arg7 = C driver dt_i2 = uid; + probe arg8 = C driver dt_i3 = gid; + + #define FILE_LSTAT 19 (probe arg3) + probe arg4 = C driver dt_s1 = path; + + #define FILE_READLINK 20 (probe arg3) + probe arg4 = C driver dt_s1 = path; + + #define FILE_LINK 21 (probe arg3) + probe arg4 = C driver dt_s1 = existing_path; + probe arg5 = C driver dt_s2 = new_path; + + #define FILE_SYMLINK 22 (probe arg3) + probe arg4 = C driver dt_s1 = existing_path; + probe arg5 = C driver dt_s2 = new_path; + + #define FILE_CLOSE 23 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + probe arg7 = C driver dt_i2 = flags; + + #define FILE_PWRITEV 24 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + probe arg7 = C driver dt_i2 = flags; + probe arg8 = C driver dt_i3 = size; + + #define FILE_PREADV 25 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + probe arg7 = C driver dt_i2 = flags; + probe arg8 = C driver dt_i3 = size; + + #define FILE_SETOPT 26 (probe arg3) + probe arg6 = C driver dt_i1 = opt_name; + probe arg7 = C driver dt_i2 = opt_specific_value; + + #define FILE_IPREAD 27 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + probe arg7 = C driver dt_i2 = flags; + probe arg8 = C driver dt_i3 = offsets[0]; + probe arg9 = C driver dt_i4 = size; + + #define FILE_ALTNAME 28 (probe arg3) + probe arg4 = C driver dt_s1 = path; + + #define FILE_READ_LINE 29 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + probe arg7 = C driver dt_i2 = flags; + probe arg8 = C driver dt_i3 = read_offset; + probe arg9 = C driver dt_i4 = read_ahead; + + #define FILE_FDATASYNC 30 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + + #define FILE_FADVISE 31 (probe arg3) + probe arg6 = C driver dt_i1 = fd; + probe arg7 = C driver dt_i2 = offset; + probe arg8 = C driver dt_i3 = length; + probe arg9 = C driver dt_i4 = advise_type; + + [1]: http://www.erlang.org/euc/08/ + [$ERL_TOP/HOWTO/SYSTEMTAP.md]: SYSTEMTAP.md diff --git a/HOWTO/INSTALL-CROSS.md b/HOWTO/INSTALL-CROSS.md new file mode 100644 index 0000000000..95264a82eb --- /dev/null +++ b/HOWTO/INSTALL-CROSS.md @@ -0,0 +1,556 @@ +Cross Compiling Erlang/OTP +========================== + +Introduction +------------ + +This document describes how to cross compile Erlang/OTP-%OTP-REL%. Note that +the support for cross compiling Erlang/OTP should be considered as +experimental. As far as we know, the %OTP-REL% release should cross compile +fine, but since we currently have a very limited set of cross compilation +environments to test with we cannot be sure. The cross compilation support +will remain in an experimental state until we get a lot more cross compilation +environments to test with. + +You are advised to read the whole document before attempting to cross +compile Erlang/OTP. However, before reading this document, you should read +the [$ERL_TOP/HOWTO/INSTALL.md][] document which describes building and installing +Erlang/OTP in general. `$ERL_TOP` is the top directory in the source tree. + +### otp\_build Versus configure/make ### + +Building Erlang/OTP can be done either by using the `$ERL_TOP/otp_build` +script, or by invoking `$ERL_TOP/configure` and `make` directly. Building using +`otp_build` is easier since it involves fewer steps, but the `otp_build` build +procedure is not as flexible as the `configure`/`make` build procedure. Note +that `otp_build configure` will produce a default configuration that differs +from what `configure` will produce by default. For example, currently +`--disable-dynamic-ssl-lib` is added to the `configure` command line arguments +unless `--enable-dynamic-ssl-lib` has been explicitly passed. The binary +releases that we deliver are built using `otp_build`. The defaults used by +`otp_build configure` may change at any time without prior notice. + +### Cross Configuration ### + +The `$ERL_TOP/xcomp/erl-xcomp.conf.template` file contains all available cross +configuration variables and can be used as a template when creating a cross +compilation configuration. All [cross configuration variables][] are also +listed at the end of this document. For examples of working cross +configurations see the `$ERL_TOP/xcomp/erl-xcomp-TileraMDE2.0-tilepro.conf` +file and the `$ERL_TOP/xcomp/erl-xcomp-x86_64-saf-linux-gnu.conf` file. If the +default behavior of a variable is satisfactory, the variable does not need to +be set. However, the `configure` script will issue a warning when a default +value is used. When a variable has been set, no warning will be issued. + +A cross configuration file can be passed to `otp_build configure` using the +`--xcomp-conf` command line argument. Note that `configure` does not accept +this command line argument. When using the `configure` script directly, pass +the configuration variables as arguments to `configure` using a +`=` syntax. Variables can also be passed as environment +variables to `configure`. However, if you pass the configuration in the +environment, make sure to unset all of these environment variables before +invoking `make`; otherwise, the environment variables might set make variables +in some applications, or parts of some applications, and you may end up with +an erroneously configured build. + +### What can be Cross Compiled? ### + +All Erlang/OTP applications except the `wx` application can be cross compiled. +The build of the `wx` driver will currently be automatically disabled when +cross compiling. + +### Compatibility ### + +The build system, including cross compilation configuration variables used, +may be subject to non backward compatible changes without prior notice. +Current cross build system has been tested when cross compiling some Linux/GNU +systems, but has only been partly tested for more esoteric platforms. The +VxWorks example file is highly dependent on our environment and is here more +or less only for internal use. + +### Patches ### + +Please submit any patches for cross compiling in a way consistent with this +system. All input is welcome as we have a very limited set of cross compiling +environments to test with. If a new configuration variable is needed, add it +to `$ERL_TOP/xcomp/erl-xcomp.conf.template`, and use it in `configure.in`. +Other files that might need to be updated are: + +- `$ERL_TOP/xcomp/erl-xcomp-vars.sh` +- `$ERL_TOP/erl-build-tool-vars.sh` +- `$ERL_TOP/erts/aclocal.m4` +- `$ERL_TOP/xcomp/README.md` +- `$ERL_TOP/xcomp/erl-xcomp-*.conf` + +Note that this might be an incomplete list of files that need to be updated. + +General information on how to submit patches can be found at: + + +Build and Install Procedure +--------------------------- + +If you are building in Git, you want to read the [Building in Git][] section +of [$ERL_TOP/HOWTO/INSTALL.md][] before proceeding. + +We will first go through the `configure`/`make` build procedure which people +probably are most familiar with. + +### Building With configure/make Directly ### + + (1) + +Change directory into the top directory of the Erlang/OTP source tree. + + $ cd $ERL_TOP + +In order to compile Erlang code, a small Erlang bootstrap system has to be +built, or an Erlang/OTP system of the same release as the one being built +has to be provided in the `$PATH`. The Erlang/OTP for the target system will +be built using this Erlang system, together with the cross compilation tools +provided. + +If you want to build the documentation out of the same source tree as you are +cross compiling in, you currently need a full Erlang/OTP system of the same +release as the one being built for the build machine. If this is the case, +build and install one for the build machine (or use one already built) and add +it to the `$PATH` before cross building, and building the documentation. See +the [How to Build the Documentation][] section in the [$ERL_TOP/HOWTO/INSTALL.md][] +document for information on how to build the documentation. + +If you want to build using a compatible Erlang/OTP system in the `$PATH`, +jump to (3). + +#### Building a Bootstrap System #### + + (2) + + $ ./configure --enable-bootstrap-only + $ make + +The `--enable-bootstrap-only` argument to `configure` isn't strictly necessary, +but will speed things up. It will only run `configure` in applications +necessary for the bootstrap, and will disable a lot of things not needed by +the bootstrap system. If you run `configure` without `--enable-boostrap-only` +you also have to run make as `make bootstrap`; otherwise, the whole system will +be built. + +#### Cross Building the System #### + + (3) + + $ ./configure --host= --build= [Other Config Args] + $ make + +`` is the host/target system that you build for. It does not have to be +a full `CPU-VENDOR-OS` triplet, but can be. The full `CPU-VENDOR-OS` triplet +will be created by executing `$ERL_TOP/erts/autoconf/config.sub `. If +`config.sub` fails, you need to be more specific. + +`` should equal the `CPU-VENDOR-OS` triplet of the system that you +build on. If you execute `$ERL_TOP/erts/autoconf/config.guess`, it will in +most cases print the triplet you want to use for this. + +Pass the cross compilation variables as command line arguments to `configure` +using a `=` syntax. + +> *NOTE*: You can *not* pass a configuration file using the `--xcomp-conf` +> argument when you invoke `configure` directly. The `--xcomp-conf` argument +> can only be passed to `otp_build configure`. + +`make` will verify that the Erlang/OTP system used when building is of the +same release as the system being built, and will fail if this is not the case. +It is possible, however not recommended, to force the cross compilation even +though the wrong Erlang/OTP system is used. This by invoking `make` like this: +`make ERL_XCOMP_FORCE_DIFFERENT_OTP=yes`. + +> *WARNING*: Invoking `make ERL_XCOMP_FORCE_DIFFERENT_OTP=yes` might fail, +> silently produce suboptimal code, or silently produce erroneous code. + +#### Installing #### + +You can either install using the installation paths determined by `configure` +(4), or install manually using (5). + +##### Installing Using Paths Determined by configure ##### + + (4) + + $ make install DESTDIR= + +`make install` will install at a location specified when doing `configure`. +`configure` arguments specifying where the installation should reside are for +example: `--prefix`, `--exec-prefix`, `--libdir`, `--bindir`, etc. By default +it will install under `/usr/local`. You typically do not want to install your +cross build under `/usr/local` on your build machine. Using [DESTDIR][] +will cause the installation paths to be prefixed by `$DESTDIR`. This makes it +possible to install and package the installation on the build machine without +having to place the installation in the same directory on the build machine as +it should be executed from on the target machine. + +When `make install` has finished, change directory into `$DESTDIR`, package +the system, move it to the target machine, and unpack it. Note that the +installation will only be working on the target machine at the location +determined by `configure`. + +##### Installing Manually ##### + + (5) + + $ make release RELEASE_ROOT= + +`make release` will copy what you have built for the target machine to +``. The `Install` script will not be run. The content of +`` is what by default ends up in `/usr/local/lib/erlang`. + +The `Install` script used when installing Erlang/OTP requires common Unix +tools such as `sed` to be present in your `$PATH`. If your target system +does not have such tools, you need to run the `Install` script on your +build machine before packaging Erlang/OTP. The `Install` script should +currently be invoked as follows in the directory where it resides +(the top directory): + + $ ./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, and is what `make install` uses. +* `-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. + +You can now either do: + + (6) + +* Decide where the installation should be located on the target machine, + run the `Install` script on the build machine, and package the installed + installation. The installation just need to be unpacked at the right + location on the target machine: + + $ cd + $ ./Install -cross [-minimal|-sasl] + +or: + + (7) + +* Package the installation in ``, place it wherever you want + on your target machine, and run the `Install` script on your target + machine: + + $ cd + $ ./Install [-minimal|-sasl] + +### Building With the otp\_build Script ### + + (8) + + $ cd $ERL_TOP + + (9) + + $ ./otp_build configure --xcomp-conf= [Other Config Args] + +alternatively: + + $ ./otp_build configure --host= --build= [Other Config Args] + +If you have your cross compilation configuration in a file, pass it using the +`--xcomp-conf=` command line argument. If not, pass `--host=`, +`--build=`, and the configuration variables using a `=` +syntax on the command line (same as in (3)). Note that `` and `` +have to be passed one way or the other; either by using `erl_xcomp_host=` +and `erl_xcomp_build=` in the configuration file, or by using the +`--host=`, and `--build=` command line arguments. + +`otp_build configure` will configure both for the boostrap system on the +build machine and the cross host system. + + (10) + + $ ./otp_build boot -a + +`otp_build boot -a` will first build a bootstrap system for the build machine +and then do the cross build of the system. + + (11) + + $ ./otp_build release -a + +`otp_build release -a` will do the same as (5), and you will after this have +to do a manual install either by doing (6), or (7). + +Testing the cross compiled system +--------------------------------- +Some of the tests that come with erlang use native code to test. This means +that when cross compiling erlang you also have to cross compile test suites +in order to run tests on the target host. To do this you first have to release +the tests as usual. + + $ make release_tests + +or + + $ ./otp_build tests + +The tests will be released into `$ERL_TOP/release/tests`. After releasing the +tests you have to install the tests on the build machine. You supply the same +xcomp file as to `./otp_build` in (9). + + $ cd $ERL_TOP/release/tests/test_server/ + $ $ERL_TOP/bootstrap/bin/erl -eval 'ts:install([{xcomp,""}])' -s ts compile_testcases -s init stop + +You should get a lot of printouts as the testcases are compiled. Once done you +should copy the entire `$ERL_TOP/release/tests` folder to the cross host system. + +Then go to the cross host system and setup the erlang installed in (4) or (5) +to be in your `$PATH`. Then go to what previously was +`$ERL_TOP/release/tests/test_server` and issue the following command. + + $ erl -s ts install -s ts run all_tests -s init stop + +The configure should be skipped and all tests should hopefully pass. For more +details about how to use ts run `erl -s ts help -s init stop` + +Currently Used Configuration Variables +-------------------------------------- + +Note that you cannot define arbitrary variables in a cross compilation +configuration file. Only the ones listed below will be guaranteed to be +visible throughout the whole execution of all `configure` scripts. Other +variables needs to be defined as arguments to `configure` or exported in +the environment. + +### Variables for otp\_build Only ### + +Variables in this section are only used, when configuring Erlang/OTP for +cross compilation using `$ERL_TOP/otp_build configure`. + +> *NOTE*: These variables currently have *no* effect if you configure using +> the `configure` script directly. + +* `erl_xcomp_build` - The build system used. This value will be passed as + `--build=$erl_xcomp_build` argument to the `configure` script. It does + not have to be a full `CPU-VENDOR-OS` triplet, but can be. The full + `CPU-VENDOR-OS` triplet will be created by + `$ERL_TOP/erts/autoconf/config.sub $erl_xcomp_build`. If set to `guess`, + the build system will be guessed using + `$ERL_TOP/erts/autoconf/config.guess`. + +* `erl_xcomp_host` - Cross host/target system to build for. This value will + be passed as `--host=$erl_xcomp_host` argument to the `configure` script. + It does not have to be a full `CPU-VENDOR-OS` triplet, but can be. The + full `CPU-VENDOR-OS` triplet will be created by + `$ERL_TOP/erts/autoconf/config.sub $erl_xcomp_host`. + +* `erl_xcomp_configure_flags` - Extra configure flags to pass to the + `configure` script. + +### Cross Compiler and Other Tools ### + +If the cross compilation tools are prefixed by `-` you probably do +not need to set these variables (where `` is what has been passed as +`--host=` argument to `configure`). + +All variables in this section can also be used when native compiling. + +* `CC` - C compiler. + +* `CFLAGS` - C compiler flags. + +* `STATIC_CFLAGS` - Static C compiler flags. + +* `CFLAG_RUNTIME_LIBRARY_PATH` - This flag should set runtime library + search path for the shared libraries. Note that this actually is a + linker flag, but it needs to be passed via the compiler. + +* `CPP` - C pre-processor. + +* `CPPFLAGS` - C pre-processor flags. + +* `CXX` - C++ compiler. + +* `CXXFLAGS` - C++ compiler flags. + +* `LD` - Linker. + +* `LDFLAGS` - Linker flags. + +* `LIBS` - Libraries. + +#### Dynamic Erlang Driver Linking #### + +> *NOTE*: Either set all or none of the `DED_LD*` variables. + +* `DED_LD` - Linker for Dynamically loaded Erlang Drivers. + +* `DED_LDFLAGS` - Linker flags to use with `DED_LD`. + +* `DED_LD_FLAG_RUNTIME_LIBRARY_PATH` - This flag should set runtime library + search path for shared libraries when linking with `DED_LD`. + +#### Large File Support #### + +> *NOTE*: Either set all or none of the `LFS_*` variables. + +* `LFS_CFLAGS` - Large file support C compiler flags. + +* `LFS_LDFLAGS` - Large file support linker flags. + +* `LFS_LIBS` - Large file support libraries. + +#### Other Tools #### + +* `RANLIB` - `ranlib` archive index tool. + +* `AR` - `ar` archiving tool. + +* `GETCONF` - `getconf` system configuration inspection tool. `getconf` is + currently used for finding out large file support flags to use, and + on Linux systems for finding out if we have an NPTL thread library or + not. + +### Cross System Root Locations ### + +* `erl_xcomp_sysroot` - The absolute path to the system root of the cross + compilation environment. Currently, the `crypto`, `odbc`, `ssh` and + `ssl` applications need the system root. These applications will be + skipped if the system root has not been set. The system root might be + needed for other things too. If this is the case and the system root + has not been set, `configure` will fail and request you to set it. + +* `erl_xcomp_isysroot` - The absolute path to the system root for includes + of the cross compilation environment. If not set, this value defaults + to `$erl_xcomp_sysroot`, i.e., only set this value if the include system + root path is not the same as the system root path. + +### Optional Feature, and Bug Tests ### + +These tests cannot (always) be done automatically when cross compiling. You +usually do not need to set these variables. + +> *WARNING*: Setting these variables wrong may cause hard to detect +> runtime errors. If you need to change these values, *really* make sure +> that the values are correct. + +> *NOTE*: Some of these values will override results of tests performed +> by `configure`, and some will not be used until `configure` is sure that +> it cannot figure the result out. + +The `configure` script will issue a warning when a default value is used. +When a variable has been set, no warning will be issued. + +* `erl_xcomp_after_morecore_hook` - `yes|no`. Defaults to `no`. If `yes`, + the target system must have a working `__after_morecore_hook` that can be + used for tracking used `malloc()` implementations core memory usage. + This is currently only used by unsupported features. + +* `erl_xcomp_bigendian` - `yes|no`. No default. If `yes`, the target system + must be big endian. If `no`, little endian. This can often be + automatically detected, but not always. If not automatically detected, + `configure` will fail unless this variable is set. Since no default + value is used, `configure` will try to figure this out automatically. + +* `erl_xcomp_clock_gettime_cpu_time` - `yes|no`. Defaults to `no`. If `yes`, + the target system must have a working `clock_gettime()` implementation + that can be used for retrieving process CPU time. + +* `erl_xcomp_getaddrinfo` - `yes|no`. Defaults to `no`. If `yes`, the target + system must have a working `getaddrinfo()` implementation that can + handle both IPv4 and IPv6. + +* `erl_xcomp_gethrvtime_procfs_ioctl` - `yes|no`. Defaults to `no`. If `yes`, + the target system must have a working `gethrvtime()` implementation and + is used with procfs `ioctl()`. + +* `erl_xcomp_dlsym_brk_wrappers` - `yes|no`. Defaults to `no`. If `yes`, the + target system must have a working `dlsym(RTLD_NEXT, )` implementation + that can be used on `brk` and `sbrk` symbols used by the `malloc()` + implementation in use, and by this track the `malloc()` implementations + core memory usage. This is currently only used by unsupported features. + +* `erl_xcomp_kqueue` - `yes|no`. Defaults to `no`. If `yes`, the target + system must have a working `kqueue()` implementation that returns a file + descriptor which can be used by `poll()` and/or `select()`. If `no` and + the target system has not got `epoll()` or `/dev/poll`, the kernel-poll + feature will be disabled. + +* `erl_xcomp_linux_clock_gettime_correction` - `yes|no`. Defaults to `yes` on + Linux; otherwise, `no`. If `yes`, `clock_gettime(CLOCK_MONOTONIC, _)` on + the target system must work. This variable is recommended to be set to + `no` on Linux systems with kernel versions less than 2.6. + +* `erl_xcomp_linux_nptl` - `yes|no`. Defaults to `yes` on Linux; otherwise, + `no`. If `yes`, the target system must have NPTL (Native POSIX Thread + Library). Older Linux systems have LinuxThreads instead of NPTL (Linux + kernel versions typically less than 2.6). + +* `erl_xcomp_linux_usable_sigaltstack` - `yes|no`. Defaults to `yes` on Linux; + otherwise, `no`. If `yes`, `sigaltstack()` must be usable on the target + system. `sigaltstack()` on Linux kernel versions less than 2.4 are + broken. + +* `erl_xcomp_linux_usable_sigusrx` - `yes|no`. Defaults to `yes`. If `yes`, + the `SIGUSR1` and `SIGUSR2` signals must be usable by the ERTS. Old + LinuxThreads thread libraries (Linux kernel versions typically less than + 2.2) used these signals and made them unusable by the ERTS. + +* `erl_xcomp_poll` - `yes|no`. Defaults to `no` on Darwin/MacOSX; otherwise, + `yes`. If `yes`, the target system must have a working `poll()` + implementation that also can handle devices. If `no`, `select()` will be + used instead of `poll()`. + +* `erl_xcomp_putenv_copy` - `yes|no`. Defaults to `no`. If `yes`, the target + system must have a `putenv()` implementation that stores a copy of the + key/value pair. + +* `erl_xcomp_reliable_fpe` - `yes|no`. Defaults to `no`. If `yes`, the target + system must have reliable floating point exceptions. + +Copyright and License +--------------------- + +%CopyrightBegin% + +Copyright Ericsson AB 2009-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% + +Modifying This Document +----------------------- + +Before modifying this document you need to have a look at the +[$ERL_TOP/HOWTO/MARKDOWN.md][] document. + + + + [$ERL_TOP/HOWTO/INSTALL.md]: INSTALL.md + [Building in Git]: INSTALL.md#How-to-Build-and-Install-ErlangOTP_Building-in-Git + [How to Build the Documentation]: INSTALL.md#The-ErlangOTP-Documentation_How-to-Build-the-Documentation + [cross configuration variables]: #Currently-Used-Configuration-Variables + [DESTDIR]: http://www.gnu.org/prep/standards/html_node/DESTDIR.html + [$ERL_TOP/HOWTO/MARKDOWN.md]: MARKDOWN.md + + [?TOC]: true diff --git a/HOWTO/INSTALL-WIN32.md b/HOWTO/INSTALL-WIN32.md new file mode 100644 index 0000000000..94d3688f23 --- /dev/null +++ b/HOWTO/INSTALL-WIN32.md @@ -0,0 +1,1047 @@ +How to Build Erlang/OTP on Windows +================================== + +Introduction +------------ + +This file describes how to build the Erlang emulator and the OTP +libraries on Windows. The instructions apply to versions of Windows +supporting the Cygwin emulated gnuish environment for Windows or the +Msys ditto. We've built on the following platforms: Windows 2003 +server, Windows XP Home/Professional, Windows Vista and Windows 7 (32 +and 64 bit). You can probably build on Windows 2000, but you will not +be able to install the latest Microsoft SDK, so you have to go back to +some earlier compiler. Any Windows95'ish platform will surely get you +into trouble, what I'm not sure of, but it certainly will... + +The procedure described uses either Cygwin or Msys as a build +environment, you run the bash shell in Cygwin/Msys and use gnu +make/configure/autoconf etc to do the build. The emulator C-source +code is, however, mostly compiled with Microsoft Visual C++™, +producing a native Windows binary. This is the same procedure as we +use to build the pre-built binaries. The fact that we use VC++ and not +gcc is explained further in the FAQ section. + +I describe the build procedure to make it possible for open source +customers to build the emulator, given that they have the needed +tools. The binary Windows releases is still a preferred alternative if +one does not have Microsoft's development tools and/or don't want to +install Cygwin or Msys. + +To use Cygwin/Msys, one needs basic experience from a Unix environment, if +one does not know how to set environment variables, run programs etc +in a Unix environment, one will be quite lost in the Cygwin os Msys +ditto. I can unfortunately not teach all the world how to use +Cygwin and bash, neither how to install Cygwin nor perform basic tasks +on a computer. Please refer to other documentation on the net for +help, or use the binary release instead if you have problems using the +tools. + +However, if you feel comfortable with the environment and build +system, and have all the necessary tools, you have a great opportunity +to make the Erlang/OTP distribution for Windows better. Please submit +any suggestions and patches to the appropriate [mailing lists] [1] to let +them find their way into the next version of Erlang. If making changes +to the build system (like makefiles etc) please bear in mind that the +same makefiles are used on Unix/VxWorks, so that your changes +don't break other platforms. That of course goes for C-code too, system +specific code resides in the `$ERL_TOP/erts/emulator/sys/win32` and +`$ERL_TOP/erts/etc/win32` directories mostly. The +`$ERL_TOP/erts/emulator/beam` directory is for common code. + +Before the R9C release of Erlang/OTP, the Windows release was built +partly on a Unix (Solaris) box and partly on a Windows box, using Perl +hacks to communicate and sync between the two machines. R9C was the +first release ever built solely on Windows, where no Unix machine is +needed at all. Now we've used this build procedure for a couple of +releases, and it has worked fine for us. Still, there might be all +sorts of troubles on different machines and with different +setups. I'll try to give hints wherever I've encountered difficulties, +but please share your experiences by using the [erlang-questions] [1] +mailing list. I cannot of course help everyone with all +their problems, please try to solve the problems and submit +solutions/workarounds. Remember, it's all about sharing, not about +demanding... + +Starting with R15B, our build system runs both on Cygwin and Msys +(MinGW's fork of an early cygwin version). Msys is a smaller package +to install and may on some machines run slightly faster. If Cygwin +gives you trouble, try Msys instead, and v.v. Beginning with R15B +there is also a native 64bit version of Erlang for 64bit Windows 7 +(only). These instructions apply to both the 32bit VM and the 64bit +ditto. + +Note that even if you build a 64bit VM, most of the directories and +files involved are still named win32. You can view the name win32 as +meaning any windows version not beeing 16bit. A few occurences of the +name Win64 are however present in the system, for example the +installation file for a 64 bit windows version of Erlang is by default +named `otp_win64_.exe`. + +Lets go then, I'll start with a little FAQ, based on in house questions +and misunderstandings. + + +Frequently Asked Questions +-------------------------- + +* Q: So, now I can build Erlang using GCC on Windows? + + A: No, unfortunately not. You'll need Microsoft's Visual C++ + still, a Bourne-shell script (cc.sh) wraps the Visual C++ compiler + and runs it from within the Cygwin environment. All other tools + needed to build Erlang are free-ware/open source, but not the C + compiler. The Windows SDK is however enough to build Erlang, you + do not need to buy Visual C++, just download the SDK (SDK version + 7.1 == Visual studio 2010). + +* Q: Why haven't you got rid of VC++ then, you \*\*\*\*\*\*? + + A: Well, partly because it's a good compiler - really! Actually it's + been possible in late R11-releases to build using mingw instead of + visual C++ (you might see the remnants of that in some scripts and + directories). Unfortunately the development of the SMP version for + Windows broke the mingw build and we chose to focus on the VC++ build + as the performance has been much better in the VC++ versions. The + mingw build will possibly be back, but as long as VC++ gives better + performance, the commercial build will be a VC++ one. + +* Q: OK, you need VC++, but now you've started to demand a very recent + (and expensive) version of Visual studio, not the old and stable VC++ + 6.0 that was used in earlier versions. Why? + + A: Well, it's not expensive, it's free (as in free beer). Just + download and install the latest Windows SDK from Microsoft and all + the tools you need are there. The included debugger (WinDbg) is + also quite usable, it's what I used when porting Erlang to 64bit + Windows. Another reason to use the latest Microsoft compilers is + DLL compatibility. DLL's using a new version of the standard + library might not load if the VM is compiled with an old VC++ + version, why we should aim to use the latest freely available SDK + and compiler. + +* Q: Can/will I build a Cygwin binary with the procedure you describe? + + A: No, the result will be a pure Windows binary, and as far as I know, + it's not possible to make a Cygwin binary yet. That is of course + something desirable, but there are still some problems with the + dynamic linking (dynamic Erlang driver loading) as well as the TCP/IP + emulation in Cygwin, which, I'm sure of, will improve, but still has + some problems. Fixing those problems might be easy or might be hard. + I suggest you try yourself and share your experience. No one would be + happier if a simple `./configure && make` would produce a fully fledged + Cygwin binary. Ericsson does however not pay me to do a Cygwin port, so + such a port would have to happen in spare time, which is a limited + resource... + +* Q: Hah, I saw you, you used GCC even though you said you didn't! + + A: OK, I admit, one of the files is compiled using Cygwin's or + MinGW's GCC and the resulting object code is then converted to MS + VC++ compatible coff using a small C hack. It's because that + particular file, `beam_emu.c` benefits immensely from being able + to use the GCC labels-as-values extension, which boosts emulator + performance by up to 50%. That does unfortunately not (yet) mean + that all of OTP could be compiled using GCC, that particular + source code does not do anything system specific and actually is + adopted to the fact that GCC is used to compile it on Windows. + +* Q: So now there's a MS VC++ project file somewhere and I can build OTP + using the nifty VC++ GUI? + + A: No, never. The hassle of keeping the project files up to date and + do all the steps that constitute an OTP build from within the VC++ GUI + is simply not worth it, maybe even impossible. A VC++ project + file for Erlang/OTP will never happen, at least I will never make + one. Clicking around in super-multi-tab'd dialogs to add a file or + compiler option when it's so much easier in a makefile is simply not + my style. + +* Q: So how does it all work then? + + A: Cygwin or Msys is the environment, which closely resembles the + environments found on any Unix machine. It's almost like you had a + virtual Unix machine inside Windows. Configure, given certain + parameters, then creates makefiles that are used by the + Cygwin/Msys gnu-make to built the system. Most of the actual + compilers etc are not, however, Cygwin/Msys tools, so I've written + a couple of wrappers (Bourne-shell scripts), which reside in + `$ERL_TOP/etc/win32/cygwin_tools` and + `$ERL_TOP/etc/win32/msys_tools`. They all do conversion of + parameters and switches common in the Unix environment to fit the + native Windows tools. Most notable is of course the paths, which + in Cygwin/Msys are Unix-like paths with "forward slashes" (/) and + no drive letters, the Cygwin specific command `cygpath` is used + for most of the path conversions in a Cygwin environment, other + tools are used (when needed) in the corresponding Msys + environment. Luckily most compilers accept forward slashes instead + of backslashes as path separators, but one still have to get the drive + letters etc right, though. The wrapper scripts are not general in + the sense that, for example, cc.sh would understand and translates + every possible gcc option and passes correct options to + cl.exe. The principle is that the scripts are powerful enough to + allow building of Erlang/OTP, no more, no less. They might need + extensions to cope with changes during the development of Erlang, + that's one of the reasons I made them into shell-scripts and not + Perl-scripts, I believe they are easier to understand and change + that way. I might be wrong though, cause another reason I didn't + write them in Perl is because I've never liked Perl and my Perl + code is no pleasant reading... + + In `$ERL_TOP`, there is a script called `otp_build`. That script handles + the hassle of giving all the right parameters to `configure`/`make` and + also helps you set up the correct environment variables to work with + the Erlang source under Cygwin. + +* Q: You use and need Cygwin, but then you haven't taken the time to + port Erlang to the Cygwin environment but instead focus on your + commercial release, is that really ethical? + + A: No, not really, but see this as a step in the right direction. I'm + aiming at GCC compiled emulators and a Cygwin version, but I really + need to do other things as well... In time, but don't hold your + breath... + +* Q: Can I build something that looks exactly as the commercial release? + + A: Yes, we use the exactly same build procedure. + +* Q: Which version of Cygwin/Msys and other tools do you use then? + + A: For Cygwin and Msys alike, we try to use the latest releases + available when building. What versions you use shouldn't really + matter, I try to include workarounds for the bugs I've found in + different Cygwin/Msys releases, please help me add workarounds + for new Cygwin/Msys-related bugs as soon as you encounter + them. Also please do submit bug reports to the appropriate Cygwin + and/or Msys developers. The GCC we used for %OTP-REL% was version + 4.7.0 (MinGW 64bit) and 4.3.4 (Cygwin 32bit). We used VC++ 10.0 + (i.e. Visual studio 2010), Sun's JDK 1.5.0\_17 (32bit) and Sun's + JDK 1.7.0\_1 (64bit), NSIS 2.46, and Win32 OpenSSL 0.9.8r. Please + read the next section for details on what you need. + +* Q: Can you help me setup X in Cygwin? + + A: No, unfortunately I haven't got time to help with Cygwin related + user problems, please read Cygwin related web sites, newsgroups and + mailing lists. + +* Q: Why is the instruction so long? Is it really that complicated? + + A: Partly it's long because I babble too much, partly because I've + described as much as I could about the installation of the needed + tools. Once the tools are installed, building is quite easy. I also + have tried to make this instruction understandable for people with + limited Unix experience. Cygwin/Msys is a whole new environment to some + Windows users, why careful explanation of environment variables etc + seemed to be in place. The short story, for the experienced and + impatient is: + + * Get and install complete Cygwin (latest) or complete MinGW with msys + + * Install Microsofts Windows SDK 7.1 (and .Net 4) + + * Get and install Sun's JDK 1.5.0 or higher + + * Get and install NSIS 2.01 or higher (up to 2.46 tried and working) + + * Get, build and install OpenSSL 0.9.8r or higher (up to 1.0.0a + tried & working) with static libs. + + * Get the Erlang source distribution (from + ) and unpack with Cygwin's `tar`. + + * Set `ERL_TOP` to where you unpacked the source distribution + + * `$ cd $ERL_TOP` + + * Get (from ) + and unpack the prebuilt TCL/TK binaries for windows with cygwin tar, + standing in `$ERL_TOP` + + * Modify PATH and other environment variables so that all these tools + are runnable from a bash shell. Still standing in `$ERL_TOP`, issue + the following commands: + + $ eval `./otp_build env_win32` + $ ./otp_build autoconf + $ ./otp_build configure + $ ./otp_build boot -a + $ ./otp_build release -a + $ ./otp_build installer_win32 + $ release/win32/otp_win32_%OTP-REL% /S + + Voila! `Start->Programs->Erlang OTP %OTP-REL%->Erlang` starts the Erlang + Windows shell. + + +Tools you Need and Their Environment +------------------------------------ + +You need some tools to be able to build Erlang/OTP on Windows. Most +notably you'll need Cygwin or Msys and Microsofts Windows SDK, but +you also might want a Java compiler, the NSIS install system and +OpenSSL. Well' here's the list: + +* Cygwin, the very latest is usually best. Get all the development + tools and of course all the basic ditto. In fact getting the complete + package might be a good idea, as you'll start to love Cygwin after a + while if you're accustomed to Unix. Make sure to get jar and also make + sure *not* to install a Cygwin'ish Java... The Cygwin jar command is + used but Sun's Java compiler and virtual machine... + + If you are going to build a 64bit Windows version, you should make + sure to get MinGW's 64bit gcc installed with cygwin. It's in one of + the development packages. + + URL: + + Get the installer from the web site and use that to install + Cygwin. Be sure to have fair privileges. If you're on a NT domain you + should consider running `mkpasswd -d` and `mkgroup -d` after the + installation to get the user databases correct. See their respective + manual pages. + + When you start you first bash shell, you will get an awful prompt. You + might also have a `PATH` environment variable that contains backslashes + and such. Edit `$HOME/.profile` and `$HOME/.bashrc` to set fair prompts + and set a correct PATH. Also do a `export SHELL` in `.profile`. For some + non-obvious reason the environment variable `$SHELL` is not exported in + bash. Also note that `.profile` is run at login time and `.bashrc` when + sub shells are created. You'll need to explicitly source `.bashrc` from + `.profile` if you want the commands there to be run at login time (like + setting up aliases, shell functions and the like). I personally + usually do like this at the end of `.profile`: + + ENV=$HOME/.bashrc + export ENV + . $ENV + + You might also, if you're a hard core type of person at least, want to + setup X-windows (XFree86), that might be as easy as running startx + from the command prompt and it might be much harder. Use Google to + find help... + + If you don't use X-windows, you might want to setup the Windows + console window by selecting properties in the console system menu + (upper left corner of the window, the Cygwin icon in the title + bar). Especially setting a larger screen buffer size (lines) is useful + as it gets you a scrollbar so you can see whatever error messages + that might appear... + + If you want to use (t)csh instead of bash you're on your own, I + haven't tried and know of no one that has. I expect + that you use bash in all shell examples. + +* Alternatively you download MinGW and Msys. You'll find the latest + installer at: + + URL: + + Make sure to install everything they've got. + + To be able to build the 64bit VM, you will also need the 64bit + MinGW compiler from: + + URL: + + The latest version should do it. Make sure you download the + `mingw-w64-bin_i686-mingw_.zip`, not a linux + version. You unzip the package on top of your MinGW installation + (`c:\MinGW`) and that's it. + + Setting up your environment in Msys is similar to setting it up in + Cygwin. + +* Microsofts Windows SDK version 7.1 (corresponding to VC++ 10.0 and + Visual Studio 2010). You'll find it here: + + URL: + + but before you install that, you need to have .Net 4 installed, + you'll find that here: + + URL: + + Use the web installer for the SDK, at least when I tried + downloading the whole package as an image, I got SDK 7.0 instead, + which is not what you want... + + There will be a Windows command file in `%PROGRAMFILES%\Mirosoft + SDKs\Windows\v7.1\Bin\SetEnv.cmd` that set's the appropriate + environment for a Windows command prompt. This is not appropriate + for bash, so you'll need to convert it to bash-style environments + by editing your `.bash_profile`. In my case, where the SDK is + installed in the default directory and `%PROGRAMFILES%` is + `C:\Program Files`, the commands for setting up a 32bit build + environment (on a 64bit or 32bit machine) look like this (in cygwin): + + # Some common paths + C_DRV=/cygdrive/c + PRG_FLS=$C_DRV/Program\ Files + + # nsis + NSIS_BIN=$PRG_FLS/NSIS + # java + JAVA_BIN=$PRG_FLS/Java/jdk1.6.0_16/bin + + ## + ## MS SDK + ## + + CYGWIN=nowinsymlinks + MVS10="$PRG_FILES/Microsoft Visual Studio 10.0" + WIN_MVS10="C:\\Program Files\\Microsoft Visual Studio 10.0" + SDK10="$PRG_FILES/Microsoft SDKs/Windows/v7.1" + WIN_SDK10="C:\\Program Files\\Microsoft SDKs\\Windows\\v7.1" + + PATH="$NSIS_BIN:\ + $MVS10/Common7/IDE:\ + $MVS10/Common7/Tools:\ + $MVS10/VC/Bin:\ + $MVS10/VC/Bin/VCPackages:\ + $SDK10/Bin/NETFX 4.0 Tools:\ + $SDK10/Bin:\ + /usr/local/bin:/usr/bin:/bin:\ + /cygdrive/c/WINDOWS/system32:/cygdrive/c/WINDOWS:\ + /cygdrive/c/WINDOWS/system32/Wbem:\ + $JAVA_BIN" + + LIBPATH="$WIN_MVS10\\VC\\LIB" + + LIB="$WIN_MVS10\\VC\\LIB;$WIN_SDK10\\LIB" + + INCLUDE="$WIN_MVS10\\VC\\INCLUDE;$WIN_SDK10\\INCLUDE;$WIN_SDK10\\INCLUDE\\gl" + + export CYGWIN PATH LIBPATH LIB INCLUDE + + If you're using Msys instead, the only thing you need to change is + the `C_DRV` setting, which would read: + + C_DRV=/c + + And of course you might need to change `C:\Program Files` etc if + you're using a non-english version of Windows (XP). Note that in + later versions of Windows, the national adoptions of the program + files directories etc are not on the file system but only in the + explorer, so even if explorer says that your programs reside in + e.g. `C:\Program`, they might still reside in `C:\Program Files` + in reality... + + If you are building a 64 bit version of Erlang, you should set up + PATHs etc a little differently. I use the following script to + make things work in both Cygwin and Msys: + + make_winpath() + { + P=$1 + if [ "$IN_CYGWIN" = "true" ]; then + cygpath -d "$P" + else + (cd "$P" && /bin/cmd //C "for %i in (".") do @echo %~fsi") + fi + } + + make_upath() + { + P=$1 + if [ "$IN_CYGWIN" = "true" ]; then + cygpath "$P" + else + echo "$P" | /bin/sed 's,^\([a-zA-Z]\):\\,/\L\1/,;s,\\,/,g' + fi + } + + # Some common paths + if [ -x /usr/bin/msysinfo ]; then + # Without this the path conversion won't work + COMSPEC='C:\Windows\SysWOW64\cmd.exe' + MSYSTEM=MINGW32 + export MSYSTEM COMSPEC + IN_CYGWIN=false + else + CYGWIN=nowinsymlinks + export CYGWIN + IN_CYGWIN=true + fi + + if [ "$IN_CYGWIN" = "true" ]; then + PATH=/usr/local/bin:/usr/bin:/bin:/usr/X11R6/bin:\ + /cygdrive/c/windows/system32:/cygdrive/c/windows:/cygdrive/c/windows/system32/Wbem + else + PATH=/usr/local/bin:/mingw/bin:/bin:/c/Windows/system32:/c/Windows:\ + /c/Windows/System32/Wbem + fi + + if [ "$IN_CYGWIN" = "true" ]; then + C_DRV=/cygdrive/c + else + C_DRV=/c + fi + + PRG_FLS64=$C_DRV/Program\ Files + PRG_FLS32=$C_DRV/Program\ Files\ \(x86\) + VISUAL_STUDIO_ROOT32=$PRG_FLS32/Microsoft\ Visual\ Studio\ 10.0 + MS_SDK_ROOT64=$PRG_FLS64/Microsoft\ SDKs/Windows/v7.1 + + # Okay, now mangle the paths and get rid of spaces by using short names + WIN_VCROOT32=`make_winpath "$VISUAL_STUDIO_ROOT32"` + VCROOT32=`make_upath $WIN_VCROOT32` + WIN_SDKROOT64=`make_winpath "$MS_SDK_ROOT64"` + SDKROOT64=`make_upath $WIN_SDKROOT64` + WIN_PROGRAMFILES32=`make_winpath "$PRG_FLS32"` + PROGRAMFILES32=`make_upath $WIN_PROGRAMFILES32` + + WIN_PROGRAMFILES64=`make_winpath "$PRG_FLS64"` + PROGRAMFILES64=`make_upath $WIN_PROGRAMFILES64` + + # nsis + NSIS_BIN=$PROGRAMFILES32/NSIS + # java + JAVA_BIN=$PROGRAMFILES64/Java/jdk1.7.0_01/bin + + ## The PATH variable should be Unix'ish + VCPATH=$VCROOT32/Common7/IDE:$VCROOT32/VC/BIN/amd64:$VCROOT32/Common7/Tools:\ + $VCROOT32/VC/VCPackages:$SDKROOT64/bin/NETFX4~1.0TO/x64:$SDKROOT64/bin/x64:\ + $SDKROOT64/bin + + ## Microsoft SDK libs + + LIBPATH=$WIN_VCROOT32\\VC\\LIB\\amd64 + LIB=$WIN_VCROOT32\\VC\\LIB\\amd64\;$WIN_SDKROOT64\\LIB\\X64 + INCLUDE=$WIN_VCROOT32\\VC\\INCLUDE\;$WIN_SDKROOT64\\include\;\ + $WIN_SDKROOT64\\include\\gl + + # Put nsis, c compiler and java in path + PATH=$NSIS_BIN:$VCPATH:$PATH:$JAVA_BIN + + # Make sure LIB and INCLUDE is available for others + export PATH LIBPATH LIB INCLUDE + + All this is derived from the SetEnv.cmd command file mentioned + earlier. The bottom line is to set the PATH so that NSIS and + Microsoft SDK is found before the Msys/Cygwin tools and that Java + is last in the PATH. + + Make a simple hello world (maybe one that prints out + `sizeof(void *)`) and try to compile it with the `cl` command from within + bash. If that does not work, your environment needs fixing. Also + remember to fix up the PATH environment, especially old Erlang + installations might have inserted quoted paths that Cygwin/Msys + does not understand. Remove or correct such paths. There should be + no backslashes in your path environment variable in Cygwin bash, + but LIB and INCLUDE should contain Windows style paths with + semicolon, drive letters and backslashes. + +* Sun's Java JDK 1.5.0 or higher. Our Java code (jinterface, ic) is + written for JDK 1.5.0. Get it for Windows and install it, the JRE is + not enough. If you don't care about Java, you can skip this step, the + result will be that jinterface is not built. + + URL: + + Add javac *LAST* to your path environment in bash, in my case this means: + + `PATH="$PATH:/cygdrive/c/Program Files/Java/jdk1.5.0_17/bin"` + + No `CLASSPATH` or anything is needed. Type `javac` at the bash prompt + and you should get a list of available Java options. Make sure by + typing `type java` that you use the Java you installed. Note however that + Cygwin's `jar.exe` is used, that's why the JDK bin-directory should be + added last in the `PATH`. + +* Nullsoft NSIS installer system. You need this to build the self + installing package. It's a free open source installer that's much + nicer to use than the commercial Wise and Install shield + installers. This is the installer we use for commercial releases as + well from R9C an on. + + URL: + + Install the lot, especially the modern user interface components, as + it's definitely needed. Put `makensis` in your path, in my case: + + PATH=/cygdrive/c/Program\ Files/NSIS:$PATH + + type makensis at the bash prompt and you should get a list of options + if everything is OK. + +* OpenSSL. This is if you want the SSL and crypto applications to + compile (and run). There are prebuilt binaries available, but I + strongly recommend building this yourself. It's quite easy. + + First get the source from + + URL: + + I would recommend using 0.9.8r. + + Download the tar file and unpack it (using your bash prompt) into + a directory of your choise. + + You will need a Windowish Perl for the build. ActiveState has one: + + URL: + + Download and install that. Disable options to associate it with + the .pl suffix and/or adding things to PATH, they are not needed. + + Now fire up the Microsoft Windows SDK command prompt in RELEASE + mode for the architecture you are going to build. The easiest is + to copy the shortcut from the SDKs start menu item and edit the + command line in the shortcut (Right click->Properties) to end with + `/Release`. Make sure the banner when you double click your + shortcut (the text in the resulting command window) says + `Targeting Windows XP x64 Release` if you are going to do a 64 bit + build and `Targeting Windows XP x86 Release` if you are building a + 32 bit version. + + Now cd to where you unpacked the OpenSSL source using your Release + Windows command prompt (it should be on the same drive as where + you are going to install it if everything is to work smothly). + + C:\> cd + + Add ActiveState (or some other windows perl, not cygwins) to your PATH: + + C:\...\> set PATH=C:\Perl\bin;%PATH% + + Or if you installed the 64bit perl: + + C:\...\> set PATH=C:\Perl64\bin;%PATH% + + Configure OpenSSL for 32 bit: + + C:\...\> perl Configure VC-WIN32 --prefix=/OpenSSL + + Or for 64 bit: + + C:\...\> perl Configure VC-WIN64A --prefix=/OpenSSL-Win64 + + Do some setup (for 32 bit): + + C:\...\> ms\do_ms + + The same for 64 bit: + + C:\...\> ms\do_win64a + + Then build static libraries and install: + + C:\...\> nmake -f ms\nt.mak + C:\...\> nmake -f ms\nt.mak install + + That's it - you now have your perfectly consistent static build of + openssl. If you want to get rid of any possibly patented + algorithms in the lib, just read up on the OpenSSL FAQ and follow + the instructions. + + The installation locations chosen are where configure will look + for OpenSSL, so try to keep them as is. + +* Building with wxWidgets. Download wxWidgets-2.8.9 or higher patch + release (2.9.\* is a developer release which currently does not work + with wxErlang). + + Install or unpack it to `DRIVE:/PATH/cygwin/opt/local/pgm`. + + edit: `C:\cygwin\opt\local\pgm\wxMSW-2.8.11\include\wx\msw\setup.h` + enable `wxUSE_GLCANVAS`, `wxUSE_POSTSCRIPT` and `wxUSE_GRAPHICS_CONTEXT` + + build: From a command prompt with the VC tools available (See the + instructions for OpenSSL build above for help on starting the + proper command prompt in RELEASE mode): + + C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\build\msw + C:\...\> nmake BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc + C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\contrib\build\stc + C:\...\> nmake BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc + + Or - if building a 64bit version: + + C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\build\msw + C:\...\> nmake TARGET_CPU=amd64 BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc + C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\contrib\build\stc + C:\...\> nmake TARGET_CPU=amd64 BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc + +* The Erlang source distribution (from ). + The same as for Unix platforms. Preferably use tar from within Cygwin to + unpack the source tar.gz (`tar zxf otp_src_%OTP-REL%.tar.gz`). + + set the environment `ERL_TOP` to point to the root directory of the + source distribution. Let's say I stood in `$HOME/src` and unpacked + `otp_src_%OTP-REL%.tar.gz`, I then add the following to `.profile`: + + ERL_TOP=$HOME/src/otp_src_%OTP-REL% + export $ERL_TOP + +* The TCL/TK binaries. You could compile Tcl/Tk for windows yourself, + but you can get a stripped down version from our website which is + suitable to include in the final binary package. If you want to supply + tcl/tk yourself, read the instructions about how the tcl/tk tar file + used in the build is constructed under `$ERL_TOP/lib/gs/tcl`. The easy + way is to download + and unpack it standing in the `$ERL_TOP` directory. This will create the + file `win32.tar.gz` in `$ERL_TOP/lib/gs/tcl/binaries`. + + One last alternative is to create a file named `SKIP` in the + `$ERL_TOP/lib/gs/` after configure is run, but that will give you an + erlang system without gs (which might be okay as you probably will use + wx anyway). + + Note that there is no special 64bit version of TCL/TK needed, you + can use the 32bit program even for a 64bit build. + +The Shell Environment +--------------------- + +So, if you have followed the instructions above, when you start a bash +shell, you should have an INCLUDE environment with a Windows style +path, a LIB environment variable also in Windows style, and finally a +PATH that let's you reach cl, makensis, javac etc from the +command prompt (use `which cl` etc to verify from bash). + +You should also have an `ERL_TOP` environment variable that is *Cygwin +style*, and points to a directory containing, among other files, the +script `otp_build`. + +A final massage of the environment is needed, and that is done by +the script `$ERL_TOP/otp_build`. Start bash and do the following, note +the "back-ticks" (\`), can be quite hard to get on some keyboards, but +pressing the back-tick key followed by the space bar might do it... + + $ cd $ERL_TOP + $ eval `./otp_build env_win32` + +If you're unable to produce back-ticks on your keyboard, you can use +the ksh variant: + + $ cd $ERL_TOP + $ eval $(./otp_build env_win32) + +If you are building a 64 bit version, you supply `otp_build` with an architecture parameter: + + $ cd $ERL_TOP + $ eval `./otp_build env_win32 x64` + + +This should do the final touch to the environment and building should +be easy after this. You could run `./otp_build env_win32` without +`eval` just to see what it does, and to see that the environment it +sets seems OK. The path is cleaned of spaces if possible (using DOS +style short names instead), the variables `OVERRIDE_TARGET`, `CC`, `CXX`, +`AR` and `RANLIB` are set to their respective wrappers and the directories +`$ERL_TOP/erts/etc/win32/cygwin_tools/vc` and +`$ERL_TOP/erts/etc/win32/cygwin_tool` are added first in the PATH. + +Try now a `type erlc`. That should result in the erlc wrapper script +(which does not have the .sh extension, for reasons best kept +untold...). It should reside in `$ERL_TOP/erts/etc/win32/cygwin_tools` +or `$ERL_TOP/erts/etc/win32/msys_tools`. You could also try `which +cc.sh`, which `ar.sh` etc. + +Now you're ready to build... + + +Building and Installing +----------------------- + +Now it's assumed that you have executed `` eval `./otp_build env_win32` `` or +`` eval `./otp_build env_win32 x64` `` for this particular shell... + +Building is easiest using the `otp_build` script. That script takes care +of running configure, bootstrapping etc on Windows in a simple +way. The `otp_build` script is the utility we use ourselves to build on +different platforms and it therefore contains code for all sorts of +platforms. The principle is, however, that for non-Unix platforms, one +uses `./otp_build env_` to set up environment and then the +script knows how to build on the platform "by itself". You've already +run `./otp_build env_win32` in the step above, so now it's mostly like +we build on any platform. OK, here are then steps; Assuming you will +want to build a full installation executable with NSIS, you can omit +`` and the release will be copied to +`$ERL_TOP/release/win32`: and there is where the packed self installing +executable will reside too. + + $ ./otp_build autoconf # Ignore the warning blob about versions of autoconf + $ ./otp_build configure + $ ./otp_build boot -a + $ ./otp_build release -a + $ ./otp_build installer_win32 # optional + +Now you will have a file called `otp_win32_R12B.exe` in the +``, i.e. `$ERL_TOP/release/win32`. + +Lets get into more detail: + +1. `$ ./otp_build autoconf` - This step rebuilds the configure scripts + to work correctly in the cygwin environment. In an ideal world, this + would not be needed, but alas, we have encountered several + incompatibilities between our distributed configure scripts (generated + on a Linux platform) and the cygwin environment over the + years. Running autoconf on cygwin ensures that the configure scripts + are generated in a cygwin-compatible way and that they will work well + in the next step. + +2. `$ ./otp_build configure` - This runs the newly generated configure + scripts with options making configure behave nicely. The target machine + type is plainly `win32`, so a lot of the configure-scripts recognize + this awkward target name and behave accordingly. The CC variable also + makes the compiler be `cc.sh`, which wraps MSVC++, so all configure + tests regarding the C compiler gets to run the right compiler. A lot of + the tests are not needed on Windows, but I thought it best to run the + whole configure anyway. The only configure option you might want to + supply is `--with-ssl`, which might be needed if you have built your + own OpenSSL distribution. The Shining Lights distribution should be + found automatically by `configure`, if that fails, add a + `--with-ssl=` that specifies the root directory of your OpenSSL + installation. + +3. `$ ./otp_build boot -a` - This uses the bootstrap directory (shipped + with the source, `$ERL_TOP/bootstrap`) to build a complete OTP + system. It first builds an emulator and sets up a minimal OTP system + under `$ERL_TOP/bootstrap`, then starts to compile the different OTP + compilers to make the `$ERL_TOP/bootstrap` system potent enough to be + able to compile all Erlang code in OTP. Then, all Erlang and C code + under `$ERL_TOP/lib` is built using the bootstrap system, giving a + complete OTP system (although not installed). When this is done, one + can run Erlang from within the source tree, just type `$ERL_TOP/bin/erl` + and you should have a prompt. If you omit the -a flag, you'll get a + smaller system, that might be useful during development. Now + exit from Erlang and start making a release of the thing: + +4. `$ ./otp_build release -a` - Builds a commercial release tree from the + source tree, default is to put it in `$ERL_TOP/release/win32`, you can + give any directory as parameter (Cygwin style), but it doesn't really + matter if you're going to build a self extracting installer too. You + could of course build release to the final directory and then run + `./Install.exe` standing in the directory where the release was put, + that will create a fully functional OTP installation. But let's make + the nifty installer: + +5. `$ ./otp_build installer_win32` - Create the self extracting installer + executable. The executable `otp_win32_%OTP-REL%.exe` will be placed + in the top directory of the release created in the previous step. If + no release directory is specified, the release is expected to have + been built to `$ERL_TOP/release/win32`, which also will be the place + where the installer executable will be placed. If you specified some + other directory for the release (i.e. `./otp_build release -a + /tmp/erl_release`), you're expected to give the same parameter here, + (i.e. `./otp_build installer_win32 /tmp/erl_release`). You need to have + a full NSIS installation and `makensis.exe` in your path for this to + work of course. Once you have created the installer, you can run it to + install Erlang/OTP in the regular way, just run the executable and + follow the steps in the installation wizard. To get all default settings + in the installation without any questions asked, you run the executable + with the parameter `/S` (capital S) like in: + + $ cd $ERL_TOP + $ release/win32/otp_win32_%OTP-REL% /S + ... + + or + + $ cd $ERL_TOP + $ release/win32/otp_win64_%OTP-REL% /S + ... + + + and after a while Erlang/OTP-%OTP-REL% will have been installed in + `C:\Program Files\erl%ERTS-VSN%\`, with shortcuts in the menu etc. + + The necessary setup of an Erlang installation is actually done by the + program `Install.exe`, which resides in the release top. That program + creates `.ini`-files and copies the correct boot scripts. If one has + the correct directory tree (like after a `./otp_build release -a`), only + the running of `Install.exe` is necessary to get a fully functional + OTP. What the self extracting installer adds is (of course) the + possibility to distribute the binary easily, together with adding + shortcuts to the Windows start menu. There is also some adding of + entries in the registry, to associate `.erl` and `.beam` files with + Erlang and get nifty icons, but that's not something you'll really need + to run Erlang. The registry is also used to store uninstall information, + but if one has not used the self extracting installer, one cannot + (need not) do any uninstall, one just scratches the release directory + and everything is gone. Erlang/OTP does not *need* to put anything + in the Windows registry at all, and does not if you don't use the self + extracting installer. In other words the installer is pure cosmetics. + +> *NOTE*: Beginning with R9C, the Windows installer does *not* add Erlang +> to the system wide path. If one wants to have Erlang in the path, one +> has to add it by hand. + +Development +----------- + +Once the system is built, you might want to change it. Having a test +release in some nice directory might be useful, but you also can run +Erlang from within the source tree. The target `local_setup`, makes +the program `$ERL_TOP/bin/erl.exe` usable and it also uses all the OTP +libraries in the source tree. + +If you hack the emulator, you can then build the emulator executable +by standing in `$ERL_TOP/erts/emulator` and do a simple + + $ make opt + +Note that you need to have run ``(cd $ERL_TOP && eval `./otp_build env_win32`)`` +in the particular shell before building anything on Windows. After +doing a make opt you can test your result by running `$ERL_TOP/bin/erl`. +If you want to copy the result to a release directory (say +`/tmp/erl_release`), you do this (still in `$ERL_TOP/erts/emulator`) + + $ make TESTROOT=/tmp/erl_release release + +That will copy the emulator executables. + +To make a debug build of the emulator, you need to recompile both +`beam.dll` (the actual runtime system) and `erlexec.dll`. Do like this + + $ cd $ERL_TOP + $ rm bin/win32/erlexec.dll + $ cd erts/emulator + $ make debug + $ cd ../etc + $ make debug + +and sometimes + + $ cd $ERL_TOP + $ make local_setup + +So now when you run `$ERL_TOP/erl.exe`, you should have a debug compiled +emulator, which you will see if you do a: + + 1> erlang:system_info(system_version). + +in the erlang shell. If the returned string contains `[debug]`, you +got a debug compiled emulator. + +To hack the erlang libraries, you simply do a `make opt` in the +specific "applications" directory, like: + + $ cd $ERL_TOP/lib/stdlib + $ make opt + +or even in the source directory... + + $ cd $ERL_TOP/lib/stdlib/src + $ make opt + +Note that you're expected o have a fresh Erlang in your path when +doing this, preferably the plain %OTP-REL% you have built in the previous +steps. You could also add `$ERL_TOP/bootstrap/bin` to your `PATH` before +rebuilding specific libraries, that would give you a good enough +Erlang system to compile any OTP erlang code. Setting up the path +correctly is a little bit tricky, you still need to have +`$ERL_TOP/erts/etc/win32/cygwin_tools/vc` and +`$ERL_TOP/erts/etc/win32/cygwin_tools` *before* the actual emulator +in the path. A typical setting of the path for using the bootstrap +compiler would be: + + $ export PATH=$ERL_TOP/erts/etc/win32/cygwin_tools/vc\ + :$ERL_TOP/erts/etc/win32/cygwin_tools:$ERL_TOP/bootstrap/bin:$PATH + +That should make it possible to rebuild any library without hassle... + +If you want to copy a library (an application) newly built, to a +release area, you do like with the emulator: + + $ cd $ERL_TOP/lib/stdlib + $ make TESTROOT=/tmp/erlang_release release + +Remember that: + +* Windows specific C-code goes in the `$ERL_TOP/erts/emulator/sys/win32`, + `$ERL_TOP/erts/emulator/drivers/win32` or `$ERL_TOP/erts/etc/win32`. + +* Windows specific erlang code should be used conditionally and the + host OS tested in *runtime*, the exactly same beam files should be + distributed for every platform! So write code like: + + case os:type() of + {win32,_} -> + do_windows_specific(); + Other -> + do_fallback_or_exit() + end, + +That's basically all you need to get going. + +Using GIT +--------- + +You might want to check out versions of the source code from GitHUB. That is possible directly in cygwin, but not in Msys. There is a project MsysGIT: + +URL: + +that makes a nice Git port. The msys prompt you get from MsysGIT is +however not compatible with the full version from MinGW, so you will +need to check out files using MsysGIT's command prompt and then switch +to a common Msys command prompt for building. Also all test suites +cannot be built as MsysGIT/Msys does not handle symbolic links. To +build test suites on Windows, you will need Cygwin for now. Hopefully +all symbolic links will disappear from our repository soon and this +issue will disappear. + +Final Words +----------- +My hope is that the possibility to build the whole system on Windows +will open up for free development on this platform too. There are many +things one might want to do better in the Windows version, like the +window-style command prompt as well as pure Cygwin porting. Although i +realize it's a much larger step to start building on Windows (with all +the software you need) than for instance on Linux, I sincerely hope +that some of you will make the effort and start submitting Windows +friendly patches. + +The first build system for Erlang using Cygwin on Windows was created +by Per Bergkvist. I haven't used his build system, but it's rumored to +be good. The idea to do this came from his work, so credit is well +deserved. + +Of course this would have been completely impossible without the +excellent Cygwin. The guys at Cygnus solutions and +Redhat deserve a huge THANKS! as well as all the other people in the +free software community who have helped in creating the magnificent +software that constitutes Cygwin. + +Also the people developing the alternative command prompt Msys and +the MinGW compiler are worth huge THANKS! The 64bit port would have +been impossible without the 64bit MinGW compiler. + +Good luck and Happy Hacking, +Patrik, OTP + +Copyright and License +--------------------- + +%CopyrightBegin% + +Copyright Ericsson AB 2003-2012. 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% + +Modifying This Document +----------------------- + +Before modifying this document you need to have a look at the +[$ERL_TOP/HOWTO/MARKDOWN.md][] document. + + + + [1]: http://www.erlang.org/faq.html "mailing lists" + [$ERL_TOP/HOWTO/MARKDOWN.md]: MARKDOWN.md + + [?TOC]: true diff --git a/HOWTO/INSTALL.md b/HOWTO/INSTALL.md new file mode 100644 index 0000000000..3efa48469e --- /dev/null +++ b/HOWTO/INSTALL.md @@ -0,0 +1,839 @@ +Building and Installing Erlang/OTP +================================== + +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: + + + +The source code for Erlang/OTP can also be found in a Git repository: + + + +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/HOWTO/INSTALL-CROSS.md][] + document. + +* build Erlang/OTP on Windows, see the [$ERL_TOP/HOWTO/INSTALL-WIN32.md][] + document. + + Binary releases for Windows can be found at + . + +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 +-------------------- +At Ericsson we have a "Daily Build and Test" that runs on: + +* Solaris 8, 9 + * Sparc32 + * Sparc64 +* Solaris 10 + * Sparc32 + * Sparc64 + * x86 +* SuSE Linux/GNU 9.4, 10.1 + * x86 +* SuSE Linux/GNU 10.0, 10.1, 11.0 + * x86 + * x86\_64 +* openSuSE 11.4 (Celadon) + * x86\_64 (valgrind) +* Fedora 7 + * PowerPC +* Fedora 14 + * x86\_64 +* Gentoo Linux/GNU 1.12.11.1 + * x86 +* Ubuntu Linux/GNU 7.04, 10.04, 10.10, 11.0 + * x86\_64 +* MontaVista Linux/GNU 4.0.1 + * PowerPC +* FreeBSD 8.2 + * x86 +* OpenBSD 5.0 + * x86\_64 +* Mac OS X 10.5.8 (Leopard), 10.6.0 (Snow Leopard), 10.7.3 (Lion) + * x86 +* Windows XP SP3, 2003, Vista, 7 + * x86 +* Windows 7 + * x86\_64 + +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 + +and the following "Daily Cross Build Tests": + +* SuSE Linux/GNU 10.1 x86\_64 + +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: + + * + * + +* `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 is not 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: + + * + * + +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). + +### Building ### + +* GNU `make` +* `gcc` -- GNU C compiler +* Perl 5 +* 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 + binary command program `openssl` is also needed. At least version 0.9.8 + of OpenSSL is required. Can be downloaded from . +* Sun Java jdk-1.5.0 or higher -- Optional but needed for building the + Erlang/OTP application `jinterface` and parts of `ic` and `orber`. Can + be downloaded from . 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. + +#### Building Documentation #### + +* `xsltproc` -- XSLT processor. A tool for applying XSLT stylesheets + to XML documents. Can be downloaded from + . +* `fop` -- Apache FOP print formatter (requires Java). Can be downloaded + from . + +#### 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 ### + +* An `install` program that can take multiple file names. + +How to Build and Install Erlang/OTP +----------------------------------- + +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][] +section below before proceeding. + +### Unpacking ### + +Step 1: Start by unpacking the Erlang/OTP distribution file with your GNU +compatible TAR program. + + $ 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_%OTP-REL% + +### Configuring ### + +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}`. +To instead install in `/{bin,lib/erlang}`, 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. Before doing a `make clean`, +be sure to read the [Pre-built Source Release][] section below. + +### Building ### + +Step 5: Build the Erlang/OTP package. + + $ make + +### Installing ### + +Step 6: Install then Erlang/OTP package + + $ make install + +### A Closer Look at the individual Steps ### + +Let us go through them in some detail. + +#### Configuring #### + +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` 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, `` say, +use the `--prefix` argument like this: `./configure --prefix=`. + +Some of the available `configure` options are: + +* `--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 + possible) +* `--{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 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) +* `--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 + . + +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: + + $ 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 #### + +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 + $ 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 + +* Install using the `release` target. Instead of doing `make install` you + can create 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 (the top directory): + + $ ./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, and is what `make install` uses. + * `-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. + +* Test install using `EXTRA_PREFIX`. The content of the `EXTRA_PREFIX` + variable will prefix all installation paths when doing `make install`. + Note that `EXTRA_PREFIX` is similar to `DESTDIR`, but it does *not* have + the same effect as `DESTDIR`. The installation can and have to be run + from the location specified by `EXTRA_PREFIX`. 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`. + +### 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 +Erlang/OTP executables in `/usr/local/lib/erlang/bin`. 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 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. + +### 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, because you need to generate the +`configure` scripts before you can start building. + +The `configure` scripts are generated by invoking `./otp_build autoconf` in +the `$ERL_TOP` directory. The `configure` scripts also have to be regenerated +when a `configure.in` or `aclocal.m4` file has been modified. Note that when +checking out a branch a `configure.in` or `aclocal.m4` file may change +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*: 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: + + +### 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 +`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. + +The Erlang/OTP Documentation +---------------------------- + +### How to Build the Documentation ### + + $ cd $ERL_TOP + +If you have just built Erlang/OTP in the current source tree, you have +already ran `configure` and do not need to do this again; otherwise, run +`configure`. + + $ ./configure [Configure Args] + +When building the documentation you need a full Erlang/OTP-%OTP-REL% system in +the `$PATH`. + + $ export PATH=:$PATH # Assuming bash/sh + +Build the documentation. + + $ make docs + +The documentation can be installed either using the `install-docs` target, +or using the `release_docs` target. + +* If you have installed Erlang/OTP using the `install` target, install + the documentation using the `install-docs` target. Install locations + determined by `configure` will be used. `$DESTDIR` can be used the + same way as when doing `make install`. + + $ make install-docs + +* 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`. + + $ make release_docs RELEASE_ROOT= + +#### Build Issues #### + +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. + + $ export FOP_OPTS="-Xmxm" + +More information can be found at +. + +### How to Install the Pre-formatted Documentation ### + +Pre-formatted [html documentation][] and [man pages][] can be downloaded at +. + +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 + $ gunzip -c otp_html_%OTP-REL%.tar.gz | tar xf - + +For `erl -man ` to work the Unix manual pages have to be +installed in the same way, i.e. + + $ cd + $ gunzip -c otp_man_%OTP-REL%.tar.gz | tar xf - + +Where `` is + +* `/lib/erlang` if you have installed Erlang/OTP using + `make install`. +* `$DESTDIR/lib/erlang` if you have installed Erlang/OTP + using `make install DESTDIR=`. +* `RELEASE_ROOT` if you have installed using + `make release RELEASE_ROOT=`. + +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 does not +automatically enable SMP support, the build is very likely to fail. + +Use `./configure --disable-smp-support` if you for some reason do not +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`. + +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 is supported. 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. + + * Linux (Aurora) is supported. + +* 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) +----------------- + +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. + +Use the `--enable-darwin-64bit` configure flag to build a 64-bit +binaries on Mac OS X. + +Building universal binaries on Mac OS X (obsolete information) +-------------------------------------------------------------- + +(This information was written when Mac OS X Leopard was the current +release. It may no longer work.) + +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. + +Building a fast Erlang VM on Mac OS Lion +---------------------------------------- + +Starting with Xcode 4.2, Apple no longer includes a "real" `gcc` +compiler (not based on the LLVM). Building with `llvm-gcc` or `clang` +will work, but the performance of the Erlang run-time system will not +be the best possible. + +Note that if you have `gcc-4.2` installed and included in `PATH` +(from a previous version of Xcode), `configure` will automatically +make sure that `gcc-4.2` will be used to compile `beam_emu.c` +(the source file most in need of `gcc`). + +If you don't have `gcc-4.2.` and want to build a run-time system with +the best possible performance, do like this: + +Install Xcode from the AppStore if it is not already installed. + +For Xcode 4.3 you will also need to download "Command Line Tools" +via the Downloads preference pane i Xcode. + +Some tools may still be lacking or out-of-date, we recommend using +[Homebrew](https://github.com/mxcl/homebrew/wiki/installation) or +Macports update those tools. + +Install MacPorts (). Then: + + $ sudo port selfupdate + $ sudo port install gcc45 +universal + +If you want to build the `wx` application, get wxMac-2.8.12 +(`wxMac-2.8.12.tar.gz` from +) and build: + +Export the path for MacOSX10.6.sdk, + + $ export SDK=/Developer/SDKs/MacOSX10.6.sdk + +In Xcode 4.3 the path has changed so use the following instead, + + $ export SDK=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.6.sdk + +Then configure and build wx, + + $ arch_flags="-arch i386" ./configure CFLAGS="$arch_flags" CXXFLAGS="$arch_flags" CPPFLAGS="$arch_flags" LDFLAGS="$arch_flags" OBJCFLAGS="$arch_flags" OBJCXXFLAGS="$arch_flags" --prefix=/usr/local --with-macosx-sdk="$SDK" --with-macosx-version-min=10.6 --enable-unicode --with-opengl --disable-shared + $ make + $ sudo make install + +To link wx properly we will also need to build and install `wxStyledTextCtrl` + + $ cd contrib/src/stc + $ make + $ sudo make install + +Build Erlang with the MacPorts GCC as the main compiler (using `clang` +for the Objective-C Cocoa code in the `wx` application): + + $ PATH=/usr/local/bin:$PATH CC=/opt/local/bin/gcc-mp-4.5 CXX=/opt/local/bin/g++-mp-4.5 ./configure --enable-m32-build make + $ sudo make install + + +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`, or `lcnt`. +These different beam types are useful for debugging and profiling +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. + +Copyright and License +--------------------- + +%CopyrightBegin% + +Copyright Ericsson AB 1998-2012. 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 . + +Modifying This Document +----------------------- + +Before modifying this document you need to have a look at the +[$ERL_TOP/HOWTO/MARKDOWN.md][] document. + + + + [$ERL_TOP/HOWTO/INSTALL-CROSS.md]: INSTALL-CROSS.md + [$ERL_TOP/HOWTO/INSTALL-WIN32.md]: INSTALL-WIN32.md + [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 + [$ERL_TOP/HOWTO/MARKDOWN.md]: MARKDOWN.md + + [?TOC]: true diff --git a/HOWTO/MARKDOWN.md b/HOWTO/MARKDOWN.md new file mode 100644 index 0000000000..42045fb10c --- /dev/null +++ b/HOWTO/MARKDOWN.md @@ -0,0 +1,266 @@ +Erlangish Markdown Text Files +============================= + +Introduction +------------ + +If you are looking for information on how to build and install Erlang/OTP you +want to read the [$ERL_TOP/HOWTO/INSTALL.md][] document instead of this document +(where `$ERL_TOP` is the top source directory in the source tree). + +All files with the `.md` suffix (as well as this file) are ordinary text files +written using a Markdown like notation, and can be read using an ordinary text +editor such as for example `emacs`. + +This document describes how `*.md` files in the Erlang/OTP source tree should +be written. + +> *NOTE*: Before modifying a `*.md` file read all of this document. + +Erlangish Markdown +------------------ + +We do not use Markdown straight out of the box. The Markdown syntax we use is +similar to the original Markdown but with a number of tweaks. The original +Markdown is documented at . You +should read that documentation as well as this document before modifying any +Erlangish Markdown files in the Erlang/OTP source tree. + +The original Markdown syntax was designed for generating HTML code from an +"easy to read/easy to write" plain text. Instead of generating HTML we generate +XML that fits into our documentation, i.e. we generate Erlangish XML from +Erlangish Markdown. + +The `.md` suffix has been chosen since [github][] will generate HTML pages for +files with the `.md` suffix. Github does however not generate HTML according to +Erlangish Markdown, so some features do not work. The Erlangish Markdown +documents viewed at [our github repository][] will typically suffer from broken +links. The original Markdown script, gitub's Markdown, and our Erlangish +Markdown script will generate somewhat different results if you do not follow +indentation rules outlined in the Markdown documentation. You are encouraged to +try to write using a Markdown syntax that also looks nice on github. However, +it is *much* more important that the document is formatted correct in the +Erlang/OTP documentation. + +### Differences Between Markdown and Erlangish Markdown ### + +#### Missing Features #### + +This functionality is missing compared to Markdown version 1.0.1. Do not +depend on the fact that these features are missing. Some of them might appear +in the future. + +* No inline HTML. Currently no inline XML is allowed either. Inline XML might + be allowed in the future, but there is no real need for it since we use + Erlangish Markdown for "readme"s that have a main purpose of being readable + in plain text. + +* Backslash escapes all characters. + +* No support for "horizontal rules". + +* Links. + * No support for the "title" attribute. + * Automatic links does not support email addresses. + +* Images. + * No support for the "title" attribute. Specified "title" will however + be used as ``. + * No support for the "alt" attribute. + +* Lists aren't supported inside block quotes. + +* Link and image definition names *are* case sensitive. + +#### Additional Features #### + +* Automatic anchors at each heading. + +* Optionally automatically generated table of contents. + +* Note blocks. + +* Warning blocks. + +#### Extra requirements #### + +* One and only one level 1 heading is allowed and required. + +* The level 1 heading must be the first heading in the document. + +* A level `X` heading must have a level `X-1` heading as parent heading. + +* Link and image definition names aren't allowed to begin with a + question mark (?) character. Names beginning with a question mark have + been reserved for other use. + +* The encoding of the file containing Erlangish Markdown should be + UTF-8. + +### Generated XML ### + +> *WARNING*: The `emd2exml` script will blindly generate XML code according +> to the Erlangish Markdown in a file. Successfully generated XML does **not** +> imply that the generated XML adheres to used DTDs. `emd2exml` does very +> seldom fail and can easily generate XML that will cause the documentation +> build to fail. You always have to keep in mind that the XML generated +> should fit the chapter DTD of Erlang/OTP. Also note that even though HTML +> generation succeeds the PDF generation might fail, etc. +> +> *Always build the Erlang/OTP documentation after modifying an Erlangish +> Markdown document!* + +A note about how we talk about "tags" below. When we say "generate(s) `` +tags" this also imply that ending `` tags will be generated at appropriate +places. Appropriate attributes to the `X` tag will also be generated. + +* Inline and reference style links will either generate `` tags + or `` tags. If a "://" character sequence is found in the URL an + `` tag will be generated; otherwise, a `` tag is generated. + +* Automatic links will only generate `` tags. This since a + "://" character sequence have to be present in the URL in order + for the link to be identified. + +* Inline and reference style images will generate a ` + ... ` sequence where the "title" will be + placed between `` and ``. + +* Block quotes generate `
` tags. + +* If the first line of a top level block quote begins with a `> *NOTE*:` + character sequence, a `` tag will be generated instead of a + `
` tag. The note will span the entire block quote. + +* If the first line of a top level block quote begins with a `> *WARNING*:` + character sequence, a `` tag will be generated instead of a + `
` tag. The warning will span the entire block quote. + +* Paragraphs will generate `

` tags. + +* Break line (double trailing white space) will generate `
` tags. + +* An unordered list generates a `` tag and `` + tags for each item. + +* An ordered list generates a `` tag and `` tags + for each item. + +* Code blocks will generate `` tags. + +* Code span (backticks) will generate `` tags. + +* Emphasis (single `*` or `_`) will generate `` tags. + +* Strong emphasis (double `*` or `_`) will generate `` tags. + +* The level 1 heading will cause the following to be generated: + + + + +

+ + ... + + + ... + + + ... + ... + ... +
+ + ... + + + + The content of copyright section and the legalnotice section will + contain information from a \%CopyrightBegin\%, \%CopyrightEnd\% block + if such exist (see below). + +* A level `X` heading where `1 < X <= 3` will cause the the following + to be generated: + + +
+ ... + ... +
+ + The marker id is automatically generated as a combination of all parent + headings up to and including level 2 separated by a `_` character. As in + `__ ... _` + where each "marker heading" is constructed as follows. All characters a-z + and A-Z are kept as they are, space and tab characters are replaced by + `-` characters, and all other characters are dropped. + + This way it is relatively easy to make sure that all marker ids of a + document are unique, but there is of course no guarantee that they are. + + The upside of these auto generated markers is that we wont have to clutter + the document with XML or something else while being able to refer into + the document. The downside is that if you change a level 2 heading you + change a lot of marker ids which may break links into a document from + other documents. That is, *be careful* when changing headings in an + existing document. + +* A level `X` heading where `3 < X` will cause the the following + to be generated: + + +

...

+ ... + + Current DTD:s used don't support deeper levels of sections, and we + therefore simulate a section this way. The marker id is generated as for + a true section (see above). + +* If a section enclosed by \%CopyrightBegin\% and \%CopyrightEnd\% is + encountered, it will be interpreted as an EPL copyright and license, + and will be used in the header section of the document. The + \%CopyrightBegin\% and \%CopyrightEnd\% "tags" will be removed from + the output. + +* All occurrences of \%OTP-REL% will be replaced by current release number + (e.g. R14A). + +* All occurrences of \%ERTS-VSN% will be replaced by current ERTS version + (e.g. 5.8). + +* Adding a `[?TOC]: true` line (optionally indented with three spaces) + anywhere in the document will cause a table of contents to be automatically + generated at the beginning of the generated document. + +* Unicode characters (encoded in UTF-8) are allowed and will be passed + through as is to the output file. + +Copyright and License +--------------------- + +%CopyrightBegin% + +Copyright Ericsson AB 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% + + + + [$ERL_TOP/HOWTO/INSTALL.md]: INSTALL.md + [github]: http://github.com + [our github repository]: http://github.com/erlang/otp + + + [?TOC]: true diff --git a/HOWTO/SYSTEMTAP.md b/HOWTO/SYSTEMTAP.md new file mode 100644 index 0000000000..094b61f1c0 --- /dev/null +++ b/HOWTO/SYSTEMTAP.md @@ -0,0 +1,75 @@ +SystemTap and Erlang/OTP +======================== + +Introduction +------------ + +SystemTap is DTrace for Linux. In fact Erlang's SystemTap support +is build using SystemTap's DTrace compatibility's layer. For an +introduction to Erlang DTrace support read [$ERL_TOP/HOWTO/DTRACE.md][]. + +Requisites +---------- + +* Linux Kernel with UTRACE support + + check for UTRACE support in your current kernel: + + # grep CONFIG_UTRACE /boot/config-`uname -r` + CONFIG_UTRACE=y + + Fedora 16 is known to contain UTRACE, for most other Linux distributions + a custom build kernel will be required. + Check Fedora's SystemTap documentation for additional required packages + (e.g. Kernel Debug Symbols) + +* SystemTap > 1.6 + + A the time of writing this, the latest released version of SystemTap is + version 1.6. Erlang's DTrace support requires a MACRO that was introduced + after that release. So either get a newer release or build SystemTap from + git yourself (see: http://sourceware.org/systemtap/getinvolved.html) + +Building Erlang +--------------- + +Configure and build Erlang with SystemTap support: + + # ./configure --with-dynamic-trace=systemtap + whatever args you need + # make + +Testing +------- + +SystemTap, unlike DTrace, needs to know what binary it is tracing and has to +be able to read that binary before it starts tracing. Your probe script +therefor has to reference the correct beam emulator and stap needs to be able +to find that binary. +The examples are written for "beam", but other versions such as "beam.smp" or +"beam.debug.smp" might exist (depending on your configuration). Make sure you +either specify the full the path of the binary in the probe or your "beam" +binary is in the search path. + +All available probes can be listed like this: + + # stap -L 'process("beam").mark("*")' + +or: + + # PATH=/path/to/beam:$PATH stap -L 'process("beam").mark("*")' + + +Probes in the dtrace.so NIF library like this: + + # PATH=/path/to/dtrace/priv/lib:$PATH stap -L 'process("dtrace.so").mark("*")' + +Running SystemTap scripts +------------------------- + +Adjust the process("beam") reference to your beam version and attach the script +to a running "beam" instance: + + # stap /path/to/probe/script/port1.systemtap -x + + + [$ERL_TOP/HOWTO/DTRACE.md]: DTRACE.md diff --git a/INSTALL-CROSS.md b/INSTALL-CROSS.md deleted file mode 120000 index 9e7743b9de..0000000000 --- a/INSTALL-CROSS.md +++ /dev/null @@ -1 +0,0 @@ -xcomp/README.md \ No newline at end of file diff --git a/INSTALL-WIN32.md b/INSTALL-WIN32.md deleted file mode 100644 index ff253d3dfa..0000000000 --- a/INSTALL-WIN32.md +++ /dev/null @@ -1,1046 +0,0 @@ -How to Build Erlang/OTP on Windows -================================== - -Introduction ------------- - -This file describes how to build the Erlang emulator and the OTP -libraries on Windows. The instructions apply to versions of Windows -supporting the Cygwin emulated gnuish environment for Windows or the -Msys ditto. We've built on the following platforms: Windows 2003 -server, Windows XP Home/Professional, Windows Vista and Windows 7 (32 -and 64 bit). You can probably build on Windows 2000, but you will not -be able to install the latest Microsoft SDK, so you have to go back to -some earlier compiler. Any Windows95'ish platform will surely get you -into trouble, what I'm not sure of, but it certainly will... - -The procedure described uses either Cygwin or Msys as a build -environment, you run the bash shell in Cygwin/Msys and use gnu -make/configure/autoconf etc to do the build. The emulator C-source -code is, however, mostly compiled with Microsoft Visual C++™, -producing a native Windows binary. This is the same procedure as we -use to build the pre-built binaries. The fact that we use VC++ and not -gcc is explained further in the FAQ section. - -I describe the build procedure to make it possible for open source -customers to build the emulator, given that they have the needed -tools. The binary Windows releases is still a preferred alternative if -one does not have Microsoft's development tools and/or don't want to -install Cygwin or Msys. - -To use Cygwin/Msys, one needs basic experience from a Unix environment, if -one does not know how to set environment variables, run programs etc -in a Unix environment, one will be quite lost in the Cygwin os Msys -ditto. I can unfortunately not teach all the world how to use -Cygwin and bash, neither how to install Cygwin nor perform basic tasks -on a computer. Please refer to other documentation on the net for -help, or use the binary release instead if you have problems using the -tools. - -However, if you feel comfortable with the environment and build -system, and have all the necessary tools, you have a great opportunity -to make the Erlang/OTP distribution for Windows better. Please submit -any suggestions and patches to the appropriate [mailing lists] [1] to let -them find their way into the next version of Erlang. If making changes -to the build system (like makefiles etc) please bear in mind that the -same makefiles are used on Unix/VxWorks, so that your changes -don't break other platforms. That of course goes for C-code too, system -specific code resides in the `$ERL_TOP/erts/emulator/sys/win32` and -`$ERL_TOP/erts/etc/win32` directories mostly. The -`$ERL_TOP/erts/emulator/beam` directory is for common code. - -Before the R9C release of Erlang/OTP, the Windows release was built -partly on a Unix (Solaris) box and partly on a Windows box, using Perl -hacks to communicate and sync between the two machines. R9C was the -first release ever built solely on Windows, where no Unix machine is -needed at all. Now we've used this build procedure for a couple of -releases, and it has worked fine for us. Still, there might be all -sorts of troubles on different machines and with different -setups. I'll try to give hints wherever I've encountered difficulties, -but please share your experiences by using the [erlang-questions] [1] -mailing list. I cannot of course help everyone with all -their problems, please try to solve the problems and submit -solutions/workarounds. Remember, it's all about sharing, not about -demanding... - -Starting with R15B, our build system runs both on Cygwin and Msys -(MinGW's fork of an early cygwin version). Msys is a smaller package -to install and may on some machines run slightly faster. If Cygwin -gives you trouble, try Msys instead, and v.v. Beginning with R15B -there is also a native 64bit version of Erlang for 64bit Windows 7 -(only). These instructions apply to both the 32bit VM and the 64bit -ditto. - -Note that even if you build a 64bit VM, most of the directories and -files involved are still named win32. You can view the name win32 as -meaning any windows version not beeing 16bit. A few occurences of the -name Win64 are however present in the system, for example the -installation file for a 64 bit windows version of Erlang is by default -named `otp_win64_.exe`. - -Lets go then, I'll start with a little FAQ, based on in house questions -and misunderstandings. - - -Frequently Asked Questions --------------------------- - -* Q: So, now I can build Erlang using GCC on Windows? - - A: No, unfortunately not. You'll need Microsoft's Visual C++ - still, a Bourne-shell script (cc.sh) wraps the Visual C++ compiler - and runs it from within the Cygwin environment. All other tools - needed to build Erlang are free-ware/open source, but not the C - compiler. The Windows SDK is however enough to build Erlang, you - do not need to buy Visual C++, just download the SDK (SDK version - 7.1 == Visual studio 2010). - -* Q: Why haven't you got rid of VC++ then, you \*\*\*\*\*\*? - - A: Well, partly because it's a good compiler - really! Actually it's - been possible in late R11-releases to build using mingw instead of - visual C++ (you might see the remnants of that in some scripts and - directories). Unfortunately the development of the SMP version for - Windows broke the mingw build and we chose to focus on the VC++ build - as the performance has been much better in the VC++ versions. The - mingw build will possibly be back, but as long as VC++ gives better - performance, the commercial build will be a VC++ one. - -* Q: OK, you need VC++, but now you've started to demand a very recent - (and expensive) version of Visual studio, not the old and stable VC++ - 6.0 that was used in earlier versions. Why? - - A: Well, it's not expensive, it's free (as in free beer). Just - download and install the latest Windows SDK from Microsoft and all - the tools you need are there. The included debugger (WinDbg) is - also quite usable, it's what I used when porting Erlang to 64bit - Windows. Another reason to use the latest Microsoft compilers is - DLL compatibility. DLL's using a new version of the standard - library might not load if the VM is compiled with an old VC++ - version, why we should aim to use the latest freely available SDK - and compiler. - -* Q: Can/will I build a Cygwin binary with the procedure you describe? - - A: No, the result will be a pure Windows binary, and as far as I know, - it's not possible to make a Cygwin binary yet. That is of course - something desirable, but there are still some problems with the - dynamic linking (dynamic Erlang driver loading) as well as the TCP/IP - emulation in Cygwin, which, I'm sure of, will improve, but still has - some problems. Fixing those problems might be easy or might be hard. - I suggest you try yourself and share your experience. No one would be - happier if a simple `./configure && make` would produce a fully fledged - Cygwin binary. Ericsson does however not pay me to do a Cygwin port, so - such a port would have to happen in spare time, which is a limited - resource... - -* Q: Hah, I saw you, you used GCC even though you said you didn't! - - A: OK, I admit, one of the files is compiled using Cygwin's or - MinGW's GCC and the resulting object code is then converted to MS - VC++ compatible coff using a small C hack. It's because that - particular file, `beam_emu.c` benefits immensely from being able - to use the GCC labels-as-values extension, which boosts emulator - performance by up to 50%. That does unfortunately not (yet) mean - that all of OTP could be compiled using GCC, that particular - source code does not do anything system specific and actually is - adopted to the fact that GCC is used to compile it on Windows. - -* Q: So now there's a MS VC++ project file somewhere and I can build OTP - using the nifty VC++ GUI? - - A: No, never. The hassle of keeping the project files up to date and - do all the steps that constitute an OTP build from within the VC++ GUI - is simply not worth it, maybe even impossible. A VC++ project - file for Erlang/OTP will never happen, at least I will never make - one. Clicking around in super-multi-tab'd dialogs to add a file or - compiler option when it's so much easier in a makefile is simply not - my style. - -* Q: So how does it all work then? - - A: Cygwin or Msys is the environment, which closely resembles the - environments found on any Unix machine. It's almost like you had a - virtual Unix machine inside Windows. Configure, given certain - parameters, then creates makefiles that are used by the - Cygwin/Msys gnu-make to built the system. Most of the actual - compilers etc are not, however, Cygwin/Msys tools, so I've written - a couple of wrappers (Bourne-shell scripts), which reside in - `$ERL_TOP/etc/win32/cygwin_tools` and - `$ERL_TOP/etc/win32/msys_tools`. They all do conversion of - parameters and switches common in the Unix environment to fit the - native Windows tools. Most notable is of course the paths, which - in Cygwin/Msys are Unix-like paths with "forward slashes" (/) and - no drive letters, the Cygwin specific command `cygpath` is used - for most of the path conversions in a Cygwin environment, other - tools are used (when needed) in the corresponding Msys - environment. Luckily most compilers accept forward slashes instead - of backslashes as path separators, but one still have to get the drive - letters etc right, though. The wrapper scripts are not general in - the sense that, for example, cc.sh would understand and translates - every possible gcc option and passes correct options to - cl.exe. The principle is that the scripts are powerful enough to - allow building of Erlang/OTP, no more, no less. They might need - extensions to cope with changes during the development of Erlang, - that's one of the reasons I made them into shell-scripts and not - Perl-scripts, I believe they are easier to understand and change - that way. I might be wrong though, cause another reason I didn't - write them in Perl is because I've never liked Perl and my Perl - code is no pleasant reading... - - In `$ERL_TOP`, there is a script called `otp_build`. That script handles - the hassle of giving all the right parameters to `configure`/`make` and - also helps you set up the correct environment variables to work with - the Erlang source under Cygwin. - -* Q: You use and need Cygwin, but then you haven't taken the time to - port Erlang to the Cygwin environment but instead focus on your - commercial release, is that really ethical? - - A: No, not really, but see this as a step in the right direction. I'm - aiming at GCC compiled emulators and a Cygwin version, but I really - need to do other things as well... In time, but don't hold your - breath... - -* Q: Can I build something that looks exactly as the commercial release? - - A: Yes, we use the exactly same build procedure. - -* Q: Which version of Cygwin/Msys and other tools do you use then? - - A: For Cygwin and Msys alike, we try to use the latest releases - available when building. What versions you use shouldn't really - matter, I try to include workarounds for the bugs I've found in - different Cygwin/Msys releases, please help me add workarounds - for new Cygwin/Msys-related bugs as soon as you encounter - them. Also please do submit bug reports to the appropriate Cygwin - and/or Msys developers. The GCC we used for %OTP-REL% was version - 4.7.0 (MinGW 64bit) and 4.3.4 (Cygwin 32bit). We used VC++ 10.0 - (i.e. Visual studio 2010), Sun's JDK 1.5.0\_17 (32bit) and Sun's - JDK 1.7.0\_1 (64bit), NSIS 2.46, and Win32 OpenSSL 0.9.8r. Please - read the next section for details on what you need. - -* Q: Can you help me setup X in Cygwin? - - A: No, unfortunately I haven't got time to help with Cygwin related - user problems, please read Cygwin related web sites, newsgroups and - mailing lists. - -* Q: Why is the instruction so long? Is it really that complicated? - - A: Partly it's long because I babble too much, partly because I've - described as much as I could about the installation of the needed - tools. Once the tools are installed, building is quite easy. I also - have tried to make this instruction understandable for people with - limited Unix experience. Cygwin/Msys is a whole new environment to some - Windows users, why careful explanation of environment variables etc - seemed to be in place. The short story, for the experienced and - impatient is: - - * Get and install complete Cygwin (latest) or complete MinGW with msys - - * Install Microsofts Windows SDK 7.1 (and .Net 4) - - * Get and install Sun's JDK 1.5.0 or higher - - * Get and install NSIS 2.01 or higher (up to 2.46 tried and working) - - * Get, build and install OpenSSL 0.9.8r or higher (up to 1.0.0a - tried & working) with static libs. - - * Get the Erlang source distribution (from - ) and unpack with Cygwin's `tar`. - - * Set `ERL_TOP` to where you unpacked the source distribution - - * `$ cd $ERL_TOP` - - * Get (from ) - and unpack the prebuilt TCL/TK binaries for windows with cygwin tar, - standing in `$ERL_TOP` - - * Modify PATH and other environment variables so that all these tools - are runnable from a bash shell. Still standing in `$ERL_TOP`, issue - the following commands: - - $ eval `./otp_build env_win32` - $ ./otp_build autoconf - $ ./otp_build configure - $ ./otp_build boot -a - $ ./otp_build release -a - $ ./otp_build installer_win32 - $ release/win32/otp_win32_%OTP-REL% /S - - Voila! `Start->Programs->Erlang OTP %OTP-REL%->Erlang` starts the Erlang - Windows shell. - - -Tools you Need and Their Environment ------------------------------------- - -You need some tools to be able to build Erlang/OTP on Windows. Most -notably you'll need Cygwin or Msys and Microsofts Windows SDK, but -you also might want a Java compiler, the NSIS install system and -OpenSSL. Well' here's the list: - -* Cygwin, the very latest is usually best. Get all the development - tools and of course all the basic ditto. In fact getting the complete - package might be a good idea, as you'll start to love Cygwin after a - while if you're accustomed to Unix. Make sure to get jar and also make - sure *not* to install a Cygwin'ish Java... The Cygwin jar command is - used but Sun's Java compiler and virtual machine... - - If you are going to build a 64bit Windows version, you should make - sure to get MinGW's 64bit gcc installed with cygwin. It's in one of - the development packages. - - URL: - - Get the installer from the web site and use that to install - Cygwin. Be sure to have fair privileges. If you're on a NT domain you - should consider running `mkpasswd -d` and `mkgroup -d` after the - installation to get the user databases correct. See their respective - manual pages. - - When you start you first bash shell, you will get an awful prompt. You - might also have a `PATH` environment variable that contains backslashes - and such. Edit `$HOME/.profile` and `$HOME/.bashrc` to set fair prompts - and set a correct PATH. Also do a `export SHELL` in `.profile`. For some - non-obvious reason the environment variable `$SHELL` is not exported in - bash. Also note that `.profile` is run at login time and `.bashrc` when - sub shells are created. You'll need to explicitly source `.bashrc` from - `.profile` if you want the commands there to be run at login time (like - setting up aliases, shell functions and the like). I personally - usually do like this at the end of `.profile`: - - ENV=$HOME/.bashrc - export ENV - . $ENV - - You might also, if you're a hard core type of person at least, want to - setup X-windows (XFree86), that might be as easy as running startx - from the command prompt and it might be much harder. Use Google to - find help... - - If you don't use X-windows, you might want to setup the Windows - console window by selecting properties in the console system menu - (upper left corner of the window, the Cygwin icon in the title - bar). Especially setting a larger screen buffer size (lines) is useful - as it gets you a scrollbar so you can see whatever error messages - that might appear... - - If you want to use (t)csh instead of bash you're on your own, I - haven't tried and know of no one that has. I expect - that you use bash in all shell examples. - -* Alternatively you download MinGW and Msys. You'll find the latest - installer at: - - URL: - - Make sure to install everything they've got. - - To be able to build the 64bit VM, you will also need the 64bit - MinGW compiler from: - - URL: - - The latest version should do it. Make sure you download the - `mingw-w64-bin_i686-mingw_.zip`, not a linux - version. You unzip the package on top of your MinGW installation - (`c:\MinGW`) and that's it. - - Setting up your environment in Msys is similar to setting it up in - Cygwin. - -* Microsofts Windows SDK version 7.1 (corresponding to VC++ 10.0 and - Visual Studio 2010). You'll find it here: - - URL: - - but before you install that, you need to have .Net 4 installed, - you'll find that here: - - URL: - - Use the web installer for the SDK, at least when I tried - downloading the whole package as an image, I got SDK 7.0 instead, - which is not what you want... - - There will be a Windows command file in `%PROGRAMFILES%\Mirosoft - SDKs\Windows\v7.1\Bin\SetEnv.cmd` that set's the appropriate - environment for a Windows command prompt. This is not appropriate - for bash, so you'll need to convert it to bash-style environments - by editing your `.bash_profile`. In my case, where the SDK is - installed in the default directory and `%PROGRAMFILES%` is - `C:\Program Files`, the commands for setting up a 32bit build - environment (on a 64bit or 32bit machine) look like this (in cygwin): - - # Some common paths - C_DRV=/cygdrive/c - PRG_FLS=$C_DRV/Program\ Files - - # nsis - NSIS_BIN=$PRG_FLS/NSIS - # java - JAVA_BIN=$PRG_FLS/Java/jdk1.6.0_16/bin - - ## - ## MS SDK - ## - - CYGWIN=nowinsymlinks - MVS10="$PRG_FILES/Microsoft Visual Studio 10.0" - WIN_MVS10="C:\\Program Files\\Microsoft Visual Studio 10.0" - SDK10="$PRG_FILES/Microsoft SDKs/Windows/v7.1" - WIN_SDK10="C:\\Program Files\\Microsoft SDKs\\Windows\\v7.1" - - PATH="$NSIS_BIN:\ - $MVS10/Common7/IDE:\ - $MVS10/Common7/Tools:\ - $MVS10/VC/Bin:\ - $MVS10/VC/Bin/VCPackages:\ - $SDK10/Bin/NETFX 4.0 Tools:\ - $SDK10/Bin:\ - /usr/local/bin:/usr/bin:/bin:\ - /cygdrive/c/WINDOWS/system32:/cygdrive/c/WINDOWS:\ - /cygdrive/c/WINDOWS/system32/Wbem:\ - $JAVA_BIN" - - LIBPATH="$WIN_MVS10\\VC\\LIB" - - LIB="$WIN_MVS10\\VC\\LIB;$WIN_SDK10\\LIB" - - INCLUDE="$WIN_MVS10\\VC\\INCLUDE;$WIN_SDK10\\INCLUDE;$WIN_SDK10\\INCLUDE\\gl" - - export CYGWIN PATH LIBPATH LIB INCLUDE - - If you're using Msys instead, the only thing you need to change is - the `C_DRV` setting, which would read: - - C_DRV=/c - - And of course you might need to change `C:\Program Files` etc if - you're using a non-english version of Windows (XP). Note that in - later versions of Windows, the national adoptions of the program - files directories etc are not on the file system but only in the - explorer, so even if explorer says that your programs reside in - e.g. `C:\Program`, they might still reside in `C:\Program Files` - in reality... - - If you are building a 64 bit version of Erlang, you should set up - PATHs etc a little differently. I use the following script to - make things work in both Cygwin and Msys: - - make_winpath() - { - P=$1 - if [ "$IN_CYGWIN" = "true" ]; then - cygpath -d "$P" - else - (cd "$P" && /bin/cmd //C "for %i in (".") do @echo %~fsi") - fi - } - - make_upath() - { - P=$1 - if [ "$IN_CYGWIN" = "true" ]; then - cygpath "$P" - else - echo "$P" | /bin/sed 's,^\([a-zA-Z]\):\\,/\L\1/,;s,\\,/,g' - fi - } - - # Some common paths - if [ -x /usr/bin/msysinfo ]; then - # Without this the path conversion won't work - COMSPEC='C:\Windows\SysWOW64\cmd.exe' - MSYSTEM=MINGW32 - export MSYSTEM COMSPEC - IN_CYGWIN=false - else - CYGWIN=nowinsymlinks - export CYGWIN - IN_CYGWIN=true - fi - - if [ "$IN_CYGWIN" = "true" ]; then - PATH=/usr/local/bin:/usr/bin:/bin:/usr/X11R6/bin:\ - /cygdrive/c/windows/system32:/cygdrive/c/windows:/cygdrive/c/windows/system32/Wbem - else - PATH=/usr/local/bin:/mingw/bin:/bin:/c/Windows/system32:/c/Windows:\ - /c/Windows/System32/Wbem - fi - - if [ "$IN_CYGWIN" = "true" ]; then - C_DRV=/cygdrive/c - else - C_DRV=/c - fi - - PRG_FLS64=$C_DRV/Program\ Files - PRG_FLS32=$C_DRV/Program\ Files\ \(x86\) - VISUAL_STUDIO_ROOT32=$PRG_FLS32/Microsoft\ Visual\ Studio\ 10.0 - MS_SDK_ROOT64=$PRG_FLS64/Microsoft\ SDKs/Windows/v7.1 - - # Okay, now mangle the paths and get rid of spaces by using short names - WIN_VCROOT32=`make_winpath "$VISUAL_STUDIO_ROOT32"` - VCROOT32=`make_upath $WIN_VCROOT32` - WIN_SDKROOT64=`make_winpath "$MS_SDK_ROOT64"` - SDKROOT64=`make_upath $WIN_SDKROOT64` - WIN_PROGRAMFILES32=`make_winpath "$PRG_FLS32"` - PROGRAMFILES32=`make_upath $WIN_PROGRAMFILES32` - - WIN_PROGRAMFILES64=`make_winpath "$PRG_FLS64"` - PROGRAMFILES64=`make_upath $WIN_PROGRAMFILES64` - - # nsis - NSIS_BIN=$PROGRAMFILES32/NSIS - # java - JAVA_BIN=$PROGRAMFILES64/Java/jdk1.7.0_01/bin - - ## The PATH variable should be Unix'ish - VCPATH=$VCROOT32/Common7/IDE:$VCROOT32/VC/BIN/amd64:$VCROOT32/Common7/Tools:\ - $VCROOT32/VC/VCPackages:$SDKROOT64/bin/NETFX4~1.0TO/x64:$SDKROOT64/bin/x64:\ - $SDKROOT64/bin - - ## Microsoft SDK libs - - LIBPATH=$WIN_VCROOT32\\VC\\LIB\\amd64 - LIB=$WIN_VCROOT32\\VC\\LIB\\amd64\;$WIN_SDKROOT64\\LIB\\X64 - INCLUDE=$WIN_VCROOT32\\VC\\INCLUDE\;$WIN_SDKROOT64\\include\;\ - $WIN_SDKROOT64\\include\\gl - - # Put nsis, c compiler and java in path - PATH=$NSIS_BIN:$VCPATH:$PATH:$JAVA_BIN - - # Make sure LIB and INCLUDE is available for others - export PATH LIBPATH LIB INCLUDE - - All this is derived from the SetEnv.cmd command file mentioned - earlier. The bottom line is to set the PATH so that NSIS and - Microsoft SDK is found before the Msys/Cygwin tools and that Java - is last in the PATH. - - Make a simple hello world (maybe one that prints out - `sizeof(void *)`) and try to compile it with the `cl` command from within - bash. If that does not work, your environment needs fixing. Also - remember to fix up the PATH environment, especially old Erlang - installations might have inserted quoted paths that Cygwin/Msys - does not understand. Remove or correct such paths. There should be - no backslashes in your path environment variable in Cygwin bash, - but LIB and INCLUDE should contain Windows style paths with - semicolon, drive letters and backslashes. - -* Sun's Java JDK 1.5.0 or higher. Our Java code (jinterface, ic) is - written for JDK 1.5.0. Get it for Windows and install it, the JRE is - not enough. If you don't care about Java, you can skip this step, the - result will be that jinterface is not built. - - URL: - - Add javac *LAST* to your path environment in bash, in my case this means: - - `PATH="$PATH:/cygdrive/c/Program Files/Java/jdk1.5.0_17/bin"` - - No `CLASSPATH` or anything is needed. Type `javac` at the bash prompt - and you should get a list of available Java options. Make sure by - typing `type java` that you use the Java you installed. Note however that - Cygwin's `jar.exe` is used, that's why the JDK bin-directory should be - added last in the `PATH`. - -* Nullsoft NSIS installer system. You need this to build the self - installing package. It's a free open source installer that's much - nicer to use than the commercial Wise and Install shield - installers. This is the installer we use for commercial releases as - well from R9C an on. - - URL: - - Install the lot, especially the modern user interface components, as - it's definitely needed. Put `makensis` in your path, in my case: - - PATH=/cygdrive/c/Program\ Files/NSIS:$PATH - - type makensis at the bash prompt and you should get a list of options - if everything is OK. - -* OpenSSL. This is if you want the SSL and crypto applications to - compile (and run). There are prebuilt binaries available, but I - strongly recommend building this yourself. It's quite easy. - - First get the source from - - URL: - - I would recommend using 0.9.8r. - - Download the tar file and unpack it (using your bash prompt) into - a directory of your choise. - - You will need a Windowish Perl for the build. ActiveState has one: - - URL: - - Download and install that. Disable options to associate it with - the .pl suffix and/or adding things to PATH, they are not needed. - - Now fire up the Microsoft Windows SDK command prompt in RELEASE - mode for the architecture you are going to build. The easiest is - to copy the shortcut from the SDKs start menu item and edit the - command line in the shortcut (Right click->Properties) to end with - `/Release`. Make sure the banner when you double click your - shortcut (the text in the resulting command window) says - `Targeting Windows XP x64 Release` if you are going to do a 64 bit - build and `Targeting Windows XP x86 Release` if you are building a - 32 bit version. - - Now cd to where you unpacked the OpenSSL source using your Release - Windows command prompt (it should be on the same drive as where - you are going to install it if everything is to work smothly). - - C:\> cd - - Add ActiveState (or some other windows perl, not cygwins) to your PATH: - - C:\...\> set PATH=C:\Perl\bin;%PATH% - - Or if you installed the 64bit perl: - - C:\...\> set PATH=C:\Perl64\bin;%PATH% - - Configure OpenSSL for 32 bit: - - C:\...\> perl Configure VC-WIN32 --prefix=/OpenSSL - - Or for 64 bit: - - C:\...\> perl Configure VC-WIN64A --prefix=/OpenSSL-Win64 - - Do some setup (for 32 bit): - - C:\...\> ms\do_ms - - The same for 64 bit: - - C:\...\> ms\do_win64a - - Then build static libraries and install: - - C:\...\> nmake -f ms\nt.mak - C:\...\> nmake -f ms\nt.mak install - - That's it - you now have your perfectly consistent static build of - openssl. If you want to get rid of any possibly patented - algorithms in the lib, just read up on the OpenSSL FAQ and follow - the instructions. - - The installation locations chosen are where configure will look - for OpenSSL, so try to keep them as is. - -* Building with wxWidgets. Download wxWidgets-2.8.9 or higher patch - release (2.9.\* is a developer release which currently does not work - with wxErlang). - - Install or unpack it to `DRIVE:/PATH/cygwin/opt/local/pgm`. - - edit: `C:\cygwin\opt\local\pgm\wxMSW-2.8.11\include\wx\msw\setup.h` - enable `wxUSE_GLCANVAS`, `wxUSE_POSTSCRIPT` and `wxUSE_GRAPHICS_CONTEXT` - - build: From a command prompt with the VC tools available (See the - instructions for OpenSSL build above for help on starting the - proper command prompt in RELEASE mode): - - C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\build\msw - C:\...\> nmake BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc - C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\contrib\build\stc - C:\...\> nmake BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc - - Or - if building a 64bit version: - - C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\build\msw - C:\...\> nmake TARGET_CPU=amd64 BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc - C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\contrib\build\stc - C:\...\> nmake TARGET_CPU=amd64 BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc - -* The Erlang source distribution (from ). - The same as for Unix platforms. Preferably use tar from within Cygwin to - unpack the source tar.gz (`tar zxf otp_src_%OTP-REL%.tar.gz`). - - set the environment `ERL_TOP` to point to the root directory of the - source distribution. Let's say I stood in `$HOME/src` and unpacked - `otp_src_%OTP-REL%.tar.gz`, I then add the following to `.profile`: - - ERL_TOP=$HOME/src/otp_src_%OTP-REL% - export $ERL_TOP - -* The TCL/TK binaries. You could compile Tcl/Tk for windows yourself, - but you can get a stripped down version from our website which is - suitable to include in the final binary package. If you want to supply - tcl/tk yourself, read the instructions about how the tcl/tk tar file - used in the build is constructed under `$ERL_TOP/lib/gs/tcl`. The easy - way is to download - and unpack it standing in the `$ERL_TOP` directory. This will create the - file `win32.tar.gz` in `$ERL_TOP/lib/gs/tcl/binaries`. - - One last alternative is to create a file named `SKIP` in the - `$ERL_TOP/lib/gs/` after configure is run, but that will give you an - erlang system without gs (which might be okay as you probably will use - wx anyway). - - Note that there is no special 64bit version of TCL/TK needed, you - can use the 32bit program even for a 64bit build. - -The Shell Environment ---------------------- - -So, if you have followed the instructions above, when you start a bash -shell, you should have an INCLUDE environment with a Windows style -path, a LIB environment variable also in Windows style, and finally a -PATH that let's you reach cl, makensis, javac etc from the -command prompt (use `which cl` etc to verify from bash). - -You should also have an `ERL_TOP` environment variable that is *Cygwin -style*, and points to a directory containing, among other files, the -script `otp_build`. - -A final massage of the environment is needed, and that is done by -the script `$ERL_TOP/otp_build`. Start bash and do the following, note -the "back-ticks" (\`), can be quite hard to get on some keyboards, but -pressing the back-tick key followed by the space bar might do it... - - $ cd $ERL_TOP - $ eval `./otp_build env_win32` - -If you're unable to produce back-ticks on your keyboard, you can use -the ksh variant: - - $ cd $ERL_TOP - $ eval $(./otp_build env_win32) - -If you are building a 64 bit version, you supply `otp_build` with an architecture parameter: - - $ cd $ERL_TOP - $ eval `./otp_build env_win32 x64` - - -This should do the final touch to the environment and building should -be easy after this. You could run `./otp_build env_win32` without -`eval` just to see what it does, and to see that the environment it -sets seems OK. The path is cleaned of spaces if possible (using DOS -style short names instead), the variables `OVERRIDE_TARGET`, `CC`, `CXX`, -`AR` and `RANLIB` are set to their respective wrappers and the directories -`$ERL_TOP/erts/etc/win32/cygwin_tools/vc` and -`$ERL_TOP/erts/etc/win32/cygwin_tool` are added first in the PATH. - -Try now a `type erlc`. That should result in the erlc wrapper script -(which does not have the .sh extension, for reasons best kept -untold...). It should reside in `$ERL_TOP/erts/etc/win32/cygwin_tools` -or `$ERL_TOP/erts/etc/win32/msys_tools`. You could also try `which -cc.sh`, which `ar.sh` etc. - -Now you're ready to build... - - -Building and Installing ------------------------ - -Now it's assumed that you have executed `` eval `./otp_build env_win32` `` or -`` eval `./otp_build env_win32 x64` `` for this particular shell... - -Building is easiest using the `otp_build` script. That script takes care -of running configure, bootstrapping etc on Windows in a simple -way. The `otp_build` script is the utility we use ourselves to build on -different platforms and it therefore contains code for all sorts of -platforms. The principle is, however, that for non-Unix platforms, one -uses `./otp_build env_` to set up environment and then the -script knows how to build on the platform "by itself". You've already -run `./otp_build env_win32` in the step above, so now it's mostly like -we build on any platform. OK, here are then steps; Assuming you will -want to build a full installation executable with NSIS, you can omit -`` and the release will be copied to -`$ERL_TOP/release/win32`: and there is where the packed self installing -executable will reside too. - - $ ./otp_build autoconf # Ignore the warning blob about versions of autoconf - $ ./otp_build configure - $ ./otp_build boot -a - $ ./otp_build release -a - $ ./otp_build installer_win32 # optional - -Now you will have a file called `otp_win32_R12B.exe` in the -``, i.e. `$ERL_TOP/release/win32`. - -Lets get into more detail: - -1. `$ ./otp_build autoconf` - This step rebuilds the configure scripts - to work correctly in the cygwin environment. In an ideal world, this - would not be needed, but alas, we have encountered several - incompatibilities between our distributed configure scripts (generated - on a Linux platform) and the cygwin environment over the - years. Running autoconf on cygwin ensures that the configure scripts - are generated in a cygwin-compatible way and that they will work well - in the next step. - -2. `$ ./otp_build configure` - This runs the newly generated configure - scripts with options making configure behave nicely. The target machine - type is plainly `win32`, so a lot of the configure-scripts recognize - this awkward target name and behave accordingly. The CC variable also - makes the compiler be `cc.sh`, which wraps MSVC++, so all configure - tests regarding the C compiler gets to run the right compiler. A lot of - the tests are not needed on Windows, but I thought it best to run the - whole configure anyway. The only configure option you might want to - supply is `--with-ssl`, which might be needed if you have built your - own OpenSSL distribution. The Shining Lights distribution should be - found automatically by `configure`, if that fails, add a - `--with-ssl=` that specifies the root directory of your OpenSSL - installation. - -3. `$ ./otp_build boot -a` - This uses the bootstrap directory (shipped - with the source, `$ERL_TOP/bootstrap`) to build a complete OTP - system. It first builds an emulator and sets up a minimal OTP system - under `$ERL_TOP/bootstrap`, then starts to compile the different OTP - compilers to make the `$ERL_TOP/bootstrap` system potent enough to be - able to compile all Erlang code in OTP. Then, all Erlang and C code - under `$ERL_TOP/lib` is built using the bootstrap system, giving a - complete OTP system (although not installed). When this is done, one - can run Erlang from within the source tree, just type `$ERL_TOP/bin/erl` - and you should have a prompt. If you omit the -a flag, you'll get a - smaller system, that might be useful during development. Now - exit from Erlang and start making a release of the thing: - -4. `$ ./otp_build release -a` - Builds a commercial release tree from the - source tree, default is to put it in `$ERL_TOP/release/win32`, you can - give any directory as parameter (Cygwin style), but it doesn't really - matter if you're going to build a self extracting installer too. You - could of course build release to the final directory and then run - `./Install.exe` standing in the directory where the release was put, - that will create a fully functional OTP installation. But let's make - the nifty installer: - -5. `$ ./otp_build installer_win32` - Create the self extracting installer - executable. The executable `otp_win32_%OTP-REL%.exe` will be placed - in the top directory of the release created in the previous step. If - no release directory is specified, the release is expected to have - been built to `$ERL_TOP/release/win32`, which also will be the place - where the installer executable will be placed. If you specified some - other directory for the release (i.e. `./otp_build release -a - /tmp/erl_release`), you're expected to give the same parameter here, - (i.e. `./otp_build installer_win32 /tmp/erl_release`). You need to have - a full NSIS installation and `makensis.exe` in your path for this to - work of course. Once you have created the installer, you can run it to - install Erlang/OTP in the regular way, just run the executable and - follow the steps in the installation wizard. To get all default settings - in the installation without any questions asked, you run the executable - with the parameter `/S` (capital S) like in: - - $ cd $ERL_TOP - $ release/win32/otp_win32_%OTP-REL% /S - ... - - or - - $ cd $ERL_TOP - $ release/win32/otp_win64_%OTP-REL% /S - ... - - - and after a while Erlang/OTP-%OTP-REL% will have been installed in - `C:\Program Files\erl%ERTS-VSN%\`, with shortcuts in the menu etc. - - The necessary setup of an Erlang installation is actually done by the - program `Install.exe`, which resides in the release top. That program - creates `.ini`-files and copies the correct boot scripts. If one has - the correct directory tree (like after a `./otp_build release -a`), only - the running of `Install.exe` is necessary to get a fully functional - OTP. What the self extracting installer adds is (of course) the - possibility to distribute the binary easily, together with adding - shortcuts to the Windows start menu. There is also some adding of - entries in the registry, to associate `.erl` and `.beam` files with - Erlang and get nifty icons, but that's not something you'll really need - to run Erlang. The registry is also used to store uninstall information, - but if one has not used the self extracting installer, one cannot - (need not) do any uninstall, one just scratches the release directory - and everything is gone. Erlang/OTP does not *need* to put anything - in the Windows registry at all, and does not if you don't use the self - extracting installer. In other words the installer is pure cosmetics. - -> *NOTE*: Beginning with R9C, the Windows installer does *not* add Erlang -> to the system wide path. If one wants to have Erlang in the path, one -> has to add it by hand. - -Development ------------ - -Once the system is built, you might want to change it. Having a test -release in some nice directory might be useful, but you also can run -Erlang from within the source tree. The target `local_setup`, makes -the program `$ERL_TOP/bin/erl.exe` usable and it also uses all the OTP -libraries in the source tree. - -If you hack the emulator, you can then build the emulator executable -by standing in `$ERL_TOP/erts/emulator` and do a simple - - $ make opt - -Note that you need to have run ``(cd $ERL_TOP && eval `./otp_build env_win32`)`` -in the particular shell before building anything on Windows. After -doing a make opt you can test your result by running `$ERL_TOP/bin/erl`. -If you want to copy the result to a release directory (say -`/tmp/erl_release`), you do this (still in `$ERL_TOP/erts/emulator`) - - $ make TESTROOT=/tmp/erl_release release - -That will copy the emulator executables. - -To make a debug build of the emulator, you need to recompile both -`beam.dll` (the actual runtime system) and `erlexec.dll`. Do like this - - $ cd $ERL_TOP - $ rm bin/win32/erlexec.dll - $ cd erts/emulator - $ make debug - $ cd ../etc - $ make debug - -and sometimes - - $ cd $ERL_TOP - $ make local_setup - -So now when you run `$ERL_TOP/erl.exe`, you should have a debug compiled -emulator, which you will see if you do a: - - 1> erlang:system_info(system_version). - -in the erlang shell. If the returned string contains `[debug]`, you -got a debug compiled emulator. - -To hack the erlang libraries, you simply do a `make opt` in the -specific "applications" directory, like: - - $ cd $ERL_TOP/lib/stdlib - $ make opt - -or even in the source directory... - - $ cd $ERL_TOP/lib/stdlib/src - $ make opt - -Note that you're expected o have a fresh Erlang in your path when -doing this, preferably the plain %OTP-REL% you have built in the previous -steps. You could also add `$ERL_TOP/bootstrap/bin` to your `PATH` before -rebuilding specific libraries, that would give you a good enough -Erlang system to compile any OTP erlang code. Setting up the path -correctly is a little bit tricky, you still need to have -`$ERL_TOP/erts/etc/win32/cygwin_tools/vc` and -`$ERL_TOP/erts/etc/win32/cygwin_tools` *before* the actual emulator -in the path. A typical setting of the path for using the bootstrap -compiler would be: - - $ export PATH=$ERL_TOP/erts/etc/win32/cygwin_tools/vc\ - :$ERL_TOP/erts/etc/win32/cygwin_tools:$ERL_TOP/bootstrap/bin:$PATH - -That should make it possible to rebuild any library without hassle... - -If you want to copy a library (an application) newly built, to a -release area, you do like with the emulator: - - $ cd $ERL_TOP/lib/stdlib - $ make TESTROOT=/tmp/erlang_release release - -Remember that: - -* Windows specific C-code goes in the `$ERL_TOP/erts/emulator/sys/win32`, - `$ERL_TOP/erts/emulator/drivers/win32` or `$ERL_TOP/erts/etc/win32`. - -* Windows specific erlang code should be used conditionally and the - host OS tested in *runtime*, the exactly same beam files should be - distributed for every platform! So write code like: - - case os:type() of - {win32,_} -> - do_windows_specific(); - Other -> - do_fallback_or_exit() - end, - -That's basically all you need to get going. - -Using GIT ---------- - -You might want to check out versions of the source code from GitHUB. That is possible directly in cygwin, but not in Msys. There is a project MsysGIT: - -URL: - -that makes a nice Git port. The msys prompt you get from MsysGIT is -however not compatible with the full version from MinGW, so you will -need to check out files using MsysGIT's command prompt and then switch -to a common Msys command prompt for building. Also all test suites -cannot be built as MsysGIT/Msys does not handle symbolic links. To -build test suites on Windows, you will need Cygwin for now. Hopefully -all symbolic links will disappear from our repository soon and this -issue will disappear. - -Final Words ------------ -My hope is that the possibility to build the whole system on Windows -will open up for free development on this platform too. There are many -things one might want to do better in the Windows version, like the -window-style command prompt as well as pure Cygwin porting. Although i -realize it's a much larger step to start building on Windows (with all -the software you need) than for instance on Linux, I sincerely hope -that some of you will make the effort and start submitting Windows -friendly patches. - -The first build system for Erlang using Cygwin on Windows was created -by Per Bergkvist. I haven't used his build system, but it's rumored to -be good. The idea to do this came from his work, so credit is well -deserved. - -Of course this would have been completely impossible without the -excellent Cygwin. The guys at Cygnus solutions and -Redhat deserve a huge THANKS! as well as all the other people in the -free software community who have helped in creating the magnificent -software that constitutes Cygwin. - -Also the people developing the alternative command prompt Msys and -the MinGW compiler are worth huge THANKS! The 64bit port would have -been impossible without the 64bit MinGW compiler. - -Good luck and Happy Hacking, -Patrik, OTP - -Copyright and License ---------------------- - -%CopyrightBegin% - -Copyright Ericsson AB 2003-2012. 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% - -Modifying This Document ------------------------ - -Before modifying this document you need to have a look at the -`$ERL_TOP/README.md.txt` document. - - - - [1]: http://www.erlang.org/faq.html "mailing lists" - - [?TOC]: true diff --git a/INSTALL.md b/INSTALL.md deleted file mode 100644 index 70d465831d..0000000000 --- a/INSTALL.md +++ /dev/null @@ -1,838 +0,0 @@ -Building and Installing Erlang/OTP -================================== - -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: - - - -The source code for Erlang/OTP can also be found in a Git repository: - - - -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][] - document. - -* build Erlang/OTP on Windows, see the [$ERL_TOP/INSTALL-WIN32.md][] - document. - - Binary releases for Windows can be found at - . - -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 --------------------- -At Ericsson we have a "Daily Build and Test" that runs on: - -* Solaris 8, 9 - * Sparc32 - * Sparc64 -* Solaris 10 - * Sparc32 - * Sparc64 - * x86 -* SuSE Linux/GNU 9.4, 10.1 - * x86 -* SuSE Linux/GNU 10.0, 10.1, 11.0 - * x86 - * x86\_64 -* openSuSE 11.4 (Celadon) - * x86\_64 (valgrind) -* Fedora 7 - * PowerPC -* Fedora 14 - * x86\_64 -* Gentoo Linux/GNU 1.12.11.1 - * x86 -* Ubuntu Linux/GNU 7.04, 10.04, 10.10, 11.0 - * x86\_64 -* MontaVista Linux/GNU 4.0.1 - * PowerPC -* FreeBSD 8.2 - * x86 -* OpenBSD 5.0 - * x86\_64 -* Mac OS X 10.5.8 (Leopard), 10.6.0 (Snow Leopard), 10.7.3 (Lion) - * x86 -* Windows XP SP3, 2003, Vista, 7 - * x86 -* Windows 7 - * x86\_64 - -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 - -and the following "Daily Cross Build Tests": - -* SuSE Linux/GNU 10.1 x86\_64 - -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: - - * - * - -* `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 is not 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: - - * - * - -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). - -### Building ### - -* GNU `make` -* `gcc` -- GNU C compiler -* Perl 5 -* 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 - binary command program `openssl` is also needed. At least version 0.9.8 - of OpenSSL is required. Can be downloaded from . -* Sun Java jdk-1.5.0 or higher -- Optional but needed for building the - Erlang/OTP application `jinterface` and parts of `ic` and `orber`. Can - be downloaded from . 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. - -#### Building Documentation #### - -* `xsltproc` -- XSLT processor. A tool for applying XSLT stylesheets - to XML documents. Can be downloaded from - . -* `fop` -- Apache FOP print formatter (requires Java). Can be downloaded - from . - -#### 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 ### - -* An `install` program that can take multiple file names. - -How to Build and Install Erlang/OTP ------------------------------------ - -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][] -section below before proceeding. - -### Unpacking ### - -Step 1: Start by unpacking the Erlang/OTP distribution file with your GNU -compatible TAR program. - - $ 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_%OTP-REL% - -### Configuring ### - -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}`. -To instead install in `/{bin,lib/erlang}`, 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. Before doing a `make clean`, -be sure to read the [Pre-built Source Release][] section below. - -### Building ### - -Step 5: Build the Erlang/OTP package. - - $ make - -### Installing ### - -Step 6: Install then Erlang/OTP package - - $ make install - -### A Closer Look at the individual Steps ### - -Let us go through them in some detail. - -#### Configuring #### - -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` 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, `` say, -use the `--prefix` argument like this: `./configure --prefix=`. - -Some of the available `configure` options are: - -* `--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 - possible) -* `--{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 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) -* `--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 - . - -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: - - $ 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 #### - -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 - $ 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 - -* Install using the `release` target. Instead of doing `make install` you - can create 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 (the top directory): - - $ ./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, and is what `make install` uses. - * `-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. - -* Test install using `EXTRA_PREFIX`. The content of the `EXTRA_PREFIX` - variable will prefix all installation paths when doing `make install`. - Note that `EXTRA_PREFIX` is similar to `DESTDIR`, but it does *not* have - the same effect as `DESTDIR`. The installation can and have to be run - from the location specified by `EXTRA_PREFIX`. 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`. - -### 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 -Erlang/OTP executables in `/usr/local/lib/erlang/bin`. 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 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. - -### 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, because you need to generate the -`configure` scripts before you can start building. - -The `configure` scripts are generated by invoking `./otp_build autoconf` in -the `$ERL_TOP` directory. The `configure` scripts also have to be regenerated -when a `configure.in` or `aclocal.m4` file has been modified. Note that when -checking out a branch a `configure.in` or `aclocal.m4` file may change -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*: 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: - - -### 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 -`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. - -The Erlang/OTP Documentation ----------------------------- - -### How to Build the Documentation ### - - $ cd $ERL_TOP - -If you have just built Erlang/OTP in the current source tree, you have -already ran `configure` and do not need to do this again; otherwise, run -`configure`. - - $ ./configure [Configure Args] - -When building the documentation you need a full Erlang/OTP-%OTP-REL% system in -the `$PATH`. - - $ export PATH=:$PATH # Assuming bash/sh - -Build the documentation. - - $ make docs - -The documentation can be installed either using the `install-docs` target, -or using the `release_docs` target. - -* If you have installed Erlang/OTP using the `install` target, install - the documentation using the `install-docs` target. Install locations - determined by `configure` will be used. `$DESTDIR` can be used the - same way as when doing `make install`. - - $ make install-docs - -* 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`. - - $ make release_docs RELEASE_ROOT= - -#### Build Issues #### - -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. - - $ export FOP_OPTS="-Xmxm" - -More information can be found at -. - -### How to Install the Pre-formatted Documentation ### - -Pre-formatted [html documentation][] and [man pages][] can be downloaded at -. - -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 - $ gunzip -c otp_html_%OTP-REL%.tar.gz | tar xf - - -For `erl -man ` to work the Unix manual pages have to be -installed in the same way, i.e. - - $ cd - $ gunzip -c otp_man_%OTP-REL%.tar.gz | tar xf - - -Where `` is - -* `/lib/erlang` if you have installed Erlang/OTP using - `make install`. -* `$DESTDIR/lib/erlang` if you have installed Erlang/OTP - using `make install DESTDIR=`. -* `RELEASE_ROOT` if you have installed using - `make release RELEASE_ROOT=`. - -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 does not -automatically enable SMP support, the build is very likely to fail. - -Use `./configure --disable-smp-support` if you for some reason do not -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`. - -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 is supported. 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. - - * Linux (Aurora) is supported. - -* 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) ------------------ - -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. - -Use the `--enable-darwin-64bit` configure flag to build a 64-bit -binaries on Mac OS X. - -Building universal binaries on Mac OS X (obsolete information) --------------------------------------------------------------- - -(This information was written when Mac OS X Leopard was the current -release. It may no longer work.) - -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. - -Building a fast Erlang VM on Mac OS Lion ----------------------------------------- - -Starting with Xcode 4.2, Apple no longer includes a "real" `gcc` -compiler (not based on the LLVM). Building with `llvm-gcc` or `clang` -will work, but the performance of the Erlang run-time system will not -be the best possible. - -Note that if you have `gcc-4.2` installed and included in `PATH` -(from a previous version of Xcode), `configure` will automatically -make sure that `gcc-4.2` will be used to compile `beam_emu.c` -(the source file most in need of `gcc`). - -If you don't have `gcc-4.2.` and want to build a run-time system with -the best possible performance, do like this: - -Install Xcode from the AppStore if it is not already installed. - -For Xcode 4.3 you will also need to download "Command Line Tools" -via the Downloads preference pane i Xcode. - -Some tools may still be lacking or out-of-date, we recommend using -[Homebrew](https://github.com/mxcl/homebrew/wiki/installation) or -Macports update those tools. - -Install MacPorts (). Then: - - $ sudo port selfupdate - $ sudo port install gcc45 +universal - -If you want to build the `wx` application, get wxMac-2.8.12 -(`wxMac-2.8.12.tar.gz` from -) and build: - -Export the path for MacOSX10.6.sdk, - - $ export SDK=/Developer/SDKs/MacOSX10.6.sdk - -In Xcode 4.3 the path has changed so use the following instead, - - $ export SDK=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.6.sdk - -Then configure and build wx, - - $ arch_flags="-arch i386" ./configure CFLAGS="$arch_flags" CXXFLAGS="$arch_flags" CPPFLAGS="$arch_flags" LDFLAGS="$arch_flags" OBJCFLAGS="$arch_flags" OBJCXXFLAGS="$arch_flags" --prefix=/usr/local --with-macosx-sdk="$SDK" --with-macosx-version-min=10.6 --enable-unicode --with-opengl --disable-shared - $ make - $ sudo make install - -To link wx properly we will also need to build and install `wxStyledTextCtrl` - - $ cd contrib/src/stc - $ make - $ sudo make install - -Build Erlang with the MacPorts GCC as the main compiler (using `clang` -for the Objective-C Cocoa code in the `wx` application): - - $ PATH=/usr/local/bin:$PATH CC=/opt/local/bin/gcc-mp-4.5 CXX=/opt/local/bin/g++-mp-4.5 ./configure --enable-m32-build make - $ sudo make install - - -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`, or `lcnt`. -These different beam types are useful for debugging and profiling -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. - -Copyright and License ---------------------- - -%CopyrightBegin% - -Copyright Ericsson AB 1998-2012. 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 . - -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 - - [?TOC]: true diff --git a/README.bootstrap b/README.bootstrap deleted file mode 100644 index f42bc7aa47..0000000000 --- a/README.bootstrap +++ /dev/null @@ -1,61 +0,0 @@ -Notes about prebuilt beam files under version control ------------------------------------------------------ - -This information applies mostly to developers, some parts only -to developers of the main branch i.e. Ericsson and HiPE personel. - -There are two types of derived code under version control, namely: - -primary bootstrap - Resides in the $ERL_TOP/bootstrap/{lib,bin} directories. -preloaded code - Resides in the $ERL_TOP/erts/preloaded directory. - -Primary bootstrap -................. - -The two types of version controlled code are fundamentally -different. The primary bootstrap is code compiled from source files in -the lib/{kernel,stdlib,compiler} (and header files from -lib/orber/include. They are checked in in the version control system -to make it possible to build directly from the code base tree without -the need for an earlier version of the compiler. When a new version of -OTP is released, these files are updated manually (or rather, by using -the $ERL_TOP/otp_build script) and checked in. The files can also be -updated due to changes in the compiler during the development -process. The primary bootstrap is always updated as a separate -deliberate process, never during a normal development build. - -If a prebuilt open source version of erlang is used, the directory -bootstrap initially does not contain any beam files, the directory is -instead populated by copying beam files from the -$ERL_TOP/lib/{kernel,stdlib,compiler}/ebin directories. This -construction is to save space in the distribution, but the result -would be the same. Open source developers need not provide patches for -the precompiled beam files in the primary bootstrap, the bootstrap -update is always performed by the main developers. - -Preloaded code -.............. - -The directory $ERL_TOP/preloaded contains both src and ebin -subdirectories. The preloaded code is compiled into the virtual -machine and always present. When compiling the virtual machine, those -beam files need to be present and they are considered a part of the -virtual machine rather than a part of the kernel application. When -preloaded files are to be updated, the source code is built using a -special Makefile in the $ERL_TOP/preloaded/src directory, which -creates beam files in the same directory. When they seem to compile -successfully, they can be used in an emulator build by being copied -to the ebin directory. otp_build update_preloaded can be used to -ease the process (there are also similar targets in the -$ERL_TOP/preloaded/src/Makefile). - -In prebuilt open source distributions, these beam files are also -present, but to update them one might need to change permission on the -$ERL_TOP/preloaded/ebin directory, then build and then manually copy -the beam files from the source directory to ../ebin. If patches are -created that involve the source files used to build preloaded code, -always note this specially as the preloaded/ebin directory needs -updating, or provide the new derived files in the patch or as complete -binaries. - -/Patrik, OTP diff --git a/README.dtrace.md b/README.dtrace.md deleted file mode 100644 index 5bc042f9fc..0000000000 --- a/README.dtrace.md +++ /dev/null @@ -1,393 +0,0 @@ -DTrace and Erlang/OTP -===================== - -History -------- - -The first implementation of DTrace probes for the Erlang virtual -machine was presented at the [2008 Erlang User Conference] [4]. That -work, based on the Erlang/OTP R12 release, was discontinued due to -what appears to be miscommunication with the original developers. - -Several users have created Erlang port drivers, linked-in drivers, or -NIFs that allow Erlang code to try to activate a probe, -e.g. `foo_module:dtrace_probe("message goes here!")`. - -Goals ------ - -1. Annotate as much of the Erlang VM as is practical. - * The initial goal is to trace file I/O operations. -2. Support all platforms that implement DTrace: OS X, Solaris, - and (I hope) FreeBSD and NetBSD. -3. To the extent that it's practical, support SystemTap on Linux - via DTrace provider compatibility. -4. Allow Erlang code to supply annotations. - -Supported platforms -------------------- - -* OS X 10.6.x / Snow Leopard. It should also work for 10.7 / Lion, - but I haven't personally tested it. -* Solaris 10. I have done limited testing on Solaris 11 and - OpenIndiana release 151a, and both appear to work. -* FreeBSD 9.0, though please see the "FreeBSD 9.0 Release Notes" - section below! -* Linux via SystemTap compatibility. Please see the file - `README.systemtap.md` for more details. - -Just add the `--with-dynamic-trace=dtrace` option to your command when you -run the `configure` script. If you are using systemtap, the configure option -is `--with-dynamic-trace=systemtap` - -Status ------- - -As of R15B01, the dynamic trace code is included in the main OTP distribution, -although it's considered experimental. The main development of the dtrace code -still happens outside of Ericsson, but there is no need to fetch a patched -version of OTP to get the basic funtionality. - -Implementation summary ----------------------- - -So far, most effort has been focused on the `efile_drv.c` code, -which implements most file I/O on behalf of the Erlang virtual -machine. This driver also presents a big challenge: its use of an I/O -worker pool (enabled by using the `erl +A 8` flag, for example) makes -it much more difficult to trace I/O activity because each of the -following may be executed in a different Pthread: - -* I/O initiation (Erlang code) -* I/O proxy process handling, e.g. read/write when file is not opened - in `raw` mode, operations executed by the code & file server processes. - (Erlang code) -* `efile_drv` command setup (C code) -* `efile_drv` command execution (C code) -* `efile_drv` status return (C code) - -**TODO: keep this description up-to-date.** - -Example output from `lib/dtrace/examples/efile_drv.d` while executing -`file:rename("old-name", "new-name")`: - - efile_drv enter tag={3,84} user tag some-user-tag | RENAME (12) | args: old-name new-name , 0 0 (port #Port<0.59>) - async I/O worker tag={3,83} | RENAME (12) | efile_drv-int_entry - async I/O worker tag={3,83} | RENAME (12) | efile_drv-int_return - efile_drv return tag={3,83} user tag | RENAME (12) | errno 2 - -... where the following key can help decipher the output: - -* `{3,83}` is the Erlang scheduler thread number (3) and operation - counter number (83) assigned to this I/O operation. Together, - these two numbers form a unique ID for the I/O operation. -* `12` is the command number for the rename operation. See the - definition for `FILE_RENAME` in the source code file `efile_drv.c` - or the `BEGIN` section of the D script `lib/dtrace/examples/efile_drv.d`. -* `old-name` and `new-name` are the two string arguments for the - source and destination of the `rename(2)` system call. - The two integer arguments are unused; the simple formatting code - prints the arguments anyway, 0 and 0. -* The worker pool code was called on behalf of Erlang port `#Port<0.59>`. -* The system call failed with a POSIX errno value of 2: `ENOENT`, - because the path `old-name` does not exist. -* The `efile_drv-int_entry` and `efile_drv_int_return` probes are - provided in case the user is - interested in measuring only the latency of code executed by - `efile_drv` asynchronous functions by I/O worker pool threads - and the OS system call that they encapsulate. - -So, where does the `some-user-tag` string come from? - -At the moment, the user tag comes from code like the following: - - put(dtrace_utag, "some-user-tag"), - file:rename("old-name", "new-name"). - -This method of tagging I/O at the Erlang level is subject to change. - -Example DTrace probe specification ----------------------------------- - - /** - * Fired when a message is sent from one local process to another. - * - * NOTE: The 'size' parameter is in machine-dependent words and - * that the actual size of any binary terms in the message - * are not included. - * - * @param sender the PID (string form) of the sender - * @param receiver the PID (string form) of the receiver - * @param size the size of the message being delivered (words) - * @param token_label for the sender's sequential trace token - * @param token_previous count for the sender's sequential trace token - * @param token_current count for the sender's sequential trace token - */ - probe message__send(char *sender, char *receiver, uint32_t size, - int token_label, int token_previous, int token_current); - - /** - * Fired when a message is sent from a local process to a remote process. - * - * NOTE: The 'size' parameter is in machine-dependent words and - * that the actual size of any binary terms in the message - * are not included. - * - * @param sender the PID (string form) of the sender - * @param node_name the Erlang node name (string form) of the receiver - * @param receiver the PID/name (string form) of the receiver - * @param size the size of the message being delivered (words) - * @param token_label for the sender's sequential trace token - * @param token_previous count for the sender's sequential trace token - * @param token_current count for the sender's sequential trace token - */ - probe message__send__remote(char *sender, char *node_name, char *receiver, - uint32_t size, - int token_label, int token_previous, int token_current); - - /** - * Fired when a message is queued to a local process. This probe - * will not fire if the sender's pid == receiver's pid. - * - * NOTE: The 'size' parameter is in machine-dependent words and - * that the actual size of any binary terms in the message - * are not included. - * - * @param receiver the PID (string form) of the receiver - * @param size the size of the message being delivered (words) - * @param queue_len length of the queue of the receiving process - * @param token_label for the sender's sequential trace token - * @param token_previous count for the sender's sequential trace token - * @param token_current count for the sender's sequential trace token - */ - probe message__queued(char *receiver, uint32_t size, uint32_t queue_len, - int token_label, int token_previous, int token_current); - - /** - * Fired when a message is 'receive'd by a local process and removed - * from its mailbox. - * - * NOTE: The 'size' parameter is in machine-dependent words and - * that the actual size of any binary terms in the message - * are not included. - * - * @param receiver the PID (string form) of the receiver - * @param size the size of the message being delivered (words) - * @param queue_len length of the queue of the receiving process - * @param token_label for the sender's sequential trace token - * @param token_previous count for the sender's sequential trace token - * @param token_current count for the sender's sequential trace token - */ - probe message__receive(char *receiver, uint32_t size, uint32_t queue_len, - int token_label, int token_previous, int token_current); - - /* ... */ - - /* Async driver pool */ - - /** - * Show the post-add length of the async driver thread pool member's queue. - * - * NOTE: The port name is not available: additional lock(s) must - * be acquired in order to get the port name safely in an SMP - * environment. The same is true for the aio__pool_get probe. - * - * @param port the Port (string form) - * @param new queue length - */ - probe aio_pool__add(char *, int); - - /** - * Show the post-get length of the async driver thread pool member's queue. - * - * @param port the Port (string form) - * @param new queue length - */ - probe aio_pool__get(char *, int); - - /* Probes for efile_drv.c */ - - /** - * Entry into the efile_drv.c file I/O driver - * - * For a list of command numbers used by this driver, see the section - * "Guide to probe arguments" in ../../../README.md. That section - * also contains explanation of the various integer and string - * arguments that may be present when any particular probe fires. - * - * TODO: Adding the port string, args[10], is a pain. Making that - * port string available to all the other efile_drv.c probes - * will be more pain. Is the pain worth it? If yes, then - * add them everywhere else and grit our teeth. If no, then - * rip it out. - * - * @param thread-id number of the scheduler Pthread arg0 - * @param tag number: {thread-id, tag} uniquely names a driver operation - * @param user-tag string arg2 - * @param command number arg3 - * @param string argument 1 arg4 - * @param string argument 2 arg5 - * @param integer argument 1 arg6 - * @param integer argument 2 arg7 - * @param integer argument 3 arg8 - * @param integer argument 4 arg9 - * @param port the port ID of the busy port args[10] - */ - probe efile_drv__entry(int, int, char *, int, char *, char *, - int64_t, int64_t, int64_t, int64_t, char *); - - /** - * Entry into the driver's internal work function. Computation here - * is performed by a async worker pool Pthread. - * - * @param thread-id number - * @param tag number - * @param command number - */ - probe efile_drv__int_entry(int, int, int); - - /** - * Return from the driver's internal work function. - * - * @param thread-id number - * @param tag number - * @param command number - */ - probe efile_drv__int_return(int, int, int); - - /** - * Return from the efile_drv.c file I/O driver - * - * @param thread-id number arg0 - * @param tag number arg1 - * @param user-tag string arg2 - * @param command number arg3 - * @param Success? 1 is success, 0 is failure arg4 - * @param If failure, the errno of the error. arg5 - */ - probe efile_drv__return(int, int, char *, int, int, int); - -Guide to efile_drv.c probe arguments ------------------------------------- - - /* Driver op code: used by efile_drv-entry arg3 */ - /* used by efile_drv-int_entry arg3 */ - /* used by efile_drv-int_return arg3 */ - /* used by efile_drv-return arg3 */ - - #define FILE_OPEN 1 (probe arg3) - probe arg6 = C driver dt_i1 = flags; - probe arg4 = C driver dt_s1 = path; - - #define FILE_READ 2 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - probe arg7 = C driver dt_i2 = flags; - probe arg8 = C driver dt_i3 = size; - - #define FILE_LSEEK 3 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - probe arg7 = C driver dt_i2 = offset; - probe arg8 = C driver dt_i3 = origin; - - #define FILE_WRITE 4 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - probe arg7 = C driver dt_i2 = flags; - probe arg8 = C driver dt_i3 = size; - - #define FILE_FSTAT 5 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - - #define FILE_PWD 6 (probe arg3) - none - - #define FILE_READDIR 7 (probe arg3) - probe arg4 = C driver dt_s1 = path; - - #define FILE_CHDIR 8 (probe arg3) - probe arg4 = C driver dt_s1 = path; - - #define FILE_FSYNC 9 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - - #define FILE_MKDIR 10 (probe arg3) - probe arg4 = C driver dt_s1 = path; - - #define FILE_DELETE 11 (probe arg3) - probe arg4 = C driver dt_s1 = path; - - #define FILE_RENAME 12 (probe arg3) - probe arg4 = C driver dt_s1 = old_name; - probe arg5 = C driver dt_s2 = new_name; - - #define FILE_RMDIR 13 (probe arg3) - probe arg4 = C driver dt_s1 = path; - - #define FILE_TRUNCATE 14 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - probe arg7 = C driver dt_i2 = flags; - - #define FILE_READ_FILE 15 (probe arg3) - probe arg4 = C driver dt_s1 = path; - - #define FILE_WRITE_INFO 16 (probe arg3) - probe arg6 = C driver dt_i1 = mode; - probe arg7 = C driver dt_i2 = uid; - probe arg8 = C driver dt_i3 = gid; - - #define FILE_LSTAT 19 (probe arg3) - probe arg4 = C driver dt_s1 = path; - - #define FILE_READLINK 20 (probe arg3) - probe arg4 = C driver dt_s1 = path; - - #define FILE_LINK 21 (probe arg3) - probe arg4 = C driver dt_s1 = existing_path; - probe arg5 = C driver dt_s2 = new_path; - - #define FILE_SYMLINK 22 (probe arg3) - probe arg4 = C driver dt_s1 = existing_path; - probe arg5 = C driver dt_s2 = new_path; - - #define FILE_CLOSE 23 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - probe arg7 = C driver dt_i2 = flags; - - #define FILE_PWRITEV 24 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - probe arg7 = C driver dt_i2 = flags; - probe arg8 = C driver dt_i3 = size; - - #define FILE_PREADV 25 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - probe arg7 = C driver dt_i2 = flags; - probe arg8 = C driver dt_i3 = size; - - #define FILE_SETOPT 26 (probe arg3) - probe arg6 = C driver dt_i1 = opt_name; - probe arg7 = C driver dt_i2 = opt_specific_value; - - #define FILE_IPREAD 27 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - probe arg7 = C driver dt_i2 = flags; - probe arg8 = C driver dt_i3 = offsets[0]; - probe arg9 = C driver dt_i4 = size; - - #define FILE_ALTNAME 28 (probe arg3) - probe arg4 = C driver dt_s1 = path; - - #define FILE_READ_LINE 29 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - probe arg7 = C driver dt_i2 = flags; - probe arg8 = C driver dt_i3 = read_offset; - probe arg9 = C driver dt_i4 = read_ahead; - - #define FILE_FDATASYNC 30 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - - #define FILE_FADVISE 31 (probe arg3) - probe arg6 = C driver dt_i1 = fd; - probe arg7 = C driver dt_i2 = offset; - probe arg8 = C driver dt_i3 = length; - probe arg9 = C driver dt_i4 = advise_type; - - [1]: http://www.erlang.org/euc/08/ diff --git a/README.md b/README.md index c38f097b0f..b7addf72e2 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Building and Installing ----------------------- Information on building and installing Erlang/OTP can be found -in the `INSTALL.md` document. +in the [$ERL_TOP/HOWTO/INSTALL.md][] document. Contributing to Erlang/OTP -------------------------- @@ -74,3 +74,4 @@ Copyright and License [1]: http://www.erlang.org [2]: http://wiki.github.com/erlang/otp/submitting-patches [3]: http://www.erlang.org/faq.html + [$ERL_TOP/HOWTO/INSTALL.md]: HOWTO/INSTALL.md diff --git a/README.md.txt b/README.md.txt deleted file mode 100644 index a5a1bf4b7d..0000000000 --- a/README.md.txt +++ /dev/null @@ -1,266 +0,0 @@ -Erlangish Markdown Text Files -============================= - -Introduction ------------- - -If you are looking for information on how to build and install Erlang/OTP you -want to read the [$ERL_TOP/INSTALL.md][] document instead of this document -(where `$ERL_TOP` is the top source directory in the source tree). - -All files with the `.md` suffix (as well as this file) are ordinary text files -written using a Markdown like notation, and can be read using an ordinary text -editor such as for example `emacs`. - -This document describes how `*.md` files in the Erlang/OTP source tree should -be written. - -> *NOTE*: Before modifying a `*.md` file read all of this document. - -Erlangish Markdown ------------------- - -We do not use Markdown straight out of the box. The Markdown syntax we use is -similar to the original Markdown but with a number of tweaks. The original -Markdown is documented at . You -should read that documentation as well as this document before modifying any -Erlangish Markdown files in the Erlang/OTP source tree. - -The original Markdown syntax was designed for generating HTML code from an -"easy to read/easy to write" plain text. Instead of generating HTML we generate -XML that fits into our documentation, i.e. we generate Erlangish XML from -Erlangish Markdown. - -The `.md` suffix has been chosen since [github][] will generate HTML pages for -files with the `.md` suffix. Github does however not generate HTML according to -Erlangish Markdown, so some features do not work. The Erlangish Markdown -documents viewed at [our github repository][] will typically suffer from broken -links. The original Markdown script, gitub's Markdown, and our Erlangish -Markdown script will generate somewhat different results if you do not follow -indentation rules outlined in the Markdown documentation. You are encouraged to -try to write using a Markdown syntax that also looks nice on github. However, -it is *much* more important that the document is formatted correct in the -Erlang/OTP documentation. - -### Differences Between Markdown and Erlangish Markdown ### - -#### Missing Features #### - -This functionality is missing compared to Markdown version 1.0.1. Do not -depend on the fact that these features are missing. Some of them might appear -in the future. - -* No inline HTML. Currently no inline XML is allowed either. Inline XML might - be allowed in the future, but there is no real need for it since we use - Erlangish Markdown for "readme"s that have a main purpose of being readable - in plain text. - -* Backslash escapes all characters. - -* No support for "horizontal rules". - -* Links. - * No support for the "title" attribute. - * Automatic links does not support email addresses. - -* Images. - * No support for the "title" attribute. Specified "title" will however - be used as ``. - * No support for the "alt" attribute. - -* Lists aren't supported inside block quotes. - -* Link and image definition names *are* case sensitive. - -#### Additional Features #### - -* Automatic anchors at each heading. - -* Optionally automatically generated table of contents. - -* Note blocks. - -* Warning blocks. - -#### Extra requirements #### - -* One and only one level 1 heading is allowed and required. - -* The level 1 heading must be the first heading in the document. - -* A level `X` heading must have a level `X-1` heading as parent heading. - -* Link and image definition names aren't allowed to begin with a - question mark (?) character. Names beginning with a question mark have - been reserved for other use. - -* The encoding of the file containing Erlangish Markdown should be - UTF-8. - -### Generated XML ### - -> *WARNING*: The `emd2exml` script will blindly generate XML code according -> to the Erlangish Markdown in a file. Successfully generated XML does **not** -> imply that the generated XML adheres to used DTDs. `emd2exml` does very -> seldom fail and can easily generate XML that will cause the documentation -> build to fail. You always have to keep in mind that the XML generated -> should fit the chapter DTD of Erlang/OTP. Also note that even though HTML -> generation succeeds the PDF generation might fail, etc. -> -> *Always build the Erlang/OTP documentation after modifying an Erlangish -> Markdown document!* - -A note about how we talk about "tags" below. When we say "generate(s) `` -tags" this also imply that ending `` tags will be generated at appropriate -places. Appropriate attributes to the `X` tag will also be generated. - -* Inline and reference style links will either generate `` tags - or `` tags. If a "://" character sequence is found in the URL an - `` tag will be generated; otherwise, a `` tag is generated. - -* Automatic links will only generate `` tags. This since a - "://" character sequence have to be present in the URL in order - for the link to be identified. - -* Inline and reference style images will generate a ` - ... ` sequence where the "title" will be - placed between `` and ``. - -* Block quotes generate `
` tags. - -* If the first line of a top level block quote begins with a `> *NOTE*:` - character sequence, a `` tag will be generated instead of a - `
` tag. The note will span the entire block quote. - -* If the first line of a top level block quote begins with a `> *WARNING*:` - character sequence, a `` tag will be generated instead of a - `
` tag. The warning will span the entire block quote. - -* Paragraphs will generate `

` tags. - -* Break line (double trailing white space) will generate `
` tags. - -* An unordered list generates a `` tag and `` - tags for each item. - -* An ordered list generates a `` tag and `` tags - for each item. - -* Code blocks will generate `` tags. - -* Code span (backticks) will generate `` tags. - -* Emphasis (single `*` or `_`) will generate `` tags. - -* Strong emphasis (double `*` or `_`) will generate `` tags. - -* The level 1 heading will cause the following to be generated: - - - - -

- - ... - - - ... - - - ... - ... - ... -
- - ... - - - - The content of copyright section and the legalnotice section will - contain information from a \%CopyrightBegin\%, \%CopyrightEnd\% block - if such exist (see below). - -* A level `X` heading where `1 < X <= 3` will cause the the following - to be generated: - - -
- ... - ... -
- - The marker id is automatically generated as a combination of all parent - headings up to and including level 2 separated by a `_` character. As in - `__ ... _` - where each "marker heading" is constructed as follows. All characters a-z - and A-Z are kept as they are, space and tab characters are replaced by - `-` characters, and all other characters are dropped. - - This way it is relatively easy to make sure that all marker ids of a - document are unique, but there is of course no guarantee that they are. - - The upside of these auto generated markers is that we wont have to clutter - the document with XML or something else while being able to refer into - the document. The downside is that if you change a level 2 heading you - change a lot of marker ids which may break links into a document from - other documents. That is, *be careful* when changing headings in an - existing document. - -* A level `X` heading where `3 < X` will cause the the following - to be generated: - - -

...

- ... - - Current DTD:s used don't support deeper levels of sections, and we - therefore simulate a section this way. The marker id is generated as for - a true section (see above). - -* If a section enclosed by \%CopyrightBegin\% and \%CopyrightEnd\% is - encountered, it will be interpreted as an EPL copyright and license, - and will be used in the header section of the document. The - \%CopyrightBegin\% and \%CopyrightEnd\% "tags" will be removed from - the output. - -* All occurrences of \%OTP-REL% will be replaced by current release number - (e.g. R14A). - -* All occurrences of \%ERTS-VSN% will be replaced by current ERTS version - (e.g. 5.8). - -* Adding a `[?TOC]: true` line (optionally indented with three spaces) - anywhere in the document will cause a table of contents to be automatically - generated at the beginning of the generated document. - -* Unicode characters (encoded in UTF-8) are allowed and will be passed - through as is to the output file. - -Copyright and License ---------------------- - -%CopyrightBegin% - -Copyright Ericsson AB 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% - - - - [$ERL_TOP/INSTALL.md]: doc/installation_guide:INSTALL - [github]: http://github.com - [our github repository]: http://github.com/erlang/otp - - - [?TOC]: true diff --git a/README.systemtap.md b/README.systemtap.md deleted file mode 100644 index c190bcc893..0000000000 --- a/README.systemtap.md +++ /dev/null @@ -1,72 +0,0 @@ -SystemTap and Erlang/OTP -======================== - -Introduction ------------- - -SystemTap is DTrace for Linux. In fact Erlang's SystemTap support -is build using SystemTap's DTrace compatibility's layer. For an -introduction to Erlang DTrace support read README.dtrace.md. - -Requisites ----------- - -* Linux Kernel with UTRACE support - - check for UTRACE support in your current kernel: - - # grep CONFIG_UTRACE /boot/config-`uname -r` - CONFIG_UTRACE=y - - Fedora 16 is known to contain UTRACE, for most other Linux distributions - a custom build kernel will be required. - Check Fedora's SystemTap documentation for additional required packages - (e.g. Kernel Debug Symbols) - -* SystemTap > 1.6 - - A the time of writing this, the latest released version of SystemTap is - version 1.6. Erlang's DTrace support requires a MACRO that was introduced - after that release. So either get a newer release or build SystemTap from - git yourself (see: http://sourceware.org/systemtap/getinvolved.html) - -Building Erlang ---------------- - -Configure and build Erlang with SystemTap support: - - # ./configure --with-dynamic-trace=systemtap + whatever args you need - # make - -Testing -------- - -SystemTap, unlike DTrace, needs to know what binary it is tracing and has to -be able to read that binary before it starts tracing. Your probe script -therefor has to reference the correct beam emulator and stap needs to be able -to find that binary. -The examples are written for "beam", but other versions such as "beam.smp" or -"beam.debug.smp" might exist (depending on your configuration). Make sure you -either specify the full the path of the binary in the probe or your "beam" -binary is in the search path. - -All available probes can be listed like this: - - # stap -L 'process("beam").mark("*")' - -or: - - # PATH=/path/to/beam:$PATH stap -L 'process("beam").mark("*")' - - -Probes in the dtrace.so NIF library like this: - - # PATH=/path/to/dtrace/priv/lib:$PATH stap -L 'process("dtrace.so").mark("*")' - -Running SystemTap scripts -------------------------- - -Adjust the process("beam") reference to your beam version and attach the script -to a running "beam" instance: - - # stap /path/to/probe/script/port1.systemtap -x diff --git a/TAR.include b/TAR.include index 5146458eea..87854d24c7 100644 --- a/TAR.include +++ b/TAR.include @@ -2,10 +2,10 @@ AUTHORS EPLICENCE Makefile.in README.md -README.md.txt -INSTALL.md -INSTALL-CROSS.md -INSTALL-WIN32.md +HOWTO/MARKDOWN.md +HOWTO/INSTALL.md +HOWTO/INSTALL-CROSS.md +HOWTO/INSTALL-WIN32.md configure.in aclocal.m4 otp_build diff --git a/erts/emulator/beam/erlang_dtrace.d b/erts/emulator/beam/erlang_dtrace.d index c1024dafc4..ac9b0052e5 100644 --- a/erts/emulator/beam/erlang_dtrace.d +++ b/erts/emulator/beam/erlang_dtrace.d @@ -639,9 +639,9 @@ provider erlang { * Entry into the efile_drv.c file I/O driver * * For a list of command numbers used by this driver, see the section - * "Guide to probe arguments" in ../../../README.md. That section - * also contains explanation of the various integer and string - * arguments that may be present when any particular probe fires. + * "Guide to efile_drv.c probe arguments" in ../../../HOWTO/DTRACE.md. + * That section also contains explanation of the various integer and + * string arguments that may be present when any particular probe fires. * * NOTE: Not all Linux platforms (using SystemTap) can support * arguments beyond arg9. diff --git a/lib/runtime_tools/doc/src/dyntrace.xml b/lib/runtime_tools/doc/src/dyntrace.xml index 5fc5530f25..9bcbdfc19a 100644 --- a/lib/runtime_tools/doc/src/dyntrace.xml +++ b/lib/runtime_tools/doc/src/dyntrace.xml @@ -42,7 +42,7 @@

Both building with dynamic trace probes and using them is experimental and unsupported by Erlang/OTP. It is included as an option for the developer to trace and debug performance issues in their systems.

The original implementation is mostly done by Scott Lystiger Fritchie as an Open Source Contribution and it should be viewed as such even though the source for dynamic tracing as well as this module is included in the main distribution. However, the ability to use dynamic tracing of the virtual machine is a very valuable contribution which OTP has every intention to maintain as a tool for the developer.

-

How to write d programs or systemtap scripts can be learned from books and from a lot of pages on the Internet. This manual page does not include any documentation about using the dynamic trace tools of respective platform. The examples directory of the runtime_tools application however contains comprehensive examples of both d and systemtap programs that will help you get started. Another source of information is the README.dtrace(.md) and README.systemtap(.md) files in the Erlang source top directory.

+

How to write d programs or systemtap scripts can be learned from books and from a lot of pages on the Internet. This manual page does not include any documentation about using the dynamic trace tools of respective platform. The examples directory of the runtime_tools application however contains comprehensive examples of both d and systemtap programs that will help you get started. Another source of information is the DTRACE(.md) and SYSTEMTAP(.md) files in the HOWTO folder in the Erlang source directory.

diff --git a/make/emd2exml.in b/make/emd2exml.in index 16c38379d9..5bf7758be3 100644 --- a/make/emd2exml.in +++ b/make/emd2exml.in @@ -994,7 +994,7 @@ resolve_link([_|Cs], start, "", "", "") -> resolve_link(Cs, start, "", "", ""); resolve_link("]:" ++ Rest, key, Yek, "", "") -> resolve_link(Rest, url, Yek, "", ""); -resolve_link([C|Cs], url, Yek, Lru, "") when C == $"; C == $' -> +resolve_link([C|Cs], url, Yek, Lru, "") when C == $"; C == $' -> %" resolve_link(Cs, {title, C}, Yek, Lru, ""); resolve_link([$(|Cs], url, Yek, Lru, "") -> resolve_link(Cs, {title, $)}, Yek, Lru, ""); @@ -1010,9 +1010,21 @@ resolve_link([_|Cs], drop, Yek, Lru, Eltit) -> resolve_link(Cs, drop, Yek, Lru, Eltit); resolve_link([], _, Yek, Lru, Eltit) -> {ws_strip(lists:reverse(Yek)), - ws_strip(lists:reverse(Lru)), + ws_strip(md_strip_n_reverse(Lru)), ws_strip(lists:reverse(Eltit))}. +%% Remove .md at end of references. +md_strip_n_reverse(Lru) -> + md_strip_n_reverse(Lru,[]). +md_strip_n_reverse("\ndm."++Lru,Acc) -> + md_strip_n_reverse(Lru,Acc); +md_strip_n_reverse("#dm."++Lru,Acc) -> + md_strip_n_reverse(Lru,[$#|Acc]); +md_strip_n_reverse([C|T],Acc) -> + md_strip_n_reverse(T,[C|Acc]); +md_strip_n_reverse([], Acc) -> + Acc. + %% %% Misc %% diff --git a/system/doc/installation_guide/Makefile b/system/doc/installation_guide/Makefile index 4636650570..5ad9af4be9 100644 --- a/system/doc/installation_guide/Makefile +++ b/system/doc/installation_guide/Makefile @@ -58,7 +58,8 @@ XML_FILES = \ GENERATED_XML_FILES = \ INSTALL.xml \ INSTALL-CROSS.xml \ - INSTALL-WIN32.xml + INSTALL-WIN32.xml \ + MARKDOWN.xml # ---------------------------------------------------- @@ -73,7 +74,8 @@ REDIRECT_HTML_DIR = $(HTMLDIR)/source REDIRECT_HTML_FILES = \ $(REDIRECT_HTML_DIR)/INSTALL.html \ $(REDIRECT_HTML_DIR)/INSTALL-CROSS.html \ - $(REDIRECT_HTML_DIR)/INSTALL-WIN32.html + $(REDIRECT_HTML_DIR)/INSTALL-WIN32.html \ + $(REDIRECT_HTML_DIR)/MARKDOWN.html # ---------------------------------------------------- # FLAGS @@ -85,7 +87,7 @@ DVIPS_FLAGS += # Targets # ---------------------------------------------------- -%.xml: $(ERL_TOP)/%.md $(ERL_TOP)/make/emd2exml +%.xml: $(ERL_TOP)/HOWTO/%.md $(ERL_TOP)/make/emd2exml $(ERL_TOP)/make/emd2exml $< $@ $(REDIRECT_HTML_DIR)/%.html: Makefile diff --git a/system/doc/installation_guide/part.xml b/system/doc/installation_guide/part.xml index fceacdd8f6..648beb0afd 100644 --- a/system/doc/installation_guide/part.xml +++ b/system/doc/installation_guide/part.xml @@ -36,5 +36,5 @@ - - + + \ No newline at end of file diff --git a/system/doc/installation_guide/xmlfiles.mk b/system/doc/installation_guide/xmlfiles.mk index dee67b3c70..8ea2b296aa 100644 --- a/system/doc/installation_guide/xmlfiles.mk +++ b/system/doc/installation_guide/xmlfiles.mk @@ -21,4 +21,5 @@ INST_GUIDE_CHAPTER_FILES = \ verification.xml \ INSTALL.xml \ INSTALL-CROSS.xml \ - INSTALL-WIN32.xml + INSTALL-WIN32.xml \ + MARKDOWN.xml diff --git a/xcomp/README.md b/xcomp/README.md deleted file mode 100644 index 5f4b36bdca..0000000000 --- a/xcomp/README.md +++ /dev/null @@ -1,555 +0,0 @@ -Cross Compiling Erlang/OTP -========================== - -Introduction ------------- - -This document describes how to cross compile Erlang/OTP-%OTP-REL%. Note that -the support for cross compiling Erlang/OTP should be considered as -experimental. As far as we know, the %OTP-REL% release should cross compile -fine, but since we currently have a very limited set of cross compilation -environments to test with we cannot be sure. The cross compilation support -will remain in an experimental state until we get a lot more cross compilation -environments to test with. - -You are advised to read the whole document before attempting to cross -compile Erlang/OTP. However, before reading this document, you should read -the [$ERL_TOP/INSTALL.md][] document which describes building and installing -Erlang/OTP in general. `$ERL_TOP` is the top directory in the source tree. - -### otp\_build Versus configure/make ### - -Building Erlang/OTP can be done either by using the `$ERL_TOP/otp_build` -script, or by invoking `$ERL_TOP/configure` and `make` directly. Building using -`otp_build` is easier since it involves fewer steps, but the `otp_build` build -procedure is not as flexible as the `configure`/`make` build procedure. Note -that `otp_build configure` will produce a default configuration that differs -from what `configure` will produce by default. For example, currently -`--disable-dynamic-ssl-lib` is added to the `configure` command line arguments -unless `--enable-dynamic-ssl-lib` has been explicitly passed. The binary -releases that we deliver are built using `otp_build`. The defaults used by -`otp_build configure` may change at any time without prior notice. - -### Cross Configuration ### - -The `$ERL_TOP/xcomp/erl-xcomp.conf.template` file contains all available cross -configuration variables and can be used as a template when creating a cross -compilation configuration. All [cross configuration variables][] are also -listed at the end of this document. For examples of working cross -configurations see the `$ERL_TOP/xcomp/erl-xcomp-TileraMDE2.0-tilepro.conf` -file and the `$ERL_TOP/xcomp/erl-xcomp-x86_64-saf-linux-gnu.conf` file. If the -default behavior of a variable is satisfactory, the variable does not need to -be set. However, the `configure` script will issue a warning when a default -value is used. When a variable has been set, no warning will be issued. - -A cross configuration file can be passed to `otp_build configure` using the -`--xcomp-conf` command line argument. Note that `configure` does not accept -this command line argument. When using the `configure` script directly, pass -the configuration variables as arguments to `configure` using a -`=` syntax. Variables can also be passed as environment -variables to `configure`. However, if you pass the configuration in the -environment, make sure to unset all of these environment variables before -invoking `make`; otherwise, the environment variables might set make variables -in some applications, or parts of some applications, and you may end up with -an erroneously configured build. - -### What can be Cross Compiled? ### - -All Erlang/OTP applications except the `wx` application can be cross compiled. -The build of the `wx` driver will currently be automatically disabled when -cross compiling. - -### Compatibility ### - -The build system, including cross compilation configuration variables used, -may be subject to non backward compatible changes without prior notice. -Current cross build system has been tested when cross compiling some Linux/GNU -systems, but has only been partly tested for more esoteric platforms. The -VxWorks example file is highly dependent on our environment and is here more -or less only for internal use. - -### Patches ### - -Please submit any patches for cross compiling in a way consistent with this -system. All input is welcome as we have a very limited set of cross compiling -environments to test with. If a new configuration variable is needed, add it -to `$ERL_TOP/xcomp/erl-xcomp.conf.template`, and use it in `configure.in`. -Other files that might need to be updated are: - -- `$ERL_TOP/xcomp/erl-xcomp-vars.sh` -- `$ERL_TOP/erl-build-tool-vars.sh` -- `$ERL_TOP/erts/aclocal.m4` -- `$ERL_TOP/xcomp/README.md` -- `$ERL_TOP/xcomp/erl-xcomp-*.conf` - -Note that this might be an incomplete list of files that need to be updated. - -General information on how to submit patches can be found at: - - -Build and Install Procedure ---------------------------- - -If you are building in Git, you want to read the [Building in Git][] section -of [$ERL_TOP/INSTALL.md][] before proceeding. - -We will first go through the `configure`/`make` build procedure which people -probably are most familiar with. - -### Building With configure/make Directly ### - - (1) - -Change directory into the top directory of the Erlang/OTP source tree. - - $ cd $ERL_TOP - -In order to compile Erlang code, a small Erlang bootstrap system has to be -built, or an Erlang/OTP system of the same release as the one being built -has to be provided in the `$PATH`. The Erlang/OTP for the target system will -be built using this Erlang system, together with the cross compilation tools -provided. - -If you want to build the documentation out of the same source tree as you are -cross compiling in, you currently need a full Erlang/OTP system of the same -release as the one being built for the build machine. If this is the case, -build and install one for the build machine (or use one already built) and add -it to the `$PATH` before cross building, and building the documentation. See -the [How to Build the Documentation][] section in the [$ERL_TOP/INSTALL.md][] -document for information on how to build the documentation. - -If you want to build using a compatible Erlang/OTP system in the `$PATH`, -jump to (3). - -#### Building a Bootstrap System #### - - (2) - - $ ./configure --enable-bootstrap-only - $ make - -The `--enable-bootstrap-only` argument to `configure` isn't strictly necessary, -but will speed things up. It will only run `configure` in applications -necessary for the bootstrap, and will disable a lot of things not needed by -the bootstrap system. If you run `configure` without `--enable-boostrap-only` -you also have to run make as `make bootstrap`; otherwise, the whole system will -be built. - -#### Cross Building the System #### - - (3) - - $ ./configure --host= --build= [Other Config Args] - $ make - -`` is the host/target system that you build for. It does not have to be -a full `CPU-VENDOR-OS` triplet, but can be. The full `CPU-VENDOR-OS` triplet -will be created by executing `$ERL_TOP/erts/autoconf/config.sub `. If -`config.sub` fails, you need to be more specific. - -`` should equal the `CPU-VENDOR-OS` triplet of the system that you -build on. If you execute `$ERL_TOP/erts/autoconf/config.guess`, it will in -most cases print the triplet you want to use for this. - -Pass the cross compilation variables as command line arguments to `configure` -using a `=` syntax. - -> *NOTE*: You can *not* pass a configuration file using the `--xcomp-conf` -> argument when you invoke `configure` directly. The `--xcomp-conf` argument -> can only be passed to `otp_build configure`. - -`make` will verify that the Erlang/OTP system used when building is of the -same release as the system being built, and will fail if this is not the case. -It is possible, however not recommended, to force the cross compilation even -though the wrong Erlang/OTP system is used. This by invoking `make` like this: -`make ERL_XCOMP_FORCE_DIFFERENT_OTP=yes`. - -> *WARNING*: Invoking `make ERL_XCOMP_FORCE_DIFFERENT_OTP=yes` might fail, -> silently produce suboptimal code, or silently produce erroneous code. - -#### Installing #### - -You can either install using the installation paths determined by `configure` -(4), or install manually using (5). - -##### Installing Using Paths Determined by configure ##### - - (4) - - $ make install DESTDIR= - -`make install` will install at a location specified when doing `configure`. -`configure` arguments specifying where the installation should reside are for -example: `--prefix`, `--exec-prefix`, `--libdir`, `--bindir`, etc. By default -it will install under `/usr/local`. You typically do not want to install your -cross build under `/usr/local` on your build machine. Using [DESTDIR][] -will cause the installation paths to be prefixed by `$DESTDIR`. This makes it -possible to install and package the installation on the build machine without -having to place the installation in the same directory on the build machine as -it should be executed from on the target machine. - -When `make install` has finished, change directory into `$DESTDIR`, package -the system, move it to the target machine, and unpack it. Note that the -installation will only be working on the target machine at the location -determined by `configure`. - -##### Installing Manually ##### - - (5) - - $ make release RELEASE_ROOT= - -`make release` will copy what you have built for the target machine to -``. The `Install` script will not be run. The content of -`` is what by default ends up in `/usr/local/lib/erlang`. - -The `Install` script used when installing Erlang/OTP requires common Unix -tools such as `sed` to be present in your `$PATH`. If your target system -does not have such tools, you need to run the `Install` script on your -build machine before packaging Erlang/OTP. The `Install` script should -currently be invoked as follows in the directory where it resides -(the top directory): - - $ ./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, and is what `make install` uses. -* `-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. - -You can now either do: - - (6) - -* Decide where the installation should be located on the target machine, - run the `Install` script on the build machine, and package the installed - installation. The installation just need to be unpacked at the right - location on the target machine: - - $ cd - $ ./Install -cross [-minimal|-sasl] - -or: - - (7) - -* Package the installation in ``, place it wherever you want - on your target machine, and run the `Install` script on your target - machine: - - $ cd - $ ./Install [-minimal|-sasl] - -### Building With the otp\_build Script ### - - (8) - - $ cd $ERL_TOP - - (9) - - $ ./otp_build configure --xcomp-conf= [Other Config Args] - -alternatively: - - $ ./otp_build configure --host= --build= [Other Config Args] - -If you have your cross compilation configuration in a file, pass it using the -`--xcomp-conf=` command line argument. If not, pass `--host=`, -`--build=`, and the configuration variables using a `=` -syntax on the command line (same as in (3)). Note that `` and `` -have to be passed one way or the other; either by using `erl_xcomp_host=` -and `erl_xcomp_build=` in the configuration file, or by using the -`--host=`, and `--build=` command line arguments. - -`otp_build configure` will configure both for the boostrap system on the -build machine and the cross host system. - - (10) - - $ ./otp_build boot -a - -`otp_build boot -a` will first build a bootstrap system for the build machine -and then do the cross build of the system. - - (11) - - $ ./otp_build release -a - -`otp_build release -a` will do the same as (5), and you will after this have -to do a manual install either by doing (6), or (7). - -Testing the cross compiled system --------------------------------------- -Some of the tests that come with erlang use native code to test. This means -that when cross compiling erlang you also have to cross compile test suites -in order to run tests on the target host. To do this you first have to release -the tests as usual. - - $ make release_tests - -or - - $ ./otp_build tests - -The tests will be released into `$ERL_TOP/release/tests`. After releasing the -tests you have to install the tests on the build machine. You supply the same -xcomp file as to `./otp_build` in (9). - - $ cd $ERL_TOP/release/tests/test_server/ - $ $ERL_TOP/bootstrap/bin/erl -eval 'ts:install([{xcomp,""}])' -s ts compile_testcases -s init stop - -You should get a lot of printouts as the testcases are compiled. Once done you -should copy the entire `$ERL_TOP/release/tests` folder to the cross host system. - -Then go to the cross host system and setup the erlang installed in (4) or (5) -to be in your `$PATH`. Then go to what previously was -`$ERL_TOP/release/tests/test_server` and issue the following command. - - $ erl -s ts install -s ts run all_tests -s init stop - -The configure should be skipped and all tests should hopefully pass. For more -details about how to use ts run `erl -s ts help -s init stop` - -Currently Used Configuration Variables --------------------------------------- - -Note that you cannot define arbitrary variables in a cross compilation -configuration file. Only the ones listed below will be guaranteed to be -visible throughout the whole execution of all `configure` scripts. Other -variables needs to be defined as arguments to `configure` or exported in -the environment. - -### Variables for otp\_build Only ### - -Variables in this section are only used, when configuring Erlang/OTP for -cross compilation using `$ERL_TOP/otp_build configure`. - -> *NOTE*: These variables currently have *no* effect if you configure using -> the `configure` script directly. - -* `erl_xcomp_build` - The build system used. This value will be passed as - `--build=$erl_xcomp_build` argument to the `configure` script. It does - not have to be a full `CPU-VENDOR-OS` triplet, but can be. The full - `CPU-VENDOR-OS` triplet will be created by - `$ERL_TOP/erts/autoconf/config.sub $erl_xcomp_build`. If set to `guess`, - the build system will be guessed using - `$ERL_TOP/erts/autoconf/config.guess`. - -* `erl_xcomp_host` - Cross host/target system to build for. This value will - be passed as `--host=$erl_xcomp_host` argument to the `configure` script. - It does not have to be a full `CPU-VENDOR-OS` triplet, but can be. The - full `CPU-VENDOR-OS` triplet will be created by - `$ERL_TOP/erts/autoconf/config.sub $erl_xcomp_host`. - -* `erl_xcomp_configure_flags` - Extra configure flags to pass to the - `configure` script. - -### Cross Compiler and Other Tools ### - -If the cross compilation tools are prefixed by `-` you probably do -not need to set these variables (where `` is what has been passed as -`--host=` argument to `configure`). - -All variables in this section can also be used when native compiling. - -* `CC` - C compiler. - -* `CFLAGS` - C compiler flags. - -* `STATIC_CFLAGS` - Static C compiler flags. - -* `CFLAG_RUNTIME_LIBRARY_PATH` - This flag should set runtime library - search path for the shared libraries. Note that this actually is a - linker flag, but it needs to be passed via the compiler. - -* `CPP` - C pre-processor. - -* `CPPFLAGS` - C pre-processor flags. - -* `CXX` - C++ compiler. - -* `CXXFLAGS` - C++ compiler flags. - -* `LD` - Linker. - -* `LDFLAGS` - Linker flags. - -* `LIBS` - Libraries. - -#### Dynamic Erlang Driver Linking #### - -> *NOTE*: Either set all or none of the `DED_LD*` variables. - -* `DED_LD` - Linker for Dynamically loaded Erlang Drivers. - -* `DED_LDFLAGS` - Linker flags to use with `DED_LD`. - -* `DED_LD_FLAG_RUNTIME_LIBRARY_PATH` - This flag should set runtime library - search path for shared libraries when linking with `DED_LD`. - -#### Large File Support #### - -> *NOTE*: Either set all or none of the `LFS_*` variables. - -* `LFS_CFLAGS` - Large file support C compiler flags. - -* `LFS_LDFLAGS` - Large file support linker flags. - -* `LFS_LIBS` - Large file support libraries. - -#### Other Tools #### - -* `RANLIB` - `ranlib` archive index tool. - -* `AR` - `ar` archiving tool. - -* `GETCONF` - `getconf` system configuration inspection tool. `getconf` is - currently used for finding out large file support flags to use, and - on Linux systems for finding out if we have an NPTL thread library or - not. - -### Cross System Root Locations ### - -* `erl_xcomp_sysroot` - The absolute path to the system root of the cross - compilation environment. Currently, the `crypto`, `odbc`, `ssh` and - `ssl` applications need the system root. These applications will be - skipped if the system root has not been set. The system root might be - needed for other things too. If this is the case and the system root - has not been set, `configure` will fail and request you to set it. - -* `erl_xcomp_isysroot` - The absolute path to the system root for includes - of the cross compilation environment. If not set, this value defaults - to `$erl_xcomp_sysroot`, i.e., only set this value if the include system - root path is not the same as the system root path. - -### Optional Feature, and Bug Tests ### - -These tests cannot (always) be done automatically when cross compiling. You -usually do not need to set these variables. - -> *WARNING*: Setting these variables wrong may cause hard to detect -> runtime errors. If you need to change these values, *really* make sure -> that the values are correct. - -> *NOTE*: Some of these values will override results of tests performed -> by `configure`, and some will not be used until `configure` is sure that -> it cannot figure the result out. - -The `configure` script will issue a warning when a default value is used. -When a variable has been set, no warning will be issued. - -* `erl_xcomp_after_morecore_hook` - `yes|no`. Defaults to `no`. If `yes`, - the target system must have a working `__after_morecore_hook` that can be - used for tracking used `malloc()` implementations core memory usage. - This is currently only used by unsupported features. - -* `erl_xcomp_bigendian` - `yes|no`. No default. If `yes`, the target system - must be big endian. If `no`, little endian. This can often be - automatically detected, but not always. If not automatically detected, - `configure` will fail unless this variable is set. Since no default - value is used, `configure` will try to figure this out automatically. - -* `erl_xcomp_clock_gettime_cpu_time` - `yes|no`. Defaults to `no`. If `yes`, - the target system must have a working `clock_gettime()` implementation - that can be used for retrieving process CPU time. - -* `erl_xcomp_getaddrinfo` - `yes|no`. Defaults to `no`. If `yes`, the target - system must have a working `getaddrinfo()` implementation that can - handle both IPv4 and IPv6. - -* `erl_xcomp_gethrvtime_procfs_ioctl` - `yes|no`. Defaults to `no`. If `yes`, - the target system must have a working `gethrvtime()` implementation and - is used with procfs `ioctl()`. - -* `erl_xcomp_dlsym_brk_wrappers` - `yes|no`. Defaults to `no`. If `yes`, the - target system must have a working `dlsym(RTLD_NEXT, )` implementation - that can be used on `brk` and `sbrk` symbols used by the `malloc()` - implementation in use, and by this track the `malloc()` implementations - core memory usage. This is currently only used by unsupported features. - -* `erl_xcomp_kqueue` - `yes|no`. Defaults to `no`. If `yes`, the target - system must have a working `kqueue()` implementation that returns a file - descriptor which can be used by `poll()` and/or `select()`. If `no` and - the target system has not got `epoll()` or `/dev/poll`, the kernel-poll - feature will be disabled. - -* `erl_xcomp_linux_clock_gettime_correction` - `yes|no`. Defaults to `yes` on - Linux; otherwise, `no`. If `yes`, `clock_gettime(CLOCK_MONOTONIC, _)` on - the target system must work. This variable is recommended to be set to - `no` on Linux systems with kernel versions less than 2.6. - -* `erl_xcomp_linux_nptl` - `yes|no`. Defaults to `yes` on Linux; otherwise, - `no`. If `yes`, the target system must have NPTL (Native POSIX Thread - Library). Older Linux systems have LinuxThreads instead of NPTL (Linux - kernel versions typically less than 2.6). - -* `erl_xcomp_linux_usable_sigaltstack` - `yes|no`. Defaults to `yes` on Linux; - otherwise, `no`. If `yes`, `sigaltstack()` must be usable on the target - system. `sigaltstack()` on Linux kernel versions less than 2.4 are - broken. - -* `erl_xcomp_linux_usable_sigusrx` - `yes|no`. Defaults to `yes`. If `yes`, - the `SIGUSR1` and `SIGUSR2` signals must be usable by the ERTS. Old - LinuxThreads thread libraries (Linux kernel versions typically less than - 2.2) used these signals and made them unusable by the ERTS. - -* `erl_xcomp_poll` - `yes|no`. Defaults to `no` on Darwin/MacOSX; otherwise, - `yes`. If `yes`, the target system must have a working `poll()` - implementation that also can handle devices. If `no`, `select()` will be - used instead of `poll()`. - -* `erl_xcomp_putenv_copy` - `yes|no`. Defaults to `no`. If `yes`, the target - system must have a `putenv()` implementation that stores a copy of the - key/value pair. - -* `erl_xcomp_reliable_fpe` - `yes|no`. Defaults to `no`. If `yes`, the target - system must have reliable floating point exceptions. - -Copyright and License ---------------------- - -%CopyrightBegin% - -Copyright Ericsson AB 2009-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% - -Modifying This Document ------------------------ - -Before modifying this document you need to have a look at the -`$ERL_TOP/README.md.txt` document. - - - - [$ERL_TOP/INSTALL.md]: INSTALL - [Building in Git]: INSTALL#How-to-Build-and-Install-ErlangOTP_Building-in-Git - [How to Build the Documentation]: INSTALL#The-ErlangOTP-Documentation_How-to-Build-the-Documentation - [cross configuration variables]: #Currently-Used-Configuration-Variables - [DESTDIR]: http://www.gnu.org/prep/standards/html_node/DESTDIR.html - - [?TOC]: true diff --git a/xcomp/README.md b/xcomp/README.md new file mode 120000 index 0000000000..d08b3160ba --- /dev/null +++ b/xcomp/README.md @@ -0,0 +1 @@ +../HOWTO/INSTALL-CROSS.md \ No newline at end of file -- cgit v1.2.3 From d26f31992baae77d6fd3fa063f22ee8ace33792c Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Tue, 10 Jul 2012 12:25:36 +0200 Subject: Add a testing HOWTO --- HOWTO/TESTING.md | 150 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 HOWTO/TESTING.md diff --git a/HOWTO/TESTING.md b/HOWTO/TESTING.md new file mode 100644 index 0000000000..34eaa68df8 --- /dev/null +++ b/HOWTO/TESTING.md @@ -0,0 +1,150 @@ +Testing Erlang/OTP +================== + +Before you start testing you need to have the Erlang release which you +are going to test in your path. See [$ERL_TOP/HOWTO/INSTALL.md][] for +instructions on how to build an Erlang release. + +Short version +------------- +Move to the top directory of the Erlang release you want to test, i.e. +cd /ldisk/work/otp + + export ERL_TOP=`pwd` + ./otp_build setup -a + export PATH=`pwd`/bin:$PATH + ./otp_build tests + cd release/tests/test_server + erl -s ts install -s ts run all_tests -s init stop + +Where are the tests +------------------- + +There are a lot of tests which test Erlang/OTP (as of 2012 about 12000) and +they are located in different places throughout the source tree. Below is a list +of the places where you can expect to find tests: + +* $ERL_TOP/lib/AppName/test/ +* $ERL_TOP/erts/test/ +* $ERL_TOP/erts/emulator/test/ +* $ERL_TOP/erts/epmd/test/ + +Writing tests +------------- + +All tests are [common_test][] suites and follow the same pattern as all +[common_test][] suites. However, a couple of corner cases are +handled by a test wrapper called `ts`. `ts` allows the test writer to put +`Makefile.src` and `Makefile.first` files in the [data_dir][] and a special +directory called `all_SUITE_data`. + +`Makefile.first` is run before any other Makefile and is typically used to +generate .hrl files which are needed by other test suites. At the moment only +the erl_interface tests use this feature and it should remain that way. + +`Makefile.src` is configured to a `Makefile` using the `variables` created when +[configuring the tests][]. These `Makefile`s are later run by the test suite +to compile whatever platform specific code the tests need to run. + +Releasing tests +--------------- + +If you cannot use [ct_run][] in the source tree you have to release the tests +into a common test directory. The easiest way to do this is to use `otp_build` +like this: + + export ERL_TOP=`pwd`; ./otp_build tests + +This will release all tests in Erlang/OTP to `$ERL_TOP/release/tests/`. If you +want to change the directory where the tests are released to use the `TESTROOT` +environmental variable. + +In the `$TESTROOT` you should now see *_test folders. These folders contain +everything needed to test Erlang/OTP and are platform independent; if you are +testing Erlang on multiple platforms you just have to release on one and copy +the tests to all other platforms. + +### Releasing cross tests + +For releasing tests in a cross compilation environment see [$ERL_TOP/HOWTO/INSTALL-CROSS.md][]. + +Configuring and Running tests +----------------------------- + +Running tests is done by first navigating to the `$TESTROOT/test_server` folder +created when you released the tests and then start `erl` in that directory. The +emulator flags specified will be used in the test runs. For example, if you want +to test using async threads you have to supply `+A 10` to `erl` when you start it. + +To configure and run the tests `ts` is used. `ts` is a wrapper module to +[common_test][] which takes care of configuration and build issues before +[common_test][] is started. + +`ts` has a lot of special options and functions which can be usefull when +testing Erlang/OTP. For a full listing issue `ts:help()` in the erlang shell. + +### Configuring the test environment + +Before running released tests you have to install them on the target system. +Installing the tests is done by calling `ts:install().` in the Erlang shell +which you intend to test from. `ts:install()` is basically a wrapper to a +configure script and some Erlang code which figures out what your system looks +like and what kind of emulator you are testing with. `ts:install()` can also +take some arguments if necessary, see `ts:help()` for details. + +All variables created by `ts:install()` are found in +`$TESTROOT/test_server/variables`. + +### Running the tests + +To run all test suites go to `$TESTROOT/test_server` fire up an Erlang shell and type: + + ts:run(). + +Note that running all tests will require several hours, so you may want to run +the test cases for a single application + + ts:run(Application, [batch]). + +or even part of the test suite for an application, for example + + ts:run(emulator, bs, [batch]). + +to run all test suite modules starting with `bs` (i.e. all modules that test +the bit syntax). + +To run a specific test case in a module, the full name of the module and test +case must be specified: + + ts:run(emulator, bs_bincomp_SUITE, byte_aligned, [batch]). + +Run `ts:help().` for more information. + +As of R14B02 it is also possibly to start all tests but the erl_interface tests +by invoking Common Test directly from the released applications test directory, +i.e. + + cd $TESTROOT/test_server + $ERL_TOP/bin/ct_run -suite ../compiler_test/andor_SUITE -case t_orelse + +Running [ct_run][] from the command line still requires you to do the +`ts:install()` step above. + +Examining the results +--------------------- + +Open the file `release/tests/test_server/index.html` in a web browser. Or open +`release/tests/test_server/last_test.html` when a test suite is running to +examine the results so far for the currently executing test suite (in R14B02 and +later you want to open the `release/tests/test_server/all_runs.html` file to +get to the currently running test) + + [ct_run]: http://www.erlang.org/doc/man/ct_run.html + [ct hook]: http://www.erlang.org/doc/apps/common_test/ct_hooks_chapter.html + [$ERL_TOP/HOWTO/INSTALL.md]: INSTALL.md + [$ERL_TOP/HOWTO/INSTALL-CROSS.md]: INSTALL-CROSS.md#testing-the-cross-compiled-system + [common_test]: http://www.erlang.org/doc/man/ct.html + [data_dir]: http://www.erlang.org/doc/apps/common_test/write_test_chapter.html#data_priv_dir + [configuring the tests]: #configuring-the-test-environment + + [?TOC]: true -- cgit v1.2.3