robotframework-clang 1.0.0

Robot Framework library for Clang-REPL execution via xeus-cpp

Robot Framework Clang Library

robotframework-clang is a Robot Framework library designed to execute and test C++ code interactively using Clang-REPL (via the xeus-cpp extension).

Goals

The primary goal of this library is to support unit testing of C++ code directly from Robot Framework, overcoming the limitations of traditional approaches.

Unlike classic unit test frameworks, robotframework-clang:

• Does not require an explicit main: Code is JIT (Just-In-Time) compiled and executed incrementally.
• Advanced native C++ support: By using Clang-REPL, you can leverage the latest language features, including C++ Modules, without the configuration complexity of traditional build systems.
• Isolation and Fast Iteration: Each suite can manage its own C++ kernel, allowing isolated tests and immediate feedback without full compilation and linking cycles.

Why Clang-REPL (xeus-cpp) over cppyy?

While cppyy (based on Cling) is an excellent tool for creating Pythonic bindings and manipulating C++ objects directly from Python, this library consciously chooses Clang-REPL (via xeus-cpp) for the specific use case of Unit Testing.

Here is why:

1. Process Isolation & Stability:

   • xeus-cpp: Uses a client-server architecture (Jupyter Kernel). If the C++ code segfaults or crashes, only the kernel subprocess dies. Robot Framework detects the failure, reports it, and can restart the kernel for the next test suite.
   • cppyy: Runs in the same process as Python. A C++ crash brings down the entire test runner, causing the loss of test reports and halting execution.

2. Future-Proofing & Standards:

   • Clang-REPL: Is part of the upstream LLVM project. It represents the future of interactive C++ (with ROOT and CppInterOp moving in this direction) and guarantees day-one support for new compiler features.
   • Cling: Is a legacy fork of Clang. While powerful, it often lags behind upstream LLVM versions.

3. Mature C++20 Support:

   • Thanks to the underlying Clang 21+ engine, this library provides robust support for modern C++ standards, including C++20 Modules and Concepts, which are essential for testing modern codebases.

4. Testing vs. Bindings:

   • The goal here is not to "write C++ in Python" (bindings), but to verify C++ behavior in its native environment. We want to compile and run C++ snippets exactly as a compiler would, without the "magic" or type conversion layers that might obscure bugs in the C++ logic itself.

Requirements

• Python 3.10+
• xeus-cpp 0.8.0
• Clang 21
• libcxx (LLVM C++ standard library)
• A working C++ kernel (e.g., xcpp20).

Installation

Using Pixi (Recommended)

Installation via Pixi is the preferred method as it automatically manages all binary dependencies (Clang, xeus-cpp, libcxx) and Python requirements in a reproducible environment.

# To use it in your project
pixi add robotframework-clang

# Or to run tests/build within this repository
pixi run test
pixi run build-recipe

Using Pip

If you already have an environment with xeus-cpp and Clang 20 installed and configured:

pip install robotframework-clang

Documentation and Testing

This project uses an "executable documentation" approach. Tests are written in reStructuredText format within the docs/ folder, serving as both usage examples and the actual test suite.

Running Tests

To execute the tests (which are embedded in the documentation):

pixi run test

Building Documentation

To generate the HTML documentation:

pixi run docs

The output will be available in html/index.html.

License

This project is distributed under the Apache License 2.0. See the LICENSE file for details.