wolfMQTT was written with portability in mind, and should generally be easy to build on most systems. If you have difficulty building, please don’t hesitate to seek support through our support forums https://www.wolfssl.com/forums or contact us directly at firstname.lastname@example.org . This chapter explains how to build wolfMQTT on Unix and Windows, and provides guidance for building in a non-standard environment.
When using the autoconf / automake system to build, wolfMQTT uses a single Makefile to build all parts and examples of the library, which is both simpler and faster than using Makefiles recursively. If using the TLS features or the Firmware/Azure IoT Hub examples you’ll need to have wolfSSL installed. For wolfSSL and wolfMQTT we recommend using config options below
./configure --enable-ecc --enable-supportedcurves --enable-base64encode.
For wolfSSL use
make && sudo make install. If you get an error locating the libwolfssl.so, run
sudo ldconfig from the wolfSSL directory.
Getting the Source Code
The most recent version of wolfMQTT can be downloaded from the wolfSSL downloads page here
Or from Github with the command:
git clone https://github.com/wolfSSL/wolfMQTT.git
Building on *nix/Mac
When building on Linux, BSD, OS X, Solaris, or other nix-like systems, use the autoconf system. If cloned from github, run the following three commands:
./autogen.sh ./configure make
Otherwise, just run these two commands:
You can append any number of build options to
./configure. For a list of available build options, run the command below:
To build wolfMQTT, run:
To install wolfMQTT run:
You may need superuser privileges to install, in which case precede the command with sudo:
sudo make install
wolfssl was recently installed, run
sudo ldconfig to update the linker cache.
* Debug messages can be enabled using
--enable-debug=verbose (for extra logging).
* For a list of build options run
* The build options are generated in a file here:
To test the build, run the mqttclient program from the root wolfMQTT source directory:
If you want to build only the wolfMQTT library and not the additional items (examples), you can run the following command from the wolfMQTT root directory:
Building on Windows
Visual Studio :
For building wolfMQTT with TLS support in Visual Studio:
- Open the
- Re-target for your Visual Studio version (right-click on solution and choose
- Make sure the
Release DLLconfiguration is selected. Make note if you are building 32-bit
- Build the wolfSSL solution.
- Copy the
x86the files are in:
x86the files are in:
x64the files are in:
x64the files are in:
- Open the
- Make sure you have the same architecture (
x64selected) as used in wolfSSL above.
- By default the include path for the wolfssl headers is
./../wolfssl/. If your wolfssl root location is different you can go into the project settings and adjust this in
Additional Include Directories.
- Configure your Visual Studio build settings using
- Build the wolfMQTT solution.
The wolfmqtt.sln solution is included for Visual Studio 2015 in the root directory of the install. To test each build, choose “Build All” from the Visual Studio menu and then run the mqttclient program. To edit build options in the Visual Studio project, select your desired project (wolfmqtt, mqttclient) and browse to the “Properties” panel.
For instructions on building the required wolfssl.dll see here. When done copy the wolfssl.dll and wolfssl.lib into the wolfMQTT root. The project also assumes the wolfSSL headers are located
Cygwin : If using Cygwin, or other toolsets for Windows that provides nix-like commands and functionality, please follow the instructions in Section 2.2, above, for “Building on nix”. If building wolfMQTT for Windows on a Windows development machine, we recommend using the included Visual Studio project files to build wolfMQTT.
Building on Arduino
Reformatting wolfMQTT as a compatible Arduino Library
wolfmqtt-arduino.sh is a shell script that will re-organize the wolfMQTT library to be compatible with Arduino projects. The Arduino IDE requires a library's source files to be in the library's root directory with a header file in the name of the library. This script copies all source files to the
IDE/ARDUINO/wolfMQTT directory and creates a stub header file called
To configure wolfMQTT with Arduino, enter the following from within the IDE/ARDUINO directory:
Including wolfMQTT in Arduino Libraries (for Arduino version 1.8.2)
- In the Arduino IDE:
Sketch -> Include Library -> Add .ZIP Library...and choose the
Sketch -> Include Librarychoose wolfMQTT.
To enable TLS support, add
#define ENABLE_MQTT_TLS in
Note: If using wolfSSL TLS then you'll need to do this for wolfSSL as well.
<wolfssl-root>/IDE/ARDUINO/README.md for instructions.
An example wolfMQTT client INO sketch exists here:
wolfmqtt_client/wolfmqtt_client.ino to demonstrate using the wolfMQTT library.
Building with MinGW
After downloading both wolfSSL and wolfMQTT, run the script below to build then install both:
export PATH="/opt/mingw-w32-bin_i686-darwin/bin:$PATH" export PREFIX=$PWD/build # wolfSSL cd wolfssl ./configure --host=i686 CC=i686-w64-mingw32-gcc LD=i686-w64-mingw32-ld CFLAGS="-DWIN32 -DMINGW -D_WIN32_WINNT=0x0600" LIBS="-lws2_32 -L$PREFIX/lib -lwolfssl" --prefix=$PREFIX make make install # wolfMQTT cd ../wolfmqtt ./configure --host=i686 CC=i686-w64-mingw32-gcc LD=i686-w64-mingw32-ld CFLAGS="-DWIN32 -DMINGW -D_WIN32_WINNT=0x0600 -DBUILDING_WOLFMQTT -I$PREFIX/include" LDFLAGS="-lws2_32 -L$PREFIX/lib -lwolfssl" --prefix=$PREFIX --disable-examples make
Building in a non-standard environment
While not officially supported, we try to help users wishing to build wolfMQTT in a non-standard environment, particularly with embedded and cross-compilation systems. Below are some notes on getting started with this.
- The source and header files need to remain in the same directory structure as they are in the wolfMQTT download package.
- Some build systems will want to explicitly know where the wolfMQTT header files are located, so you may need to specify that. They are located in the
<wolfmqtt_root>/wolfmqttdirectory. Typically, you can add the
directory to your include path to resolve header problems.
- wolfMQTT defaults to a little endian system unless the configure process detects big endian. Since users building in a non-standard environment aren't using the configure process, BIG_ENDIAN_ORDER will need to be defined if using a big endian system.
- Try to build the library, and let us know if you run into any problems. If you need help, contact us at email@example.com .
Many users on embedded platforms cross compile for their environment. The easiest way to cross compile the library is to use the ./configure system. It will generate a Makefile which can then be used to build wolfMQTT. When cross compiling, you’ll need to specify the host to
./configure, such as:
You may also need to specify the compiler, linker, etc. that you want to use:
./configure --host=arm-linux CC=arm-linux-gcc AR=arm-linux-ar RANLIB=arm-linux
After correctly configuring wolfMQTT for cross-compilation, you should be able to follow standard autoconf practices for building and installing the library:
make sudo make install
If you have any additional tips or feedback about cross compiling wolfMQTT, please let us know at firstname.lastname@example.org.
Install to Custom Directory
To setup a custom install directory for wolfSSL and specify the custom wolfSSL lib/include directories for wolfMQTT, use the following:
./configure --prefix=~/wolfssl make make install
This will place the libs in
~/wolfssl/lib and includes in
./configure --prefix=~/wolfmqtt --libdir=~/wolfssl/lib --includedir=~/wolfssl/include make make install
Make sure the paths above match your actual location.