robojerk
a23b4e53fd
Some checks failed
Compile apt-layer (v2) / compile (push) Has been cancelled
- Added 20-daemon-integration.sh scriptlet for D-Bus and daemon lifecycle management - Updated 99-main.sh with new daemon subcommands (start, stop, status, install, uninstall, test, layer, deploy, upgrade, rollback) - Enhanced help and usage text for daemon integration - Fixed bash syntax errors in daemon integration scriptlet - Updated compile.sh to include daemon integration in build process - Updated .gitignore to exclude src/rpm-ostree/ reference source - Updated CHANGELOG.md and TODO.md to document daemon integration milestone - Removed src/rpm-ostree/ from git tracking (reference only, not committed)
565 lines
No EOL
10 KiB
Markdown
565 lines
No EOL
10 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Configure for development
|
|
./configure --prefix=/usr --libdir=/usr/lib64 --sysconfdir=/etc \
|
|
--enable-debug --enable-verbose --enable-tests \
|
|
--enable-valgrind --enable-sanitizers
|
|
```
|
|
|
|
#### Custom Installation Path
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Run integration tests
|
|
make check-integration
|
|
|
|
# Run specific integration test
|
|
make check-integration TESTS="test-upgrade"
|
|
```
|
|
|
|
#### Rust Tests
|
|
```bash
|
|
# Run Rust unit tests
|
|
cd rust
|
|
cargo test
|
|
|
|
# Run tests with output
|
|
cargo test -- --nocapture
|
|
```
|
|
|
|
### Test Environment Setup
|
|
|
|
#### Virtual Machine Testing
|
|
```bash
|
|
# Setup test VM
|
|
./ci/vmcheck.sh
|
|
|
|
# Run tests in VM
|
|
./ci/vmcheck.sh --test
|
|
```
|
|
|
|
#### Container Testing
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
git checkout -b feature/my-feature
|
|
```
|
|
|
|
2. **Make changes and test**
|
|
```bash
|
|
# Edit source files
|
|
vim src/lib/rpmostree-core.c
|
|
|
|
# Build and test
|
|
make
|
|
make check
|
|
```
|
|
|
|
3. **Commit changes**
|
|
```bash
|
|
git add .
|
|
git commit -m "Add new feature: description"
|
|
```
|
|
|
|
#### Code Quality Checks
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Profile performance
|
|
perf record ./rpm-ostree upgrade
|
|
perf report
|
|
|
|
# Analyze specific functions
|
|
perf record -g -p $(pidof rpm-ostreed)
|
|
perf report
|
|
```
|
|
|
|
#### Using strace
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```json
|
|
// .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
|
|
```cmake
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Regenerate build system
|
|
autoreconf -fiv
|
|
|
|
# Clean and rebuild
|
|
make distclean
|
|
./autogen.sh
|
|
make
|
|
```
|
|
|
|
#### Rust Build Issues
|
|
```bash
|
|
# Update Rust toolchain
|
|
rustup update
|
|
|
|
# Clean Rust build
|
|
cd rust
|
|
cargo clean
|
|
cargo build
|
|
```
|
|
|
|
### Debugging Build Failures
|
|
|
|
#### Verbose Build Output
|
|
```bash
|
|
# Enable verbose make output
|
|
make V=1
|
|
|
|
# Enable verbose configure
|
|
./configure --enable-verbose
|
|
```
|
|
|
|
#### Dependency Analysis
|
|
```bash
|
|
# 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.* |