Skip to content

Commit

Permalink
Updates to README for better build instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@fpagliughi
fpagliughi committed Dec 11, 2018
1 parent 8579305 commit 39a2132
Showing 1 changed file with 99 additions and 65 deletions.
164 changes: 99 additions & 65 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# Eclipse Paho MQTT C++ Client Library

Master: [![Build Status](https://travis-ci.org/eclipse/paho.mqtt.cpp.svg?branch=master)](https://travis-ci.org/eclipse/paho.mqtt.cpp) Develop: [![Build Status](https://travis-ci.org/eclipse/paho.mqtt.cpp.svg?branch=master)](https://travis-ci.org/eclipse/paho.mqtt.cpp)

This repository contains the source code for the [Eclipse Paho](http://eclipse.org/paho) MQTT C++ client library on memory-managed operating systems such as Linux/Posix and Windows.

Expand Down Expand Up @@ -35,114 +36,96 @@ Contributions to this project are gladly welcomed. Before submitting a Pull Requ

## Building from source

_CMake_ is now the only supported build system. For information about _autotools_, see [DEPRECATED_BUILD.md](https://github.com/eclipse/paho.mqtt.cpp/blob/master/CONTRIBUTING.md).
_CMake_ is now the only supported build system. For information about _autotools_, see [DEPRECATED_BUILD.md](https://github.com/eclipse/paho.mqtt.cpp/blob/master/CONTRIBUTING.md). CMake is a cross-platform build system suitable for Unix and non-Unix platforms such as Microsoft Windows.

### CMake
The Paho C++ library requires the Paho C library, v1.2.1 or greater, to be built and installed first. More information below.

CMake is a cross-platform build system suitable for Unix and non-Unix platforms like Microsoft Windows.
CMake allows for options to direct the build. The following are specific to Paho C++:

#### Unix and GNU/Linux
Variable | Default Value | Description
------------ | ------------- | -------------
PAHO_BUILD_SHARED | TRUE (Linux), FALSE (Win32) | Whether to build the shared library
PAHO_BUILD_STATIC | FALSE (Linux), TRUE (Win32) | Whether to build the static library
PAHO_BUILD_DOCUMENTATION | FALSE | Create and install the HTML based API documentation (requires Doxygen)
PAHO_BUILD_SAMPLES | FALSE | Build sample programs
PAHO_BUILD_TESTS | FALSE | Build the unit tests
PAHO_WITH_SSL | TRUE (Linux), FALSE (Win32) | Flag that defines whether to build ssl-enabled binaries too

On Unix systems CMake creates Makefiles.
In addition, the C++ build might commonly use `CMAKE_PREFIX_PATH` to help the build system find the location of the Paho C library.

##### Build requirements
### Unix and Linux

On *nix systems CMake creates Makefiles.

The build process currently supports a number of Unix and Linux flavors. The build process requires the following tools:
* CMake (cmake.org)
* GNU Make (www.gnu.org/software/make)
* GCC (gcc.gnu.org)

* CMake v3.5 or newer
* GCC v4.8 or newer or Clang v3.9 or newer
* GNU Make

On Debian based systems this would mean that the following packages have to be installed:

```
apt-get install build-essential gcc make cmake cmake-gui cmake-curses-gui
$ sudo apt-get install build-essential gcc make cmake cmake-gui cmake-curses-gui
```

The documentation requires doxygen and optionally graphviz:
Building the documentation requires doxygen and optionally graphviz to be installed:

```
apt-get install doxygen graphviz
$ sudo apt-get install doxygen graphviz
```

##### Build instructions
First, build and install the Paho C library:

Before compiling, determine the value of some variables in order to configure features, library locations, and other options:
```
$ git clone https://github.com/eclipse/paho.mqtt.c.git
$ cd paho.mqtt.c
$ git checkout v1.2.1
$ cmake -Bbuild -H. -DPAHO_WITH_SSL=ON
$ sudo cmake --build build/ --target install
$ sudo ldconfig
```

Variable | Default Value | Description
------------ | ------------- | -------------
PAHO_BUILD_SHARED | TRUE (Linux), FALSE (Win32) | Whether to build the shared library
PAHO_BUILD_STATIC | FALSE (Linux), TRUE (Win32) | Whether to build the static library
PAHO_BUILD_DOCUMENTATION | FALSE | Create and install the HTML based API documentation (requires Doxygen)
PAHO_BUILD_SAMPLES | FALSE | Build sample programs
PAHO_BUILD_TESTS | FALSE | Build the unit tests
PAHO_WITH_SSL | TRUE (Linux), FALSE (Win32) | Flag that defines whether to build ssl-enabled binaries too
This builds with SSL/TLS enabled. If that is not desired, omit the `-DPAHO_WITH_SSL=ON`.

If you installed the C library on a non-standard path, you might want to pass it as value to the
`CMAKE_PREFIX_PATH` option.
If you installed the C library on a non-standard path, you might want to pass it as value to the `CMAKE_PREFIX_PATH` option.

Using these variables CMake can be used to generate your Makefiles. The out-of-source build is the default on CMake. Therefore it is recommended to invoke all build commands inside your chosen build directory.

An example build session targeting the build platform could look like this:
An example build session might look like this:

```
$ git clone https://github.com/eclipse/paho.mqtt.cpp
$ cd paho.mqtt.cpp
$ mkdir build
$ cd build
$ cmake -DPAHO_BUILD_DOCUMENTATION=TRUE -DPAHO_BUILD_SAMPLES=TRUE -DCMAKE_PREFIX_PATH=../../paho.mqtt.c ..
$ make
$ sudo make install
$ cmake -Bbuild -H. -DPAHO_BUILD_DOCUMENTATION=TRUE -DPAHO_BUILD_SAMPLES=TRUE
$ sudo cmake --build build/ --target install
```

or
If you did not install Paho C library to a default system location or you want to build against a different version, use the `CMAKE_PREFIX_PATH` to specify its install location:

```
$ cmake -DCMAKE_INSTALL_PREFIX=/tmp/paho-cpp -DCMAKE_PREFIX_PATH=/tmp/paho-c \
-DPAHO_BUILD_SAMPLES:BOOL=ON -DPAHO_BUILD_STATIC:BOOL=ON \
-DPAHO_BUILD_DOCUMENTATION:BOOL=ON
$ make
$ sudo make install
$ cmake -Bbuild -H. -DPAHO_BUILD_DOCUMENTATION=TRUE -DPAHO_BUILD_SAMPLES=TRUE \
-DCMAKE_PREFIX_PATH=../../paho.mqtt.c/build/install/usr/local ..
```

Invoking cmake and specifying build options can also be performed using cmake-gui or ccmake (see https://cmake.org/runningcmake/). For example:
To use another compiler, either the CXX environment variable can be specified in the configuration step:

```
$ cmake ..
$ make
$ sudo make install
$ CXX=clang++ cmake ..
```

To use another compiler:
or the `CMAKE_CXX_COMPILER` flag can be used:


```
$ cmake -DCMAKE_CXX_COMPILER=clang++
$ make
$ sudo make install
```

#### Windows

On Windows systems CMake creates Visual Studio project files.

##### Build requirements

The build process currently supports a number Windows versions. The build process requires the following tools:
* CMake GUI (cmake.org)
* Visual Studio (www.visualstudio.com)

##### Build instructions

First install and open the cmake-gui application. This tutorial is based on cmake-gui 3.5.2.

Second, select the path to the Paho MQTT C library (CMAKE_PREFIX_PATH) if not installed in a standard path. Remember that the Paho MQTT C must be installed on the system. Next, choose if it is supposed to build the documentation (PAHO_BUILD_DOCUMENTATION) and/or the sample applications (PAHO_BUILD_SAMPLES).

Once the configuration is done, click on the Configure button, select the version of the Visual Studio, and then click on Generate button.

At the end of this process you have a Visual Studio solution.
#### Updating CMake on Ubuntu 14.04 or 16.04

#### Updating CMake on Ubuntu 14.04 / Mint 17 (LTS)
The versions of CMake on Ubuntu 14.04 or 16.04 LTS are pretty old and have some problems with Paho C++ library. A newer version can be added by downloading the source and building it. If the older cmake can be removed from the system using the package manager, or it can be kept, using the Ububtu alternatives to chose between the versions.

The version of cmake on Ubuntu 14.04 LTS is pretty old and has some problems with Paho C++ library. A newer version can be added by downloading the source and building it. If the older cmake can be removed from the system using the package manager, or it can be kept, using the Ububtu alternatives to chose between the versions. For example:
For example, here's how to install CMake v3.6 on Ubuntu 14.04:

```
$ wget http://www.cmake.org/files/v3.6/cmake-3.6.3.tar.gz
Expand All @@ -158,13 +141,64 @@ $ cmake --version
cmake version 3.6.3
```

You can speed up the build on multi-core systems, by specifying parallel buid jobs for the configure and make steps, above, such as the following for a 4-core system:
You can speed up the CMake build on multi-core systems, by specifying parallel buid jobs for the configure and make steps, above, such as the following for a 4-core system:
```
$ ./configure --parallel=4
$ make -j4
$ sudo make install
```

### Windows

On Windows systems CMake creates Visual Studio project files.

The build process currently supports a number Windows versions. The build process requires the following tools:
* CMake GUI v3.5 or newer
* Visual Studio 2015 or newer

First install and open the cmake-gui application. This tutorial is based on cmake-gui 3.5.2.

Second, select the path to the Paho MQTT C library (CMAKE_PREFIX_PATH) if not installed in a standard path. Remember that the Paho MQTT C must be installed on the system. Next, choose if it is supposed to build the documentation (PAHO_BUILD_DOCUMENTATION) and/or the sample applications (PAHO_BUILD_SAMPLES).

Once the configuration is done, click on the Configure button, select the version of the Visual Studio, and then click on Generate button.

At the end of this process you have a Visual Studio solution.

Alternately, the libraries can be completely built at an MSBuild Command Prompt. Download the Paho C and C++ library sources, then open a command window and first compile the Paho C library:

```
> cd paho.mqtt.c
> cmake -Bbuild -H. -DCMAKE_INSTALL_PREFIX=C:\mqtt\paho-c
> cmake --build build/ --target install
```

Then build the C++ library:

```
> cd ..\paho.mqtt.cpp
> cmake -Bbuild -H. -DCMAKE_INSTALL_PREFIX=C:\mqtt\paho-cpp -DPAHO_BUILD_SAMPLES=ON -DPAHO_WITH_SSL=OFF -DCMAKE_PREFIX_PATH=C:\mqtt\paho-c
> cmake --build build/ --target install
```
This builds and installs both libraries to a non-standard location under `C:\mqtt`. Modify this location as desired or use the default location, but either way, the C++ library will most likely need to be told where the C library was built using `CMAKE_PREFIX_PATH`.

It seems quite odd, but even on a 64-bit system using a 64-bit compiler, MSVC seems to default to a 32-bit build target.

The 64-bit target can be selected using tge CMake generator switch, *-G*, at configuration time. The full version must be provided. For Visual Studio 2015 which is v14 do this to first build the Paho C library:

```
> cmake -G "Visual Studio 14 Win64" -Bbuild -H. -DCMAKE_INSTALL_PREFIX=C:\mqtt\paho-c
...
```

Then use it to build the C++ library:

```
> cmake -G "Visual Studio 14 Win64" -Bbuild -H. -DCMAKE_INSTALL_PREFIX=C:\mqtt\paho-cpp -DPAHO_WITH_SSL=OFF -DCMAKE_PREFIX_PATH=C:\mqtt\paho-c
...
```

*Note that it is very important that you use the same generator (target) to build BOTH libraries, otherwise you will get lots of linker errors when you try to build the C++ library.*


## Example

Expand Down

0 comments on commit 39a2132

Please sign in to comment.