Développement
Organisation du code
Sources/cakectl/Commands/ – gestionnaires de commandes CLI
Sources/caked/Commands/ et Sources/caked/Handlers/ – gestionnaires de commandes et d’exécution du démon
Sources/cakedlib/ – utilitaires partagés, configuration et abstractions principales
Catalogue d’images de VM (assistant Caker.app, et build/launch --alias)
L’assistant de création de VM de Caker.app (Sources/caker/Views/VirtualMachineWizard.swift) propose des images ISO, IPSW et cloud (qcow2) préconfigurées. Cette liste n’est plus codée en dur dans des enums Swift : elle provient d’une ressource JSON embarquée, chargée au runtime. Le catalogue vit désormais dans CakedLib (il était auparavant réservé à caker), ce qui permet à caked build/cakectl build (et launch) de résoudre eux aussi un id du catalogue via une option unique --alias <id> (ex. --alias macos12, --alias ubuntu2604) ; caked aliases/cakectl aliases listent tous les ids connus — voir Sources/Grpc/options/BuildOptions.swift, Sources/caked/Commands/Aliases.swift/Sources/cakectl/Commands/Aliases.swift, et la section « VM image catalog, --alias, and the aliases command » du CLAUDE.md pour cette seconde moitié du mécanisme.
Sources/cakedlib/Resources/VMImages.json – le catalogue, organisé par architecture au premier niveau : {"arm64": {...}, "amd64": {...}}, chaque nœud contenant trois tableaux iso, ipsw et cloud d’entrées {id, label, url} déjà résolues (pas de gabarit {arch} à substituer au runtime). Une image qui n’existe pas pour une architecture donnée est simplement absente de son tableau — par exemple l’ISO Fedora 41 Workstation, qui n’a jamais été publiée en aarch64, n’apparaît que sous amd64.
Sources/cakedlib/VMImageCatalog.swift – VMImageCatalog/VMImageArchCatalog/VMImageEntry (tous public), le modèle Codable correspondant. VMImageCatalog.current (et les raccourcis availableISOImages/availableIPSWImages/availableCloudImages) sélectionne le nœud arm64 ou amd64 selon l’architecture d’exécution via #if arch(arm64).
Les entrées iso et cloud portent aussi des champs optionnels minCPU/minMemoryMiB, absents des entrées ipsw (les installations macOS appliquent leur propre plancher fixe, indépendamment de ce catalogue). Convention actuelle : 2 CPU / 2048 MiB pour les ISO « Server » et les images cloud (headless par nature), 4 CPU / 4096 MiB pour les ISO « Desktop ». VMImageEntry.applyMinimumResources(to:) (VirtualMachineWizard.swift) applique ce plancher via max(...) chaque fois qu’une image est sélectionnée ou que la source d’image change vers .iso/.qcow2 — il ne fait jamais redescendre une valeur que l’utilisateur a déjà augmentée au-delà du minimum.
Pour ajouter ou modifier une entrée, il suffit d’éditer VMImages.json — aucune modification Swift n’est nécessaire. Tests/CakerTests/VMImageCatalogURLTests.swift envoie une requête HEAD à chaque URL ISO/cloud des deux architectures (limitée à 8 requêtes concurrentes) afin que les liens obsolètes soient détectés par swift test plutôt que de casser silencieusement l’assistant ; des tests dédiés vérifient aussi que Fedora 41 Workstation reste absent du nœud arm64, et que chaque entrée respecte la convention minCPU/minMemoryMiB ci-dessus.
Sources de chargement
VMImageCatalog.shared résout le catalogue dans cet ordre, à la première utilisation :
<CAKE_HOME>/VMImages.json, si présent et valide — un fichier déposé à la main (pour personnaliser ou figer la liste) ou déjà mis en cache par un rafraîchissement GitHub précédent. Un fichier invalide à cet endroit est simplement ignoré (repli sur l’étape suivante) plutôt que de faire planter l’application, puisqu’il s’agit d’un état fourni par l’utilisateur et non d’un invariant de packaging.
- La ressource embarquée
VMImages.json, avec la même bascule Bundle.module/cible-native déjà utilisée par PackerLiteTemplateResolver pour les autres ressources embarquées de CakedLib : Bundle.module pour les builds swift build/swift test, repli sur une recherche Bundle(for:) + .bundle pour Caker.xcodeproj/CakerAppStore.xcodeproj, qui hébergent CakedLib comme cible native sans accesseur Bundle.module généré. Tout nouveau fichier ajouté sous Sources/cakedlib/Resources/ doit donc aussi être ajouté manuellement aux deux fichiers .xcodeproj (référence de fichier + phases de build Resources des cibles CakedLib/Caker/caked.app, selon le cas) pour rester disponible dans les builds construits via Xcode.
Séparément, VMImageCatalog.refreshFromGitHub() télécharge la version courante de VMImages.json depuis la branche main sur GitHub, la met en cache dans <CAKE_HOME>/VMImages.json, et met à jour VMImageCatalog.shared en place. MainApp.init() déclenche cet appel en tâche de fond (best-effort, erreurs ignorées) au lancement de l’application — comme les vues de l’assistant relisent VMImageCatalog.shared à chaque rendu plutôt que de le mettre en cache dans un @State, une session déjà lancée profite du catalogue rafraîchi dès que le téléchargement aboutit, sans redémarrage.
Ceci vaut pour le mode .app. Connecté à un caked (mode service ou distant), l’assistant liste le catalogue de ce caked, obtenu par la RPC Aliases (la même que cakectl aliases, qui renvoie aussi l’URL et les ressources minimales de chaque entrée) à chaque ouverture : les listes proposent donc ce que l’hôte de ce caked peut construire (son architecture, son propre <CAKE_HOME>/VMImages.json). Si la RPC échoue ou si le caked est trop ancien pour renvoyer les URL, l’assistant garde son propre catalogue. De son côté, caked relit <CAKE_HOME>/VMImages.json dès que le fichier change (VMImageCatalog.reloadIfChanged()), si bien qu’un rafraîchissement GitHub fait par Caker.app est pris en compte sans redémarrer le service.
L’interface Web fait de même via GET /1.0/vm-images (une extension Caker de l’API REST, comme /1.0/remotes) : la fenêtre de création d’instance liste le catalogue du caked qui la sert. Tant que la réponse n’est pas arrivée, ou si l’endpoint n’existe pas (un caked plus ancien), elle utilise src/data/vmImages.ts, la copie que npm run sync-vm-images intègre au moment du build.
Bibliothèque de modèles compose
Sources/cakedlib/ComposeLibrary.swift charge la bibliothèque de modèles compose.yml comme VMImageCatalog charge VMImages.json, mais un modèle est un fichier : le dossier Sources/cakedlib/Resources/compose-library/ contient un <id>.yml par modèle et un index.json qui liste leurs ids. <CAKE_HOME>/compose-library/ (copie synchronisée, écrite par un sync : il contient alors index.json) a la priorité sur le dossier embarqué ; un modèle illisible y est ignoré sans écarter les autres. ComposeLibrary.refreshFromGitHub() (compose library sync, bouton « Synchroniser » de ComposeLibraryView) télécharge index.json puis chaque <id>.yml depuis la branche main ; tant que le dossier n’y est pas publié, la réponse 404 est signalée et la copie embarquée est utilisée. Une bibliothèque téléchargée est refusée en bloc si un modèle est invalide (ids valides et uniques, YAML qui se décode en ComposeFile, au moins un service) ; chaque id de l’index devient un nom de fichier, il est donc validé avant tout accès au disque.
Pour ajouter ou modifier un modèle, éditer Sources/cakedlib/Resources/compose-library/<id>.yml (un compose.yml dont les premières lignes sont des commentaires # library-id/name/category/summary/tags, retirés du texte que clone écrit), ajouter son id à index.json (c’est ce que le sync télécharge) et valider :
swift test --filter ComposeLibraryTests
Le test vérifie aussi que index.json liste exactement les fichiers du dossier.
ComposeLibraryTests fait passer chaque service de chaque modèle par toBuildOptions, ce qui détecte un YAML invalide ou un champ que compose up ne sait pas honorer. Un modèle désigne ses pairs par leur nom DNS compose (<service>.<projet>.compose.internal) : le projet doit être le sien, ce que le test vérifie aussi (clone --name renomme ces références).
Un modèle qui sert quelque chose doit rediriger ses ports vers l’hôte avec ports: (et sockets: pour un socket unix, comme le socket Docker de docker-host) : sans cela le service n’est joignable que depuis le réseau des VM. Les redirections de docker-host, k3s et ubuntu-dev sont verrouillées par ComposeLibraryTests.
Options de compilation
Variables d’environnement lues par Package.swift :
| Variable |
Effet |
APPSTORE=1 |
Build App Store : sandbox, sans Sparkle, sans serveur DHCP. |
USE_DHCP_SERVER=1 |
Inclut le serveur DHCP par réseau (désactivé par défaut ; les scripts de build signé debug et release l’activent). |
USE_AUTHORIZATION_HELPER=1 |
Compile et embarque l’assistant privilégié AuthorizationHelper (désactivé par défaut ; build signé debug et release uniquement). caked authorization enable ou disable l’enregistre (via Caker.app). Le serveur DHCP se désactive dans Réglages > Avancé (local.use-dhcp-server). |
BECOME_PARANOID=1 |
Définit le drapeau BECOME_PARANOID : règle sudo épinglée par SHA-256, caked et son bundle appartenant à root, assistant qui n’exécute qu’un caked de root, répertoire du PID réseau épinglé par descripteur contre les remplacements par lien symbolique. Absent par défaut. |
BECOME_PARANOID=1 pilote aussi .ci/create-pkg.sh : le postinstall du paquet épingle alors l’empreinte et la rafraîchit pour chaque utilisateur. Pour un paquet strict, utilisez la même variable aux deux étapes :
BECOME_PARANOID=1 swift build
BECOME_PARANOID=1 .ci/create-pkg.sh
Les projets Xcode n’utilisent pas Package.swift : ajoutez BECOME_PARANOID à leurs conditions de compilation à la main. Voir Architecture.
Tests
Emplacements principaux des tests :
Tests/CakerTests/
Caker/CakerTests/
integration/tests/
Workflow de contribution
- Créez une branche depuis
main.
- Implémentez des modifications ciblées.
- Exécutez les tests pertinents et les vérifications de build.
- Ouvrez une pull request avec un contexte clair.
Guide du contributeur :
Interface Web
Caker inclut une interface Web basée sur React, située dans le répertoire webui/. Elle est construite avec Vite, TypeScript et Bootstrap 5.
Prérequis
Installer les dépendances
Mode développement
Démarrez le serveur de développement Vite avec un proxy vers un caked exécuté localement :
Le serveur de développement écoute sur http://localhost:5173. Les appels API vers /1.0 sont redirigés par défaut vers http://127.0.0.1:8080. Modifiez la cible avec la variable d’environnement VITE_API_TARGET :
VITE_API_TARGET=http://127.0.0.1:9090 npm run dev
Build de production
Le résultat est écrit dans webui/dist/. Passez ce répertoire à caked avec l’option --web-ui :
caked service --rest --web-ui /path/to/caker/webui/dist
L’interface est alors servie sur http://<host>:<port>/ui.
Déploiement depuis une archive zip
--web-ui accepte également une archive .zip. caked l’extrait automatiquement au démarrage dans un répertoire temporaire :
cd webui && npm run build && zip -r ../webui-dist.zip dist/
caked service --rest --web-ui /path/to/webui-dist.zip
Si l’archive contient un unique répertoire de premier niveau (par ex. dist/), caked y descend automatiquement pour résoudre correctement le fichier index.
Structure du projet
webui/
index.html # Point d'entrée HTML
vite.config.ts # Configuration Vite (base /ui/, proxy /1.0)
tsconfig.json # Configuration TypeScript
src/
main.tsx # Point d'entrée React (CSS/JS Bootstrap importés ici)
App.tsx # HashRouter + routes
types/lxd.ts # Interfaces TypeScript correspondant à l'API REST
api/ # Modules du client API axios
components/ # Composants UI partagés (Layout, StatusBadge, …)
pages/ # Un composant par page
dist/ # Sortie de production (après npm run build)
Scripts utiles
Scripts/build-signed-debug.sh - Compile la version debug avec signature
Scripts/build-signed-release.sh - Compile la version release avec signature
Scripts/build-signed-snapshot.sh - Compile le package et le dmg avec signature
Scripts/act.sh - Test local des GitHub Actions
Scripts/run-signed-caked.sh - Exécute le démon signé
Scripts/run-signed-cakectl.sh - Exécute la CLI signée
Environnement de développement
Prérequis
- macOS (requis pour le framework Virtualization)
- Xcode avec toolchain Swift
- Certificats de signature et profils de provisioning
- Optionnel : GitHub CLI pour la gestion des pull requests
Démarrage
- Clonez le dépôt
- Exécutez
./Scripts/build-signed-debug.sh pour compiler
- Utilisez les scripts d’exécution pour tester les composants
- Exécutez les tests via Xcode ou en ligne de commande
Style de code
- Suivez les conventions Swift
- Utilisez des noms clairs et descriptifs
- Documentez les API publiques
- Incluez des tests pour les nouvelles fonctionnalités
Development
Code organization
Sources/cakectl/Commands/ – CLI command handlers
Sources/caked/Commands/ and Sources/caked/Handlers/ – daemon command and runtime handlers
Sources/cakedlib/ – shared utilities, config, and core abstractions
VM image catalog (Caker.app wizard, and build/launch --alias)
Caker.app’s VM creation wizard (Sources/caker/Views/VirtualMachineWizard.swift) offers preconfigured ISO, IPSW, and cloud (qcow2) image choices. That list is no longer hardcoded in Swift enums — it’s driven by a bundled JSON resource, decoded at runtime. The catalog now lives in CakedLib (it used to be caker-only), so caked build/cakectl build (and launch) can also resolve a catalog id via a single --alias <id> option (--alias macos12, --alias ubuntu2604, …) — run caked aliases/cakectl aliases to list every known id. See Sources/Grpc/options/BuildOptions.swift and CLAUDE.md’s “VM image catalog, --alias, and the aliases command” section for that half of the picture.
Sources/cakedlib/Resources/VMImages.json – the catalog, keyed by architecture at the top level: {"arm64": {...}, "amd64": {...}}, each node holding three arrays — iso, ipsw, cloud — of already-resolved {id, label, url} entries (no {arch} template to substitute at runtime). An image that doesn’t exist for a given architecture is simply absent from that array — e.g. the Fedora 41 Workstation ISO, never published for aarch64, only appears under amd64.
Sources/cakedlib/VMImageCatalog.swift – VMImageCatalog/VMImageArchCatalog/VMImageEntry (all public), the matching Codable model. VMImageCatalog.current (and the availableISOImages/availableIPSWImages/availableCloudImages shortcuts) picks the arm64 or amd64 node based on the running architecture via #if arch(arm64).
iso and cloud entries also carry optional minCPU/minMemoryMiB fields, absent from ipsw entries (macOS installs apply their own fixed floor independently of this catalog). Current convention: 2 CPU / 2048 MiB for “Server” ISOs and cloud images (headless by nature), 4 CPU / 4096 MiB for “Desktop” ISOs. VMImageEntry.applyMinimumResources(to:) (VirtualMachineWizard.swift) applies this floor via max(...) whenever an image is selected or the image source switches to .iso/.qcow2 — it never lowers a value the user already raised above the minimum.
To add or update an entry, edit VMImages.json — no Swift changes needed. Tests/CakerTests/VMImageCatalogURLTests.swift HEAD-requests every ISO/cloud URL from both architectures (bounded to 8 concurrent requests) so stale links get caught by swift test instead of silently breaking the wizard; dedicated tests also assert Fedora 41 Workstation stays absent from the arm64 node, and that every entry follows the minCPU/minMemoryMiB convention above.
Loading sources
VMImageCatalog.shared resolves the catalog in this order, on first use:
<CAKE_HOME>/VMImages.json, if present and valid — either dropped there by hand (to pin or customize the list) or already cached by a previous GitHub refresh. An invalid file here is skipped (falls through to the next step) rather than crashing the app, since unlike the bundled resource it’s user-supplied state, not a packaging invariant.
- The bundled
VMImages.json resource, following the same Bundle.module/native-target fallback already used by PackerLiteTemplateResolver for CakedLib’s other bundled resources: Bundle.module for swift build/swift test builds, falling back to a Bundle(for:)-plus-.bundle-lookup dance for Caker.xcodeproj/CakerAppStore.xcodeproj, which mirror CakedLib as a native Xcode target with no generated Bundle.module accessor. Any new file added under Sources/cakedlib/Resources/ therefore also needs to be added by hand to both .xcodeproj files (file reference + the CakedLib/Caker/caked.app targets’ Resources build phases, as applicable) to stay available in Xcode-built binaries.
Separately, VMImageCatalog.refreshFromGitHub() downloads the current VMImages.json from the main branch on GitHub, caches it to <CAKE_HOME>/VMImages.json, and updates VMImageCatalog.shared in place. MainApp.init() fires this in a background task (best-effort, errors ignored) at app launch — since the wizard’s views re-read VMImageCatalog.shared on every render rather than caching it in @State, an already-running session picks up the refreshed catalog as soon as the download completes, no restart needed.
That holds in .app mode. Connected to a caked (service or remote mode), the wizard lists that caked’s catalog instead, fetched with the Aliases RPC (the one behind cakectl aliases, which also returns each entry’s URL and minimum resources) every time the wizard opens, so the pickers offer what that caked’s host can build (its architecture, its own <CAKE_HOME>/VMImages.json). If the RPC fails, or the caked is too old to send URLs, the wizard keeps its own catalog. On its side, caked re-reads <CAKE_HOME>/VMImages.json whenever the file changes (VMImageCatalog.reloadIfChanged()), so a GitHub refresh done by Caker.app is picked up without restarting the service.
The web UI does the same through GET /1.0/vm-images (a Caker extension of the REST API, like /1.0/remotes): the create-instance dialog lists the catalog of the caked serving it. Until the reply arrives, or when the endpoint is missing (an older caked), it uses src/data/vmImages.ts, the copy npm run sync-vm-images bakes in at build time.
Compose template library
Sources/cakedlib/ComposeLibrary.swift loads the library of compose.yml templates like VMImageCatalog loads VMImages.json, except that a template is a file: the Sources/cakedlib/Resources/compose-library/ folder holds one <id>.yml per template and an index.json listing their ids. <CAKE_HOME>/compose-library/ (the synced copy, written by a sync: it then holds index.json) takes precedence over the bundled folder; a template that can’t be read there is skipped without discarding the others. ComposeLibrary.refreshFromGitHub() (compose library sync, the “Sync” button of ComposeLibraryView) downloads index.json and then each <id>.yml from the main branch; until the folder is published there, the 404 is reported and the bundled copy is used. A downloaded library is refused as a whole when one template is invalid (valid and unique ids, YAML that decodes to a ComposeFile, at least one service); every id of the index becomes a file name, so it is validated before anything touches the disk.
To add or change a template, edit Sources/cakedlib/Resources/compose-library/<id>.yml (a compose.yml whose first lines are # library-id/name/category/summary/tags comments, removed from the text clone writes), add its id to index.json (it is what sync downloads) and check it:
swift test --filter ComposeLibraryTests
The test also checks that index.json lists exactly the files of the folder.
ComposeLibraryTests runs every service of every template through toBuildOptions, which catches invalid YAML or a field compose up can’t honour. A template names its peers by their compose DNS name (<service>.<project>.compose.internal): the project must be its own, which the test also checks (clone --name renames those references).
A template that serves something must forward its ports to the host with ports: (and sockets: for a unix socket, like docker-host’s Docker socket): without it the service is only reachable from the VM network. The forwards of docker-host, k3s and ubuntu-dev are pinned by ComposeLibraryTests.
Build options
Environment variables read by Package.swift:
| Variable |
Effect |
APPSTORE=1 |
App Store build: sandboxed, no Sparkle, no DHCP server. |
USE_DHCP_SERVER=1 |
Includes the per-network DHCP server (off by default; the debug and release signed-build scripts turn it on). |
USE_AUTHORIZATION_HELPER=1 |
Compiles and ships the privileged AuthorizationHelper (off by default; signed debug and release builds only). caked authorization enable or disable registers it (through Caker.app). The DHCP server can be turned off in Settings > Advanced (local.use-dhcp-server). |
BECOME_PARANOID=1 |
Defines the BECOME_PARANOID flag: sudo rule pinned by SHA-256, caked and its bundle owned by root, a helper that only runs a root-owned caked, network PID directory pinned by descriptor against symlink swaps. Off by default. |
BECOME_PARANOID=1 also drives .ci/create-pkg.sh: the package’s postinstall then pins the digest and refreshes it for every user. For a strict package, use the same variable for both steps:
BECOME_PARANOID=1 swift build
BECOME_PARANOID=1 .ci/create-pkg.sh
The Xcode projects do not use Package.swift: add BECOME_PARANOID to their compilation conditions by hand. See Architecture.
Tests
Primary test locations:
Tests/CakerTests/
Caker/CakerTests/
integration/tests/
Contribution workflow
- Create a branch from
main.
- Implement focused changes.
- Run relevant tests and build checks.
- Open a pull request with clear context.
Contributor guide:
Web UI
Caker includes a React-based web UI located in the webui/ directory. It is built with Vite, TypeScript, and Bootstrap 5.
Requirements
Install dependencies
Development mode
Start the Vite dev server with a proxy to a locally running caked:
The dev server listens on http://localhost:5173. API calls to /1.0 are proxied to http://127.0.0.1:8080 by default. Override the target with the VITE_API_TARGET environment variable:
VITE_API_TARGET=http://127.0.0.1:9090 npm run dev
Production build
The output is written to webui/dist/. Pass this directory to caked with the --web-ui flag:
caked service --rest --web-ui /path/to/caker/webui/dist
The UI is then served at http://<host>:<port>/ui.
Deploying from a zip archive
--web-ui also accepts a .zip archive. caked extracts it automatically at startup to a temporary directory:
cd webui && npm run build && zip -r ../webui-dist.zip dist/
caked service --rest --web-ui /path/to/webui-dist.zip
If the archive contains a single top-level directory (e.g. dist/), caked descends into it automatically so the index file is resolved correctly.
Project structure
webui/
index.html # HTML entry point
vite.config.ts # Vite configuration (base /ui/, proxy /1.0)
tsconfig.json # TypeScript configuration
src/
main.tsx # React entry point (Bootstrap CSS/JS imported here)
App.tsx # HashRouter + routes
types/lxd.ts # TypeScript interfaces matching the REST API
api/ # axios API client modules
components/ # Shared UI components (Layout, StatusBadge, …)
pages/ # One component per page
dist/ # Production output (after npm run build)
Useful scripts
Scripts/build-signed-debug.sh - Build debug version with signing
Scripts/build-signed-release.sh - Build release version with signing
Scripts/build-signed-snapshot.sh - Build package and dmg with signing
Scripts/act.sh - Local GitHub Actions testing
Scripts/run-signed-caked.sh - Run signed daemon
Scripts/run-signed-cakectl.sh - Run signed CLI
Development Environment
Requirements
- macOS (required for Virtualization framework)
- Xcode with Swift toolchain
- Signing certificates and provisioning profiles
- Optional: GitHub CLI for pull request management
Getting Started
- Clone the repository
- Run
./Scripts/build-signed-debug.sh to build
- Use the run scripts to test components
- Run tests via Xcode or command line
Code Style
- Follow Swift conventions
- Use clear, descriptive naming
- Add documentation for public APIs
- Include tests for new functionality