cariad-tech / dev_essential

Dev essential

• Dev essential
  • Introduction
  • How to build
  • How to use
  • Supported platforms
  • Portation guide
  • Changelog
  • License Information

Introduction

The dev_essential project is the successor of the following projects:

• Utility library aka a_util
• Package Remote Procedure Call aka pkg_rpc
• Data Definition Language Library aka ddl
• DDL C Application Programming Interface aka ddl_capi
• ...

The dev_essential project strives for backwards compatibility with the latest versions of these projects. The following table provides an overview of the versions and the compatibility.

Project	Supported since
a_util v5.8.x	dev_essential 1.0.0
pkg_rpc 3.5.x	dev_essential 1.0.0
ddl 4.6.x	dev_essential 1.0.0
ddl_capi	dev_essential 1.1.0

However, for downstream projects already using one of the aforementioned projects and porting to the dev_essential project, the portation guide shall be consulted.

How to build

Build with CMake

• Download CMake at least in version 3.20.0
• Using git, clone the repository and checkout the desired branch (e.g. master)
• Use CMake with CMakeLists.txt within the root directory
• Do not forget to set CMAKE_INSTALL_PREFIX
• Example:
  • cmake -H<root_dir> -B<build_dir> -G "Visual Studio 16 2019" -DCMAKE_INSTALL_PREFIX=<install_dir>
  • cmake --build . --target INSTALL --config RelWithDebInfo

CMake options

dev_essential_cmake_enable_integrated_tests (default: OFF)

• Enable tests as integrated build - requires googletest

dev_essential_cmake_enable_self_contained_header_tests (default: ON)

• Whether or not to enable tests checking for self contained header files
• Requires dev_essential_cmake_enable_integrated_tests=ON

dev_essential_cmake_enable_third_party_tests (default: OFF)

• Enable tests of 3rdparty dependencies
• Requires dev_essential_cmake_enable_integrated_tests=ON

dev_essential_cmake_enable_position_independent_code (Default: ON)

• Enable position independent code for static libraries

dev_essential_cmake_enable_result_header_only (default: OFF)

• Whether or not to build header only version of dev_essential_result library

dev_essential_cmake_enable_visibility_hidden (default: ON)

• If ON, set visibility of target symbols to hidden, otherwise use the default visibility

dev_essential_cmake_enable_warn_on_default_cmake_install_prefix (Default: ON)

• Warn if CMAKE_INSTALL_PREFIX is set to default

dev_essential_cmake_enable_add_test_command (Default: OFF)

• If OFF, a fatal error is emitted when using add_test() command in subfolder test/. Instead gtest_discover_tests() shall be used.
• Requires dev_essential_cmake_enable_integrated_tests=ON

How to use

Use with CMake

To simply use all components in your project, use

• find_package(dev_essential) with dev_essential_DIR=<dev_essential_root>/lib/cmake/dev_essential, with <dev_essential_root> being the path to the dev_essential installation folder
• target_link_libraries(<target> PRIVATE|PUBLIC dev_essential::dev_essential) with <target> being the name of your library or executable

To only use specific components in your project, use

• find_package(dev_essential COMPONENTS <components>) with <components> being a list of components (e.g. process, xml, ...), separated by spaces
• target_link_libraries(<target> PRIVATE|PUBLIC dev_essential::<component>) with
  • <target> being the name of your library or executable and
  • <component> being the component you want to link against

Use in your code

To simply use all functionality of one component, include the equivalent component header into your code. For example, to use all functionality of components a_util::filesystem and a_util::process:

// my_file.h

#include <a_util/filesystem.h> // for a_util::filesystem
#include <a_util/process.h>    // for a_util::process

However, all delivered header files are self-contained and so each functionality can be included individually.

---

NOTE: Do not directly include header files ending with _decl.h or _impl.h. Those files are meant for implementation specific functionalilty and might change unannounced in future releases.

---

Supported platforms

The libraries are currently built and tested using the following compilers and operating systems:

Windows

• Visual C++ (x86_64): 14.1, 14.2

Linux

• GCC (-std=c++14, libstdc++11, x86_64): 5.4.0, 5.5.0. 7.5.0, 8.4.0
• GCC (-std=c++14, libstdc++11, armv8): 5.4.0, 7.5.0

QNX

• GCC (-std=c++1y, libstdc++11, x86): 5.2.0

Portation guide

The following changes have to be done.

a_util

CMake

• find_package(a_util REQUIRED) → find_package(dev_essential REQUIRED)
• find_package(a_util REQUIRED COMPONENTS <component>) → find_package(dev_essential REQUIRED COMPONENTS <component>)
  • e.g. find_package(a_util REQUIRED COMPONENTS xml) → find_package(dev_essential REQUIRED COMPONENTS xml)
• target_link_libraries(myLib a_util) → target_link_libraries(myLib dev_essential::dev_essential) NOTE: This pulls in ALL components, including those ported from other projects (e.g. pkg_rpc)
• target_link_libraries(myLib a_util_<component>) → target_link_libraries(myLib dev_essential::<component>)
  • e.g. target_link_libraries(myLib a_util_xml) → target_link_libraries(myLib dev_essential::xml)

ddl library

CMake

• find_package(ddl REQUIRED) → find_package(dev_essential REQUIRED COMPONENTS ddl)
• target_link_libraries(myLib ddl) → target_link_libraries(myLib dev_essential::ddl)

C++

All headers are moved to subfolder ddl which is reflected in the include directories. So e.g. the following includes:

#include <ddl.h>
#include <codec/pkg_codec.h>
//...

Become respectively:

#include <ddl/ddl.h>
#include <ddl/codec/pkg_codec.h>
//...

---

Namespace mapping::oo is removed, all implementations went into namespace mapping. Namespace mapping is moved into namespace ddl. All references to namespace mapping need to be referenced by namespace ddl::mapping now. So the following usage of namespace mapping:

using MapConfiguration = mapping::oo::MapConfiguration;

Becomes:

using MapConfiguration = ddl::mapping::MapConfiguration;

---

The implementation of the deprecated ddl::DDLDescription has been removed and completely refactored into the new DDL DataDefinition. Please refer to the DD documentation for its usage. A guide to port the deprecated DDL description to the new DDL DataDefinition is under development.

pkg_rpc

CMake

• find_package(pkg_rpc REQUIRED) → find_package(dev_essential REQUIRED COMPONENTS pkg_rpc)
• target_link_libraries(myLib pkg_rpc) → target_link_libraries(myLib dev_essential::pkg_rpc)

C++

The following includes:

#include <pkg_rpc.h>
#include <rpc_pkg/rpc_server.h>
#include <rpc_pkg/json_rpc.h>

Become respectively:

#include <rpc/rpc.h>
#include <rpc/rpc_server.h>
#include <rpc/json_rpc.h>

Changelog

The changelog can be found here.

License Information

Dev essential libraries - License

The dev essential libraries are delivered under the MPL - Mozilla Public License - Version 2.0.

Used software license information

The dev essential libraries are delivered with the following 3rdparty dependencies:

• clipp 1.2.3 (License)
• current_function of Boost 1.64.0 (License)
• pugixml 1.8 (License)
• uuid 1.6.2 (License)
• UTF8-CPP (License)