1 files changed, 124 insertions, 0 deletions
diff --git a/docs/en/erlang.mk/1/guide/installation.asciidoc b/docs/en/erlang.mk/1/guide/installation.asciidoc
new file mode 100644
index 00000000..cc18e7f1
--- /dev/null
+++ b/docs/en/erlang.mk/1/guide/installation.asciidoc
@@ -0,0 +1,124 @@
+[[installation]]
+== Installation
+
+This chapter explains how to setup your system in
+order to use Erlang.mk.
+
+=== On Unix
+
+Erlang.mk requires GNU Make to be installed. GNU Make 3.81
+or later is required. GNU Make 4.1 or later is recommended,
+as this is the version Erlang.mk is developed on.
+
+Some functionality requires that Autoconf 2.59 or later be
+installed, in order to compile Erlang/OTP. Erlang/OTP may
+have further requirements depending on your needs.
+
+Erlang.mk currently requires Erlang/OTP to be installed in
+order to compile Erlang projects.
+
+Some packages may require additional libraries.
+
+=== On Windows
+
+Erlang.mk can be used on Windows inside an MSYS2 environment.
+Cygwin, MSYS (the original) and native Windows (both Batch
+and PowerShell) are currently not supported.
+
+The rest of this section details how to setup Erlang/OTP and
+MSYS2 in order to use Erlang.mk.
+
+==== Installing Erlang/OTP
+
+Erlang.mk requires Erlang/OTP to be installed. The OTP team
+provides binaries of Erlang/OTP for all major and minor releases,
+available from the http://www.erlang.org/download.html[official download page].
+It is recommended that you use the 64-bit installer unless
+technically impossible. Please follow the instructions from
+the installer to complete the installation.
+
+The OTP team also provides a short guide to
+http://www.erlang.org/download.html[installing Erlang/OTP on Windows]
+if you need additional references.
+
+You can install Erlang/OTP silently using the `/S` switch
+on the command line:
+
+----
+C:\Users\essen\Downloads> otp_win64_18.0.exe /S
+----
+
+==== Installing MSYS2
+
+The only supported environment on Windows is MSYS2. MSYS2 is
+a lightweight Unix-like environment for Windows that comes
+with the Arch Linux package manager, `pacman`.
+
+The MSYS2 project provides a http://msys2.github.io[one click installer]
+and instructions to set things up post-installation.
+
+It is currently not possible to use the installer silently.
+Thankfully, the MSYS2 project provides an archive that can
+be used in lieu of the installer. The archive however requires
+_7zip_ to decompress it.
+
+First, download the
+http://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-base-x86_64-20150512.tar.xz/download[MSYS2 base archive]
+and extract it under 'C:\'. Assuming you downloaded the
+archive as 'msys2.tar.xz' and put it in 'C:\', you can
+use the following commands to extract it:
+
+----
+C:\> 7z x msys2.tar.xz
+C:\> 7z x msys2.tar > NUL
+----
+
+Then you can run the two commands needed to perform the
+post-installation setup:
+
+----
+C:\> C:\msys64\usr\bin\bash -lc "pacman --needed --noconfirm -Sy bash pacman pacman-mirrors msys2-runtime"
+C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -Syu"
+----
+
+==== Installing the required MSYS2 packages
+
+After following these instructions, you can install GNU Make,
+Git and any other required softwares. From an MSYS2 shell,
+you can call `pacman` directly:
+
+[source,bash]
+$ pacman -S git make
+
+You can use `pacman -Ss` to search packages. For example,
+to find all packages related to GCC:
+
+[source,bash]
+$ pacman -Ss gcc
+
+If you are going to compile C/C++ code, you will need to
+install this package, as Erlang.mk cannot use the normal
+"gcc" package:
+
+[source,bash]
+$ pacman -S mingw-w64-x86_64-gcc
+
+You can also run commands under the MSYS2 environment from
+the Windows command line or batch files. This command will
+install GNU Make and Git:
+
+----
+C:\> C:\msys64\usr\bin\bash -lc "pacman --noconfirm -S git make"
+----
+
+You can use similar `bash` commands if you need to run programs
+inside the MSYS2 environment from a batch file.
+
+==== Gotchas
+
+While most of the basic functionality will just work, there are
+still some issues. Erlang.mk needs to be fixed to pass the
+right paths when running Erlang scripts. We are working on it.
+Erlang.mk is fully tested on both Linux and Windows, but is
+lacking tests in the areas not yet covered by this guide,
+so expect bugs to be fixed as more tests are added.