crosspack 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb2e2fb91b4f2215649e739ff6ec7128a11e06abe8d776f870d686261439a974
-  data.tar.gz: 3b17f1325d46d5147a0d87fee2d62ee2cb021f4a11c4ab16cf54a94562d843ad
+  metadata.gz: 527794ea0ef513791363042fcace5c4a973a859e74c4300dedeec931268b00fc
+  data.tar.gz: 5bbad1503be58d2190c7f042fdd29ca8271d1d107826d8653589ef17c8587a9d
 SHA512:
-  metadata.gz: 19cfe0db0863bff0e3b69d39ccefd0066ae99a85586ae8cabe19951897f0852b70966cc39372740a9a7e779ad36c81827797094befe8e292c7f420d1a17a0578
-  data.tar.gz: 9b220eff4186f4f1f88875d0b802c0d7a76f1b5d394e0ec828706a2e56d71676f809c1726de82e39f950ad323056b73104c9022c9fa181f554830817748dd612
+  metadata.gz: 465b113f78d7e0dce817e0a65c122437998938dbb66cd438c63762289dcc1a9c4a3ccf4df9a7639f73ec983aa20f31a94c34d357118efbdfdfb1415b9828fad1
+  data.tar.gz: 021f427e66d2a9c58eb02dde0907cfb7bf5f8c89a081018b2839df819a7c478dc4952f7fc9ba7246c4b2030488065b644401edfd32282ca987809019675c0670

data/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-09-13
+
+### Breaking
+- The separate `crossbuild` executable is gone: one command, one staged
+  pipeline — `crosspack deps <target>` → `crosspack build <target>` →
+  `crosspack pack <target>`. The former crossbuild commands moved under
+  `crosspack` (validate/matrix/version gained build.yaml coverage; the gem
+  now installs only the `crosspack` binary).
+- build.yaml `deps:` schema: host rules are now mappings with per-system
+  `verify` and `install` commands instead of a global `check:` plus a
+  bare command string. The 0.3.0 schema was never released outside the
+  local gem build, so no migration path is provided.
+- `crosspack pack <target>` takes the target as a positional argument
+  (the old `--target` flag is gone) and `--version` is now optional: it
+  defaults to the version stamped by the build stage.
+
+### Added
+- Stage pipeline with gating: `crosspack build <target>` resolves the
+  matrix entry distributing to that target, runs the deps stage first,
+  and fans artifacts out into that target's builds/ directory only;
+  `crosspack pack <target>` refuses to run before the build stage
+  ("Build stage not done for target ... — Run: crosspack build <target>").
+- The build stage stamps `.crosspack-build` (version) into every
+  `builds/<target>/` directory; `crosspack pack` reads it as the default
+  package version.
+- deps.yaml schema versioning: an optional top-level `version:` (default
+  1). A deps.yaml declaring a newer schema than this crosspack is
+  rejected at load time with an upgrade hint; the key is reserved and no
+  longer parsed as a canonical dependency name.
+- deps: rules may be verify-only (no install command) — presence is
+  checked, and a missing dependency reports which `install:` to add.
+
+## [0.3.0] - 2026-09-13
+
+### Added
+- build.yaml `deps:` section: build dependencies with per-host install
+  commands (e.g. `ubuntu: sudo apt-get install -y imagemagick`, `windows:
+  winget install ...`, or any project script). Host selectors resolve in
+  order: distro id from `/etc/os-release`, `ID_LIKE` tokens, os, `"*"`.
+- `crossbuild deps` command: doctor + install of the deps: dependencies;
+  `--check` reports presence only and exits 1 when something is missing.
+- `crossbuild build` now verifies/installs deps: dependencies before the
+  matrix entries; `--no-deps` skips the pass.
+- `crossbuild matrix` lists how each deps: entry resolves on this host.
+
+## [0.2.1] - 2026-09-11
+
+### Fixed
+- WiX builder: `wix build` is now invoked with `-arch <arch>` as separate
+  argv entries — the previous single `"-arch x64"` argument could never parse.
+- WiX builder: a bare `dotnet` on PATH is no longer mistaken for the WiX
+  toolset (`dotnet build` cannot build an MSI); only a real `wix` command
+  triggers the real MSI build, otherwise the `.wxs` + `BUILD-MSI.txt`
+  fallback is emitted.
+- WiX builder: manifest values (name, maintainer, summary) are XML-escaped
+  in the generated `.wxs`; a maintainer like `Name <email>` previously
+  produced invalid XML no WiX build could parse.
+
 ## [0.2.0] - 2026-09-08
 
 ### Added

data/README.md

@@ -1,32 +1,49 @@
 # crosspack
 
 Cross-platform build **and** pack toolchain for Wails-style desktop apps,
-shipped as one gem with two cooperating commands:
+shipped as one gem with one command and a staged pipeline:
 
-- **`crossbuild`** — runs the build steps of a project from a small
-  `build.yaml` matrix and fans the produced artifacts out into the
-  per-target tree `builds/<family>[/<version>]/<arch>/`.
-- **`crosspack`** — turns that compiled tree into native packages
-  (deb / rpm / PKGBUILD / WiX / app bundle) for any target
-  distro × version × arch, driven by two small manifests.
+```
+crosspack deps <target>     # verify/install the build host's dependencies
+crosspack build <target>    # compile the target's matrix entry into builds/
+crosspack pack <target>     # package builds/<target> as a native package
+```
 
-The two commands share the same target vocabulary (`Crosspack::Target`),
-so the build tree and the pack tree never drift apart. Build and pack
-stay cleanly separated: `crossbuild` never packages, `crosspack` never
-compiles — feed the output of one straight into the other:
+Every stage is keyed by the same target vocabulary — `debian-12`,
+`ubuntu-24.04`, `fedora-41`, `arch`, `macos`, `windows-11.0` — and gated by
+the previous one: `build` refuses to start before the deps stage passes, and
+`pack` refuses to run before `build` filled `builds/<target>/`. The build
+stage also stamps the version into the tree, so `pack` normally needs no
+`--version`:
 
 ```
-crossbuild build                          # builds/ tree
-crosspack pack --target debian-12 --version 2026.08.31-33837
+crosspack deps ubuntu-24.04
+crosspack build ubuntu-24.04
+crosspack pack ubuntu-24.04
 ```
 
-## crossbuild: build.yaml
+## build.yaml — what and where to build
 
 ```yaml
 name: myapp
 version: calver            # calver | git-tag | env:VAR | any literal string
 output: builds             # default builds; mirrors package.yaml `sources`
 
+deps:                      # build dependencies, per-host verify/install
+  imagemagick:
+    hosts:                 # first selector matching this host wins
+      ubuntu:
+        verify: dpkg -s imagemagick
+        install: sudo apt-get install -y imagemagick
+      darwin:
+        verify: magick -version
+        install: brew install imagemagick
+      windows:
+        verify: where magick
+        install: winget install -e --id ImageMagick.ImageMagick
+      "*":                 # any command — package manager or a project script
+        install: ./scripts/install-imagemagick.sh
+
 matrix:
   - build: linux/amd64     # os/arch this entry builds on (arch may be "any")
     env:                   # extra env for the steps of this entry
@@ -63,6 +80,19 @@ builds/ubuntu/24.04/amd64/myapp -> build/bin/myapp   (symlink)
 builds/windows/11.0/x86_64/myapp.exe
 ```
 
+### Build dependencies (deps:)
+
+`deps:` is the host axis to `deps.yaml`'s target axis: deps.yaml declares
+what a *package* needs at runtime; `deps:` declares what the *build host*
+must have. Checks differ per system, so every host rule carries its own
+commands: `verify` (presence probe; exit 0 = present; without it the name is
+looked up in PATH) and `install` (how to install it; may be omitted for
+verify-only rules). Selectors are tried in order: distro id from
+`/etc/os-release` (`ubuntu`), then `ID_LIKE` tokens (`debian`), then the os
+(`linux`, `darwin`, `windows`), then `"*"`. The deps stage runs verify →
+install → re-verify for every dependency; a dependency that is still missing
+fails the stage. Commands support the `{{name}}`/`{{os}}`/... placeholders.
+
 ### Version schemes
 
 | scheme        | value                                                      |
@@ -72,22 +102,9 @@ builds/windows/11.0/x86_64/myapp.exe
 | `env:VAR`     | taken from `VAR`; build fails loudly when unset            |
 | other string  | used verbatim, e.g. `version: 1.2.3`                       |
 
-### crossbuild CLI
-
-```
-crossbuild validate                       # build.yaml against the schema
-crossbuild matrix                         # entries × host buildability table
-crossbuild version                        # computed version
-crossbuild build [--target linux/amd64]   # all host-buildable entries, or one
-crossbuild targets                        # what is in builds/ ready to pack
-```
-
-`build` refuses invalid manifests with path-pointing errors, runs only the
-entries whose `build:` platform matches the host, then distributes.
+## package.yaml + deps.yaml — what and how to pack
 
-## crosspack: two manifests
-
-**`package.yaml`** — what and how to pack:
+**`package.yaml`**:
 
 ```yaml
 name: myapp
@@ -99,9 +116,9 @@ description: |-
 license: Proprietary       # optional, default Proprietary
 section: utils             # optional, deb only
 
-sources: builds             # compiled artifacts tree written by crossbuild:
-                            # builds/<family>/<version>/<arch>/ — pack without
-                            # a matching build directory fails honestly
+sources: builds             # compiled artifacts tree written by the build
+                            # stage: builds/<family>/<version>/<arch>/ —
+                            # pack without a matching build dir fails honestly
 prefix: usr/local          # install prefix inside the package
 lib_dir: lib/myapp       # optional, default lib/<name>
 
@@ -124,9 +141,13 @@ icon: build/appicon.png    # optional, -> <prefix>/share/pixmaps/<name>.png
 ```
 
 **`deps.yaml`** — canonical dependency names resolved to concrete packages
-per distro family/version (see the file itself for the full schema):
+per distro family/version. An optional top-level `version:` declares the
+schema version; a deps.yaml written for a newer crosspack is rejected with
+an upgrade hint:
 
 ```yaml
+version: 1                  # optional, currently 1
+
 webkit2gtk:
   targets:
     debian:
@@ -136,17 +157,24 @@ webkit2gtk:
     windows: system    # preinstalled (WebView2)
 ```
 
-Both files are validated against embedded schemas with actionable,
-path-pointing error messages; every builder refuses to run on an invalid
+All three files are validated against embedded schemas with actionable,
+path-pointing error messages; every stage refuses to run on an invalid
 manifest.
 
 ## CLI
 
 ```
-crosspack validate                       # both package.yaml and deps.yaml
-crosspack resolve --target debian-12     # Depends line for the target
-crosspack matrix                         # dependency x target table
-crosspack pack --target debian-12 --version 2026.08.31-1234 [--root .]
+# staged pipeline
+crosspack deps <target> [--check]        # verify/install build deps (--check: report only)
+crosspack build <target>|--all [--no-deps] [--version X]
+crosspack pack <target> [--version X]    # version defaults to the build stamp
+
+# inspection
+crosspack validate                       # package.yaml, deps.yaml and build.yaml
+crosspack resolve <target>               # Depends line for the target
+crosspack matrix                         # deps x target + build matrix tables
+crosspack version                        # computed build version
+crosspack targets                        # what is in builds/ ready to pack
 ```
 
 `pack` picks the builder from the target and writes to
@@ -164,20 +192,21 @@ crosspacks/arch/x86_64/PKGBUILD
 require 'crosspack'   # pulls in Crossbuild too
 
 Crossbuild.build('build.yaml', root: Dir.pwd)            # all host entries
-Crossbuild.build('build.yaml', entry_id: 'windows')      # one entry explicitly
+Crossbuild.build('build.yaml', target: 'ubuntu-24.04')   # the stages' build, library-level
 
 Crosspack.pack(
   manifest: 'package.yaml', deps: 'deps.yaml',
   target: Crosspack::Target.parse('debian-12', arch: 'amd64'),
-  version: '2026.08.31-1234',
+  version: nil,        # nil -> the version stamped by the build stage
   root: Dir.pwd, output_base: 'crosspacks'
 )
 ```
 
 Lower-level pieces are public too: on the build side `Crossbuild::
 BuildManifest`, `VersionScheme`, `Runner`, `Distributor`, `Matrix`,
-`Builder`, `Platform`; on the pack side `Crosspack::PackageManifest`,
-`Manifest`, `Resolver`, `Matrix`, `Target`, `Builders::*`.
+`Builder`, `DepInstaller`, `Platform`; on the pack side `Crosspack::
+PackageManifest`, `Manifest`, `Resolver`, `Matrix`, `Target`, `Builds`,
+`Builders::*`.
 
 Deb needs `dpkg-deb` (present on any Debian/Ubuntu), rpm needs
 `rpmbuild` (`sudo apt install rpm`), PKGBUILD generation needs nothing.

data/exe/crosspack

@@ -5,8 +5,10 @@ require 'optparse'
 
 begin
   require 'crosspack'
+  require 'crossbuild'
 rescue LoadError
   require_relative '../lib/crosspack'
+  require_relative '../lib/crossbuild'
 end
 
 def abort_with(message)
@@ -14,21 +16,28 @@ def abort_with(message)
   exit 1
 end
 
-options = { file: 'deps.yaml', package: 'package.yaml', arch: 'amd64', format: nil,
-            version: nil, root: Dir.pwd, output_base: 'crosspacks' }
+options = { file: 'deps.yaml', package: 'package.yaml', build: 'build.yaml', arch: 'amd64',
+            format: nil, version: nil, root: Dir.pwd, output_base: nil,
+            check_only: false, no_deps: false, all: false }
 parser = OptionParser.new do |opts|
-  opts.banner = "crosspack #{Crosspack::VERSION} — native package packer (deb/rpm/PKGBUILD/MSI/app)\n" \
+  opts.banner = "crosspack #{Crosspack::VERSION} — staged pipeline: deps → build → pack\n" \
                 "Usage: crosspack <command> [options]\n" \
-                'Commands: validate, resolve, matrix, pack, targets'
+                "Stages:   deps <target> [--check]      verify/install build deps for the target's host\n" \
+                "          build <target>|--all          compile the target's matrix entry into builds/\n" \
+                "          pack <target> [--version X]   package builds/<target> (version from the build stamp)\n" \
+                'Commands: validate, resolve, matrix, version, targets'
 
   opts.on('-f', '--file PATH', 'path to deps.yaml (default: ./deps.yaml)') { |v| options[:file] = v }
   opts.on('--package PATH', 'path to package.yaml (default: ./package.yaml)') { |v| options[:package] = v }
-  opts.on('--target TARGET', 'target: debian-12, ubuntu-24.04, fedora-41, arch, macos, windows') { |v| options[:target] = v }
+  opts.on('--build PATH', 'path to build.yaml (default: ./build.yaml)') { |v| options[:build] = v }
   opts.on('--arch ARCH', 'architecture: amd64/x86_64, arm64/aarch64 (default: amd64)') { |v| options[:arch] = v }
   opts.on('--format FORMAT', 'output format for resolve: deb, rpm, pkgbuild (default: derived from the target)') { |v| options[:format] = v.to_sym }
-  opts.on('--version VERSION', 'package version for pack (required for pack)') { |v| options[:version] = v }
+  opts.on('--version VERSION', 'override the version for build/pack') { |v| options[:version] = v }
   opts.on('--root PATH', 'project root for relative paths (default: .)') { |v| options[:root] = v }
-  opts.on('--output-base DIR', 'output directory (default: ./crosspacks)') { |v| options[:output_base] = v }
+  opts.on('--output-base DIR', 'output directory (build stage: the manifest output, default builds; pack: default ./crosspacks)') { |v| options[:output_base] = v }
+  opts.on('--check', 'with `deps`: only report presence, never install (exit 1 if missing)') { options[:check_only] = true }
+  opts.on('--no-deps', 'with `build`: skip the deps stage') { options[:no_deps] = true }
+  opts.on('--all', 'with `build`: every host-buildable matrix entry (default target selection off)') { options[:all] = true }
   opts.on('-h', '--help', 'show help') do
     puts opts
     exit
@@ -43,63 +52,142 @@ end
 command = ARGV.shift
 abort_with 'No command given. See: crosspack --help' if command.nil?
 
-# Positional file path: crosspack validate path/to/deps.yaml
-options[:file] = ARGV.shift if ARGV.first && !ARGV.first.start_with?('-')
+# Positional argument: a target for the stage commands (deps/build/pack,
+# resolve), a deps.yaml path for validate.
+positional = ARGV.shift if ARGV.first && !ARGV.first.start_with?('-')
 
-begin
-  manifest = Crosspack::Manifest.load(options[:file])
-rescue Crosspack::InvalidManifestError => e
-  abort_with e.message
+build_path = File.expand_path(options[:build], options[:root])
+build_manifest = if File.file?(build_path)
+                   begin
+                     Crossbuild::BuildManifest.load(build_path)
+                   rescue Crossbuild::InvalidManifestError => e
+                     abort_with e.message
+                   end
+                 end
+
+# The matrix entry that builds `target` — the deps/build stages operate on
+# its host platform.
+def entry_for_target!(manifest, target, host_os, host_arch)
+  entry = manifest.entry_for_target(target)
+  host = "#{host_os}/#{Crossbuild::Platform.display_arch(host_arch)}"
+  unless entry.buildable_on?(host_os, host_arch)
+    abort_with "The entry for #{target.inspect} (#{entry.id}) builds on #{entry.platform}, " \
+               "this host is #{host} — cross-compilation is not supported"
+  end
+
+  entry
 end
 
 case command
 when 'validate'
+  if positional
+    options[:file] = positional
+  elsif build_manifest.nil?
+    warn "note: #{options[:build]} not found — the deps/build stages need it (validate covered deps/package only)"
+  end
   begin
-    pkg = Crosspack::PackageManifest.load(options[:package])
+    pkg = Crosspack::PackageManifest.load(File.expand_path(options[:package], options[:root]))
+  rescue Crosspack::InvalidManifestError => e
+    abort_with e.message
+  end
+  begin
+    manifest = Crosspack::Manifest.load(File.expand_path(options[:file], options[:root]))
   rescue Crosspack::InvalidManifestError => e
     abort_with e.message
   end
   puts manifest.error_report
   puts pkg.error_report
-  exit(manifest.valid? && pkg.valid? ? 0 : 1)
+  puts build_manifest.error_report if build_manifest
+  ok = manifest.valid? && pkg.valid? && (build_manifest.nil? || build_manifest.valid?)
+  exit(ok ? 0 : 1)
 when 'matrix'
-  abort_with 'Schema is invalid — the matrix cannot be built. Run: crosspack validate' unless manifest.valid?
-  puts Crosspack::Matrix.new(manifest).render
-when 'resolve'
-  abort_with 'Specify a target: --target debian-12 (see crosspack --help)' unless options[:target]
   begin
-    target = Crosspack::Target.parse(options[:target], arch: options[:arch])
-  rescue Crosspack::Target::Error => e
-    abort_with "Invalid target #{options[:target].inspect}: #{e.message}"
+    manifest = Crosspack::Manifest.load(File.expand_path(options[:file], options[:root]))
+  rescue Crosspack::InvalidManifestError => e
+    abort_with e.message
+  end
+  abort_with 'deps.yaml schema is invalid — run: crosspack validate' unless manifest.valid?
+  puts Crosspack::Matrix.new(manifest).render
+  if build_manifest
+    puts "\n#{Crossbuild::Matrix.new(build_manifest).render}"
+  else
+    warn "\nnote: #{options[:build]} not found — build matrix not shown"
   end
+when 'resolve'
+  target_str = positional
+  abort_with 'Specify a target: crosspack resolve debian-12 (see crosspack --help)' unless target_str
   begin
+    manifest = Crosspack::Manifest.load(File.expand_path(options[:file], options[:root]))
+    target = Crosspack::Target.parse(target_str, arch: options[:arch])
     resolver = Crosspack::Resolver.new(manifest)
     format = options[:format] || target.format
     result = resolver.depends(target, format: format)
+    puts "# #{target} (#{format})"
     if result.is_a?(Array)
-      puts "# #{target} (#{format})"
       result.each { |d| puts d }
     else
-      puts "# #{target} (#{format})"
       puts "Depends: #{result}"
     end
-  rescue Crosspack::ResolveError => e
-    abort_with "Failed to resolve dependencies for #{target}:\n  #{e.message}"
+  rescue Crosspack::Target::Error => e
+    abort_with "Invalid target #{target_str.inspect}: #{e.message}"
+  rescue Crosspack::InvalidManifestError, Crosspack::ResolveError => e
+    abort_with e.message
+  end
+when 'version'
+  abort_with "#{options[:build]} not found — crosspack version needs a build manifest" unless build_manifest
+  abort_with 'Schema is invalid. Run: crosspack validate' unless build_manifest.valid?
+  begin
+    puts Crossbuild::VersionScheme.new(build_manifest.version).compute(root: options[:root])
+  rescue Crossbuild::VersionScheme::Error => e
+    abort_with e.message
+  end
+when 'deps'
+  abort_with 'Specify a target: crosspack deps debian-12 (see crosspack --help)' unless positional
+  abort_with "#{options[:build]} not found — crosspack deps needs a build manifest" unless build_manifest
+  entry_for_target!(build_manifest, positional, Crossbuild::Platform.os, Crossbuild::Platform.arch)
+  installer = Crossbuild::DepInstaller.new(build_manifest, root: options[:root])
+  begin
+    if options[:check_only]
+      installer.check_all
+      puts "deps on this host:\n#{installer.report}"
+      exit(installer.statuses.any? { |s| !s.installed } ? 1 : 0)
+    end
+    installer.ensure_all
+  rescue Crossbuild::Error => e
+    abort_with e.message
+  end
+  puts "deps ready:\n#{installer.report}"
+when 'build'
+  abort_with "#{options[:build]} not found — crosspack build needs a build manifest" unless build_manifest
+  if options[:all]
+    target = nil
+  else
+    abort_with 'Specify a target: crosspack build ubuntu-24.04 (or --all for every host-buildable entry)' unless positional
+    target = positional
+  end
+  begin
+    result = Crossbuild::Builder.new(build_manifest, root: options[:root],
+                                      output_base: options[:output_base], version: options[:version],
+                                      deps: !options[:no_deps]).run(target: target)
+  rescue Crossbuild::Error, Crosspack::InvalidManifestError => e
+    abort_with e.message
   end
+  puts "\n📦 #{result.entries.size} entr#{result.entries.size == 1 ? 'y' : 'ies'} built, version #{result.version}"
+  puts 'Pack with: crosspack pack <target>'
 when 'pack'
-  abort_with 'Specify a target: --target debian-12 and a version: --version 1.0-1' unless options[:target] && options[:version]
+  abort_with 'Specify a target: crosspack pack debian-12' unless positional
   begin
-    target = Crosspack::Target.parse(options[:target], arch: options[:arch])
+    target = Crosspack::Target.parse(positional, arch: options[:arch])
     path = Crosspack.pack(
       manifest: options[:package],
       deps: options[:file],
       target: target,
       version: options[:version],
       root: options[:root],
-      output_base: options[:output_base]
+      output_base: options[:output_base] || 'crosspacks'
     )
   rescue Crosspack::Target::Error => e
-    abort_with "Invalid target #{options[:target].inspect}: #{e.message}"
+    abort_with "Invalid target #{positional.inspect}: #{e.message}"
   rescue Crosspack::InvalidManifestError, Crosspack::ResolveError, Crosspack::BuildError => e
     abort_with e.message
   end
@@ -115,5 +203,5 @@ when 'targets'
   root = sources ? File.expand_path(sources, options[:root]) : File.join(options[:root], 'builds')
   puts Crosspack::Builds.report(root)
 else
-  abort_with "Unknown command #{command.inspect}. Available: validate, resolve, matrix, pack, targets"
+  abort_with "Unknown command #{command.inspect}. Available: deps, build, pack, validate, resolve, matrix, version, targets"
 end

data/lib/crossbuild/build_manifest.rb

@@ -24,9 +24,10 @@ module Crossbuild
     ARCH_LIST = %w[amd64 x86_64 arm64 aarch64 any].freeze
     ARTIFACT_MODES = %w[symlink copy].freeze
     VERSION_SCHEMES = %w[calver git-tag].freeze
-    TOP_LEVEL_KEYS = %w[name version output matrix].freeze
+    TOP_LEVEL_KEYS = %w[name version output deps matrix].freeze
     ENTRY_KEYS = %w[id build env steps artifacts].freeze
     ARTIFACTS_KEYS = %w[from include to mode].freeze
+    DEP_KEYS = %w[hosts].freeze
     BUILD_RE = /\A(linux|darwin|windows)\/(#{ARCH_LIST.join('|')})\z/.freeze
     NAME_RE = /\A[a-z0-9][a-z0-9+._-]*\z/i.freeze
 
@@ -54,6 +55,22 @@ module Crossbuild
       end
     end
 
+    # A build dependency from the top-level deps: section. `hosts` maps a
+    # host selector (distro id from os-release, ID_LIKE token, os name or
+    # "*") to a rule with per-system commands:
+    #   verify:  presence probe (default: PATH lookup of the name)
+    #   install: how to install it (a verify-only rule may omit this)
+    class Dependency
+      RULE_KEYS = %w[verify install].freeze
+
+      attr_reader :name, :hosts
+
+      def initialize(name, hosts)
+        @name = name
+        @hosts = hosts
+      end
+    end
+
     # Where artifacts come from and which builds/ directories they fan out to.
     class Artifacts
       attr_reader :from, :include, :to, :mode
@@ -66,7 +83,7 @@ module Crossbuild
       end
     end
 
-    attr_reader :path, :name, :version, :output, :entries, :errors, :warnings
+    attr_reader :path, :name, :version, :output, :deps, :entries, :errors, :warnings
 
     def self.load(path)
       unless File.file?(path)
@@ -89,6 +106,7 @@ module Crossbuild
       @name = nil
       @version = nil
       @output = 'builds'
+      @deps = []
       @entries = []
       @errors = []
       @warnings = []
@@ -132,6 +150,26 @@ module Crossbuild
       @entries.find { |e| e.id == id }
     end
 
+    # The single matrix entry that distributes artifacts to the given target
+    # string (e.g. "ubuntu-24.04"). Raises Crossbuild::Error when no entry
+    # claims it or when several do (ambiguous).
+    def entry_for_target(raw)
+      matches = @entries.select { |e| e.artifacts&.to&.include?(raw) }
+      declared = @entries.filter_map { |e| e.artifacts&.to }.flatten.uniq
+      if matches.empty?
+        raise Error,
+              "no matrix entry distributes to target #{raw.inspect}; " \
+              "declared targets: #{declared.join(', ')}"
+      end
+      if matches.size > 1
+        raise Error,
+              "target #{raw.inspect} is distributed by several entries " \
+              "(#{matches.map(&:id).join(', ')}) — crosspack build <target> needs exactly one"
+      end
+
+      matches.first
+    end
+
     private
 
     def validate
@@ -144,6 +182,7 @@ module Crossbuild
       validate_name
       validate_version
       validate_output
+      validate_deps
       validate_matrix
     end
 
@@ -184,6 +223,76 @@ module Crossbuild
       end
     end
 
+    def validate_deps
+      deps = @raw['deps']
+      return if deps.nil?
+
+      unless deps.is_a?(Hash)
+        @errors << Issue.new(
+          'deps',
+          "must be a mapping of dependency name -> {check?, hosts}; expected:\n" \
+          "    deps:\n" \
+          "      imagemagick:\n" \
+          "        check: magick -version\n" \
+          "        hosts:\n" \
+          "          ubuntu: sudo apt-get install -y imagemagick"
+        )
+        return
+      end
+
+      deps.each { |name, body| validate_dep(name, body) }
+    end
+
+    def validate_dep(name, body)
+      path = "deps.#{name}"
+      if name !~ NAME_RE
+        @errors << Issue.new(path, "invalid dependency name #{name.inspect} (letters, digits, \"+\", \"_\", \"-\", \".\")")
+        return
+      end
+      unless body.is_a?(Hash)
+        @errors << Issue.new(path, 'must be a mapping with the key: hosts')
+        return
+      end
+      check_unknown_keys(path, body.keys, DEP_KEYS)
+
+      hosts = body['hosts']
+      unless hosts.is_a?(Hash) && !hosts.empty?
+        @errors << Issue.new(
+          "#{path}.hosts",
+          "must be a non-empty mapping of host selector -> {verify?, install?}; expected:\n" \
+          "    deps:\n" \
+          "      #{name}:\n" \
+          "        hosts:\n" \
+          "          ubuntu:\n" \
+          "            verify: dpkg -s #{name}\n" \
+          "            install: sudo apt-get install -y #{name}"
+        )
+        return
+      end
+      hosts.each { |selector, rule| validate_host_rule(name, selector, rule) }
+      return unless valid_dep?(name, body)
+
+      @deps << Dependency.new(name, hosts)
+    end
+
+    def validate_host_rule(name, selector, rule)
+      path = "deps.#{name}.hosts.#{selector}"
+      unless rule.is_a?(Hash) && !rule.empty?
+        @errors << Issue.new(path, "must be a mapping with verify and/or install commands, e.g. { install: sudo apt-get install -y #{name} }")
+        return
+      end
+      check_unknown_keys(path, rule.keys, Dependency::RULE_KEYS)
+      rule.each do |key, command|
+        unless command.is_a?(String) && !command.strip.empty?
+          @errors << Issue.new("#{path}.#{key}", 'must be a non-empty shell command')
+        end
+      end
+    end
+
+    def valid_dep?(name, body)
+      @errors.none? { |e| e.path.start_with?("deps.#{name}") }
+    end
+
     def validate_matrix
       matrix = @raw['matrix']
       unless matrix.is_a?(Array) && !matrix.empty?