universalisos/website/docs/BUILD_ENVIRONMENT.md

Universalisos Build Environment Setup

This document provides comprehensive instructions for setting up the Universalisos development environment for compiling the UniversalisOS codebase and working with the XSD → C code generation pipeline.

Overview

Universalisos requires a cross-compilation environment for building UniversalisOS source code, processing XSD schemas, and generating C code from XML definitions. This setup is designed for safety-critical embedded systems development with AUTOSAR C++ compliance.

Hardware Requirements

Minimum System Requirements:

• CPU: 4 cores, x86_64 architecture
• RAM: 8GB (16GB recommended for large builds)
• Storage: 50GB free space (for source, build artifacts, and toolchains)
• Network: Internet access for package downloads and Nextcloud synchronization

Recommended System:

• CPU: 8+ cores, x86_64 architecture
• RAM: 16GB+
• Storage: 100GB+ SSD
• Network: High-speed connection for repository synchronization

Operating System

Supported Platforms:

• Linux (Ubuntu 22.04 LTS or later recommended)
• Debian 12+ (Bookworm)
• Fedora 38+

Development Environment: This setup assumes a Debian-based Linux distribution. Commands may need adjustment for other distributions.

Toolchain Installation

Core Build Tools

# Update package manager
sudo apt update

# Install core development tools
sudo apt install -y \
    build-essential \
    gcc \
    g++ \
    make \
    cmake \
    ninja-build \
    git \
    pkg-config \
    autoconf \
    automake \
    libtool

Cross-Compilation Toolchains

# ARM Cortex-M toolchain (for embedded targets)
sudo apt install -y \
    gcc-arm-none-eabi \
    libnewlib-arm-none-eabi \
    libstdc++-arm-none-eabi-newlib

# ARM Cortex-A toolchain (for Linux targets)
sudo apt install -y \
    gcc-arm-linux-gnueabihf \
    g++-arm-linux-gnueabihf \
    libstdc++-arm-linux-gnueabihf-dev

# RISC-V toolchain (emerging architectures)
sudo apt install -y \
    gcc-riscv64-unknown-elf \
    libnewlib-riscv64-unknown-elf

AUTOSAR and Safety-Critical Tools

# AUTOSAR build tools
sudo apt install -y \
    autosar \
    can-utils \
    python3-can

# Safety-critical analysis tools
sudo apt install -y \
    cppcheck \
    clang-tidy \
    clang-format \
    vera++ \
    splint

XSD Processing and Validation

# XML schema processing
sudo apt install -y \
    libxml2-utils \
    libxslt1.1 \
    python3-lxml \
    python3-jinja2 \
    xsltproc

# XSD validation tools
sudo apt install -y \
    xsd-tools \
    libxml2-dev

Eclipse IDE for XSD Workflow Analysis

# Install Eclipse IDE
wget https://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/2023-12/R/eclipse-cpp-2023-12-R-linux-gtk-x86_64.tar.gz
tar -xzf eclipse-cpp-2023-12-R-linux-gtk-x86_64.tar.gz
sudo mv eclipse /opt/eclipse

# Install Eclipse XSD plugins
/opt/eclipse/eclipse -application org.eclipse.equinox.p2.director \
  -repository https://download.eclipse.org/modeling/emf/emf/builds/release/2.29.0 \
  -installIU org.eclipse.xsd.feature.group

# Create desktop shortcut
cat > ~/.local/share/applications/eclipse.desktop << EOF
[Desktop Entry]
Name=Eclipse IDE
Exec=/opt/eclipse/eclipse
Icon=eclipse
Type=Application
Categories=Development;IDE;
EOF

Environment Configuration

Path Setup

# Add toolchains to PATH
echo 'export PATH=/opt/gcc-arm-none-eabi/bin:$PATH' >> ~/.bashrc
echo 'export PATH=/opt/eclipse:$PATH' >> ~/.bashrc

# Set environment variables for UniversalisOS compilation
echo 'export PIKEOS_ROOT=/home/fabiorafaelcoutada/portugalfuturista/universalisos' >> ~/.bashrc
echo 'export PIKEOS_BUILD_DIR=$PIKEOS_ROOT/build' >> ~/.bashrc
echo 'export PIKEOS_TOOLCHAIN_PREFIX=arm-none-eabi-' >> ~/.bashrc

# Reload shell configuration
source ~/.bashrc

CMake Configuration

# Create CMake toolchain file
cat > ~/.cmake/arm-none-eabi.cmake << 'EOF'
set(CMAKE_SYSTEM_NAME Generic)
set(CMAKE_SYSTEM_PROCESSOR ARM)

set(CMAKE_C_COMPILER arm-none-eabi-gcc)
set(CMAKE_CXX_COMPILER arm-none-eabi-g++)
set(CMAKE_ASM_COMPILER arm-none-eabi-gcc)
set(CMAKE_OBJCOPY arm-none-eabi-objcopy)
set(CMAKE_OBJDUMP arm-none-eabi-objdump)
set(CMAKE_SIZE arm-none-eabi-size)

set(CMAKE_EXECUTABLE_SUFFIX_ASM .elf)
set(CMAKE_EXECUTABLE_SUFFIX_C .elf)
set(CMAKE_EXECUTABLE_SUFFIX_CXX .elf)

set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)

EOF

Verification Steps

Toolchain Verification

# Verify GCC cross-compiler installation
arm-none-eabi-gcc --version
arm-linux-gnueabihf-gcc --version

# Verify CMake and Ninja
cmake --version
ninja --version

# Verify XSD tools
xmllint --version
xsd --version

# Verify Eclipse installation
/opt/eclipse/eclipse -version

Build System Test

# Create test project
cd /tmp
mkdir universalisos-test
cd universalisos-test

# Create test C file
cat > main.c << 'EOF'
#include <stdio.h>

int main(void) {
    printf("Universalisos build environment test\n");
    return 0;
}
EOF

# Test cross-compilation
cmake -DCMAKE_TOOLCHAIN_FILE=~/.cmake/arm-none-eabi.cmake -G Ninja ..
ninja

XSD → C Code Generation Workflow

XSD Schema Processing

# Validate XSD schema
xmllint --schema universalisos/xsd/*.xsd \
  universalisos/xsd/test_config.xml

# Generate C code from XSD
xsd cxx-tree --generate-serialization \
  --generate-polymorphic \
  --output-dir universalisos/src/generated \
  universalisos/xsd/pikoes_config.xsd

Integration with Build System

# Configure UniversalisOS build with code generation
cd universalisos/src
mkdir build && cd build

cmake -DCMAKE_TOOLCHAIN_FILE=~/.cmake/arm-none-eabi.cmake \
  -G Ninja \
  -DGENERATE_FROM_XSD=ON \
  -DXSD_SCHEMA_DIR=$PIKEOS_ROOT/xsd \
  ..

# Build with generated code
ninja

Safety-Critical Build Configuration

MISRA C++ Compliance Checking

# Configure cppcheck for MISRA compliance
cppcheck --enable=all \
  --std=c++17 \
  --suppressions-list=misra-suppressions.txt \
  --inline-suppr \
  --xml \
  --xml-version=2 \
  universalisos/src/

# Run clang-tidy for additional safety checks
clang-tidy universalisos/src/**/*.c \
  -checks=* \
  --config-file=.clang-tidy \
  -p universalisos/build/

AUTOSAR Build Verification

# Verify AUTOSAR compliance
autosar-check --config=autosar-config.json \
  --source=universalisos/src/ \
  --output=autosar-report.xml

# Generate compliance report
autosar-report --input=autosar-report.xml \
  --format=html \
  --output=autosar-compliance.html

Troubleshooting

Common Issues

Issue: Cross-compiler not found

# Solution: Verify PATH configuration
echo $PATH | grep arm-none-eabi
# Reinstall if missing: sudo apt install gcc-arm-none-eabi

Issue: CMake cannot find toolchain

# Solution: Specify toolchain explicitly
cmake -DCMAKE_TOOLCHAIN_FILE=~/.cmake/arm-none-eabi.cmake ..

Issue: XSD processing errors

# Solution: Verify XSD schema validity
xmllint --schema universalisos/xsd/schema.xsd test.xml
# Install missing dependencies: sudo apt install libxml2-dev

Issue: Build errors with generated code

# Solution: Clean build and regenerate
rm -rf build/
mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE=~/.cmake/arm-none-eabi.cmake ..
ninja clean
ninja

Performance Optimization

Parallel Builds

# Use all CPU cores for compilation
export NINJA_STATUS="[%p/%f] "
ninja -j$(nproc)

# For specific targets
ninja -j8 kernel drivers

CCache Configuration

# Install ccache
sudo apt install ccache

# Configure ccache for compilation cache
ccache -M 50G  # Set 50GB cache limit
ccache -s     # Show cache statistics

# Use with CMake
cmake -DCMAKE_C_COMPILER_LAUNCHER=ccache \
  -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
  -DCMAKE_TOOLCHAIN_FILE=~/.cmake/arm-none-eabi.cmake ..

Continuous Integration Setup

CI/CD Pipeline Configuration

# .gitlab-ci.yml example
image: ubuntu:22.04

build:
  script:
    - apt update && apt install -y gcc-arm-none-eabi cmake ninja-build
    - mkdir build && cd build
    - cmake -DCMAKE_TOOLCHAIN_FILE=.cmake/arm-none-eabi.cmake ..
    - ninja
    - ctest --output-on-failure

Maintenance and Updates

Toolchain Updates

# Check for toolchain updates
apt list --upgradable | grep gcc-arm

# Update cross-compilers
sudo apt update && sudo apt upgrade gcc-arm-none-eabi

# Verify updates don't break builds
cd universalisos/src/build && ninja clean && ninja

Documentation Updates

Keep this document synchronized with:

• Toolchain version changes
• New dependency requirements
• Build system modifications
• Safety standard compliance updates

---

Next Steps: After completing this setup, proceed to XSD_WORKFLOW_ANALYSIS.md for detailed XSD → C code generation workflow documentation.