Skip to content

Build & Configuration Guide

Instructions for building TinyRL from source, configuration options, and deployment.

Table of Contents

Quick Start

Default Build

git clone https://github.com/mohmdelsayed/TinyRL.git
cd TinyRL
./install.sh

Common Configurations

# Debug build
./install.sh --build-type Debug

# With Python bindings
./install.sh --with-bindings

# With Stream-X (streaming RL)
./install.sh --with-stream-x

# Full build with everything
./install.sh --with-bindings --with-stream-x --with-stream-x-bindings

Prerequisites

Required

Dependency Version Notes
C++ Compiler C++17 GCC 13+, Clang 16+, MSVC 2022+
CMake 3.14+ Build system

Optional

Dependency Purpose
Python 3.8+ Python bindings
pybind11 Python bindings
Graphviz Graph visualization

Platform Setup

Ubuntu/Debian: 

sudo apt update
sudo apt install build-essential cmake python3-dev
pip3 install pybind11

macOS: 

brew install cmake python3
pip3 install pybind11

Build Options

Option Description Default
AUTOGRAD_BUILD_EXAMPLES Build examples ON
AUTOGRAD_BUILD_TESTS Build test suite ON
AUTOGRAD_BUILD_BINDINGS Python bindings OFF
AUTOGRAD_BUILD_STREAM_X Stream-X module OFF
AUTOGRAD_ENABLE_SIMD SIMD acceleration ON
AUTOGRAD_EMBEDDED Embedded mode OFF
AUTOGRAD_FAST_MATH Enable -ffast-math in Release builds ON
AUTOGRAD_USE_DOUBLE Use double precision (AG_USE_DOUBLE) OFF 
## Numeric Precision

TinyRL uses **float32** (`Float` type) by default, providing optimal performance and memory efficiency for embedded systems.

### Using Double Precision

To use **float64** (double precision), define `AG_USE_DOUBLE` before including headers:

```cpp
// In your code
#define AG_USE_DOUBLE
#include "autograd.h"

Or via CMake: 

cmake .. -DAUTOGRAD_USE_DOUBLE=ON

Or via the install script: 

./install.sh --use-double

Note: Double precision increases memory usage and may reduce performance on embedded devices.

Python Bindings

Building Python Bindings

# Using install script
./install.sh --with-bindings

# Manual build
cd bindings && mkdir build && cd build
cmake .. && make -j$(nproc)

Using Python Bindings

import autograd
import numpy as np

# Create tensors
x = autograd.Tensor(np.random.rand(2, 3), requires_grad=True)
y = autograd.Tensor(np.random.rand(3, 2), requires_grad=True)

# Perform operations
z = x.matmul(y)
loss = autograd.sum(z)
loss.backward()

print("x gradients:", x.grad())

Installation Location

The Python module (autograd.so) is placed in: - examples/python/ (relative to project root) - System Python path (if permissions allow)

Embedded Development

ESP32-S3 Configuration

# Embedded build for ESP32
mkdir build_esp32 && cd build_esp32
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DAUTOGRAD_EMBEDDED=ON \
    -DAUTOGRAD_ENABLE_SIMD=OFF \
    -DCMAKE_CXX_FLAGS="-DAG_EMBEDDED"
make -j$(nproc)

PlatformIO Integration

; platformio.ini
[env:freenove_esp32_s3_wroom]
platform = espressif32
board = freenove_esp32_s3_wroom
framework = arduino
build_flags = 
    -DAG_EMBEDDED
    -DAG_ENABLE_SIMD=OFF
    -I../src
    -I../../examples/stream_x/src   # Stream-X module headers (StreamAC, StreamQ, StreamSARSA algorithms)

Host Simulation

# Compile for host simulation
c++ -std=c++17 \
    -DAG_EMBEDDED \
    -I src -I examples/stream_x/src \
    examples/stream_x_esp32/src/stream_ac_continuous.cpp -o esp32_sim

# Run simulation
./esp32_sim

Troubleshooting

Common Issues

C++17 Not Supported

Error: error: 'std::expected' is not a member of 'std' Solution: Update to GCC 13+, Clang 16+, or recent MSVC

# Check compiler version
g++ --version
clang++ --version

Missing Python Headers

Error: fatal error: Python.h: No such file or directory
Solution: Install Python development headers

# Ubuntu/Debian
sudo apt install python3-dev

# macOS
brew install python3

Memory Issues on Embedded

Error: std::bad_alloc or out-of-memory crashes
Solution: Use smaller models and enable embedded mode

cmake .. -DAUTOGRAD_EMBEDDED=ON

Debugging Build Issues

Verbose Output

# Enable verbose make output
make VERBOSE=1

# Enable CMake debug output
cmake .. -DCMAKE_VERBOSE_MAKEFILE=ON

Clean Builds

# Remove all build artifacts
rm -rf build build_* CMakeCache.txt

Check Dependencies

# Verify CMake version
cmake --version

# Check compiler support
echo 'int main() { return 0; }' > test.cpp
g++ -std=c++17 test.cpp -o test
./test && echo "C++17 supported" || echo "C++17 not supported"

Performance Optimization

Compiler Flags

# Optimized build
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_CXX_FLAGS="-O3 -march=native -ffast-math"

# Debug with optimizations
cmake .. \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DCMAKE_CXX_FLAGS="-O2 -g"

SIMD Optimization

# Enable SIMD (default)
cmake .. -DAUTOGRAD_ENABLE_SIMD=ON

# Disable SIMD for compatibility
cmake .. -DAUTOGRAD_ENABLE_SIMD=OFF

See Also