README.md

libcluon

Linux & OSX Build (TravisCI)	Win64 Build (AppVeyor)	Test Coverage	Coverity Analysis	CII Best Practices

libcluon is a small single-file, header-only library written in modern C++ library to glue microservices - in a clever way - simply: cluon. Its name is inspired by gluon, an elementary particle acting as exchange particle.

libcluon is distributed as single-file, header-only library - just drop cluon-complete.hpp into your project, #include "cluon-complete.hpp", and compile your project with a modern C++ compiler (C++14 or newer)

Say you want to quickly realize a distributed software system where individual software components exchange messages and you want to keep your project as simple and clean as possible - that's a typical use-case for libcluon. Getting Started Tutorial using an online C++ compiler.

Table of Contents

• Features
• Dependencies
• Installation on Ubuntu 20.04 LTS
• Installation on Ubuntu 18.04 LTS
• Installation on Debian
• Installation on Alpine 3.13
• Installation on Windows
• Build from sources on the example of Ubuntu 16.04 LTS
• Tutorials
• Contributing
• License

Features

• Written in highly portable and high quality C++14
• Available as header-only, single-file distribution - just drop cluon-complete.hpp into your project, #include "cluon-complete.hpp", and compile your project with a modern C++ compiler (C++14 or newer)
• Message compiler produces fully self-contained messages that do only depend on C++14 - external libraries are not needed allowing easy embedding into existing projects
• Native implementation of Protobuf for data serialization & deserialization: Example
• Native implementation of LCM/ZCM for data serialization & deserialization: Example
• Native implementation of JSON for data serialization & deserialization: Example
• Native implementation of MsgPack for data serialization & deserialization: Example
• libcluon natively available for JavaScript via Emscripten: libcluon.js
• Portable implementation of publish/subscribe communication (Linux, MacOSX, Windows): Example
• Intermediate Data Representation (IDR) enables flexible message transformations at runtime; for example: Convert Protobuf to JSON or convert OD4 to JSON or convert LCM to JSON at runtime without generating any data structures beforehand
• Message self-reflection to extract portable message specifications at runtime: Examples
• Message transformatiom into platform-independent CSV format: Examples

Dependencies

No dependencies! All you need is a C++14-compliant compiler as the project ships the following dependencies as part of the source distribution:

• Unit Test Framework Catch2 v2.11 - - Source
• adishavit/argh v1.3.1 - - Source
• chrberger/stringtoolbox - - Source
• kainjow/Mustache v4.1 - - Source
• thelink2012/any - - Source
• yhirose/cpp-peglib v0.1.7 - - Source

As part of our CI strategy thanks to TravisCI and AppVeyor, we are continuously building with:

• Darwin 16.7.0 (x86_64)/AppleClang 9.0.0.9000038

• FreeBSD 11.1 (x86_64)/GCC 6.4.0

• NetBSD 8.0 (x86_64)/GCC 5.5.0

• OpenBSD 6.3 (x86_64)/clang 5.0.1

• Windows (x86_64)/MSVC 19.13.26129.0

• Ubuntu 18.04 LTS (x86_64)/GCC 7.4.0

• Ubuntu 18.04 LTS (x86_64)/clang 7.0.0

• Ubuntu 16.04 LTS (x86_64)/GCC 5.4.0

• Ubuntu 16.04 LTS (x86_64)/clang 7.0.0

• Ubuntu 14.04 LTS (armhf)/clang 3.8.1

• Ubuntu 14.04 LTS (x86_64)/GCC 8.0.1

• Ubuntu 14.04 LTS (x86_64)/GCC 7.3.0

• Ubuntu 14.04 LTS (x86_64)/GCC 6.4.0

• Ubuntu 14.04 LTS (x86_64)/GCC 5.5.0

• Ubuntu 14.04 LTS (x86_64)/clang 6.0.1

• Ubuntu 14.04 LTS (x86_64)/clang 5.0.2

• Ubuntu 14.04 LTS (x86_64)/clang 5.0.0

• Ubuntu 14.04 LTS (x86_64)/clang 4.0.1

• Ubuntu 14.04 LTS (x86_64)/clang 3.9.1

• Ubuntu 14.04 LTS (x86_64)/clang 3.8.0

Installation

Installation as single-file, header-only library

libcluon is provided as header-only, single-file library as well - just drop cluon-complete.hpp into your project, #include "cluon-complete.hpp" where you want to use libcluon, and compile your project with a modern C++ compiler (C++14 or newer).

Installation on Ubuntu 20.04 LTS

We are providing pre-compiled binaries for Ubuntu 20.04 LTS (Focal Fossa) via Ubuntu's Launchpad for amd64, i386, armfh, and arm64; simply add the following PPA to your sources list:

sudo add-apt-repository ppa:chrberger/libcluon

Afterwards, update your package database and install libcluon:

sudo apt-get update
sudo apt-get install libcluon

Installation on Ubuntu 18.04 LTS

We are providing pre-compiled binaries for Ubuntu 18.04 LTS (Bionic Beaver) via Ubuntu's Launchpad for amd64, i386, armfh, and arm64; simply add the following PPA to your sources list:

sudo add-apt-repository ppa:chrberger/libcluon

Afterwards, update your package database and install libcluon:

sudo apt-get update
sudo apt-get install libcluon

Installation on Debian

To use libcluon on Debian, you need to add the repository key first:

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 8EA63C9470BA0E595B75BBA2A92E492AC0B8C7EC

Afterwards, install add-apt-repository and its dependencies:

sudo apt install dirmngr software-properties-common

Then, you can add the libcluon repository:

sudo add-apt-repository ppa:chrberger/libcluon

Now, you can finally install libcluon:

sudo apt update && sudo apt install libcluon

Installation on Alpine 3.13

We are providing pre-compiled binaries for Alpine 3.13 for x86_64, armfh, and aarch64; simply install the pre-compile .apk package as follows:

apk add libcluon --no-cache --repository https://chrberger.github.io/libcluon/alpine/v3.13 --allow-untrusted

Installation on Windows

We are providing pre-compiled binaries including debug symbols for Windows 64 via BinTray here: https://bintray.com/chrberger/libcluon/libcluon-win64-debug#files/

Build from sources on the example of Ubuntu 16.04 LTS

To compile libcluon from sources on an Ubuntu 16.04 LTS (Xenial Xerus) system, you need to have build-essential, cmake, and git installed:

sudo apt-get install build-essential git cmake

Afterwards, simply clone our Git repository:

git clone https://github.com/chrberger/libcluon.git

As an alternative, you can download our latest source release from here: https://github.com/chrberger/libcluon/releases/latest

Change to your working copy and create a build folder:

cd libcluon
mkdir build
cd build

Next, run cmake to create the necessary build files:

cmake ../libcluon

Finally, compile and install the software:

make
make test
make install

Tutorials & API Documentation

• API Documentation
• Tutorial: "Getting Started" explaining how to exchange messages between distributed applications (using an online C++ compiler)
• Tutorial: Sending & receiving data via UDP (using an online C++ compiler)
• Tutorial: Creating a TCP server to send & receive data (using an online C++ compiler)
• Tutorial: Exchanging data via shared memory with wait & notify (using an online C++ compiler)
• Tutorial: Timestamping (using an online C++ compiler)
• Tutorial: Encoding & decoding using libcluon's native Protobuf (using an online C++ compiler)
• Tutorial: Encoding & decoding using libcluon's native LCM (using an online C++ compiler)
• Tutorial: Encoding & decoding using libcluon's native MsgPack (using an online C++ compiler)
• Tutorial: Encoding using libcluon's native JSON (using an online C++ compiler)
• Tutorial: Encoding using libcluon's native CSV (using an online C++ compiler)
• Tutorial: Encoding & decoding with dynamic message specifications using libcluon's native Protobuf (using an online C++ compiler)
• Tutorial: Turn a JSON string into Protobuf with dynamic message specifications (using an online C++ compiler)
• Tutorial: Using libcluon to realize an application communicating between JavaScript and C++

Contributing

We are happy to receive your PRs to accelerate libcluon's development; before contributing, please take a look at the Contribution Documents.

License

• This project is released under the terms of the Mozilla Public License 2.0 - - FAQ
• Commercial support is available at [email protected]