View Source Cross Compiling Erlang/OTP
Introduction
This document describes how to cross compile Erlang/OTP-27.
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.
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 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 canonicalized
CPU-VENDOR-OS
triplet will be created by executing
$ERL_TOP/make/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/make/autoconf/config.guess
, it will in
most cases print the triplet you want to use for this.
The use of <HOST>
and <BUILD>
values that differ will trigger cross
compilation. Note that if <HOST>
and <BUILD>
differ, the canonicalized
values of <HOST>
and <BUILD>
must also differ. If they do not, the
configuration will fail.
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 invokeconfigure
directly. The--xcomp-conf
argument can only be passed tootp_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., onlykernel
andstdlib
are started. The minimal system is normally enough, and is whatmake install
uses. -
-sasl
Creates an installation that also starts up thesasl
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 theInstall
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 bootstrap 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).
Building and Installing the Documentation
After the system has been cross built you can build and install the documentation the same way as after a native build of the system. See the How to Build the Documentation section in the $ERL_TOP/HOWTO/INSTALL.md document for information on how to build the documentation.
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 theconfigure
script. It does not have to be a fullCPU-VENDOR-OS
triplet, but can be. The fullCPU-VENDOR-OS
triplet will be created by$ERL_TOP/make/autoconf/config.sub $erl_xcomp_build
. If set toguess
, the build system will be guessed using$ERL_TOP/make/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 theconfigure
script. It does not have to be a fullCPU-VENDOR-OS
triplet, but can be. The fullCPU-VENDOR-OS
triplet will be created by$ERL_TOP/make/autoconf/config.sub $erl_xcomp_host
.erl_xcomp_configure_flags
- Extra configure flags to pass to theconfigure
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
). Compiler and other tools can
otherwise be identified via variables passed as arguments on the command
line to configure
, in then xcomp file, or as environment variables. For
more information see the Important Variables Inspected by configure
section of the $ERL_TOP/HOWTO/INSTALL.md document.
Cross System Root Locations
erl_xcomp_sysroot
- The absolute path to the system root of the cross compilation environment. Currently, thecrypto
,odbc
,ssh
andssl
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 untilconfigure
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 tono
. Ifyes
, the target system must have a working__after_morecore_hook
that can be used for tracking usedmalloc()
implementations core memory usage. This is currently only used by unsupported features.erl_xcomp_bigendian
-yes|no
. No default. Ifyes
, the target system must be big endian. Ifno
, 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_double_middle
-yes|no
. Defaults tono
. Ifyes
, the target system must have doubles in "middle-endian" format. Ifno
, it has "regular" endianness.erl_xcomp_clock_gettime_cpu_time
-yes|no
. Defaults tono
. Ifyes
, the target system must have a workingclock_gettime()
implementation that can be used for retrieving process CPU time.erl_xcomp_getaddrinfo
-yes|no
. Defaults tono
. Ifyes
, the target system must have a workinggetaddrinfo()
implementation that can handle both IPv4 and IPv6.erl_xcomp_gethrvtime_procfs_ioctl
-yes|no
. Defaults tono
. Ifyes
, the target system must have a workinggethrvtime()
implementation and is used with procfsioctl()
.erl_xcomp_dlsym_brk_wrappers
-yes|no
. Defaults tono
. Ifyes
, the target system must have a workingdlsym(RTLD_NEXT, <S>)
implementation that can be used onbrk
andsbrk
symbols used by themalloc()
implementation in use, and by this track themalloc()
implementations core memory usage. This is currently only used by unsupported features.erl_xcomp_kqueue
-yes|no
. Defaults tono
. Ifyes
, the target system must have a workingkqueue()
implementation that returns a file descriptor which can be used bypoll()
and/orselect()
. Ifno
and the target system has not gotepoll()
or/dev/poll
, the kernel-poll feature will be disabled.erl_xcomp_linux_clock_gettime_correction
-yes|no
. Defaults toyes
on Linux; otherwise,no
. Ifyes
,clock_gettime(CLOCK_MONOTONIC, _)
on the target system must work. This variable is recommended to be set tono
on Linux systems with kernel versions less than 2.6.erl_xcomp_linux_nptl
-yes|no
. Defaults toyes
on Linux; otherwise,no
. Ifyes
, 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 toyes
on Linux; otherwise,no
. Ifyes
,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 toyes
. Ifyes
, theSIGUSR1
andSIGUSR2
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 tono
on Darwin/MacOSX; otherwise,yes
. Ifyes
, the target system must have a workingpoll()
implementation that also can handle devices. Ifno
,select()
will be used instead ofpoll()
.erl_xcomp_putenv_copy
-yes|no
. Defaults tono
. Ifyes
, the target system must have aputenv()
implementation that stores a copy of the key/value pair.erl_xcomp_reliable_fpe
-yes|no
. Defaults tono
. Ifyes
, the target system must have reliable floating point exceptions.erl_xcomp_posix_memalign
-yes|no
. Defaults toyes
ifposix_memalign
system call exists; otherwiseno
. Ifyes
, the target system must have aposix_memalign
implementation that accepts larger than page size alignment.erl_xcomp_code_model_small
-yes|no
. Default tono
. Ifyes
, the target system must place the beam.smp executable in the lower 2 GB of memory. That is it should not use position independent executable.