Eclipse Paho MQTT C++ Client Library

This repository contains the source code for the Eclipse Paho MQTT C++ client library for memory-managed operating systems such as Linux, MacOS, and Windows.

This code builds a library which enables Modern C++ applications (C++17 and beyond) to connect to an MQTT broker, publish messages, subscribe to topics, and receive messages from the broker.

The library has the following features:

• Support for MQTT v3.1, v3.1.1, and v5.
• Network Transports:
  • Standard TCP
  • UNIX-domain sockets
  • Secure sockets with SSL/TLS
  • WebSockets
    • Secure and insecure
    • Proxy support
• Message persistence
  • User configurable
  • Built-in File persistence
  • User-defined key/value persistence easy to implement
• Automatic Reconnect
• Offline Buffering
• High Availability
• Blocking and non-blocking APIs
• Modern C++ interface (C++17)

This code requires the Paho C library by Ian Craggs, et al., specifically version 1.3.14 or possibly later.

Latest News

To keep up with the latest announcements for this project, or to ask questions:

Email: Eclipse Paho Mailing List

What’s New in v1.5.x

The latest updates for v1.5 moved the codebase to C++17 and added support for UNIX-domain sockets. They also fixed a number of build issues, now targeting the latest Paho C release, v1.3.14.

The primary changes in the v1.5 versions are:

• Updated the code base to C++17
• Support for the Paho C v1.3.14 release.
  • Support for UNIX-domain sockets
• Reorganize and reformat the sources and added a .clang-format capability.
• Create universal client instances that can connect using v3 or v5. (i.e. no more instances that are only v3 capable)
• Bump the CMake to v3.13
• Fix a large number of CMake build issues
• Updated the GitHub CI
• (v1.5.3) Fixes for building this library and the Paho C library with the latest C & C++ compilers, like Clang 20 and GCC 15 which created some breaking hcanges for legacy code.
• (v1.5.4) Fixes for topic_matcher and topic_filter to match against parent with the multi-field wildcard.

For the full list of updates in each release, see the CHANGELOG.

Contributing

Contributions to this project are gladly welcomed and appreciated. Before submitting a Pull Request, please keep three things in mind:

• This is an official Eclipse project, so it is required that all contributors sign an Eclipse Contributor Agreement (ECA)
• Please submit all Pull Requests against the develop branch (not master).
• Please sign all commits.

For full details, see CONTRIBUTING.md.

Building from source

As of v1.5, the Paho C++ library uses C++17 features, thus requiring a fully compliant C++17 compiler. Some of the more common compilers that can be used, depending on the target platform, are:

• GCC v8 or later
• clang v5 or later
• Visual Studio 2017 15.8 (MSVC 19.15) or later

CMake is a cross-platform build system suitable for Unix and non-Unix platforms such as Microsoft Windows. It is the only supported build system. The current supported minimum version is:

• cmake v3.13

The Paho C++ library requires the Paho C library, v1.3.14 or greater to be built and installed. That can be done before building this library, or it can be done here using the CMake PAHO_WITH_MQTT_C build option to build both libraries at the same time. This also guarantees that a proper version of the C library is used, and that it is build with compatible options.

Build Options

CMake allows for options to direct the build. The following are specific to Paho C++:

Enabling PAHO_WITH_MQTT_C builds and links in the Paho C library using compatible build options. If this is enabled, it passes the PAHO_WITH_SSL option to the C library, and also sets the options PAHO_HIGH_PERFORMANCE and PAHO_WITH_UNIX_SOCKETS for the C lib. These can be disabled in the cache before building if desired.

In addition, the C++ build might commonly use CMAKE_PREFIX_PATH to help the build system find the location of the Paho C library if it was built separately.

Build the Paho C++ and Paho C libraries together

The quickest and easiest way to build Paho C++ is to build it together with Paho C in a single step using the included Git submodule. This requires the CMake option PAHO_WITH_MQTT_C set.

File truncated at 100 lines see the full file

Contributing to Paho

Thanks for your interest in this project!

You can contribute bugfixes and new features by sending pull requests through GitHub.

Legal

In order for your contribution to be accepted, it must comply with the Eclipse Foundation IP policy.

Please read the Eclipse Foundation policy on accepting contributions via Git.

1. Sign the Eclipse ECA
2. Register for an Eclipse Foundation User ID. You can register here.
3. Log into the Eclipse projects forge, and click on ‘Eclipse Contributor Agreement’.
4. Go to your account settings and add your GitHub username to your account.
5. Make sure that you sign-off your Git commits in the following format:

Signed-off-by: Alex Smith <alexsmith@nowhere.com> This is usually at the bottom of the commit message. You can automate this by adding the ‘-s’ flag when you make the commits. e.g.
```git commit -s -m “Adding a cool feature”

4. Ensure that the email address that you make your commits with is the same one you used to sign up to the Eclipse Foundation website with.

## Contributing a change

1. [Fork the repository on GitHub](https://github.com/eclipse/paho.mqtt.cpp/fork)
2. Clone the forked repository onto your computer: 
``` git clone https://github.com/<your username>/paho.mqtt.cpp.git 

1. Create a new branch from the latest

   ``` branch with 
   ```git checkout -b YOUR_BRANCH_NAME origin/develop
   

2. Make your changes
3. If developing a new feature, make sure to include unit tests.
4. Ensure that all new and existing tests pass.
5. Commit the changes into the branch: git commit -s Make sure that your commit message is meaningful and describes your changes correctly.
6. If you have a lot of commits for the change, squash them into a single / few commits.
7. Push the changes in your branch to your forked repository.
8. Finally, go to https://github.com/eclipse/paho.mqtt.cpp and create a pull request from your “YOUR_BRANCH_NAME” branch to the develop one to request review and merge of the commits in your pushed branch.

What happens next depends on the content of the patch. If it is 100% authored by the contributor and is less than 1000 lines (and meets the needs of the project), then it can be pulled into the main repository. If not, more steps are required. These are detailed in the legal process poster.

Developer resources:

Information regarding source code management, builds, coding standards, and more.

• https://projects.eclipse.org/projects/iot.paho/developer

Contact:

Contact the project developers via the project’s development mailing list.

Search for bugs:

This project uses GitHub Issues here: github.com/eclipse/paho.mqtt.cpp/issues to track ongoing development and issues.

Create a new bug:

Be sure to search for existing bugs before you create another one. Remember that contributions are always welcome!

• Create new Paho bug