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

Repository Structure

Overview

This document describes the organization and structure of the rpm-ostree codebase. Understanding the repository structure is essential for effective development and contribution to the project.

Directory Organization

Root Directory Structure

rpm-ostree/
├── src/                    # Source code
├── ci/                     # Continuous integration
├── docs/                   # Documentation
├── scripts/                # Build and utility scripts
├── tests/                  # Test files
├── rust/                   # Rust components
├── libglnx/                # GLib extensions
├── libdnf/                 # DNF integration
├── libpriv/                # Private libraries
├── daemon/                 # Daemon implementation
├── client/                 # Client implementation
├── compose/                # Compose server
├── contrib/                # Contrib scripts
├── packaging/              # Package configuration
├── .github/                # GitHub configuration
├── Makefile.am             # Build configuration
├── configure.ac            # Autotools configuration
└── README.md               # Project overview

Source Code Organization

Main Source Directory (src/)

src/
├── lib/                    # Core libraries
│   ├── rpmostree-core.c    # Core functionality
│   ├── rpmostree-core.h    # Core headers
│   ├── rpmostree-util.c    # Utility functions
│   ├── rpmostree-util.h    # Utility headers
│   ├── rpmostree-cxxutil.cxx  # C++ utilities
│   └── rpmostree-cxxutil.h    # C++ headers
├── daemon/                 # Daemon implementation
│   ├── rpmostreed.c        # Main daemon
│   ├── rpmostreed-os.c     # OS operations
│   ├── rpmostreed-transaction.c  # Transaction handling
│   └── rpmostreed-dbus.c   # D-Bus integration
├── client/                 # Client implementation
│   ├── rpmostree.c         # Main client
│   ├── rpmostree-builtin-*.c  # Builtin commands
│   └── rpmostree-client.c  # Client utilities
├── compose/                # Compose server
│   ├── rpmostree-compose.c # Compose functionality
│   └── rpmostree-compose-tree.c  # Tree building
└── tools/                  # Utility tools
    ├── rpmostree-tool.c    # Tool framework
    └── rpmostree-tool-*.c  # Specific tools

Rust Components (rust/)

rust/
├── src/                    # Rust source code
│   ├── lib.rs              # Library root
│   ├── core.rs             # Core functionality
│   ├── daemon.rs           # Daemon implementation
│   ├── client.rs           # Client implementation
│   ├── compose.rs          # Compose functionality
│   └── utils.rs            # Utility functions
├── Cargo.toml              # Rust build configuration
├── Cargo.lock              # Dependency lock file
└── tests/                  # Rust tests
    ├── integration_tests.rs
    └── unit_tests.rs

Library Organization

Core Library (lib/)

The core library provides fundamental functionality:

• rpmostree-core.c/h: Core package management and OSTree integration
• rpmostree-util.c/h: Utility functions and helpers
• rpmostree-cxxutil.cxx/h: C++ utility functions

Daemon Library (daemon/)

The daemon handles system operations:

• rpmostreed.c: Main daemon entry point
• rpmostreed-os.c: OS-level operations
• rpmostreed-transaction.c: Transaction management
• rpmostreed-dbus.c: D-Bus interface implementation

Client Library (client/)

The client provides user interface:

• rpmostree.c: Main client entry point
• rpmostree-builtin-*.c: Individual command implementations
• rpmostree-client.c: Client utility functions

Build System

Autotools Configuration

configure.ac                # Main configuration
Makefile.am                 # Build rules
lib/Makefile.am             # Library build rules
daemon/Makefile.am          # Daemon build rules
client/Makefile.am          # Client build rules
compose/Makefile.am         # Compose build rules
tests/Makefile.am           # Test build rules

Rust Build Configuration

rust/Cargo.toml             # Rust dependencies and build config
rust/Cargo.lock             # Locked dependency versions

Test Organization

Test Directory (tests/)

tests/
├── test-*.c                # C unit tests
├── test-*.py               # Python integration tests
├── test-*.sh               # Shell integration tests
├── fixtures/               # Test data and fixtures
│   ├── repos/              # Test repositories
│   ├── packages/           # Test packages
│   └── configs/            # Test configurations
└── vmcheck/                # VM-based tests
    ├── vmcheck.sh          # VM test runner
    └── vmcheck-*.sh        # Specific VM tests

Rust Tests (rust/tests/)

rust/tests/
├── integration_tests.rs     # Integration tests
├── unit_tests.rs           # Unit tests
└── fixtures/               # Rust test fixtures

Documentation

Documentation Directory (docs/)

docs/
├── *.md                    # Markdown documentation
├── api/                    # API documentation
├── examples/               # Code examples
└── images/                 # Documentation images

CI/CD Configuration

CI Directory (ci/)

ci/
├── installdeps.sh          # Install dependencies
├── install-cxx.sh          # Install C++ dependencies
├── install-test-deps.sh    # Install test dependencies
├── build.sh                # Build script
├── test.sh                 # Test script
├── vmcheck.sh              # VM test script
└── github/                 # GitHub Actions
    ├── workflows/          # Workflow definitions
    └── actions/            # Custom actions

Code Architecture

Component Relationships

Core Components

libglnx/                    # GLib extensions
    ↓
lib/                        # Core library
    ↓
daemon/                     # Daemon (uses core)
client/                     # Client (uses core)
compose/                    # Compose (uses core)

Data Flow

Client Request → D-Bus → Daemon → Core Library → OSTree/DNF

Module Dependencies

Library Dependencies

• libglnx: GLib extensions and utilities
• libostree: OSTree filesystem operations
• libsolv: Package dependency resolution
• libdnf: DNF package management
• glib2: Core GLib functionality
• systemd: Systemd integration

Internal Dependencies

• lib/: Core functionality (no internal dependencies)
• daemon/: Depends on lib/
• client/: Depends on lib/
• compose/: Depends on lib/

Build Dependencies

System Dependencies

# Core dependencies
glib2-devel
libostree-devel
libsolv-devel
libdnf-devel

# Build tools
autoconf
automake
libtool
pkgconfig
gcc
gcc-c++

# Development tools
valgrind
gdb
strace

Rust Dependencies

# rust/Cargo.toml
[dependencies]
glib = "0.15"
ostree = "0.17"
serde = "1.0"
serde_json = "1.0"
tokio = "1.0"

Development Workflow

Code Organization Principles

Separation of Concerns

• Core library: Pure functionality, no UI
• Daemon: System operations and D-Bus interface
• Client: User interface and command parsing
• Compose: Build server functionality

Modularity

• Each component is self-contained
• Clear interfaces between components
• Minimal coupling between modules

Testability

• Unit tests for each component
• Integration tests for component interaction
• VM tests for full system testing

File Naming Conventions

C Files

• rpmostree-*.c: Main library files
• rpmostreed-*.c: Daemon files
• rpmostree-builtin-*.c: Client command files
• test-*.c: Test files

Header Files

• rpmostree-*.h: Public headers
• rpmostree-*-private.h: Private headers
• rpmostreed-*.h: Daemon headers

Rust Files

• lib.rs: Library root
• *.rs: Module files
• test_*.rs: Test files

Code Style Guidelines

C Code Style

// Function naming: lowercase with underscores
rpmostree_core_new()

// Variable naming: lowercase with underscores
g_autoptr(RpmOstreeCore) core = NULL;

// Type naming: CamelCase
typedef struct _RpmOstreeCore RpmOstreeCore;

Rust Code Style

// Function naming: snake_case
fn rpmostree_core_new() -> Result<Core, Error> {
    // Implementation
}

// Type naming: PascalCase
pub struct RpmOstreeCore {
    // Fields
}

Build Configuration

Autotools Configuration

configure.ac

AC_INIT([rpm-ostree], [version])
AM_INIT_AUTOMAKE([foreign])

# Check for dependencies
PKG_CHECK_MODULES([GLIB], [glib-2.0 >= 2.56])
PKG_CHECK_MODULES([OSTREE], [libostree-1 >= 2020.8])
PKG_CHECK_MODULES([SOLV], [libsolv >= 0.7.0])

# Configure options
AC_ARG_ENABLE([debug], AS_HELP_STRING([--enable-debug], [Enable debug build]))
AC_ARG_ENABLE([tests], AS_HELP_STRING([--enable-tests], [Enable tests]))

AC_CONFIG_FILES([Makefile])
AC_OUTPUT

Makefile.am

SUBDIRS = lib daemon client compose tests

# Global flags
AM_CFLAGS = $(GLIB_CFLAGS) $(OSTREE_CFLAGS) $(SOLV_CFLAGS)
AM_LDFLAGS = $(GLIB_LIBS) $(OSTREE_LIBS) $(SOLV_LIBS)

# Include directories
AM_CPPFLAGS = -I$(top_srcdir)/src

Rust Configuration

Cargo.toml

[package]
name = "rpmostree"
version = "0.1.0"
edition = "2021"

[dependencies]
glib = "0.15"
ostree = "0.17"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tokio = { version = "1.0", features = ["full"] }

[dev-dependencies]
tokio-test = "0.4"

Testing Infrastructure

Test Organization

Unit Tests

• C unit tests: Test individual functions
• Rust unit tests: Test Rust components
• Mock objects: Isolate components for testing

Integration Tests

• Python tests: Test command-line interface
• Shell tests: Test system integration
• VM tests: Test full system behavior

Test Data

• Fixtures: Pre-built test data
• Repositories: Test OSTree repositories
• Packages: Test RPM packages

Test Execution

Running Tests

# Run all tests
make check

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

# Run with verbose output
make check VERBOSE=1

# Run Rust tests
cd rust && cargo test

Test Environment

# Setup test environment
./ci/install-test-deps.sh

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

---

Understanding the repository structure is essential for effective development and contribution. This organization promotes maintainability, testability, and clear separation of concerns.