diff options
Diffstat (limited to 'xcomp/README')
| -rw-r--r-- | xcomp/README | 449 |
1 files changed, 0 insertions, 449 deletions
diff --git a/xcomp/README b/xcomp/README deleted file mode 100644 index f4285cd16f..0000000000 --- a/xcomp/README +++ /dev/null @@ -1,449 +0,0 @@ -=============================================================================== - Cross Compiling Erlang/OTP -=============================================================================== - -%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% - -=============================================================================== - -This document describes how to cross compile Erlang/OTP. Note that the support -for cross compiling Erlang/OTP is in its early stage of development, and -should be considered as experimental. You are encouraged to read the whole -document before attempting to cross compile Erlang/OTP. - -Building Erlang/OTP can be done either by using the `$ERL_TOP/otp_build' -script, or by invoking `configure' and `make' directly. The -`erl-xcomp.conf.template' file contains all available configuration variables -and can be used as a template when creating a configuration. See -`erl-xcomp-TileraMDE2.0-tilepro.conf` and `erl-xcomp-x86_64-saf-linux-gnu.conf' -for examples of working configurations. - -The configuration files can be passed to `$ERL_TOP/otp_build configure' using -the `--xcomp-conf' command line argument. Note that `configure' doesn't accept -this command line argument. When using the `configure' script directly, pass -the configuration variables as arguments to `configure' (or exported in the -environment). If the default behavior of a variable is satisfactory, the -variable doesn't 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. - -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. - -Note, that `$ERL_TOP/otp_build configure' will produce a default configuration -that differs from what `$ERL_TOP/configure' will produce by default. For -example, currently `--disable-dynamic-ssl-lib' is added to the -`$ERL_TOP/configure' command line arguments unless `--enable-dynamic-ssl-lib' -has been explicitly passed. The defaults used by `$ERL_TOP/otp_build configure' -may change at any time without prior notice. - -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. - -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' -- `$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 ===================================================== - - [1] - -Change directory into the top directory of the Erlang/OTP source tree. - - $ cd $ERL_TOP - -------- Build ----------------------------------------------------------------- - -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 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 --build=<BUILD> --host=<HOST> [Other Configure Args] - $ make - -<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. - -<HOST> is the 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. - -Pass the cross compilation variables as command line arguments to `configure' -using a `<VAR>=<VALUE>' syntax (or export them in the environment). Note that -you can *not* pass a configuration file using `--xcomp-conf=<FILE>' when you -invoke `configure' directly. The `--xcomp-conf=<FILE>' argument can only -be passed to `$ERL_TOP/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'. Note that this build 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]. - - [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. - -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: - - [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> - - [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 [--build=<BUILD>] [--host=<HOST>] \ - [--with-xcomp-conf=<FILE>] [Other Configure Args] - -If you have your cross compilation configuration in a file, pass it using the -`--xcomp-conf=<FILE>' command line argument. If not, pass the configuration -variables on the command line using a `<VAR>=<VALUE>' syntax (or in the -environment). - -`--build=<BUILD>', and `--host=<HOST>' are the same as described at [3]. -The `--xcomp-conf=<FILE>' argument causes `otp_build' to read the cross -compilation configuration from `<FILE>'. All of these arguments are in this -case optional, but `<BUILD>', and `<HOST>' must be given either by passing -`--build=<BUILD>' and `--host=<HOST>' on the command line, or by setting -`erl_xcomp_build=<HOST>', and `erl_xcomp_host=<HOST>' in `<FILE>' and -passing the `--xcomp-conf=<FILE>' argument. - -`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]. - -======== 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. - --------- `otp_build' only variables ------------------------------------------- - -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 - Build system. - 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 `erl_xcomp_build=guess', the build system will be guessed using: - `$ERL_TOP/erts/autoconf/config.guess'. - -* erl_xcomp_host - Cross host system. - 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. - Extra flags to pass to the `configure' script. - --------- Cross compiler and other tools to use -------------------------------- - -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'). - -* CC - C compiler. - -* CFLAGS - C compiler flags. - -* STATIC_CFLAGS - Static C compiler flags. - -* CFLAG_RUNTIME_LIBRARY_PATH - C compiler runtime library path flag. - This flag should set a specific runtime library path for the shared - library at link time. Note that this is actually 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 linker flags -- - -NOTE! Either set all or non of the DED_LD* variables. - -* DED_LD - Linker. - -* DED_LDFLAGS - Linker flags. - -* DED_LD_FLAG_RUNTIME_LIBRARY_PATH - Linker runtime library path flag. - This flag should set a specific runtime library path for the shared - library at link time. - --- Large file support -- - -NOTE! Either set all or non 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. - --------- Cross System Root Locations ------------------------------------------ - -* erl_xcomp_sysroot - Absolute cross system root path. - 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 - Absolute cross include system root path. - 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, or bug tests --------------------------------------- - -These tests cannot (always) be done automatically when cross compiling. You -usually does not need to set these variables. Only set these if you really -know what you are doing. - -Note that 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_bigendian - yes|no - 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. No default value is used, i.e., `configure' will try to figure - this out automatically. - -* 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_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 less than 2.2) - used these signals and made them unusable by the ERTS. - -* 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_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_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_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. - -* 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_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_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. - -* 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. - -=============================================================================== |