7.1.1. C/C++ Setup#

To set up your environment for C++ development with eCAL, you will need:

  • A C++ compiler (e.g., GCC, Clang, or MSVC) compatible with C++14 or newer.

  • CMake (version 3.16 or higher) for project configuration and build management.

  • An installed eCAL SDK, as described in the general installation instructions.

  • Optionally, additional libraries such as Protobuf, Cap’n Proto, or FlatBuffers if you plan to use those features.

7.1.1.1. Including eCAL in CMake Projects#

For a basic integration, find_package(eCAL REQUIRED) needs to be called. CMake locates libraries using the find_package command, which searches for installed packages and their configuration files. When installing eCAL via PPA, Debian package, or the Windows installer, the necessary CMake configuration files are placed in standard system locations. This means that find_package(eCAL REQUIRED) should work out of the box, and CMake will automatically find eCAL without requiring manual path configuration.

Furthermore, the eCAL::core target needs to be linked in order to be able to create binary publishers and subscribers.

The CMakeLists.txt looks as follows:

cmake_minimum_required(VERSION 3.16)
project(blob_send)

# Tell CMake to find the eCAL installation.
find_package(eCAL REQUIRED)

# We create an executable and add a source file.
add_executable(blob_send)
target_sources(blob_send
  PRIVATE
    blob_send.cpp
)

# Finally we need to link the necessary eCAL libraries to the executable.
# The appropriate target name can be taken from the target name table.
target_link_libraries(blob_send
  PRIVATE
    eCAL::core
)

7.1.1.2. Protobuf entity integration#

When using special serialization protocols like Protobuf, a few more steps are necessary for a proper CMake integration. In addition to the previous example, you will need to call find_package(Protobuf REQUIRED). Furthermore you want to handle the generation of the protobuf headers for your language.

cmake_minimum_required(VERSION 3.16)

# This CMakeLists.txt is used to build a protobuf example for eCAL.
# So we name this project, which is also the name of the executable, accordingly.
project(ecal_hello_world_send_protobuf)

# We set the C++ standard to C++14, which is currently required by eCAL.
set(CMAKE_CXX_STANDARD 14)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Tell CMake to find the eCAL installation and the protobuf library.
find_package(eCAL REQUIRED)
find_package(Protobuf REQUIRED)

# Set a list all source files for the project.
# In our case it is only one file, but can be simply extended to multiple files.
set(source_files
  hello_world_send_protobuf.cpp
)

# We set a list of protobuf files here. The path is relative to the CMakeLists.txt file.
# This CMakeLists.txt assumes that the protobuf files are located in the ../proto_messages/ directory.
set(protobuf_files
    ${CMAKE_CURRENT_SOURCE_DIR}/../proto_messages/hello_world.proto
)

# Now we add the source file to the executable to be generated.
# The name of the executable is the same as the project name.
add_executable(${PROJECT_NAME} ${source_files})

# We need to tell CMake to generate the protobuf files. This is done by the PROTOBUF_TARGET_CPP function.
# This compiles the .proto file to a C++ header, in our case "hello_world.pb.h".
# Note that the PROTOBUF_TARGET_CPP function is a eCAL convenience function. 
# You can also use the protobuf_generate_cpp function from the protobuf package directly if you are already familiar with it.
PROTOBUF_TARGET_CPP(${PROJECT_NAME} ${CMAKE_CURRENT_SOURCE_DIR}/../proto_messages/ ${protobuf_files})

# Finally we need to link the necessary libararies to the executable.
# Which target you link to depends on the type of the message you are using.
# In our case we use the protobuf message, so we link to the eCAL protobuf core library.
target_link_libraries(${PROJECT_NAME}
  PRIVATE
  eCAL::protobuf_core
)

Tip

The PROTOBUF_TARGET_CPP function is a convenience function from eCAL. If you have already worked with Protobuf and CMake, you may be more familiar with the following code, which basically does the same thing:

include_directories(${CMAKE_CURRENT_BINARY_DIR})
protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS ${protobuf_files})
add_executable(${PROJECT_NAME} ${source_files} ${PROTO_SRCS} ${PROTO_HDRS})

7.1.1.3. Common CMake targets#

Below, please find an overview of the different CMake targets that are available for eCAL.

eCAL CMake targets#

CMake target

Description

eCAL::core

C++ core functionality

eCAL::core_c

C core functionality

eCAL::string_core

C++ std::string publisher/subscriber extension (implicitly links eCAL::core)

eCAL::protobuf_core

C++ protobuf publisher/subscriber/client/server extension (implicitly links eCAL::core)

eCAL::capnproto_core

C++ capnproto publisher/subscriber extension (implicitly links eCAL::core)

eCAL::flatbuffers_core

C++ flatbuffers publisher/subscriber extension (implicitly links eCAL::core)

eCAL::measurement

read/write binary eCAL measurements

eCAL::string_measurement

read/write eCAL measurements with string (implicitly links eCAL::measurement)

eCAL::protobuf_measurement

read/write eCAL measurements with protobuf (implicitly links eCAL::measurement)

eCAL::capnproto_measurement

read/write eCAL measurements with capnproto (implicitly links eCAL::measurement)

eCAL::flatbuffers_measurement

read/write eCAL measurements with flatbuffers (implicitly links eCAL::measurement)