From 4ffb0e18481640424185498fbee835068b09f149 Mon Sep 17 00:00:00 2001
From: Zaiming Shi <zmstone@gmail.com>
Date: Sun, 14 Mar 2021 13:37:35 +0100
Subject: [PATCH] docs(README): Add windows

---
 README.md  |   2 +
 Windows.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 116 insertions(+)
 create mode 100644 Windows.md

diff --git a/README.md b/README.md
index 14e0abde4..49f44d33f 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,8 @@ Starting from 3.0 release, *EMQ X* broker fully supports MQTT V5.0 protocol spec
 
 The *EMQ X* broker is cross-platform, which supports Linux, Unix, macOS and Windows. It means *EMQ X* can be deployed on x86_64 architecture servers and ARM devices like Raspberry Pi.
 
+See more details for building and running *EMQ X* on Windows in [Windows.md](./Windows.md)
+
 #### Installing via EMQ X Docker Image
 
 ```
diff --git a/Windows.md b/Windows.md
new file mode 100644
index 000000000..2f3f08876
--- /dev/null
+++ b/Windows.md
@@ -0,0 +1,114 @@
+# Build and run EMQ X on Windows
+
+NOTE: The instructions and examples are based on Windows 10.
+
+## Build Environment
+
+### Visual studio for C/C++ compile and link
+
+EMQ X includes Erlang NIF (Native Implmented Function) components, implemented
+in C/C++. To compile and link C/C++ libraries, the easiest way is perhaps to
+install Visual Studio.
+
+Visual Studio 2019 is used in our tests.
+If you (like @zmstone) do not know where to start, please follow this OTP guide:
+https://github.com/erlang/otp/blob/master/HOWTO/INSTALL-WIN32.md
+
+NOTE: To avoid surprises, you may need to add below two paths to `Path` environment variable
+and order them before other paths.
+
+```
+C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.28.29910\bin\Hostx64\x64
+C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build
+```
+
+Depending on your visual studio version and OS, the paths may differ.
+The first path is for rebar3 port compiler to find `cl.exe` and `link.exe`
+The second path is for Powershell or CMD to setup environment variables.
+
+### Erlang/OTP
+
+Install Erlang/OTP 23.2 from https://www.erlang.org/downloads
+You may need to edit the `Path` environment variable to allow running
+Erlang commands such as `erl` from powershell.
+
+To validate Erlang installation in CMD or powershell:
+
+* Start (or restart) CMD or powershell
+
+* Execute `erl` command to enter Erlang shell
+
+* Evaluate Erlang expression `halt().` to exit Erlang shell.
+
+e.g.
+
+```
+Eshell V11.1.4  (abort with ^G)
+1> halt().
+PS C:\Users\zmsto> erl
+Eshell V11.1.4  (abort with ^G)
+1> halt().
+```
+
+### bash
+
+All EMQ X build/run scripts are either in `bash` or `escript`.
+`escript` is installed as a part of Erlang. To install a `bash`
+environment in Windows, there are quite a few options.
+
+Cygwin is what we tested with.
+
+* Add `cygwin\bin` dir to `Path` environment variable
+  To do so, search for Edit environment variable in control pannel and
+  add `C:\tools\cygwin\bin` (depending on the location where it was installed)
+  to `Path` list.
+
+* Validate installation.
+  Start (restart) CMD or powershell console and execute `which bash`, it should
+  print out `/usr/bin/bash`
+
+### Other tools
+
+Some of the unix world tools are required to build EMQ X.  Including:
+
+* git
+* curl
+* make
+* jq
+* zip / unzip
+
+We recommend using [scoop](https://scoop.sh/), or [Chocolatey](https://chocolatey.org/install) to install the tools.
+
+When using scoop:
+
+```
+scoop install git curl make jq zip unzip
+```
+
+## Build EMQ X source code
+
+* Clone the repo: `git clone https://github.com/emqx/emqx.git`
+
+* Start CMD or Powershell
+
+* Execute `vcvarsall.bat x86_amd64` to load environment variables
+
+* Change to emqx directory and execute `make`
+
+### Possible errors
+
+* `'cl.exe' is not recognized as an internal or external command`
+  This error is likely due to Visual Studio executables are not set in `Path` environment variable.
+  To fix it, either add path like `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.28.29910\bin\Hostx64\x64`
+  to `Paht`. Or make sure `vcvarsall.bat x86_amd64` is executed prior to the `make` command
+
+* `fatal error C1083: Cannot open include file: 'assert.h': No such file or directory`
+  If Visual Studio is installed correctly, this is likely `LIB` and `LIB_PATH` environment
+  variables are not set. Make sure `vcvarsall.bat x86_amd64` is executed prior to the `make` command
+
+* `link: extra operand 'some.obj'`
+  This is likely due ot the usage of GNU `lnik.exe` but not the one from Visual Studio.
+  Exeucte `link.exe --version` to inspect which one is in use. The one installed from
+  Visual Studio should print out `Microsoft (R) Incremental Linker`.
+  To fix it, Visual Studio's bin paths should be ordered prior to Cygwin's (or similar installation's)
+  bin paths in `Path` environment variable.