Home

Awesome

Overview

This repository is a combination of tutorials and various how-to(s) for CommsChampion Ecosystem. It is important to understand the available components and their respective roles. Please read the introduction if you haven't done so yet.

The tutorials are organized as a combination tutorials/tutorialX folders. They gradually introduce various concepts as well as explain various nuances for specific use cases. The tutorials are expected to be read sequentially one by one. Be patient and try to follow them through even if a tutorial subject seems irrelevant to a particular use case you are trying to implement. It might still introduce a concept relevant for further tutorials.

The how-to(s) on the other hand, do not have any particular organization. They reside in howtos/howtoX folders and can be read independently. HOWEVER, it is paramount to understand the core ideas explained in tutorials before attempting to understand a particular howto example. The howto(s) are there to provide some extra examples or cover some specific nuances which are not explained properly in the tutorials. If you encounter a sutuation where it is not 100% clear how to define and/or implement some logic please open an issue for this project or send a direct e-mail. Maybe your question will end up as one of the howtos.

It is highly recommended to open a source code with your favourite IDE to be able to easily navigate it and have a full code listing visible, while reading the README files of the tutorials from this github repository using your browser.

The CommsChampion Ecosystem was built to be easy to use while providing sensible behavioural defaults suitable for most of C++ applications. It is also very flexible when it comes to application specific configurations. However, it is very difficult to cover all the capabilities in a set of introductory tutorials. It is highly recommended to read through the CommsDSL specification in order to understand the full capabilities of the schema definition as well as COMMS Library documentation (especially How to Use Defined Custom Protocol page) in order to understand application specific configuration, after finishing the whole set of the tutorials from this repository.

Repository Organization

Every tutorials/tutorialX and howotos/howtoX folder may contain the following files / directories:

IMPORTANT EMPHASIS: The include folder of each and every tutorials/tutorialX and howtows/howtoX is the generated code produced by the commsdsl2comms code generation tool during the build process. Note, that it is a bad practice to keep generated code as sources of the repository and should not be done in real life projects. It was done here to allow easy generated code demonstration and references to it from the tutorial text. Also note that commsdsl2comms generates a full CMake project while only its include folder is copied to the tutorial.

This whole repository is also a CMake project which builds code of all the tutorials and how-to(s). Every tutorial and how-to implements both client and server side of the same protocol and produces X_client and X_server binary executables (where X is the name of the tutorial / how-to). In most cases the server is an echo one, it parses the received output, creates appropriate message object, then serializes and sends it back to the client. The client-s usually send multiple messages to the server and then process and print the received messages. After exchanging all the planned messages with the server, the connection session is terminated.

The I/O handling framework used for all the applications is Boost.Asio and TCP/IP communication was chosen for all the built client / server applications. The relevant code is common for all the applications and is abstracted away into the common static library (residing in the lib folder). Note, that protocol handling and management code is completely I/O link independent and can be used in the same way with any I/O link type.

To test the binaries of the specific tutorial, first run the server application in your terminal window. It is expected to run indefinitely until manually terminated with CTRL+C. In the second terminal window run the client application. In most cases it will exchange several messages with the server and exit.

Updates to the Tutorial(s)

Any future updates to the COMMS Library and/or commsdsl2comms code generator will probably result in updates to this tutorial. All the new updates can be viewed on the releases page. The releases are all date based for easier tracking when an update was introduced.

References

The core component of the CommsChampion Ecosystem is COMMS Library. Its full tutorial and API reference can be viewed online or downloaded from latest release artifacts. The full tutorial on how to use the COMMS Library resides in How to Use Defined Custom Protocol page of the documentation.

The commsdsl2comms code generator requires schema file(s) to be written in CommsDSL. The full specification can be viewed online or downloaded as PDF from latest release artifacts.

How to Build

This project uses CMake as its build system. Please open main CMakeLists.txt file and review available options as well as mentioned available parameters, which can be used in addition to standard ones provided by CMake itself, to modify the default build.

This project also has external dependencies, it requires an access to the COMMS Library and code generators from commsdsl projects. These dependencies are expected to be built independenty and access to them provided via standard CMAKE_PREFIX_PATH and/or CMAKE_PROGRAM_PATH (for the binaries of the code generators). There are also scripts ( script/prepare_externals.sh for Linux and script/prepare_externals.bat for Windows) which can help in preparation of these dependencies. They are also used in configuration of the github actions.

NOTE, that Boost libraries are also required. In case Boost libraries are not installed in expected default location (mostly happens on Windows systems), use variables described in CMake documentation to help CMake find required libraries and headers. It is recommended to use -DBoost_USE_STATIC_LIBS=ON parameter to force linkage with static Boost libraries.

Linux Build

$> cd /source/of/this/project
$> mkdir build && cd build
$> cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/install \
    -DCMAKE_PREFIX_PATH=/path/to/comms -DCMAKE_PROGRAM_PATH=/path/to/commsdsl
$> make install

Windows Build

$> cd C:\source\of\this\project
$> mkdir build
$> cd build
$> cmake .. -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release ^
    -DCMAKE_INSTALL_PREFIX=%cd%/install ^
    -DBOOST_ROOT="C:\Libraries\boost_1_65_1" -DBoost_USE_STATIC_LIBS=ON ^
    -DCMAKE_PREFIX_PATH=C:\path\to\comms -DCMAKE_PROGRAM_PATH=C:\path\to\commsdsl
$> nmake install

Tutorials

How-Tos

`