particle-os-tools/docs/apt-layer/rpm-ostree/contributing/hacking.md

Hacking on rpm-ostree

Overview

This guide covers how to set up a development environment for rpm-ostree, build and test the codebase, and work with custom dependencies. It provides comprehensive instructions for developers who want to contribute to the project.

Development Environment Setup

Prerequisites

System Requirements

• Linux distribution: Fedora, RHEL/CentOS, or Ubuntu
• Build tools: GCC, Make, Autotools
• Development libraries: glib2, libostree, libsolv
• Container tools: Podman or Docker (optional)

Required Packages

Fedora/RHEL/CentOS

# Install build dependencies
sudo dnf install \
    gcc \
    gcc-c++ \
    make \
    autoconf \
    automake \
    libtool \
    pkgconfig \
    glib2-devel \
    libostree-devel \
    libsolv-devel \
    json-glib-devel \
    libcurl-devel \
    openssl-devel \
    polkit-devel \
    systemd-devel \
    libgpgme-devel \
    libseccomp-devel \
    libcap-devel \
    libarchive-devel \
    libxml2-devel \
    libxslt-devel \
    libyaml-devel \
    libappstream-glib-devel \
    libdnf-devel \
    librepo-devel \
    libmodulemd-devel \
    libcomps-devel \
    libxmlb-devel \
    libpeas-devel \
    libsoup-devel \
    libgirepository1-devel \
    gobject-introspection-devel \
    python3-devel \
    python3-gobject-devel \
    python3-requests \
    python3-pytest \
    python3-pytest-cov \
    python3-black \
    python3-flake8 \
    python3-mypy \
    rust \
    cargo \
    clang \
    llvm \
    llvm-devel

Ubuntu/Debian

# Install build dependencies
sudo apt-get install \
    build-essential \
    autoconf \
    automake \
    libtool \
    pkg-config \
    libglib2.0-dev \
    libostree-dev \
    libsolv-dev \
    libjson-glib-dev \
    libcurl4-openssl-dev \
    libssl-dev \
    libpolkit-gobject-1-dev \
    libsystemd-dev \
    libgpgme11-dev \
    libseccomp-dev \
    libcap-dev \
    libarchive-dev \
    libxml2-dev \
    libxslt1-dev \
    libyaml-dev \
    libappstream-glib-dev \
    libdnf-dev \
    librepo-dev \
    libmodulemd-dev \
    libcomps-dev \
    libxmlb-dev \
    libpeas-dev \
    libsoup2.4-dev \
    libgirepository1.0-dev \
    gobject-introspection \
    python3-dev \
    python3-gi \
    python3-requests \
    python3-pytest \
    python3-pytest-cov \
    python3-black \
    python3-flake8 \
    python3-mypy \
    rustc \
    cargo \
    clang \
    llvm \
    libllvm-dev

Setting Up Development Environment

Method 1: Using Toolbox (Recommended)

Toolbox provides an isolated development environment:

# Create toolbox container
toolbox create rpm-ostree-dev

# Enter toolbox
toolbox enter rpm-ostree-dev

# Install dependencies
sudo dnf install -y \
    gcc gcc-c++ make autoconf automake libtool pkgconfig \
    glib2-devel libostree-devel libsolv-devel \
    # ... (other dependencies as listed above)

Method 2: Using Buildroot Container

For consistent builds across different systems:

# Run in buildroot container
podman run --rm -it \
    -v "$PWD:$PWD:z" \
    -w "$PWD" \
    quay.io/coreos-assembler/fcos-buildroot:testing-devel

# Or with Docker
docker run --rm -it \
    -v "$PWD:$PWD" \
    -w "$PWD" \
    quay.io/coreos-assembler/fcos-buildroot:testing-devel

Method 3: Local Development

For development on your local system:

# Clone repository
git clone https://github.com/coreos/rpm-ostree.git
cd rpm-ostree

# Initialize submodules
git submodule update --init

# Install dependencies (see package lists above)
# Then proceed with build

Building rpm-ostree

Basic Build Process

# Generate build system
./autogen.sh --prefix=/usr --libdir=/usr/lib64 --sysconfdir=/etc

# Configure build
./configure --prefix=/usr --libdir=/usr/lib64 --sysconfdir=/etc

# Build
make -j$(nproc)

# Install (optional, for testing)
sudo make install

Build Options

Debug Build

# Configure with debug symbols
./configure --prefix=/usr --libdir=/usr/lib64 --sysconfdir=/etc \
    --enable-debug --enable-verbose

# Build with debug information
make CFLAGS="-g -O0" CXXFLAGS="-g -O0"

Development Build

# Configure for development
./configure --prefix=/usr --libdir=/usr/lib64 --sysconfdir=/etc \
    --enable-debug --enable-verbose --enable-tests \
    --enable-valgrind --enable-sanitizers

Custom Installation Path

# Install to custom location
./configure --prefix=/opt/rpm-ostree --libdir=/opt/rpm-ostree/lib64

# Build and install
make
sudo make install

Rust Components

rpm-ostree includes Rust components that need to be built separately:

# Build Rust components
cd rust
cargo build

# Build with release optimizations
cargo build --release

# Run Rust tests
cargo test

# Check code quality
cargo clippy
cargo fmt --check

Testing

Running Tests

Unit Tests

# Run all tests
make check

# Run specific test suite
make check TESTS="test-package"

# Run tests with verbose output
make check VERBOSE=1

Integration Tests

# Run integration tests
make check-integration

# Run specific integration test
make check-integration TESTS="test-upgrade"

Rust Tests

# Run Rust unit tests
cd rust
cargo test

# Run tests with output
cargo test -- --nocapture

Test Environment Setup

Virtual Machine Testing

# Setup test VM
./ci/vmcheck.sh

# Run tests in VM
./ci/vmcheck.sh --test

Container Testing

# Run tests in container
podman run --rm -it \
    -v "$PWD:$PWD:z" \
    -w "$PWD" \
    quay.io/coreos-assembler/fcos-buildroot:testing-devel \
    make check

Debugging Tests

Enable Debug Output

# Run tests with debug output
G_MESSAGES_DEBUG=all RUST_LOG=debug make check

# Run specific test with debug
G_MESSAGES_DEBUG=all RUST_LOG=debug \
    ./test-driver --test-name test-package --log-file test.log

Using GDB

# Run test with GDB
gdb --args ./test-package

# Run with core dumps
ulimit -c unlimited
./test-package
gdb ./test-package core

Development Workflow

Code Changes

Making Changes

1. Create feature branch

   git checkout -b feature/my-feature
   

2. Make changes and test

   # Edit source files
   vim src/lib/rpmostree-core.c
   
   # Build and test
   make
   make check
   

3. Commit changes

   git add .
   git commit -m "Add new feature: description"
   

Code Quality Checks

# Run code formatting
make format

# Run static analysis
make static-analysis

# Run linting
make lint

# Run all quality checks
make quality-check

Debugging Development

Enable Debug Logging

# Set debug environment variables
export G_MESSAGES_DEBUG=all
export RUST_LOG=debug
export RPMOSTREE_DEBUG=1

# Run with debug output
./rpm-ostree status

Using GDB

# Debug rpm-ostree binary
gdb --args ./rpm-ostree status

# Debug daemon
gdb -p $(pidof rpm-ostreed)

# Set breakpoints
(gdb) break rpmostree_core_new
(gdb) run

Using Valgrind

# Check for memory leaks
valgrind --leak-check=full --show-leak-kinds=all \
    ./rpm-ostree status

# Check for memory errors
valgrind --tool=memcheck \
    ./rpm-ostree status

Performance Analysis

Using perf

# Profile performance
perf record ./rpm-ostree upgrade
perf report

# Analyze specific functions
perf record -g -p $(pidof rpm-ostreed)
perf report

Using strace

# Trace system calls
strace -f -o trace.log ./rpm-ostree status

# Trace specific system calls
strace -e trace=file,network -f ./rpm-ostree status

Working with Dependencies

Custom OSTree Version

# Build custom OSTree
git clone https://github.com/ostreedev/ostree.git
cd ostree
./autogen.sh --prefix=/usr/local
make
sudo make install

# Rebuild rpm-ostree with custom OSTree
cd /path/to/rpm-ostree
./autogen.sh --prefix=/usr/local
make

Custom libsolv Version

# Build custom libsolv
git clone https://github.com/openSUSE/libsolv.git
cd libsolv
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..
make
sudo make install

# Rebuild rpm-ostree
cd /path/to/rpm-ostree
./autogen.sh --prefix=/usr/local
make

Development Dependencies

# Install development versions
sudo dnf install -y \
    libostree-devel \
    libsolv-devel \
    glib2-devel \
    # ... (other devel packages)

# Or build from source
# (see individual dependency build instructions)

IDE Setup

VSCode Configuration

// .vscode/settings.json
{
    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
    "C_Cpp.default.includePath": [
        "${workspaceFolder}/**",
        "/usr/include",
        "/usr/include/glib-2.0",
        "/usr/lib64/glib-2.0/include",
        "/usr/include/ostree-1",
        "/usr/include/libsolv"
    ],
    "C_Cpp.default.defines": [
        "G_LOG_DOMAIN=\"rpmostree\"",
        "HAVE_CONFIG_H"
    ]
}

CLion Configuration

# CMakeLists.txt (for CLion)
cmake_minimum_required(VERSION 3.16)
project(rpm-ostree)

set(CMAKE_C_STANDARD 11)
set(CMAKE_CXX_STANDARD 17)

find_package(PkgConfig REQUIRED)
pkg_check_modules(GLIB REQUIRED glib-2.0)
pkg_check_modules(OSTREE REQUIRED libostree-1)
pkg_check_modules(SOLV REQUIRED libsolv)

include_directories(${GLIB_INCLUDE_DIRS})
include_directories(${OSTREE_INCLUDE_DIRS})
include_directories(${SOLV_INCLUDE_DIRS})

Troubleshooting

Common Build Issues

Missing Dependencies

# Check for missing dependencies
pkg-config --exists glib-2.0 || echo "glib-2.0 not found"
pkg-config --exists libostree-1 || echo "libostree-1 not found"

# Install missing packages
sudo dnf install -y glib2-devel libostree-devel

Autotools Issues

# Regenerate build system
autoreconf -fiv

# Clean and rebuild
make distclean
./autogen.sh
make

Rust Build Issues

# Update Rust toolchain
rustup update

# Clean Rust build
cd rust
cargo clean
cargo build

Debugging Build Failures

Verbose Build Output

# Enable verbose make output
make V=1

# Enable verbose configure
./configure --enable-verbose

Dependency Analysis

# Check library dependencies
ldd ./rpm-ostree

# Check pkg-config dependencies
pkg-config --libs --cflags glib-2.0

---

This guide provides comprehensive instructions for setting up a development environment and working with the rpm-ostree codebase. Follow these practices to ensure successful development and contribution.