Gentoo Domain Policy Cards
A read-only view of Gentoo resolver policy for newcomers.
These cards answer what must hold, not how the search engine walks
candidates. Procedural detail stays in
Source/Domain/Gentoo/Rules/Resolving/
and the narrative walkthrough in
Chapter 12.
Each card uses the same skeleton:
| Field | Meaning |
|---|---|
| Concern | One Gentoo / PMS question |
| PMS / Portage | Informal package-manager meaning |
| Literals | rule/2 heads and related proof literals |
| Owns | Module(s) that implement the policy |
| Invariants | Short declarative bullets (not control flow) |
| Examples | Overlay specimens from the example index |
Keep cards in sync with overlay tests (make test-overlay) and the
one-page map. Prefer updating a card when you change
visibility, ranking, USE, or assumption polarity — not only when docs
feel stale.
Cards
| Card | Concern |
|---|---|
| Visibility | When is an ebuild admissible? |
| Target resolution | How does a CLI atom become a candidate? |
| Install obligations | What does :install require? |
| Run and PDEPEND | What does :run require? |
| Dependency atoms | Version / slot atoms → one selected CN |
| Choice groups | ||, ^^, ?? selection |
| USE | Conditionals, bracketed USE deps, merge |
| REQUIRED_USE | Hard USE constraints on a package |
| Slots | Slot / sub-slot operators and conflicts |
| Blockers | Soft ! and hard !! |
| Domain assumptions | Positive vs negative domain assumptions |
| Cycle breaks | Prover cycle-break assumptions (benign) |
Quick links
- Example index (curriculum) — learn policy by specimen
- One-page map —
rule/2head → schema → test → card - Full overlay matrix — all 80 scenarios
- Chapter 12: Resolution — end-to-end resolution story
- Chapter 9: Assumptions — fallback / learning
- Chapter 25: Testing — how to run the suite