Buildroot Tutorial¶

This section serves as a comprehensive guide to assist in creating and understanding the key points of a basic Safe DDS application using the Buildroot build system.

This project demonstrates how to create a custom Buildroot image with a Safe DDS example application for AArch64 architecture using QEMU emulation. This approach is particularly useful for embedded Linux development and testing applications in a controlled environment.

Note

This guide has been tested with Buildroot 2025.02.3 and QEMU AArch64 virtual machine.

In order to get support please contact support@eProsima.com.

Note

It is recommended to first read the Getting Started section to gain a better understanding of the basic concepts and terminology used in this section.

Project Configuration¶

This section describes how to configure a Buildroot project that includes the Safe DDS library and a sample application.

1. Download and Configure Buildroot¶

Start by downloading Buildroot and configuring it for the target architecture:

# Download Buildroot
git clone -b 2025.02.3 --single-branch https://github.com/buildroot/buildroot.git
cd buildroot

# Use the QEMU AArch64 virtual machine configuration
make qemu_aarch64_virt_defconfig

2. Create Custom Overlay¶

Create a custom overlay directory where the Safe DDS application will be placed:

mkdir custom_overlay

3. Configure Buildroot for C++ Support¶

Configure Buildroot to enable C++ support, which is required for Safe DDS:

make menuconfig

In the configuration menu, navigate to:

Toolchain > Enable C++ support: Enable this option
System Configuration > Root filesystem overlay directories: Add the path to your custom overlay directory (e.g., custom_overlay)

Save the configuration and exit the menu.

4. Build the Initial Image¶

Build the Buildroot image to generate the toolchain:

make

This process may take some time as it downloads and compiles all required components.

Safe DDS Application¶

After the initial Buildroot image has been built, the next step is to create and build a Safe DDS application using the generated toolchain.

1. Create CMake Toolchain File¶

Create a CMake toolchain file for cross-compilation:

touch toolchain_aarch64.cmake

Add the following content to the toolchain file:

# Define the system and processor
SET(CMAKE_SYSTEM_NAME Linux)
SET(CMAKE_SYSTEM_PROCESSOR aarch64)

# Specify the cross-compilers
SET(CMAKE_C_COMPILER /path/to/buildroot/output/host/bin/aarch64-buildroot-linux-gnu-gcc)
SET(CMAKE_CXX_COMPILER /path/to/buildroot/output/host/bin/aarch64-buildroot-linux-gnu-g++)

# Suppress only ABI-related notes
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wno-psabi")
SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-psabi")

# Force static linking
SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -static")
SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -static")

# Adjust compiler flags
set(SAFEDDS_COMPILE_OPTIONS_PRIVATE "" CACHE STRING "Safe DDS private compile options")
set(SAFEDDS_COMPILE_OPTIONS "-Werror" CACHE STRING "Safe DDS compile options")
set(SMOKE_TESTS_COMPILE_OPTIONS "" CACHE STRING "Smoke tests compile options")

# Set C++ standard
set(CMAKE_CXX_STANDARD 14)

Note

Replace /path/to/buildroot with the actual path to your Buildroot directory.

2. Build Safe DDS Library¶

Build the Safe DDS library using the cross-compilation toolchain:

# Set environment variables
export BUILDROOT_FOLDER=/path/to/buildroot
export SAFEDDS_SOURCE=/path/to/safedds/source
export TOOLCHAIN_FILE=/path/to/toolchain_aarch64.cmake
export INSTALL_FOLDER=/path/to/install

# Create build directory
mkdir -p safedds_build
cd safedds_build

# Configure and build Safe DDS
cmake $SAFEDDS_SOURCE \
    -DCMAKE_TOOLCHAIN_FILE=$TOOLCHAIN_FILE \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=$INSTALL_FOLDER

make -j$(nproc)
make install

3. Build Safe DDS Example Application¶

Build the Safe DDS example application using the same toolchain:

# Navigate to the getting started example
export SAFEDDS_EXAMPLE_SOURCE=/path/to/safedds/examples/getting_started

# Create build directory for the example
mkdir -p example_build
cd example_build

# Configure and build the example
cmake $SAFEDDS_EXAMPLE_SOURCE \
    -DCMAKE_TOOLCHAIN_FILE=$TOOLCHAIN_FILE \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=$INSTALL_FOLDER

make -j$(nproc)

Note

The Getting Started example uses the localhost address as its announced locator. To enable communication with external hosts, you may need to modify the example code to specify the appropriate network interface or IP address.

4. Copy Application to Overlay¶

Copy the resulting binary to the Buildroot custom overlay:

# Copy the application binary
cp safedds_getting_started $BUILDROOT_FOLDER/custom_overlay/

5. Rebuild Buildroot Image¶

Navigate back to the Buildroot directory and rebuild the image to include the Safe DDS application:

cd $BUILDROOT_FOLDER
make

This will regenerate the output images with the new Safe DDS application included.

Running the Application¶

Once the Buildroot image is ready, it can be run using QEMU with network support.

1. Create TAP Interface¶

Create a TAP network interface on the host system:

# Create and configure TAP interface
sudo ip tuntap add tap0 mode tap
sudo ip link set tap0 up
sudo ip addr add 192.168.100.1/24 dev tap0

# BEWARE! All DDS multicast traffic will be sent using this interface.
# It will be reverted during cleanup procedure (see below).
sudo ip route add 239.255.0.1 via 192.168.100.1

2. Run QEMU with Buildroot Image¶

Launch QEMU with the generated Buildroot image:

qemu-system-aarch64 \
    -M virt \
    -cpu cortex-a53 \
    -nographic \
    -smp 1 \
    -kernel output/images/Image \
    -append "rootwait root=/dev/vda console=ttyAMA0" \
    --netdev tap,id=eth0,ifname=tap0,script=no,downscript=no \
    -device virtio-net-device,netdev=eth0 \
    -drive file=output/images/rootfs.ext4,if=none,format=raw,id=hd0 \
    -device virtio-blk-device,drive=hd0

3. Configure Network in Guest System¶

Once the system boots (login as root with empty password), configure the network:

# Configure IP address and routing
ip addr add 192.168.100.2/24 dev eth0
ip route add default via 192.168.100.1

4. Run Safe DDS Application¶

Execute the Safe DDS application:

# Navigate to root and run the application
cd /
./safedds_getting_started

If the application is successfully connected to the network and running, the console output should show messages similar to the following:

[DW: 0] Message: HelloWorld with index: 1
[DW: 0] Message: HelloWorld with index: 2
[DW: 0] Message: HelloWorld with index: 3
[DW: 0] Message: HelloWorld with index: 4

The program will continue to publish messages every second until it is manually stopped.

Testing Communication¶

To test communication between the Buildroot system and the host, run the standard Getting Started example on the host machine. Both applications should discover each other and exchange messages across the network.

On the host machine:

# Run the standard getting started example
./safedds_getting_started

The console output should show messages being exchanged between both applications:

[DW: 0] Message: HelloWorld with index: 5
[DW: 16777216] Message: HelloWorld with index: 1
[DW: 0] Message: HelloWorld with index: 6
[DW: 16777216] Message: HelloWorld with index: 2

Cleanup¶

When finished, cleanup the TAP interface:

# Remove TAP interface
sudo ip link delete tap0