gportage

README

GPortage - Next-generation Package Manager for Gentoo

GPortage is a modern reimplementation of Gentoo's Portage package manager in Go, designed to solve fundamental problems in dependency resolution while maintaining full compatibility with existing Gentoo ecosystems.

Why GPortage?

Gentoo's traditional package management faces challenges with long-term system upgrades. GPortage solves these problems with:

✅ SAT-based dependency solver - Guarantees conflict-free upgrades
🚀 Transactional updates - Snapshot-based rollbacks using Btrfs/ZFS
🔁 Incremental sync - Git-like repository updates
🔄 Full Portage compatibility - Seamless transition from existing systems
⚡ Parallel processing - Optimized for modern multi-core systems

# Solve upgrade conflicts that traditional Portage can't handle
gportage resolve --deep-upgrade

Architecture Overview

v0.9.0: Single Binary with Daemon + DDD Architecture

graph TD
    subgraph "GPortage Binary"
        CLI[CLI Mode] -->|Auto-detect| DAEMON{Daemon Running?}
        DAEMON -->|Yes| GRPC[gRPC Client]
        DAEMON -->|No| STANDALONE[Standalone Mode]

        subgraph "Daemon Mode (DDD Layered Architecture)"
            subgraph "Interface Layer"
                GRPCS[gRPC Server<br/>Unix Socket]
                REST[REST API<br/>HTTP :8080]
            end

            subgraph "Application Layer"
                APP[PackageService<br/>Orchestration]
                DTO[DTOs<br/>Data Transfer]
            end

            subgraph "Domain Layer"
                PKG[Package<br/>Aggregate Root]
                DEPSVC[DependencyService<br/>Domain Logic]
            end

            subgraph "Infrastructure Layer"
                SOLVER[SAT Solver<br/>Resolution]
                REPO[Repository<br/>Package Data]
            end

            CACHE[Warm Cache<br/>Ebuilds/SAT]
            QUEUE[Job Queue<br/>Parallel Tasks]
            MONITOR[Background<br/>Monitoring]
        end

        GRPC -.->|RPC| GRPCS
        REST --> GRPCS
        GRPCS --> APP
        APP --> DTO
        APP --> DEPSVC
        APP --> SOLVER
        APP --> REPO
        DEPSVC --> PKG
        SOLVER --> REPO
        SOLVER --> PKG

        DAEMON_SERVICE[gportage daemon]
        DAEMON_SERVICE --> GRPCS
        DAEMON_SERVICE --> REST
        DAEMON_SERVICE --> MONITOR
        DAEMON_SERVICE --> CACHE
    end

    subgraph "Backend Data Sources"
        PORTAGE[Portage Tree<br/>/var/db/repos/gentoo]
        STATE[System State<br/>/var/db/pkg]
        BINPKG[Binary Packages<br/>.gpkg.tar]
    end

    STANDALONE --> APP
    REPO --> PORTAGE
    REPO --> STATE
    REPO --> BINPKG

Key Benefits:

• ⚡ Instant CLI responses - Warm cache eliminates cold-start delays
• 🔄 Job queue - Prevents package conflicts from concurrent operations
• 📡 REST API - Web dashboards and monitoring tools
• 🎯 Auto-detection - CLI automatically uses daemon when available
• 🔌 Fallback mode - Works standalone if daemon unavailable

DDD Architecture (Phase 3+):

• Interface Layer - gRPC/REST adapters (thin, protocol conversion)
• Application Layer - Use case orchestration (PackageService)
• Domain Layer - Business logic (Package, DependencyService)
• Infrastructure Layer - Technical concerns (SAT solver, Repository)

Benefits: Clean separation of concerns, testability, maintainability, future-proof for microservices migration.

Getting Started

Prerequisites

• Go 1.25+ (for building from source)
• Linux system (Gentoo recommended)
• Git

Installation

Option 1: Download Binary (Recommended for testing v0.9.0-beta.1)

# Download latest beta release
wget https://github.com/kolkov/gportage/releases/download/v0.9.0-beta.1/gportage_0.9.0-beta.1_linux_x86_64.tar.gz

# Verify checksum
wget https://github.com/kolkov/gportage/releases/download/v0.9.0-beta.1/checksums.txt
sha256sum -c checksums.txt --ignore-missing

# Extract and install
tar -xzf gportage_0.9.0-beta.1_linux_x86_64.tar.gz
sudo install -m 0755 gportage /usr/bin/gportage

# Verify installation
gportage version

Other platforms:

• ARM64: gportage_0.9.0-beta.1_linux_arm64.tar.gz
• ARMv7: gportage_0.9.0-beta.1_linux_arm_7.tar.gz
• ARMv6: gportage_0.9.0-beta.1_linux_arm_6.tar.gz
• 32-bit: gportage_0.9.0-beta.1_linux_386.tar.gz

See all releases

Option 2: Build from Source

git clone https://github.com/kolkov/gportage.git
cd gportage
make build
sudo make install

Migrating from Portage

# Convert existing Portage installation
gportage init --convert-portage

# Perform initial system scan
gportage scan-system

# Test upgrade solution
gportage update --dry-run

Basic Usage

Daemon Mode (Recommended):

# Start daemon (OpenRC)
sudo rc-service gportaged start
sudo rc-update add gportaged default

# OR systemd
sudo systemctl start gportaged
sudo systemctl enable gportaged

# Check daemon status
gportage status

# CLI now uses daemon automatically
gportage install www-servers/nginx  # ⚡ Instant via daemon
gportage update --create-snapshot
gportage search firefox

Standalone Mode (No Daemon):

# Stop daemon
sudo rc-service gportaged stop

# CLI falls back to standalone mode
gportage status  # Shows: "Daemon: not running, Mode: standalone"
gportage install www-servers/nginx  # Still works, slower cold-start

Common Operations:

# Sync repository (native Go rsync)
gportage sync

# Install packages
gportage install www-servers/nginx

# Update system with snapshot protection
gportage update --create-snapshot

# Query package information
gportage info dev-lang/go

# Remove package with dependency cleanup
gportage remove net-misc/curl

# Search packages
gportage search firefox

# Show system status
gportage status

Key Features

Advanced Dependency Resolution

// Example constraint solving
solution, err := solver.Resolve(pkg.Constraint{
    Name: "dev-lang/go",
    Version: ">=1.22",
    Slot: "0/1.22",
    UseFlags: []string{"ssl", "-pie"},
})
if err != nil {
    log.Fatal("Resolution failed:", err)
}

Transactional Safety

# Create pre-upgrade snapshot
gportage snapshot create --tag pre-upgrade-2025

# Rollback if update fails
gportage snapshot restore pre-upgrade-2025

# List available snapshots
gportage snapshot list

Portage Compatibility Layer

// Convert traditional ebuild to native format
pkg, err := compat.ConvertEbuild(
    "/var/db/repos/gentoo/sys-kernel/gentoo-sources/gentoo-sources-6.9.1.ebuild"
)
if err != nil {
    return fmt.Errorf("ebuild conversion failed: %w", err)
}

Development Setup (GoLand)

1. Clone repository:

   git clone https://github.com/kolkov/gportage.git
   

2. Open in GoLand: File > Open > Select project directory

3. Setup build configuration:

   • Go Build configuration
   • Build command: make dev-build
   • Run command: ./bin/gportage --dev-mode

4. Enable tests:

   make test       # Run all tests
   make coverage   # Generate coverage report
   make benchmark  # Run performance benchmarks
   

5. Debugging:

   • Use the built-in debugger with debug build tag
   • Example launch configuration:

   {
     "name": "Test Resolver",
     "type": "go",
     "request": "launch",
     "mode": "test",
     "program": "${workspaceFolder}/solver",
     "args": ["-test.run", "TestComplexResolution"]
   }
   

Contributing

We welcome contributions! Please follow our workflow:

1. Fork the repository
2. Create feature branch (feat/your-feature)
3. Commit using Conventional Commits
4. Submit a PR with detailed description

See our Contribution Guidelines for details.

Roadmap

Version	Status	Features	Target
v0.1.0	✅ Done	Architecture foundation, SAT solver	Q1 2025
v0.2.0	✅ Done	Portage compatibility layer	Q2 2025
v0.3.0	✅ Done	USE flag resolution	Q3 2025
v0.4.0	✅ Done	Dependency graph solver	Q4 2025
v0.5.0	✅ Done	System integration (5 phases)	Oct 2025
v0.6.0	✅ Done	Binary packages (core)	Oct 2025
v0.7.0	✅ Done	Binary packages (building)	Oct 2025
v0.9.0	📋 Next	Daemon + API/CLI	Q1 2026
v0.8.0	📋 Planned	GoReleaser (optional)	TBD
v1.0.0	🎯 Target	Production-ready release	Q2 2026

Current Status: v0.9.0-beta.1 ✅ RELEASED

v0.9.0-beta.1 - Daemon + API/CLI + DDD Architecture + Job Queue + Conflict Detection

Phase 1 - Foundation (Week 1-2) ✅ COMPLETE

• ✅ Single binary with mode detection (gportage / gportage daemon)
• ✅ Daemon core with gRPC + REST servers
• ✅ CLI client with auto-daemon detection
• ✅ Version injection via ldflags (Git commit, build date)
• ✅ Unix socket communication (/var/run/gportage.sock)
• ✅ REST API health check (/health, /api/v1/status)
• ✅ Graceful shutdown handling (SIGTERM, SIGINT)
• ✅ Professional Makefile with build targets

Phase 2 - gRPC Service (Week 3-4) ✅ COMPLETE

• ✅ Protocol Buffers service definition
• ✅ Package operations (Ping, GetStatus, InstallPackage, etc.)
• ✅ Streaming progress for long operations
• ✅ Full gRPC client-server implementation
• ✅ PID file management (cross-platform)
• ✅ Daemon detection and health checks

Phase 3 - Application Services (Week 5-6) ✅ COMPLETE

• ✅ DDD Layered Architecture implementation
• ✅ Application Service layer (PackageService)
  • ResolvePackage (SAT solver integration)
  • SearchPackages (repository queries)
  • GetPackageInfo (detailed package data)
  • InstallPackage (streaming progress)
• ✅ DTOs for clean layer boundaries
• ✅ Domain integration (Package, DependencyService)
• ✅ Infrastructure integration (Solver, Repository)
• ✅ All tests passing + linter clean

Phase 4 - Job Queue (Week 7) ✅ COMPLETE

• ✅ Job Queue implementation (Worker pool pattern)
  • Concurrent job execution with configurable workers
  • Priority support (High/Normal/Low)
  • Job types: Install, Remove, Update, Sync
  • Status tracking: Pending → Running → Completed/Failed/Canceled
  • Progress callbacks for real-time updates
  • Graceful shutdown with timeout
  • Thread-safe operations
• ✅ Daemon integration
  • Auto-start with daemon
  • Graceful stop with daemon
  • Statistics API (active workers, queue length, jobs by status)
• ✅ gRPC Job management API
  • GetJobStatus(job_id) - query job status
  • ListJobs(filter) - list all jobs with optional filtering
  • CancelJob(job_id) - cancel running/pending jobs
  • InstallPackage now uses Job Queue (streaming + job_id)
• ✅ Comprehensive tests (11 tests for Job Queue)
  • Job lifecycle tests
  • Concurrent execution tests
  • Cancellation tests
  • Graceful shutdown tests
• ✅ Context-aware cancellation
  • Proper handling of canceled vs failed jobs
  • Context propagation through job execution
  • Graceful degradation on timeout
• ✅ Package Conflict Detection (CRITICAL FOR SAFETY!)
  • SAT solver-based dependency analysis
  • Prevents parallel operations on same package
  • Detects shared dependency conflicts
  • Version-aware package name matching
  • Automatic job rejection with clear error messages
  • Examples:
    • ✗ dev-lang/go + dev-lang/go-1.22 → CONFLICT (same package)
    • ✗ pkg1 (requires glibc-2.38) + pkg2 (updates glibc) → CONFLICT (shared dep)
    • ✅ dev-lang/go + dev-lang/python → OK (different packages)

Implementation Stats (Phases 1-4):

• Code: ~3,500 lines (daemon + gRPC + Application + Job Queue + Conflict Detection)
• Files: 21+ new files
• Tests: 50+ tests (including 11 Job Queue + 10 Conflict Detection tests)
• Test Coverage: 43.5% overall (72.5% daemon, 89.3% resolver)
• Architecture: Clean DDD + Worker Pool + Conflict Detection pattern
• Build: Single binary with version injection
• Linter: 0 issues (golangci-lint)
• Safety: Production-ready conflict prevention ✅
• Race Conditions: 0 detected (verified with race detector)
• Release: Automated via GoReleaser + GitHub Actions

Next: Phase 5+

• CLI commands integration (status, job management)
• Persistent cache system
• Background monitoring service
• Full integration testing

Previous Achievement: v0.7.0 ✅ Complete

• ✅ Binary package builder (source → .gpkg.tar / .tbz2)
• ✅ Package signing (GPG/SSH/RSA)
• ✅ Local binhost manager + remote uploader
• ✅ 1,533 lines of tests (29 tests + 6 benchmarks)

Test Coverage (Overall):

• Domain layer: 92.3% ✅
• Application layer: Tested via integration ✅
• Solver layer: 75%+ ✅
• Config layer: 100% ✅
• Binpkg layer: 32.3% ✅
• Daemon layer: Full integration tests ✅
• gRPC layer: Streaming + RPC tests ✅

See ROADMAP.md for detailed plans and CHANGELOG.md for full history.

CI/CD & Release Process

Current Setup:

• ✅ GitHub Actions for automated testing (Go 1.25, Linux)
• ✅ GolangCI-Lint v2 for code quality
• ✅ Automated releases via GoReleaser
• ✅ Multi-platform binaries (amd64, arm64, arm, 386)

Release Workflow:

See RELEASE_GUIDE.md for complete release process documentation.

Quick Reference:

# Beta releases (testing, API may change)
git tag -a v0.9.0-beta.X -m "[Release notes]"
git push origin v0.9.0-beta.X

# Release candidates (API frozen, bugfixes only)
git tag -a v0.9.0-rc.X -m "[Release notes]"
git push origin v0.9.0-rc.X

# Stable releases (production-ready)
git tag -a v0.9.0 -m "[Release notes]"
git push origin v0.9.0

Automated Build Pipeline:

1. Tag push triggers GitHub Actions (.github/workflows/release.yml)
2. Runs full test suite
3. GoReleaser builds binaries for all platforms:
   • linux/amd64 (primary target)
   • linux/arm64 (ARM servers)
   • linux/386 (32-bit)
   • linux/arm/6 and arm/7 (Raspberry Pi, embedded)
4. Creates GitHub Release with:
   • Multi-platform archives
   • SHA256 checksums
   • Auto-generated changelog
   • Pre-release flag (for beta/rc)

Build Time: ~2-3 minutes for full multi-platform build

Current Release: v0.9.0-beta.1

License

GPortage is licensed under the GNU General Public License v2.0 - the same as original Portage.