Merge branch 'readme-updates' of https://github.com/fpagliughi/paho.mqtt.c...

Merge branch 'readme-updates' of https://github.com/fpagliughi/paho.mqtt.c into fpagliughi-readme-updates

README.md

@@ -23,9 +23,9 @@ Synchronous and various asynchronous programming models are supported.
 The Paho C client comprises four variant libraries, shared or static:
 
  * paho-mqtt3a - asynchronous (MQTTAsync)
- * paho-mqtt3as - asynchronous with SSL (MQTTAsync)
+ * paho-mqtt3as - asynchronous with SSL/TLS (MQTTAsync)
  * paho-mqtt3c - "classic" / synchronous (MQTTClient)
- * paho-mqtt3cs - "classic" / synchronous with SSL (MQTTClient)
+ * paho-mqtt3cs - "classic" / synchronous with SSL/TLS (MQTTClient)
 
 [Which Paho C API to use, with some history, for context](https://modelbasedtesting.co.uk/2013/10/13/which-paho-mqtt-c-api-to-use-and-some-history/)
 
@@ -33,12 +33,12 @@ The Paho C client comprises four variant libraries, shared or static:
 
 Detailed API documentation [is available online](https://eclipse.github.io/paho.mqtt.c/MQTTClient/html/).  It is also available by building the Doxygen docs in the  ``doc`` directory. 
 
-Samples are available in the Doxygen docs and also in ``src/samples`` for reference.  These are:
+Samples are available in the Doxygen docs and also in `src/samples` for reference.  These are:
 
-- paho_c_pub.c and paho_c_sub.c: command line utilities to publish and subscribe, -h will give help
-- paho_cs_pub.c paho_cs_sub.c: command line utilities using MQTTClient to publish and subscribe
-- MQTTClient_publish.c,	MQTTClient_subscribe.c and MQTTClient_publish_async.c: MQTTClient simple code examples
-- MQTTAsync_publish.c and MQTTAsync_subscribe.c: MQTTAsync simple code examples						
+- *paho_c_pub.c* and *paho_c_sub.c:* command line utilities to publish and subscribe, -h will give help
+- *paho_cs_pub.c* and *paho_cs_sub.c:* command line utilities using MQTTClient to publish and subscribe
+- *MQTTClient_publish.c, MQTTClient_subscribe.c* and *MQTTClient_publish_async.c:* MQTTClient simple code examples
+- *MQTTAsync_publish.c* and *MQTTAsync_subscribe.c:* MQTTAsync simple code examples
 
 Some potentially useful blog posts:
 
@@ -52,11 +52,11 @@ Some potentially useful blog posts:
 
 A number of environment variables control runtime tracing of the C library.
 
-Tracing is switched on using ``MQTT_C_CLIENT_TRACE`` (a value of ON traces to stdout, any other value should specify a file to trace to).
+Tracing is switched on using `MQTT_C_CLIENT_TRACE` (a value of ON traces to stdout, any other value should specify a file to trace to).
 
-The verbosity of the output is controlled using the  ``MQTT_C_CLIENT_TRACE_LEVEL`` environment variable - valid values are ERROR, PROTOCOL, MINIMUM, MEDIUM and MAXIMUM (from least to most verbose).
+The verbosity of the output is controlled using the  `MQTT_C_CLIENT_TRACE_LEVEL` environment variable - valid values are ERROR, PROTOCOL, MINIMUM, MEDIUM and MAXIMUM (from least to most verbose).
 
-The variable ``MQTT_C_CLIENT_TRACE_MAX_LINES`` limits the number of lines of trace that are output.
+The variable `MQTT_C_CLIENT_TRACE_MAX_LINES` limits the number of lines of trace that are output.
 
 ```
 export MQTT_C_CLIENT_TRACE=ON
@@ -71,75 +71,89 @@ Please open issues in the Github project: https://github.com/eclipse/paho.mqtt.c
 
 Discussion of the Paho clients takes place on the [Eclipse paho-dev mailing list](https://dev.eclipse.org/mailman/listinfo/paho-dev).
 
+Follow Eclipse Paho on Twitter: [@eclipsepaho](https://twitter.com/eclipsepaho)
+
 General questions about the MQTT protocol are discussed in the [MQTT Google Group](https://groups.google.com/forum/?hl=en-US&fromgroups#!forum/mqtt).
 
 There is more information available via the [MQTT community site](http://mqtt.org).
 
 
-## Build instructions for GNU Make
+## Building with CMake
 
-Ensure the OpenSSL development package is installed.  Then from the client library base directory run:
+The build process currently supports a number of Linux "flavors" including ARM and s390, OS X, AIX and Solaris as well as the Windows operating system. The build process requires the following tools:
+  * [CMake](http://cmake.org)
+  * [GNU Make](https://www.gnu.org/software/make/) or [Ninja](https://martine.github.io/ninja/)
+  * A conforming C compiler, such as [gcc](https://gcc.gnu.org/), [Clang](https://clang.llvm.org/), etc
+
+On Debian based systems this would mean that the following packages have to be installed:
 
 ```
-make
-sudo make install
+$ apt-get install build-essential gcc make cmake cmake-gui cmake-curses-gui
 ```
 
-This will build and install the libraries.  To uninstall:
+Also, in order to build a debian package from the source code, the following packages have to be installed
 
 ```
-sudo make uninstall
+$ apt-get install fakeroot devscripts dh-make lsb-release
 ```
 
-To build the documentation requires doxygen and optionally graphviz.
+Ninja can be downloaded from its github project page in the "releases" section. Optionally it is possible to build binaries with SSL/TLS support. This requires the OpenSSL libraries and includes to be available. E. g. on Debian:
 
 ```
-make html
+$ apt-get install libssl-dev
 ```
 
-The provided GNU Makefile is intended to perform all build steps in the ```build``` directory within the source-tree of Eclipse Paho. Generated binares, libraries, and the documentation can be found in the ```build/output``` directory after completion. 
+The documentation requires doxygen and optionally graphviz:
 
-Options that are passed to the compiler/linker can be specified by typical Unix build variables:
+```
+$ apt-get install doxygen graphviz
+```
 
-Variable | Description
------------- | -------------
-CC | Path to the C compiler
-CFLAGS | Flags passed to compiler calls
-LDFLAGS | Flags passed to linker calls
+### Building your application with CMake
 
+If the Paho C library was built with CMake and is already installed on the system, it is relatively easy to set up a CMake build for your application. (If it's not already built and installed read the next section).
 
-## Build requirements / compilation using CMake
+The library can be built with several options which create variations of the library for asynchronous or synchronous use; encryption (SSL/TLS) support or not; and whether the library is shared or static. CMake exports all of the libraries that were built as targets, and the user can chose which is best suited for an application.
 
-The build process currently supports a number of Linux "flavors" including ARM and s390, OS X, AIX and Solaris as well as the Windows operating system. The build process requires the following tools:
-  * CMake (http://cmake.org)
-  * Ninja (https://martine.github.io/ninja/) or
-    GNU Make (https://www.gnu.org/software/make/), and
-  * gcc (https://gcc.gnu.org/).
+The package is named: **eclipse-paho-mqtt-c**
 
-On Debian based systems this would mean that the following packages have to be installed:
+The namespace for all the targets is also: **eclipse-paho-mqtt-c**
 
-```
-apt-get install build-essential gcc make cmake cmake-gui cmake-curses-gui
-```
+The target names are the same as the library names. The static libraries append *-static* to the target name even for platforms that use the same base name for shared and static libraries. So:
 
-Also, in order to build a debian package from the source code, the following packages have to be installed
+Target|Description
+------|-----------
+paho-mqtt3a | asynchronous, no encryption
+paho-mqtt3as | asynchronous with SSL/TLS support
+paho-mqtt3c | synchronous, no encryption
+paho-mqtt3cs | synchronous with SSL/TLS support
+paho-mqtt3a-static | asynchronous, no encryption, static linkage
+paho-mqtt3as-static | asynchronous with SSL/TLS support, static linkage
+paho-mqtt3c-static | synchronous, no encryption, static linkage
+paho-mqtt3cs-static | synchronous with SSL/TLS support, static linkage
 
-```
-apt-get install fakeroot devscripts dh-make lsb-release
-```
+Remember, though, that not all of these targets may be available. It depends on how the library was built.
 
-Ninja can be downloaded from its github project page in the "releases" section. Optionally it is possible to build binaries with SSL support. This requires the OpenSSL libraries and includes to be available. E. g. on Debian:
+A sample *CMakeLists.txt* for an application that uses the asynchronous library with encryption support *(paho-mqtt3as)* might look like this:
 
 ```
-apt-get install libssl-dev
+cmake_minimum_required(VERSION 3.5)
+project(MyMQTTApp VERSION 1.0.0 LANGUAGES C)
+
+find_package(eclipse-paho-mqtt-c REQUIRED)
+
+add_executable(MyMQTTApp MyMQTTApp.c)
+target_link_libraries(MQTTVersion eclipse-paho-mqtt-c::paho-mqtt3as) 
 ```
 
-The documentation requires doxygen and optionally graphviz:
+If the library was installed to a non-traditional location, you may need to tell CMake where to find it using `CMAKE_PREFIX_PATH`. For example, if you installed it in */opt/mqtt/paho.mqtt.c*
 
 ```
-apt-get install doxygen graphviz
+$ cmake -DCMAKE_PREFIX_PATH=/opt/mqtt/paho.mqtt.c ..
 ```
 
+### Building the Paho C library with CMake
+
 Before compiling, determine the value of some variables in order to configure features, library locations, and other options:
 
 Variable | Default Value | Description
@@ -162,37 +176,46 @@ Using these variables CMake can be used to generate your Ninja or Make files. Us
 An example build session targeting the build platform could look like this:
 
 ```
-mkdir /tmp/build.paho
-cd /tmp/build.paho
-cmake -GNinja -DPAHO_WITH_SSL=TRUE -DPAHO_BUILD_DOCUMENTATION=TRUE -DPAHO_BUILD_SAMPLES=TRUE ~/git/org.eclipse.paho.mqtt.c
+$ mkdir /tmp/build.paho ; cd /tmp/build.paho
+$ cmake -DPAHO_WITH_SSL=TRUE -DPAHO_BUILD_DOCUMENTATION=TRUE \
+    -DPAHO_BUILD_SAMPLES=TRUE ~/paho.mqtt.c
 ```
 
 Invoking cmake and specifying build options can also be performed using cmake-gui or ccmake (see https://cmake.org/runningcmake/). For example:
 
 ```
-ccmake -GNinja ~/git/org.eclipse.paho.mqtt.c
+$ ccmake ~/paho.mqtt.c
+```
+
+To compile/link the binaries, to install, or to generate packages, use these commands:
+
+```
+$ cmake --build .
+
+$ cmake --build . --target install
+
+$ cmake --build . --target package
 ```
 
-To compile/link the binaries and to generate packages, simply invoke `ninja package` or `make -j <number-of-cores-to-use> package` after CMake. To simply compile/link invoke `ninja` or `make -j <number-of-cores-to-use>`.
+To build, install, or generate packages, you can also use the generated builder like _ninja_ or _make_ directly after invoking the initial CMake configuration step, such as `ninja package` or `make -j <number-of-jpbs> package`.
 
 ### Debug builds
 
-Debug builds can be performed by defining the value of the ```CMAKE_BUILD_TYPE``` option to ```Debug```. For example:
+Debug builds can be performed by defining the value of the `CMAKE_BUILD_TYPE` option to `Debug`. For example:
 
 ```
-cmake -GNinja -DCMAKE_BUILD_TYPE=Debug git/org.eclipse.paho.mqtt.c
+$ cmake -DCMAKE_BUILD_TYPE=Debug ~/paho.mqtt.c
 ```
 
-
 ### Running the tests
 
-Test code is available in the ``test`` directory. The tests can be built and executed with the CMake build system. The test execution requires a MQTT broker running. By default, the build system uses ```localhost```, however it is possible to configure the build to use an external broker. These parameters are documented in the Build Requirements section above.
+Test code is available in the `test` directory. The tests can be built and executed with the CMake build system. The test execution requires a MQTT broker running. By default, the build system uses `localhost`, however it is possible to configure the build to use an external broker. These parameters are documented in the Build Requirements section above.
 
 After ensuring a MQTT broker is available, it is possible to execute the tests by starting the proxy and running `ctest` as described below:
 
 ```
-python ../test/mqttsas2.py &
-ctest -VV
+$ python ../test/mqttsas2.py &
+$ ctest -VV
 ```
 
 ### Cross compilation
@@ -212,24 +235,65 @@ The provided toolchain files assume that required compilers/linkers are to be fo
 Example invocation for the Raspberry Pi:
 
 ```
-cmake -GNinja -DPAHO_WITH_SSL=TRUE -DPAHO_BUILD_SAMPLES=TRUE -DPAHO_BUILD_DOCUMENTATION=TRUE -DOPENSSL_LIB_SEARCH_PATH=/tmp/libssl-dev/usr/lib/arm-linux-gnueabihf -DOPENSSL_INC_SEARCH_PATH="/tmp/libssl-dev/usr/include/openssl;/tmp/libssl-dev/usr/include/arm-linux-gnueabihf" -DCMAKE_TOOLCHAIN_FILE=~/git/org.eclipse.paho.mqtt.c/cmake/toolchain.linux-arm11.cmake ~/git/org.eclipse.paho.mqtt.c
+$ cmake -GNinja -DPAHO_WITH_SSL=TRUE -DPAHO_BUILD_SAMPLES=TRUE \
+    -DPAHO_BUILD_DOCUMENTATION=TRUE \
+    -DOPENSSL_LIB_SEARCH_PATH=/tmp/libssl-dev/usr/lib/arm-linux-gnueabihf \
+    -DOPENSSL_INC_SEARCH_PATH="/tmp/libssl-dev/usr/include/openssl;/tmp/libssl-dev/usr/include/arm-linux-gnueabihf" \
+    -DCMAKE_TOOLCHAIN_FILE=~/paho.mqtt.c/cmake/toolchain.linux-arm11.cmake \
+    ~/paho.mqtt.c
 ```
 
-Compilers for the Raspberry Pi can be obtained from e. g. Linaro (see: http://releases.linaro.org/15.06/components/toolchain/binaries/4.8/arm-linux-gnueabihf/). This example assumes that OpenSSL-libraries and includes have been installed in the ```/tmp/libssl-dev``` directory.
+Compilers for the Raspberry Pi and other ARM targets can be obtained from ARM (https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads)
+
+This example assumes that OpenSSL-libraries and includes have been installed in the `/tmp/libssl-dev` directory.
 
 Example invocation for Windows 64 bit:
 
 ```
-cmake -GNinja -DPAHO_BUILD_SAMPLES=TRUE -DCMAKE_TOOLCHAIN_FILE=~/git/org.eclipse.paho.mqtt.c/cmake/toolchain.win64.cmake ~/git/org.eclipse.paho.mqtt.c
-
+$ cmake -DPAHO_BUILD_SAMPLES=TRUE \
+    -DCMAKE_TOOLCHAIN_FILE=~/paho.mqtt.c/cmake/toolchain.win64.cmake \
+    ~/paho.mqtt.c
 ```
 
 In this case the libraries and executable are not linked against OpenSSL Libraries. Cross compilers for the Windows platform can be installed on Debian like systems like this:
 
 ```
-apt-get install gcc-mingw-w64-x86-64 gcc-mingw-w64-i686
+$ apt-get install gcc-mingw-w64-x86-64 gcc-mingw-w64-i686
+```
+
+## Build instructions for GNU Make
+
+Ensure the OpenSSL development package is installed.  Then from the client library base directory run:
+
+```
+$ make
+$ sudo make install
+```
+
+This will build and install the libraries.  To uninstall:
+
+```
+$ sudo make uninstall
 ```
 
+To build the documentation requires doxygen and optionally graphviz.
+
+```
+$ make html
+```
+
+The provided GNU Makefile is intended to perform all build steps in the ```build``` directory within the source-tree of Eclipse Paho. Generated binares, libraries, and the documentation can be found in the ```build/output``` directory after completion. 
+
+Options that are passed to the compiler/linker can be specified by typical Unix build variables:
+
+Variable | Description
+------------ | -------------
+CC | Path to the C compiler
+CFLAGS | Flags passed to compiler calls
+LDFLAGS | Flags passed to linker calls
+
+
+
 ## Microsoft Windows
 
 ### Calling convention