README

===============================================================================
                          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.

===============================================================================