Document cross compiling

2 files changed, 96 insertions, 0 deletions

diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index 4e42234..0737bca 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -32,6 +32,8 @@ include::escripts.asciidoc[Escripts]
 
 include::kerl.asciidoc[OTP version management]
 
+include::cross_compiling.asciidoc[Cross compiling]
+
 include::compat.asciidoc[Compatibility with other build tools]
 
 [[docs]]
diff --git a/doc/src/guide/cross_compiling.asciidoc b/doc/src/guide/cross_compiling.asciidoc
new file mode 100644
index 0000000..23e14b9
--- /dev/null
+++ b/doc/src/guide/cross_compiling.asciidoc
@@ -0,0 +1,94 @@
+[[cross_compiling]]
+== Cross compiling
+
+Erlang.mk supports cross-compiling. While the compiled
+Erlang code is portable as-is, the C code is not and
+releases need to use the correct runtime system for the
+target environment.
+
+There are therefore two steps that might require some
+intervention: compiling and building the release. If
+you do not have any C code you can just compile as you
+would normally, however.
+
+=== Compiling
+
+To cross-compile the C code you need a cross compiler. If you
+were to target Windows from an Arch Linux machine you would
+install the https://aur.archlinux.org/packages/mingw-w64-gcc/[mingw-w64-gcc]
+package. You would then need to define the `CC` environment
+variable to point to this compiler instead of the default:
+
+[source,bash]
+CC=/usr/bin/x86_64-w64-mingw32-gcc
+
+Additionally, on Windows the shared libraries use a different
+extension than on Linux, so it needs to be specified as well:
+
+[source,bash]
+C_SRC_OUTPUT_SHARED_EXTENSION=.dll
+
+These values can be added to the Makefile or given from the
+command line, for example:
+
+[source,bash]
+----
+$ CC=/usr/bin/x86_64-w64-mingw32-gcc C_SRC_OUTPUT_SHARED_EXTENSION=.dll make
+ DEPEND my_nif.d
+ ERLC   my_nif.erl
+ APP    my_nif
+ C      my_nif.c
+ LD     my_nif.dll
+$ file priv/my_nif.dll                                              
+priv/my_nif.dll: PE32+ executable (DLL) (console) x86-64, for MS Windows
+----
+
+You could also add this configuration to your Makefile hidden
+behind a flag:
+
+[source,make]
+----
+ifdef WINDOWS_BUILD
+CC = /usr/bin/x86_64-w64-mingw32-gcc
+C_SRC_OUTPUT_SHARED_EXTENSION = .dll
+endif
+----
+
+And then just compile like this:
+
+[source,bash]
+$ make WINDOWS_BUILD=1
+
+=== Building the release
+
+For the release there are two options. You can either include
+the correct runtime system directly in the release; or you
+can not include the runtime system in the release and instead
+let it use the one installed in the target environment.
+
+To include the target runtime system, add the `include_erts`
+tuple to your 'relx.config' file:
+
+[source,erlang]
+{include_erts, "/path/to/alternate/erlang"}.
+
+If you were to target Windows for example, you could copy
+the Erlang installation from the 'Program Files' directory
+and then configure 'relx.config' like this:
+
+[source,erlang]
+{include_erts, "/path/to/erl10.1"}.
+
+You need to make sure that the runtime system version you
+will use is capable of running the compiled Erlang code
+you used to build your project, otherwise it will fail
+to run.
+
+If you choose to not include the runtime system at all,
+configure 'relx.config' as follow:
+
+[source,erlang]
+{include_erts, false}.
+
+In that case the runtime system needs to be available
+in the `$PATH` of the target environment.