Please see the [Eclipse Community Code of Conduct](https://eclipse.org/org/documents/Community_Code_of_Conduct.php)
# Community Code of Conduct
**Version 1.2
August 19, 2020**
## Our Pledge
In the interest of fostering an open and welcoming environment, we as community members, contributors, committers, and project leaders pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
## Our Responsibilities
With the support of the Eclipse Foundation staff (the “Staff”), project committers and leaders are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
Project committers and leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
## Scope
This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the Eclipse Foundation project or its community in public spaces. Examples of representing a project or community include posting via an official social media account, or acting as a project representative at an online or offline event. Representation of a project may be further defined and clarified by project committers, leaders, or the EMO.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the Staff at codeofconduct@eclipse.org. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The Staff is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
Project committers or leaders who do not follow the Code of Conduct in good faith may face temporary or permanent repercussions as determined by the Staff.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org) , version 1.4, available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct/)
* 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/)
## Usage and API
Detailed API documentation [is available online](https://www.eclipse.org/paho/files/mqttdoc/MQTTClient/html/index.html). It is also available by building the Doxygen docs in the ``doc`` directory.
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
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
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:
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*
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 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 compile/link the binaries, to install, or to generate packages, use these commands:
```
$ cmake --build .
$ cmake --build . --target install
$ cmake --build . --target package
```
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:
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,93 @@ The provided toolchain files assume that required compilers/linkers are to be fo
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.
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:
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
## Building paho-mqtt - Using vcpkg
You can download and install paho-mqtt using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install paho-mqtt
The paho-mqtt port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.
## Fully static builds with musl libc
(By Frank Pagliughi)
[musl libc](https://musl.libc.org/) is is an implementation of the C standard library built on top of the Linux system call API, including interfaces defined in the base language standard, POSIX, and widely agreed-upon extensions.
Users of the Rust library, which wraps this one, had been complaining that they could not compile using the musl build tools. Musl is a small std C lib that can be statically linked. With the latest Paho C library (and a very minor tweak to the build), we're now able to build Rust apps using musl and Paho C that are fully static; no runtime dependencies on the platform; not even on the standard C lib.
$ ./async_publish
Publishing a message on the 'test' topic
$ ldd async_publish
not a dynamic executable
So, for example, if maintaining a suite of apps for some newer and older embedded Linux boards, the same executables could be deployed without worry about the C ABI on the particular boards.
Certainly C apps using the Paho library could do this also.
