Hephaestus#

A high-performance C++ framework for production-ready robotics development.

Overview#

Hephaestus is a C++ framework designed for deploying robotic systems in production environments. It provides essential, performance-critical functionalities while abstracting away common C++ complexities, allowing developers to focus on their robotics-specific implementation.

Unlike other robotics frameworks that prioritize rapid prototyping, Hephaestus emphasizes production-ready code with a focus on performance, stability, and simplicity.

Design Philosophy#

Production-First: Features are added only if they improve production code quality through enhanced performance, stability, or simplicity
Focused Scope: Concentrates on common infrastructure needs across robotic platforms while avoiding use-case specific implementations
C++ Abstraction: Reduces cognitive load by handling complex C++ patterns and best practices automatically

Core Features#

Current Implementation#

Hephaestus provides robust abstractions for fundamental robotics infrastructure:

Memory Management - Automated memory handling - Memory pools for efficient allocation
Concurrency - Thread pools - Parallelism primitives - Thread-safe containers for cross-thread data sharing
System Communication - Inter-Process Communication (IPC) - Data serialization for communication and storage
Performance Optimization - Real-time execution capabilities - Telemetry for system monitoring

Project Status#

Note

Many features are currently under development. Please check the issue tracker or project boards for current status.

When should you use this over ROS? Click [here](doc/comparison_to_ros.md)!

Scope Limitations#

Hephaestus intentionally excludes the following to maintain focus and allow for use-case optimization:

Data type definitions (images, point clouds, etc.)
Visualization tools
Geometric operations
Autonomy algorithms
Use-case specific implementations

This deliberate limitation allows teams to implement these features optimally for their specific robotics applications while leveraging Hephaestus’s robust infrastructure.

Dev Env#

The best way to build Hephaestus is to do it inside the docker container provided in the docker folder. You can build and start the container with make docker-up.

If you use VS Code, run make configure-attach-container and then Command Palette (Ctrl+Shift+P) Dev Containers: Attach to Running Container... -> /hephaestus-dev

Bazel#

Bazel is the official tool to build Hephaestus.

Commands#

# Build:
bazel build //modules/...

# You can also build a specific module or library by providing the path:
``bazel build //modules/ipc/...``
``bazel build //modules/ipc:zenoh_topic_list``

# Build with clang-tidy:
bazel build //modules/... --config clang-tidy``

# Run tests
bazel test //modules/...

# Format the code:
bazel run :format       # fixes the formatting errors
bazel run :format.check # fails on error

# Generate ``compile_commands.json``, for VS Code ``clangd`` tool:
bazel run :refresh_compile_commands

# Run binaries:
bazel run //modules/ipc:zenoh_topic_list
# or:
./bazel-bin/modules/ipc/zenoh_topic_list

Clang-tidy Profiling#

It is possible to run clang-tidy with profiling enabled to see how long each check takes. To do that: * in clang_tidy.bzl uncomment line # args.add("--enable-check-profile") * in run_clang_tidy.sh comment current trap command and uncomment # trap 'head -n 15 "$logfile" 1>&2' EXIT

This will print stats for each files sorted by time.

Folders#

For more details see https://bazel.build/remote/output-directories

Bazel generates three folders in the workspace:

bazel-bin: Contains the binaries and release artifacts like debians and packages
bazel-out: Contains build artifacts, build and test logs
bazel-hephaestus: Can be ignored

CMake#

The following sections contains all the information needed to use Hephaestus with CMake

Compilation#

Hephaestus uses CMake to build, the build infrastructure is copied and adapted from [grape](cvilas/grape).

To build it:

cd hephaestus
mkdir build && cd build
cmake --preset default ..
ninja all examples

To compile and run the unit test

ninja check

> TODO: add section on the different flags and options.

Build system#

You can use the build system of hephaestus in your own project by importing the CMake files and recreating the required folder structure.

Create the top level CMakeLists.txt as:

cmake_minimum_required(VERSION 3.22.1)
project(my_project LANGUAGES CXX C)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

include(FetchContent)
FetchContent_Declare(
    hephaestus
    GIT_REPOSITORY "https://github.com/olympus-robotics/hephaestus.git"
    GIT_TAG "main"
)
FetchContent_GetProperties(hephaestus)
if(NOT hephaestus_POPULATED)
  FetchContent_Populate(hephaestus)
endif()

# If you want to use hephaestus toolchain add:
# set(CMAKE_TOOLCHAIN_FILE ${hephaestus_SOURCE_DIR}/cmake/toolchains/toolchain_clang.cmake)

# Include the Cmake functions.
include(${hephaestus_SOURCE_DIR}/cmake/build.cmake)

Create the modules folder and add your modules. You can use the hephaestus script by calling: .. code-block:: bash

cd modules python3 ../cmake/create_module.py my_module

Create the external folder and add a CMakeLists.txt file as:

cmake_minimum_required(VERSION 3.27.3)
project(my_project-external LANGUAGES C CXX)

include(${CMAKE_TEMPLATE_DIR}/external.cmake)

# Add your desired dependencies:
# add_cmake_dependency(
#     NAME hephaestus
#     GIT_REPOSITORY "https://github.com/olympus-robotics/hephaestus.git"
#     GIT_TAG "main"
#     CMAKE_ARGS -DBUILD_MODULES="utils"
# )

Using Hephaestus#

There are multiple ways to use Hephaestus in your repo.

Global installation#

Install hephaestus in a known folder, e.g. /install. When you compile your project pass -DCMAKE_PREFIX_PATH=/install and in your CMakeLists.txt:

find_package(hephaestus REQUIRED <component1> <component2>) # e.g. find_package(hephaestus REQUIRED ipc serdes)

add_library(my-lib ...)
target_link_libraries(my-lib
    PUBLIC hephaestus::ipc hephaestus::serdes
)

Use Hephaestus CMake build system#

Using Hephaestus build system build hephaestus together with your project:

add_cmake_dependency(
    NAME hephaestus
    GIT_REPOSITORY "https://github.com/olympus-robotics/hephaestus.git"
    GIT_TAG "main"
    CMAKE_ARGS -DBUILD_MODULES="utils"
)

and in your library CMakeLists.txt:

find_package(hephaestus REQUIRED <component1> <component2>) # e.g. find_package(hephaestus REQUIRED ipc serdes)

add_library(my-lib ...)
target_link_libraries(my-lib
    PUBLIC hephaestus::ipc hephaestus::serdes
)

Include Hephaestus as a submodule#

Add Hephaestus as a git submodule to your project (e.g. in third_party/hephaestus) and in the root CMakeLists.txt before adding your libraries add:

set(BUILD_MODULES "ipc;serdes") # or ``all`` if you want to build all of it.
add_subdirectory(third_party/hephaestus)

if you are using Hephaestus build system for your project you need to backup the modules list to keep it separate between the Hephaestus ones and yours:

set(hephaestus_SOURCE_DIR ${CMAKE_SOURCE_DIR}/third_party/hephaestus)

set(BUILD_MODULES_BAK ${BUILD_MODULES})
set(BUILD_MODULES "utils")
add_subdirectory(${hephaestus_SOURCE_DIR})

set(BUILD_MODULES ${BUILD_MODULES_BAK})
include(${hephaestus_SOURCE_DIR}/cmake/build.cmake)

Linting#

We’ve added shell script linting using shellcheck and docker linting using hadolint. To use this locally, add the following to your pre-commit hook file. ``` git_root=$(git rev-parse –show-toplevel)

if result=$(git status –porcelain | grep -E ‘^[MATRC]. docker/’); then: echo “Running Hadolint” “.github/scripts/hadolint.sh”

if result=$(git status –porcelain | grep -E ‘^[MATRC].*.sh’); then: echo “Running Shellcheck” “$git_root/.github/scripts/shellcheck.sh”

Spelling#

Spell checking on source code is done using [typos](crate-ci/typos). There is a make` target for spellcheck and spellfix.

Notes#

Initially this repo was supporting C++23, but to maximize compatibility we reverted back to C++20.

When switching again back to C++23 it will be possible to remove fmt and ranges-v3. The transition will be easy, just rename fmt:: -> std:: and remove fmt::formatter.

TODO#

Hephaestus is under active development. The list of tasks to be carried out can be found under the Hephaestus Masterplan project.

Development

Writing Documentation

Modules

Reference

API Reference

Index#

Index

Hephaestus

Contents

Hephaestus#

Overview#

Design Philosophy#

Core Features#

Current Implementation#

Project Status#

Scope Limitations#

Dev Env#

Bazel#

Commands#

Clang-tidy Profiling#

Folders#

CMake#

Compilation#

Build system#

Using Hephaestus#

Global installation#

Use Hephaestus CMake build system#

Include Hephaestus as a submodule#

Linting#

Spelling#

Notes#

TODO#

Index#