How conan-io/conan works
1. What this repository is
Conan is a Python-based C/C++ package manager. The codebase is organized around a user-facing CLI, a programmatic Conan API, an internal dependency-resolution/core engine, a large set of recipe helpers (“tools”), and an optional embedded Conan Server implementation.
2. Primary entry points
The two main entry surfaces are:
- conan/cli/*: command-line parsing and command dispatch for conan install, create, upload, search, profile, remote, etc.
- conan/api/conan_api.py plus conan/api/subapi/*: the programmatic API used by the CLI and tests.
Both ultimately delegate into the internal engine rather than implementing package logic themselves.
3. CLI layer
conan/cli/cli.py, args.py, and commands/* map shell commands to high-level operations. exit_codes.py and printers/formatters handle output and result formatting. The CLI is mostly an orchestration layer: parse arguments, call API methods, format results, and exit with the correct code.
4. API and sub-APIs
conan/api/subapi/* groups functionality by domain: install, export, create/new, upload, remotes, profiles, graph, cache, list, lockfiles, workspace, etc. This layer is the main contract above the engine and is where command semantics are centralized. conan/api/model/* contains typed result models for lists, references, remotes, and outputs.
5. Core package-management engine
The real package resolution and lifecycle logic lives under conan/internal/*. Key subsystems include:
- internal/graph/* for dependency graph construction, binary/package ID computation, compatibility, version-range resolution, and install graphs.
- internal/cache/* for the local Conan cache, database tables, integrity checks, and layout.
- internal/loader.py, source.py, methods.py, and model/* for loading recipes, representing Conanfiles, settings/options, manifests, lockfiles, layouts, and metadata.
This is the boundary where package identity, dependency order, and cache state are decided.
6. Local-vs-remote data flow
Package operations flow between:
- local recipes/cache (internal/cache, internal/model, internal/local)
- remote registries via REST (internal/rest, api/subapi/remotes, api/subapi/download, api/subapi/upload)
- graph resolution (internal/graph)
For install/create/upload workflows, the engine resolves a graph, checks cache for binaries, downloads missing artifacts from remotes, and uploads built packages back to remotes when requested.
7. Remote and transport subsystem
conan/internal/rest/* implements HTTP client behavior for Conan remotes, authentication, downloads/uploads, and local recipe index support. The remote manager and credential handling are separate from graph logic, so network concerns are isolated from package modeling. This subsystem is what connects Conan clients to Artifactory or other Conan-compatible repositories.
8. Recipe authoring and build-system integration
conan/tools/* is a large recipe-helper library exposed to Conan recipes. It provides toolchains, dependency generators, environment managers, and utility helpers for major ecosystems:
- CMake, Meson, Autotools/GNU Make, MSBuild/NMake, Bazel, Premake, Qbs, SCons
- Apple, Android, Intel, ROS, SBOM, SCM/Git, system package managers
These modules are not the package manager core; they are adapters that generate build files, env scripts, or metadata for consumer projects.
9. Python recipe/runtime model
Recipes and model objects are Python-centric. conan/internal/model/* and conan/internal/methods.py define the recipe interface, settings/options, package info, version handling, lockfiles, and workspace behavior. conan/cps/* adds CPS-related support. Conan’s architecture relies on executing recipe code in a controlled loader/runtime rather than parsing declarative metadata alone.
10. Execution environments and runners
conan/internal/runner/* abstracts how Conan invokes commands in Docker, SSH, and WSL contexts, while internal/util/runners.py and related helpers support command execution. This matters for cross-platform builds and test/package execution because the toolchain setup can happen in isolated or remote environments.
11. Legacy/embedded server
The conans/server/* tree is a separate, older Conan Server implementation. It includes REST controllers, auth plugins, storage adapters, JWT/basic-auth handling, and server launch/migration logic. Its boundaries are distinct from the client package manager: it stores packages/revisions and serves them over HTTP, but it is not the same code path as the Conan client’s local cache engine.
12. Compatibility and transition boundaries
The repo contains both conan/* and conans/*, reflecting modern Conan 2 client code plus compatibility/legacy server/client modules. That split is important for architecture diagrams: the client package manager and the embedded server are related but not the same subsystem, and many tests cover cross-version behavior, migrations, and legacy flows.
13. Testing and CI as architecture support
The test/, conan/test/, and .github/workflows/* trees show heavy test investment around all major boundaries: CLI, graph resolution, cache behavior, remote auth/download/upload, toolchains, and server features. CI runs matrixed platform tests and coverage; Docker is used for some conan tests and integration scenarios. This indicates the repo’s architecture is highly portability- and regression-driven.
Main entry points: internal Core engine · test Tests · cli.py CLI · server Server
Components 19
Conan client
Modern Conan 2 client package manager subsystems.
- CLI · Shell command parsing, dispatch, output, and exit codes.
conan/cli/cli.py - Commands · Command modules that translate subcommands into high-level operations.
conan/cli/commands - Conan API · Programmatic entrypoint used by the CLI and integrations.
conan/api/conan_api.py - Sub-APIs · Domain-oriented API layer for install, create, upload, remotes, graph, cache, profiles, lockfiles, and workspace.
conan/api/subapi - API models · Typed output and list/reference/remote models returned by the API.
conan/api/model - Core engine · Internal recipe loading, model handling, cache state, graph resolution, and execution plumbing.
conan/internal - Dependency graph · Builds graphs, resolves versions, computes package IDs, compatibility, and install order.
conan/internal/graph - Local cache · Local recipe and package cache, database tables, layout, and integrity checks.
conan/internal/cache - Recipe model · Conanfile, settings, options, manifests, lockfiles, layouts, and related runtime models.
conan/internal/model - Loader · Loads and prepares recipe code and recipe metadata for the engine.
conan/internal/loader.py - Remote REST · HTTP client, auth, download/upload, remote manager, and route handling for Conan remotes.
conan/internal/rest - Runners · Command execution abstractions for Docker, SSH, and WSL environments.
conan/internal/runner - Conan tools · Recipe helper library for toolchains, generators, envs, filesystem helpers, SCM, and platform adapters.
conan/tools - CPS support · CPS-related support integrated with the Conan recipe/tooling model.
conan/cps
Legacy server
Embedded Conan Server implementation and compatibility tree.
- Server · Older embedded Conan Server implementation with REST controllers, auth, storage, and launch/migration logic.
conans/server - Server REST · Bottle-based REST controllers, routes, and API v2 services for server operations.
conans/server/rest - Server auth · JWT and basic-auth plugins plus authorization services for the server.
conans/server/crypto - Server store · Disk-backed server package storage and revision handling.
conans/server/store
Tests
Functional, integration, and unit coverage around major boundaries.
- Tests · Functional, integration, unit, and performance tests covering client, tools, graph, remote, and server behavior.
test
Connections 26
- CLI → Commands: dispatches · CLI subcommands are mapped to command handlers.
- CLI → Conan API: calls · Command execution is routed through the Conan API.
- CLI → Sub-APIs: orchestrates · CLI behavior is mostly orchestration over domain sub-APIs.
- Conan API → Sub-APIs: exposes · The public API is organized into domain sub-APIs.
- Sub-APIs → Core engine: delegates to · Sub-APIs centralize semantics and delegate core work to internal engine subsystems.
- Sub-APIs → API models: returns · API calls surface typed result models.
- Core engine → Loader: loads · The engine loads recipes and prepared Conanfile state.
- Core engine → Recipe model: uses · Core behavior is built around internal recipe/runtime models.
- Core engine → Dependency graph: resolves · Dependency resolution and package identity are decided by the graph subsystem.
- Core engine → Local cache: reads/writes · The engine consults and updates the local cache.
- Core engine → Remote REST: syncs · Remote package and recipe flows use REST transport.
- Core engine → Runners: executes · Build and test actions can run in isolated execution environments.
- Core engine → Conan tools: provides · Recipe helpers and generators are part of the client surface built on the engine.
- Core engine → CPS support: supports · CPS support plugs into the client runtime model.
- Remote REST → Local cache: downloads to · Remote artifacts are cached locally after retrieval.
- Remote REST → Dependency graph: feeds · Resolution may trigger remote metadata/package discovery.
- Dependency graph → Recipe model: interprets · Graph computation depends on recipe, settings, version, and lockfile models.
- Local cache → Recipe model: stores · Cache state persists recipes, packages, manifests, and metadata.
- Server → Server REST: serves · The server exposes REST endpoints for clients.
- Server → Server auth: authorizes · Authentication and authorization are handled by server-side crypto/auth components.
- Server → Server store: persists · Packages and revisions are stored on disk.
- Tests → CLI: covers · Functional and integration tests exercise CLI flows.
- Tests → Core engine: covers · Graph, cache, loader, and model behavior are heavily tested.
- Tests → Remote REST: covers · Remote auth, download, upload, and requester behavior are tested.
- Tests → Conan tools: covers · Toolchain and helper modules are validated with extensive tests.
- Tests → Server: covers · Server auth, REST, storage, and migration flows are covered.