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 are like me (@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.

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, or Chocolatey 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.

Run EMQ X

To start EMQ X broker.

Execute _build\emqx\rel\emqx>.\bin\emqx console or _build\emqx\rel\emqx>.\bin\emqx start to start EMQ X.

Then execute _build\emqx\rel\emqx>.\bin\emqx_ctl status to check status. If everything works fine, it should print out

Node 'emqx@127.0.0.1' 4.3-beta.1 is started
Application emqx 4.3.0 is running

4.1 KiB Raw Blame History