diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | HOWTO/BOOTSTRAP.md (renamed from README.bootstrap) | 24 | ||||
| -rw-r--r-- | HOWTO/DTRACE.md (renamed from README.dtrace.md) | 7 | ||||
| -rw-r--r-- | HOWTO/INSTALL-CROSS.md | 556 | ||||
| -rw-r--r-- | HOWTO/INSTALL-WIN32.md (renamed from INSTALL-WIN32.md) | 3 | ||||
| -rw-r--r-- | HOWTO/INSTALL.md (renamed from INSTALL.md) | 11 | ||||
| -rw-r--r-- | HOWTO/MARKDOWN.md (renamed from README.md.txt) | 4 | ||||
| -rw-r--r-- | HOWTO/SYSTEMTAP.md (renamed from README.systemtap.md) | 21 | ||||
| -rw-r--r-- | HOWTO/TESTING.md | 150 | ||||
| l--------- | INSTALL-CROSS.md | 1 | ||||
| -rw-r--r-- | README.md | 3 | ||||
| -rw-r--r-- | TAR.include | 8 | ||||
| -rw-r--r-- | erts/emulator/beam/erlang_dtrace.d | 6 | ||||
| -rw-r--r-- | lib/runtime_tools/doc/src/dyntrace.xml | 2 | ||||
| -rw-r--r-- | make/emd2exml.in | 16 | ||||
| -rw-r--r-- | system/doc/installation_guide/Makefile | 8 | ||||
| -rw-r--r-- | system/doc/installation_guide/part.xml | 4 | ||||
| -rw-r--r-- | system/doc/installation_guide/xmlfiles.mk | 3 | ||||
| l---------[-rw-r--r--] | xcomp/README.md | 556 |
19 files changed, 779 insertions, 605 deletions
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/README.bootstrap b/HOWTO/BOOTSTRAP.md index f42bc7aa47..59e31165cf 100644 --- a/README.bootstrap +++ b/HOWTO/BOOTSTRAP.md @@ -1,16 +1,16 @@ 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 - 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 @@ -19,7 +19,7 @@ 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 +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. @@ -27,31 +27,31 @@ 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 +`$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 +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 +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 +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). +`$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 +`$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 diff --git a/README.dtrace.md b/HOWTO/DTRACE.md index 5bc042f9fc..1d495b0eaf 100644 --- a/README.dtrace.md +++ b/HOWTO/DTRACE.md @@ -5,7 +5,7 @@ History ------- The first implementation of DTrace probes for the Erlang virtual -machine was presented at the [2008 Erlang User Conference] [4]. That +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. @@ -33,8 +33,8 @@ Supported platforms 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. +* 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 @@ -391,3 +391,4 @@ Guide to efile_drv.c probe arguments 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 +`<VARIABLE>=<VALUE>` 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: + <http://wiki.github.com/erlang/otp/submitting-patches> + +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=<HOST> --build=<BUILD> [Other Config Args] + $ make + +`<HOST>` 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 <HOST>`. If +`config.sub` fails, you need to be more specific. + +`<BUILD>` 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 `<VARIABLE>=<VALUE>` 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=<TEMPORARY_PREFIX> + +`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=<RELEASE_DIR> + +`make release` will copy what you have built for the target machine to +`<RELEASE_DIR>`. The `Install` script will not be run. The content of +`<RELEASE_DIR>` 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] <ERL_ROOT> + +where: + +* `-minimal` Creates an installation that starts up a minimal amount + of applications, i.e., only `kernel` and `stdlib` are started. The + minimal system is normally enough, 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. +* `<ERL_ROOT>` - The absolute path to the Erlang installation to use + at run time. This is often the same as the current working directory, + but does not have to be. It can follow any other path through the file + system to the same directory. + +If neither `-minimal`, nor `-sasl` is passed as argument you will be +prompted. + +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 <RELEASE_DIR> + $ ./Install -cross [-minimal|-sasl] <ABSOLUTE_INSTALL_DIR_ON_TARGET> + +or: + + (7) + +* Package the installation in `<RELEASE_DIR>`, place it wherever you want + on your target machine, and run the `Install` script on your target + machine: + + $ cd <ABSOLUTE_INSTALL_DIR_ON_TARGET> + $ ./Install [-minimal|-sasl] <ABSOLUTE_INSTALL_DIR_ON_TARGET> + +### Building With the otp\_build Script ### + + (8) + + $ cd $ERL_TOP + + (9) + + $ ./otp_build configure --xcomp-conf=<FILE> [Other Config Args] + +alternatively: + + $ ./otp_build configure --host=<HOST> --build=<BUILD> [Other Config Args] + +If you have your cross compilation configuration in a file, pass it using the +`--xcomp-conf=<FILE>` command line argument. If not, pass `--host=<HOST>`, +`--build=<BUILD>`, and the configuration variables using a `<VARIABLE>=<VALUE>` +syntax on the command line (same as in (3)). Note that `<HOST>` and `<BUILD>` +have to be passed one way or the other; either by using `erl_xcomp_host=<HOST>` +and `erl_xcomp_build=<BUILD>` in the configuration file, or by using the +`--host=<HOST>`, and `--build=<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 <RELEASE_DIR> + +`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,"<FILE>"}])' -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 `<HOST>-` you probably do +not need to set these variables (where `<HOST>` is what has been passed as +`--host=<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, <S>)` 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/INSTALL-WIN32.md b/HOWTO/INSTALL-WIN32.md index ff253d3dfa..94d3688f23 100644 --- a/INSTALL-WIN32.md +++ b/HOWTO/INSTALL-WIN32.md @@ -1037,10 +1037,11 @@ Modifying This Document ----------------------- Before modifying this document you need to have a look at the -`$ERL_TOP/README.md.txt` document. +[$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/INSTALL.md b/HOWTO/INSTALL.md index 70d465831d..3efa48469e 100644 --- a/INSTALL.md +++ b/HOWTO/INSTALL.md @@ -18,10 +18,10 @@ 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][] +* cross compile Erlang/OTP, see the [$ERL_TOP/HOWTO/INSTALL-CROSS.md][] document. -* build Erlang/OTP on Windows, see the [$ERL_TOP/INSTALL-WIN32.md][] +* build Erlang/OTP on Windows, see the [$ERL_TOP/HOWTO/INSTALL-WIN32.md][] document. Binary releases for Windows can be found at @@ -821,12 +821,12 @@ Modifying This Document ----------------------- Before modifying this document you need to have a look at the -`$ERL_TOP/README.md.txt` document. +[$ERL_TOP/HOWTO/MARKDOWN.md][] document. - [$ERL_TOP/INSTALL-CROSS.md]: INSTALL-CROSS - [$ERL_TOP/INSTALL-WIN32.md]: INSTALL-WIN32 + [$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 @@ -834,5 +834,6 @@ Before modifying this document you need to have a look at the [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/README.md.txt b/HOWTO/MARKDOWN.md index a5a1bf4b7d..42045fb10c 100644 --- a/README.md.txt +++ b/HOWTO/MARKDOWN.md @@ -5,7 +5,7 @@ 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 +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 @@ -258,7 +258,7 @@ under the License. - [$ERL_TOP/INSTALL.md]: doc/installation_guide:INSTALL + [$ERL_TOP/HOWTO/INSTALL.md]: INSTALL.md [github]: http://github.com [our github repository]: http://github.com/erlang/otp diff --git a/README.systemtap.md b/HOWTO/SYSTEMTAP.md index c190bcc893..094b61f1c0 100644 --- a/README.systemtap.md +++ b/HOWTO/SYSTEMTAP.md @@ -6,7 +6,7 @@ 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. +introduction to Erlang DTrace support read [$ERL_TOP/HOWTO/DTRACE.md][]. Requisites ---------- @@ -15,8 +15,8 @@ Requisites check for UTRACE support in your current kernel: - # grep CONFIG_UTRACE /boot/config-`uname -r` - CONFIG_UTRACE=y + # 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. @@ -35,8 +35,8 @@ Building Erlang Configure and build Erlang with SystemTap support: - # ./configure --with-dynamic-trace=systemtap + whatever args you need - # make + # ./configure --with-dynamic-trace=systemtap + whatever args you need + # make Testing ------- @@ -52,16 +52,16 @@ binary is in the search path. All available probes can be listed like this: - # stap -L 'process("beam").mark("*")' + # stap -L 'process("beam").mark("*")' or: - # PATH=/path/to/beam:$PATH stap -L 'process("beam").mark("*")' + # 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("*")' + # PATH=/path/to/dtrace/priv/lib:$PATH stap -L 'process("dtrace.so").mark("*")' Running SystemTap scripts ------------------------- @@ -69,4 +69,7 @@ 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 <pid of beam> + # stap /path/to/probe/script/port1.systemtap -x <pid of beam> + + + [$ERL_TOP/HOWTO/DTRACE.md]: DTRACE.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 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 @@ -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/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 @@ </list> <p>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.</p> <p>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.</p> - <p>How to write <c>d</c> programs or <c>systemtap</c> 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 <c>examples</c> directory of the <c>runtime_tools</c> application however contains comprehensive examples of both <c>d</c> and <c>systemtap</c> programs that will help you get started. Another source of information is the <c>README.dtrace(.md)</c> and <c>README.systemtap(.md)</c> files in the Erlang source top directory.</p> + <p>How to write <c>d</c> programs or <c>systemtap</c> 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 <c>examples</c> directory of the <c>runtime_tools</c> application however contains comprehensive examples of both <c>d</c> and <c>systemtap</c> programs that will help you get started. Another source of information is the <c>DTRACE(.md)</c> and <c>SYSTEMTAP(.md)</c> files in the HOWTO folder in the Erlang source directory.</p> </description> <funcs> <func> 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 @@ <xi:include href="INSTALL.xml"/> <xi:include href="INSTALL-CROSS.xml"/> <xi:include href="INSTALL-WIN32.xml"/> -</part> - + <xi:include href="MARKDOWN.xml"/> +</part>
\ 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 index 5f4b36bdca..d08b3160ba 100644..120000 --- a/xcomp/README.md +++ b/xcomp/README.md @@ -1,555 +1 @@ -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 -`<VARIABLE>=<VALUE>` 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: - <http://wiki.github.com/erlang/otp/submitting-patches> - -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=<HOST> --build=<BUILD> [Other Config Args] - $ make - -`<HOST>` 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 <HOST>`. If -`config.sub` fails, you need to be more specific. - -`<BUILD>` 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 `<VARIABLE>=<VALUE>` 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=<TEMPORARY_PREFIX> - -`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=<RELEASE_DIR> - -`make release` will copy what you have built for the target machine to -`<RELEASE_DIR>`. The `Install` script will not be run. The content of -`<RELEASE_DIR>` 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] <ERL_ROOT> - -where: - -* `-minimal` Creates an installation that starts up a minimal amount - of applications, i.e., only `kernel` and `stdlib` are started. The - minimal system is normally enough, 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. -* `<ERL_ROOT>` - The absolute path to the Erlang installation to use - at run time. This is often the same as the current working directory, - but does not have to be. It can follow any other path through the file - system to the same directory. - -If neither `-minimal`, nor `-sasl` is passed as argument you will be -prompted. - -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 <RELEASE_DIR> - $ ./Install -cross [-minimal|-sasl] <ABSOLUTE_INSTALL_DIR_ON_TARGET> - -or: - - (7) - -* Package the installation in `<RELEASE_DIR>`, place it wherever you want - on your target machine, and run the `Install` script on your target - machine: - - $ cd <ABSOLUTE_INSTALL_DIR_ON_TARGET> - $ ./Install [-minimal|-sasl] <ABSOLUTE_INSTALL_DIR_ON_TARGET> - -### Building With the otp\_build Script ### - - (8) - - $ cd $ERL_TOP - - (9) - - $ ./otp_build configure --xcomp-conf=<FILE> [Other Config Args] - -alternatively: - - $ ./otp_build configure --host=<HOST> --build=<BUILD> [Other Config Args] - -If you have your cross compilation configuration in a file, pass it using the -`--xcomp-conf=<FILE>` command line argument. If not, pass `--host=<HOST>`, -`--build=<BUILD>`, and the configuration variables using a `<VARIABLE>=<VALUE>` -syntax on the command line (same as in (3)). Note that `<HOST>` and `<BUILD>` -have to be passed one way or the other; either by using `erl_xcomp_host=<HOST>` -and `erl_xcomp_build=<BUILD>` in the configuration file, or by using the -`--host=<HOST>`, and `--build=<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 <RELEASE_DIR> - -`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,"<FILE>"}])' -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 `<HOST>-` you probably do -not need to set these variables (where `<HOST>` is what has been passed as -`--host=<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, <S>)` 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 +../HOWTO/INSTALL-CROSS.md
\ No newline at end of file |