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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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
```bash
# 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
```bash
# Solution: Specify toolchain explicitly
cmake -DCMAKE_TOOLCHAIN_FILE=~/.cmake/arm-none-eabi.cmake ..
```

**Issue**: XSD processing errors
```bash
# 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
```bash
# 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

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

# For specific targets
ninja -j8 kernel drivers
```

### CCache Configuration

```bash
# 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

```yaml
# .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

```bash
# 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](XSD_WORKFLOW_ANALYSIS.md) for detailed XSD → C code generation workflow documentation.