How canonical/rockcraft works
Project Type and Purpose
• This is a Python-based command-line toolkit and library (“starbase”) that provides the scaffolding, build orchestration, and tooling foundations for Canonical’s Snapcraft-based (Rockcraft) projects.
• It exposes a CLI (rockcraft), a core application layer, commands, extension/plugin hooks, services that drive snapshot/OCI builds and remote builds, and a templating system for generating new projects.
High‐Level Architectural Components
a. CLI Layer
• rockcraft/__main__.py and rockcraft/cli.py – entry points and argument parsing via uv (a wrapper around click).
b. Core Application
• rockcraft/application.py – bootstraps the application, reads configuration, dispatches commands.
• rockcraft/commands/ – implements each CLI command (e.g., init, build, list-extensions).
c. Extensions & Plugins
• rockcraft/extensions/ – framework integrations (Django, Flask, Express, Go, FastAPI, etc.).
• rockcraft/plugins/ – language/build-tool extensions (Maven, Poetry, Python, UVicorn, Ant).
d. Services
• rockcraft/services/ – core business logic broken into service classes:
– project – introspection of existing codebases
– package – packaging logic (snapcraft.yaml generation)
– image – local OCI image operations
– remotebuild – orchestration of remote builds
– lifecycle – sequence of steps to assemble layers and overlays
– provider / service_factory – factory to wire correct service implementations
e. Templating
• rockcraft/templates/ – Jinja2 templates for each supported framework/language to scaffold a new project or rockcraft.yaml.
f. Data Models & Utilities
• rockcraft/models/ – in-memory representations (Project, Parts, Layers)
• rockcraft/utils.py / constants.py / errors.py – shared helpers and definitions
g. Configuration & Schema
• pyproject.toml, rockcraft/oci.py, schema/rockcraft.json – define CLI metadata and rockcraft.yaml schema
h. Testing
• tests/unit/, tests/integration/, tests/spread/ – layered testing harness that validates commands, services, plugins, and end-to-end spread workflows
i. Documentation & Tooling
• docs/ (Sphinx): user guides, how-tos, explanations, references
• tools/ and GitHub Actions workflows – CI, release, linting, docs publishing
Relationships & Data Flows
• User ► CLI Layer ► Core Application ► Command Handler
• Command Handler ► Service Factory ► Specific Service ► executes business logic
• Services may:
• Read/write project files (template rendering, overlay steps)
• Invoke Snapcraft / OCI tools (via local hooks or remote API)
• Produce or consume intermediate representations (layers, pebble configs)
• Extensions & Plugins register themselves on startup and hook into service factory or command discovery
• Testing harness injects fake projects into services to validate behavior
Architectural Patterns & Design Principles
• Modular layering: CLI | Application core | Commands | Services | Templates
• Inversion of Control: Service Factory binds interfaces to implementations based on project metadata
• Plugin/Extension registration: Discovery via registry.py allows new frameworks or build-tools to hook without core changes
• Schema-driven: rockcraft.yaml guided by JSON schema to validate user inputs
• Separation of concerns: templating, business logic, file I/O, external system calls are distinct