portage-ng Handbook

A comprehensive guide to portage-ng — a declarative reasoning engine for software configuration, applied to Gentoo Linux.

#Part I — Getting Started

1. Introduction
2. Installation and Quick Start
3. Configuration

#Part II — Architecture and Internals

4. Architecture Overview
5. Proof Literals
6. Knowledge Base and Cache
7. The EAPI Grammar
8. The Prover
9. Assumptions and Constraint Learning
10. Version Domains
11. Rules and Domain Logic
12. Resolution: Configuration as Proofs
    • Policy cards — what Gentoo policy requires
    • Policy by example — overlay curriculum
    • One-page map — rule/2 → schema → test → card
13. Ordering: Plans as Proofs
14. Output and Visualization

#Part III — Features

15. Command-Line Interface
16. Building and Execution
    • Why not our own ebuild? — why phase execution stays delegated
    • The ebuild contract — builder ↔ Portage ebuild boundary
17. Semantic Search and LLM Integration
18. Distributed Proving
19. Upstream and Bug Tracking
20. Gentoo Linux Security Advisories (GLSA)

#Part IV — Foundations

21. Contextual Logic Programming
22. Context Terms and Feature Unification
23. Resolver Comparison
24. Dependency Ordering

#Part V — Development

25. Testing and Regression
26. Performance and Profiling
27. Contributing

#Closing

28. Closing Thoughts