# vivo75/portuale architecture

> Architecture diagram of the GitHub repository vivo75/portuale, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vivo75/portuale
- Repository: https://github.com/vivo75/portuale

## Overview

Portuale is a Rust reimplementation of Gentoo Portage, exposed as a multicall CLI. The principal workflow is: a user invokes emerge; package configuration and dependency resolution produce an ordered merge plan; source packages are fetched, built, and merged, or binary packages are installed. Separate CLI paths support unmerge, package creation, and VDB operations. The README documents these capabilities; source excerpts confirm dispatch, phase execution, merge adapters, and VDB responsibilities, but not every runtime connection shown.

Main entry points: [`rust/portuale/src/pretend.rs`](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/pretend.rs) (Pretend and plan), [`rust/portuale/src/main.rs`](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/main.rs) (Applet dispatch), [`rust/portuale/src/ebuild_merge.rs`](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/ebuild_merge.rs) (Source merge), [`rust/portuale/src/emerge_build.rs`](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/emerge_build.rs) (Build scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and planning"]
  node_dispatch["Applet dispatch<br/>[main.rs]"]
  node_pretend["Pretend and plan<br/>[pretend.rs]"]
  node_scheduler["Build scheduler<br/>[emerge_build.rs]"]
end

subgraph group_resolve["Configuration and resolution"]
  node_profile["Profile config<br/>[lib.rs]"]
  node_atom["Dependency atoms<br/>[lib.rs]"]
  node_use_reduce["USE reduction<br/>[lib.rs]"]
  node_required_use["Required USE<br/>[lib.rs]"]
  node_repo["Repository metadata<br/>[merge_order.rs]"]
  node_ordering["Merge ordering<br/>[merge_order.rs]"]
end

subgraph group_install["Package installation"]
  node_fetch["Source fetch<br/>[fetch.rs]"]
  node_phases["Ebuild phases<br/>[ebuild_phases.rs]"]
  node_source_merge["Source merge<br/>[ebuild_merge.rs]"]
  node_merge_engine["Merge adapters<br/>[merge_engines.rs]"]
  node_package["Binary packaging<br/>[ebuild_package.rs]"]
  node_binpkg["Binary packages<br/>[binpkg.rs]"]
  node_getbinpkg["Binary retrieval"]
  node_unmerge["Unmerge<br/>[ebuild_unmerge.rs]"]
end

subgraph group_state["Installed state"]
  node_vdb_cmd["VDB commands<br/>[vdb_cmd.rs]"]
  node_vdb[("Installed database<br/>[lib.rs]")]
end

node_user(("User"))
node_filesystem[("System filesystem")]
node_sources["Package sources"]
node_binhost["Binary host"]

node_user -->|"invokes"| node_dispatch
node_dispatch -->|"routes emerge"| node_pretend
node_pretend -.->|"reads config"| node_profile
node_pretend -.->|"resolves atoms"| node_atom
node_pretend -.->|"evaluates USE"| node_use_reduce
node_pretend -.->|"checks constraints"| node_required_use
node_pretend -.->|"resolves metadata"| node_repo
node_pretend -.->|"orders tasks"| node_ordering
node_dispatch -.->|"runs emerge"| node_scheduler
node_scheduler -.->|"dispatches merges"| node_merge_engine
node_merge_engine -->|"executes source"| node_source_merge
node_source_merge -->|"runs phases"| node_phases
node_phases -->|"fetches sources"| node_fetch
node_fetch -.->|"downloads"| node_sources
node_source_merge -->|"installs files"| node_filesystem
node_source_merge -->|"writes records"| node_vdb
node_scheduler -.->|"builds packages"| node_package
node_package -->|"creates archive"| node_binpkg
node_dispatch -.->|"routes binary retrieval"| node_getbinpkg
node_getbinpkg -.->|"fetches packages"| node_binhost
node_getbinpkg -.->|"installs binary"| node_binpkg
node_dispatch -.->|"routes unmerge"| node_unmerge
node_unmerge -.->|"removes files"| node_filesystem
node_unmerge -.->|"updates records"| node_vdb
node_dispatch -->|"routes VDB"| node_vdb_cmd
node_vdb_cmd -->|"converts or verifies"| node_vdb

click node_dispatch "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/main.rs"
click node_pretend "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/pretend.rs"
click node_profile "https://github.com/vivo75/portuale/blob/main/rust/portage-profile/src/lib.rs"
click node_atom "https://github.com/vivo75/portuale/blob/main/rust/portage-dep/src/lib.rs"
click node_use_reduce "https://github.com/vivo75/portuale/blob/main/rust/portage-use-reduce/src/lib.rs"
click node_required_use "https://github.com/vivo75/portuale/blob/main/rust/portage-required-use/src/lib.rs"
click node_repo "https://github.com/vivo75/portuale/blob/main/rust/portage-repo/src/merge_order.rs"
click node_ordering "https://github.com/vivo75/portuale/blob/main/rust/portage-repo/src/merge_order.rs"
click node_scheduler "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/emerge_build.rs"
click node_fetch "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/fetch.rs"
click node_phases "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/ebuild_phases.rs"
click node_source_merge "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/ebuild_merge.rs"
click node_merge_engine "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/merge_engines.rs"
click node_package "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/ebuild_package.rs"
click node_binpkg "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/binpkg.rs"
click node_getbinpkg "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/emerge_getbinpkg.rs"
click node_unmerge "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/ebuild_unmerge.rs"
click node_vdb_cmd "https://github.com/vivo75/portuale/blob/main/rust/portuale/src/vdb_cmd.rs"
click node_vdb "https://github.com/vivo75/portuale/blob/main/rust/portage-vdb/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dispatch,node_pretend,node_scheduler,node_user toneBlue
class node_profile,node_atom,node_use_reduce,node_required_use,node_repo,node_ordering,node_filesystem toneAmber
class node_fetch,node_phases,node_source_merge,node_merge_engine,node_package,node_binpkg,node_getbinpkg,node_unmerge toneMint
class node_vdb_cmd,node_vdb toneRose
class node_sources,node_binhost toneIndigo
```

## Components

### CLI and planning

- [Applet dispatch](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/main.rs): `rust/portuale/src/main.rs`
- [Pretend and plan](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/pretend.rs): `rust/portuale/src/pretend.rs`
- [Build scheduler](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/emerge_build.rs): `rust/portuale/src/emerge_build.rs`

### Configuration and resolution

- [Profile config](https://github.com/vivo75/portuale/blob/main/rust/portage-profile/src/lib.rs): `rust/portage-profile/src/lib.rs`
- [Dependency atoms](https://github.com/vivo75/portuale/blob/main/rust/portage-dep/src/lib.rs): `rust/portage-dep/src/lib.rs`
- [USE reduction](https://github.com/vivo75/portuale/blob/main/rust/portage-use-reduce/src/lib.rs): `rust/portage-use-reduce/src/lib.rs`
- [Required USE](https://github.com/vivo75/portuale/blob/main/rust/portage-required-use/src/lib.rs): `rust/portage-required-use/src/lib.rs`
- [Repository metadata](https://github.com/vivo75/portuale/blob/main/rust/portage-repo/src/merge_order.rs): `rust/portage-repo/src/merge_order.rs`
- [Merge ordering](https://github.com/vivo75/portuale/blob/main/rust/portage-repo/src/merge_order.rs): `rust/portage-repo/src/merge_order.rs`

### Package installation

- [Source fetch](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/fetch.rs): `rust/portuale/src/fetch.rs`
- [Ebuild phases](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/ebuild_phases.rs): `rust/portuale/src/ebuild_phases.rs`
- [Source merge](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/ebuild_merge.rs): `rust/portuale/src/ebuild_merge.rs`
- [Merge adapters](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/merge_engines.rs): `rust/portuale/src/merge_engines.rs`
- [Binary packaging](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/ebuild_package.rs): `rust/portuale/src/ebuild_package.rs`
- [Binary packages](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/binpkg.rs): `rust/portuale/src/binpkg.rs`
- [Binary retrieval](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/emerge_getbinpkg.rs): `rust/portuale/src/emerge_getbinpkg.rs`
- [Unmerge](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/ebuild_unmerge.rs): `rust/portuale/src/ebuild_unmerge.rs`

### Installed state

- [VDB commands](https://github.com/vivo75/portuale/blob/main/rust/portuale/src/vdb_cmd.rs): `rust/portuale/src/vdb_cmd.rs`
- [Installed database](https://github.com/vivo75/portuale/blob/main/rust/portage-vdb/src/lib.rs): `rust/portage-vdb/src/lib.rs`

### Other components

- **User**
- **System filesystem**
- **Package sources**
- **Binary host**

## Connections

- User → Applet dispatch: invokes (evidence: `rust/portuale/src/main.rs`)
- Applet dispatch → Pretend and plan: routes emerge (evidence: `rust/portuale/src/main.rs`)
- Pretend and plan → Profile config: reads config
- Pretend and plan → Dependency atoms: resolves atoms
- Pretend and plan → USE reduction: evaluates USE
- Pretend and plan → Required USE: checks constraints
- Pretend and plan → Repository metadata: resolves metadata
- Pretend and plan → Merge ordering: orders tasks (evidence: `rust/portage-repo/src/merge_order.rs`)
- Applet dispatch → Build scheduler: runs emerge (evidence: `rust/portuale/src/main.rs`)
- Build scheduler → Merge adapters: dispatches merges (evidence: `rust/portuale/src/merge_engines.rs`)
- Merge adapters → Source merge: executes source (evidence: `rust/portuale/src/merge_engines.rs`)
- Source merge → Ebuild phases: runs phases (evidence: `rust/portuale/src/ebuild_merge.rs`)
- Ebuild phases → Source fetch: fetches sources (evidence: `rust/portuale/src/ebuild_phases.rs`)
- Source fetch → Package sources: downloads
- Source merge → System filesystem: installs files
- Source merge → Installed database: writes records
- Build scheduler → Binary packaging: builds packages (evidence: `rust/portuale/src/emerge_build.rs`)
- Binary packaging → Binary packages: creates archive (evidence: `rust/portuale/src/ebuild_package.rs`)
- Applet dispatch → Binary retrieval: routes binary retrieval (evidence: `rust/portuale/src/main.rs`)
- Binary retrieval → Binary host: fetches packages
- Binary retrieval → Binary packages: installs binary (evidence: `rust/portuale/src/emerge_getbinpkg.rs`)
- Applet dispatch → Unmerge: routes unmerge (evidence: `rust/portuale/src/main.rs`)
- Unmerge → System filesystem: removes files
- Unmerge → Installed database: updates records
- Applet dispatch → VDB commands: routes VDB (evidence: `rust/portuale/src/main.rs`)
- VDB commands → Installed database: converts or verifies (evidence: `rust/portuale/src/vdb_cmd.rs`)
