st2cpp Released

A transpiler that compiles IEC 61131-3 Structured Text into clean, native C++17. No virtual machine, no interpreter — just standard C++ you can compile, debug, and integrate anywhere.

Overview

st2cpp is the compiler component of the undoRT ecosystem. It takes .st source files as input and produces .hpp / .cpp pairs that can be compiled with any C++17-capable toolchain.

Function Blocks become C++ structs. Programs become classes with a run() method. The output is readable and auditable — not obfuscated machine code.

• All IEC 61131-3 elementary types
• STRUCT, ENUM, arrays, pointers
• FUNCTION, FUNCTION_BLOCK, PROGRAM
• FB inheritance with SUPER^ access
• Named and positional call syntax
• VAR_OUTPUT binding via =>
• Modular project generation
• Automatic dependency sorting
• Method visibility (PRIVATE, PROTECTED, PUBLIC)
• Header-only runtime (zero deps)
• Single binary, no install required

Installation

Download pre-built binary

Grab the latest release from GitHub Releases:

# Linux / macOS
tar -xzf st2cpp-*.tar.gz
./st2cpp --help

# Windows
unzip st2cpp-win-x64.zip
st2cpp.exe --help

Build from source

Prerequisites: GCC 7+ / Clang 5+ / MSVC 2017+, CMake 3.16+

git clone https://github.com/undoRT/st2cpp.git
cd st2cpp
./build.sh

# Or manually:
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

Quick Start

# Transpile a single file
./st2cpp program.st --namespace myplc

# Transpile an entire workspace in project mode
./st2cpp --workspace ./src --project-style --output-dir build --namespace myplc

# Compile the generated C++
g++ -std=c++17 -I./st2cpp_includes build/Programs/Main.cpp -o plc_main

CLI Reference

Single File Mode

The default mode. Produces one .hpp and one .cpp from a single .st source. Best for small projects or quick experiments.

./st2cpp counter.st -o counter.cpp -H counter.hpp --namespace myplc

Include st2cpp_types.hpp (from the st2cpp_includes/ folder) in your compiler's include path when building the output:

g++ -std=c++17 -I./st2cpp_includes counter.cpp -o counter

Project Mode

For workspaces with multiple POUs. st2cpp scans all .st files recursively, resolves dependencies between Function Blocks via topological sort, and generates a circular-dependency-safe header layout:

./st2cpp --workspace ./plc_src --project-style --output-dir build --namespace myplc

build/
├── SimpleGVLs.hpp        # ENUMs, simple STRUCTs, simple globals
├── FunctionBlocks.hpp    # Aggregator — includes all FB headers
├── FunctionBlocks/       # One .hpp/.cpp per Function Block
│   ├── Timer.hpp / .cpp
│   └── Counter.hpp / .cpp
├── GVLs.hpp / .cpp       # Complex globals (STRUCTs containing FBs)
├── Functions.hpp / .cpp  # Global functions
└── Programs/
    └── Main.hpp / .cpp

Full Example

Input (counter.st)

FUNCTION_BLOCK Counter
    VAR_INPUT
        Enable : BOOL;
        Reset  : BOOL;
    END_VAR
    VAR_OUTPUT
        Count : INT;
    END_VAR

    IF Reset THEN
        Count := 0;
    ELSIF Enable THEN
        Count := Count + 1;
    END_IF
END_FUNCTION_BLOCK

PROGRAM Main
    VAR
        C : Counter;
    END_VAR

    C(Enable := TRUE, Reset := FALSE);
END_PROGRAM

Generated header (counter.hpp)

#pragma once
#include "st2cpp_types.hpp"

namespace myplc {

// FUNCTION BLOCK COUNTER
struct COUNTER {
public:
    // VAR_INPUT
    Bool ENABLE{};
    Bool RESET{};
    // VAR_OUTPUT
    Int16 COUNT{};

// SETTER/GETTER
    inline void set_ENABLE(Bool val) { ENABLE = val; }
    inline void set_RESET(Bool val) { RESET = val; }
    inline Int16 get_COUNT() const { return COUNT; }
// End SETTER/GETTER

    COUNTER();
    void operator()();
    virtual ~COUNTER() = default;
};

// PROGRAM MAIN
struct MAIN {
    COUNTER C{};

    void run();
};

} // namespace myplc

Generated source (counter.cpp)

#include "counter.hpp"

namespace myplc {

// FUNCTION BLOCK COUNTER
COUNTER::COUNTER() {}

void COUNTER::operator()() {
    if (RESET) {
        COUNT = 0;
    } else if (ENABLE) {
        COUNT = COUNT + 1;
    }
}
// END FUNCTION BLOCK COUNTER

void MAIN::run() {
    C.set_ENABLE(true);
    C.set_RESET(false);
    C();
}

} // namespace myplc

Supported Constructs

Type Mapping

st2cpp uses undoCore for type definitions, ensuring consistent type mapping across the entire undoRT ecosystem.

Function Call Translation

Method Visibility (New in v0.2.1)

st2cpp now supports PRIVATE, PROTECTED, and PUBLIC visibility modifiers for methods inside FUNCTION_BLOCK.

ST Syntax

FUNCTION_BLOCK MyFB
    VAR
        counter : INT;
    END_VAR

    METHOD PRIVATE splitMix : UDINT
        VAR_IN_OUT state : UDINT; END_VAR
        // ...
    END_METHOD

    METHOD PROTECTED init : BOOL
        // ...
    END_METHOD

    METHOD PUBLIC exec : UDINT
        VAR_INPUT N : UDINT; END_VAR
        // ...
    END_METHOD
END_FUNCTION_BLOCK

Generated C++

struct MYFB {
public:
    // Variables...
    // SETTER/GETTER...

    // --- PRIVATE METHODS ---
private:
    virtual UInt32 SPLITMIX(UInt32& STATE);

    // --- PROTECTED METHODS ---
protected:
    virtual Bool INIT();

    // --- PUBLIC METHODS ---
public:
    MYFB();
    void operator()();
    virtual UInt32 EXEC(Int16 N);
    virtual ~MYFB() = default;
};

Known Limitations (Beta)

Testing

st2cpp includes a comprehensive test suite built with Google Test. The suite covers every stage of the compiler pipeline and ensures correctness of the generated code. All tests are executed automatically on every commit.

The test suite is located in the tests/ directory and can be built and run with make test or ctest after compiling the project.

Architecture

st2cpp follows a classic compiler frontend pipeline. All stages are hand-written in C++17 with no external parser generator dependencies.

ST Source
  └─▶  Lexer          (Token stream)
         └─▶  Parser       (Recursive descent → AST)
                └─▶  CodeGen     (AST visitor → C++17 source)

The AST uses std::variant for node types (ExprVariant, StmtVariant) with std::visit dispatch in the code generator — no virtual dispatch, no dynamic_cast.

Repository Layout

st2cpp/
├── include/
│   ├── ast/           # AST node definitions (std::variant-based)
│   ├── lexer/         # Token types and Lexer class
│   ├── parser/        # Parser class and helpers
│   └── codegen/       # CodeGenerator class
├── src/
│   ├── lexer/         # Lexer implementation
│   ├── parser/        # Parser + statement parser
│   ├── codegen/       # Code generator (~3600 lines)
│   └── cli/           # main.cpp + argument parsing
├── st2cpp_includes/
│   └── undoCore/      # undoCore submodule (types, conversions, math)
├── tests/             # 217+ tests
├── scripts/           # build.sh, generate_docs.sh
└── CMakeLists.txt

Full API documentation is generated with Doxygen: Browse API Reference