crosspack 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b365ad4ba6ab874d40dec1ef153ab18104f329ee6ebb7a638a27267089eb7c43
-  data.tar.gz: c8b0eef099fecc0f97f7964560e093812fe50e7627bb5a092bfadcbf8322f668
+  metadata.gz: 527794ea0ef513791363042fcace5c4a973a859e74c4300dedeec931268b00fc
+  data.tar.gz: 5bbad1503be58d2190c7f042fdd29ca8271d1d107826d8653589ef17c8587a9d
 SHA512:
-  metadata.gz: 7c3d441c8d44206115a24ca0668843781b97631fdf3064a933d51709735911153861057bd0efa81b99406d4276b7c92b70993f12905b6e4ac6e9012b39db1f1d
-  data.tar.gz: d5bc914e071fd1be81b6cd1703b3120ce3d260a2a94188bba34b3b13f8e672f271d24c985642f43005fde6dbefc4dca542f67b74b213631eba071958e7e02a1f
+  metadata.gz: 465b113f78d7e0dce817e0a65c122437998938dbb66cd438c63762289dcc1a9c4a3ccf4df9a7639f73ec983aa20f31a94c34d357118efbdfdfb1415b9828fad1
+  data.tar.gz: 021f427e66d2a9c58eb02dde0907cfb7bf5f8c89a081018b2839df819a7c478dc4952f7fc9ba7246c4b2030488065b644401edfd32282ca987809019675c0670

data/CHANGELOG.md

@@ -5,6 +5,51 @@ 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

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?

data/lib/crossbuild/builder.rb

@@ -8,12 +8,13 @@ module Crossbuild
 
     attr_reader :manifest
 
-    def initialize(manifest, root: Dir.pwd, output_base: nil, version: nil,
+    def initialize(manifest, root: Dir.pwd, output_base: nil, version: nil, deps: true,
                    host_os: Platform.os, host_arch: Platform.arch)
       @manifest = manifest
       @root = root
       @output_base = output_base || manifest.output
       @version_override = version
+      @deps = deps
       @host_os = host_os
       @host_arch = host_arch
     end
@@ -21,20 +22,44 @@ module Crossbuild
     # entry_id: nil — every entry buildable on this host; otherwise the exact
     # entry id (which must exist, but may target another host — the user
     # asked for it explicitly).
-    def run(entry_id: nil)
+    # target: a raw target string (e.g. "ubuntu-24.04") — builds the single
+    # matrix entry distributing to it and fans artifacts out to that target
+    # only; the entry must be buildable on this host (no cross-compilation).
+    def run(entry_id: nil, target: nil)
       manifest.validate!
+      ensure_deps
       version = @version_override || VersionScheme.new(manifest.version).compute(root: @root)
-      entries = select_entries(entry_id)
+      entries = target ? entries_for_target(target) : select_entries(entry_id)
 
       entries.each do |entry|
         puts "\n==> #{manifest.name} [#{entry.id}] version #{version}"
-        run_entry(entry, version)
+        run_entry(entry, version, only: target)
       end
       Result.new(version: version, entries: entries)
     end
 
     private
 
+    # deps: false (--no-deps) skips the pre-build check/install pass.
+    def ensure_deps
+      return if !@deps || manifest.deps.empty?
+
+      puts '⧗ build deps'
+      DepInstaller.new(manifest, root: @root).ensure_all
+    end
+
+    def entries_for_target(raw)
+      entry = manifest.entry_for_target(raw)
+      host = "#{@host_os}/#{Platform.display_arch(@host_arch)}"
+      unless entry.buildable_on?(@host_os, @host_arch)
+        raise Error,
+              "the entry for #{raw.inspect} (#{entry.id}) builds on #{entry.platform}, " \
+              "this host is #{host} — cross-compilation is not supported"
+      end
+
+      [entry]
+    end
+
     def select_entries(entry_id)
       if entry_id
         entry = manifest.find_entry(entry_id)
@@ -50,7 +75,7 @@ module Crossbuild
       end
     end
 
-    def run_entry(entry, version)
+    def run_entry(entry, version, only: nil)
       arch = entry.arch == :any ? @host_arch : entry.arch
       vars = {
         name: manifest.name,
@@ -63,7 +88,8 @@ module Crossbuild
 
       Runner.new(root: @root, vars: vars, env: entry.env).run(entry.steps) unless entry.steps.empty?
 
-      dirs = Distributor.new(root: @root, output_base: @output_base).distribute(entry, host_arch: @host_arch)
+      dirs = Distributor.new(root: @root, output_base: @output_base)
+                       .distribute(entry, host_arch: @host_arch, version: version, only: only)
       return if dirs.empty?
 
       dirs.each { |d| puts "🌳 #{d.sub("#{@root}/", '')}" }

data/lib/crossbuild/dep_installer.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Crossbuild
+  # Verifies and installs the build dependencies declared in the deps:
+  # section of build.yaml. Host selectors (distro id, ID_LIKE tokens, os,
+  # "*" — see Platform.selectors) are matched against each dependency's
+  # hosts: rules; the first hit wins. Every rule carries its own commands:
+  # `verify` decides presence (exit 0 = installed; default: PATH lookup of
+  # the dependency name), `install` says how to install it on that host.
+  class DepInstaller
+    class DepError < Error; end
+
+    # Outcome of one dependency: resolved selector + install command, and
+    # whether the dependency is present after ensure_all/check_all ran.
+    Status = Struct.new(:dep, :selector, :command, :installed, keyword_init: true)
+
+    attr_reader :statuses
+
+    def initialize(manifest, root:, selectors: Platform.selectors, os: Platform.os)
+      @manifest = manifest
+      @root = root
+      @selectors = selectors
+      @os = os
+      @runner = Runner.new(root: root, vars: {
+        name: manifest.name,
+        version: manifest.version,
+        os: os.to_s,
+        arch: Platform.display_arch(Platform.arch),
+        platform: Platform.to_s,
+        id: Platform.to_s
+      })
+    end
+
+    # Verify every dependency; install the missing ones via their host rule
+    # and re-verify. Raises DepError when something stays missing.
+    def ensure_all
+      @statuses = @manifest.deps.map { |dep| ensure_dep(dep) }
+      @statuses
+    end
+
+    # Report-only pass for `crosspack deps <target> --check`: never installs.
+    def check_all
+      @statuses = @manifest.deps.map do |dep|
+        selector, rule = resolve(dep)
+        Status.new(dep: dep.name, selector: selector, command: display_command(rule),
+                   installed: present?(dep, rule))
+      end
+    end
+
+    # One line per dependency for the CLI doctor output.
+    def report
+      return '  (no deps declared)' if @manifest.deps.empty?
+
+      (@statuses || check_all).map do |s|
+        format('  %-20s %-8s %-8s %s',
+               s.dep, s.installed ? 'ok' : 'MISSING', s.selector, s.command)
+      end.join("\n")
+    end
+
+    private
+
+    def ensure_dep(dep)
+      selector, rule = resolve(dep)
+      if present?(dep, rule)
+        return Status.new(dep: dep.name, selector: selector,
+                          command: display_command(rule), installed: true)
+      end
+
+      install(dep, selector, rule)
+      unless present?(dep, rule)
+        detail = rule['verify'] ? "the verify `#{rule['verify']}` still fails" : "#{dep.name} is still not on PATH"
+        raise DepError,
+              "#{dep.name}: #{detail} after `#{rule['install']}`. " \
+              'Fix the install command or the verify probe.'
+      end
+      Status.new(dep: dep.name, selector: selector, command: display_command(rule), installed: true)
+    end
+
+    def resolve(dep)
+      @selectors.each do |selector|
+        return [selector, dep.hosts[selector]] if dep.hosts.key?(selector)
+      end
+      raise DepError,
+            "#{dep.name}: no rule for this host (selectors tried: #{@selectors.join(', ')}; " \
+            "described: #{dep.hosts.keys.join(', ')}) — add one of those or a \"*\" wildcard to deps.#{dep.name}.hosts"
+    end
+
+    def present?(dep, rule)
+      verify = rule['verify']
+      return on_path?(dep.name) if verify.nil?
+
+      system(@runner.interpolate(verify), chdir: @root, out: File::NULL, err: File::NULL)
+    end
+
+    def install(dep, selector, rule)
+      command = rule['install']
+      if command.nil?
+        raise DepError,
+              "#{dep.name}: verification failed on #{selector} and the rule has no install command — " \
+              "add deps.#{dep.name}.hosts.#{selector}.install"
+      end
+
+      command = @runner.interpolate(command)
+      puts "▶ #{command}   (#{dep.name} @ #{selector})"
+      return if system(command, chdir: @root)
+
+      status = $?.nil? ? 'unknown status' : "exit #{$?.exitstatus || $?.to_i}"
+      raise DepError, "#{dep.name}: install command failed (#{status}): #{command}"
+    end
+
+    def display_command(rule)
+      rule['install'] || "(verify only: #{rule['verify']})"
+    end
+
+    # Pure-Ruby PATH probe (portable: no `command -v` / `where` shell dance;
+    # `system` skips the shell for metacharacter-free strings, where shell
+    # builtins do not resolve). On Windows PATHEXT extensions are honored.
+    def on_path?(name)
+      exts = @os == :windows ? ENV['PATHEXT'].to_s.split(File::PATH_SEPARATOR) : ['']
+      ENV['PATH'].to_s.split(File::PATH_SEPARATOR).any? do |dir|
+        base = File.join(dir.strip.empty? ? '.' : dir, name)
+        exts.any? { |ext| File.executable?("#{base}#{ext}") }
+      end
+    end
+  end
+end

data/lib/crossbuild/distributor.rb

@@ -8,7 +8,12 @@ module Crossbuild
   # crosspacks/ tree crosspack writes, so crosspack can pack straight from it.
   # Items are symlinked by default (packers copy through symlinks); copy mode
   # is available for trees that get archived or shipped as-is.
+  #
+  # The build version is stamped into .crosspack-build in every target
+  # directory, so a later `crosspack pack <target>` needs no --version.
   class Distributor
+    STAMP_NAME = Crosspack::Builds::STAMP_NAME
+
     attr_reader :placed_dirs
 
     def initialize(root:, output_base:)
@@ -18,7 +23,9 @@ module Crossbuild
     end
 
     # Returns the list of builds/ directories that received artifacts.
-    def distribute(entry, host_arch:)
+    # only: distribute to just this raw target string (from artifacts.to)
+    # instead of all of them — used by `crosspack build <target>`.
+    def distribute(entry, host_arch:, version: nil, only: nil)
       spec = entry.artifacts
       return [] unless spec
 
@@ -30,11 +37,17 @@ module Crossbuild
       items = select_items(from_dir, spec.include)
       arch = entry.arch == :any ? host_arch : entry.arch
 
-      spec.to.each do |raw|
+      targets = only ? spec.to.select { |raw| raw == only } : spec.to
+      if targets.empty?
+        raise Error, "#{entry.id} does not distribute to #{only.inspect} (its targets: #{spec.to.join(', ')})"
+      end
+
+      targets.each do |raw|
         target = Crosspack::Target.parse(raw, arch: arch)
         dst_dir = target.output_dir(File.expand_path(@output_base, @root))
         FileUtils.mkdir_p(dst_dir)
         items.each { |item| place(item, File.join(dst_dir, File.basename(item)), spec.mode) }
+        File.write(File.join(dst_dir, STAMP_NAME), "#{version}\n") if version
         @placed_dirs << dst_dir
       end
       @placed_dirs.uniq

data/lib/crossbuild/matrix.rb

@@ -4,10 +4,12 @@ module Crossbuild
   # Human-readable build matrix: which entries exist, which can run on this
   # host, what they run and where their artifacts land.
   class Matrix
-    def initialize(manifest, host_os: Platform.os, host_arch: Platform.arch)
+    def initialize(manifest, host_os: Platform.os, host_arch: Platform.arch,
+                   selectors: Platform.selectors)
       @manifest = manifest
       @host_os = host_os
       @host_arch = host_arch
+      @selectors = selectors
     end
 
     def render
@@ -20,6 +22,7 @@ module Crossbuild
                else
                  "\n#{buildable.size} of #{@manifest.entries.size} entries build here: #{buildable.map(&:id).join(', ')}"
                end
+      lines << render_deps
       lines.join("\n")
     end
 
@@ -48,5 +51,29 @@ module Crossbuild
       to = entry.artifacts.to.join(', ')
       "#{from} -> #{to}"
     end
+
+    # How each deps: entry resolves on this host's selector list.
+    def render_deps
+      return '' if @manifest.deps.empty?
+
+      lines = ["\ndeps on this host (#{join_selectors}):"]
+      @manifest.deps.each do |dep|
+        selector = @selectors.find { |s| dep.hosts.key?(s) }
+        lines << if selector
+                   "  ⚙ #{dep.name.ljust(18)} #{selector} -> #{rule_note(dep.hosts[selector])}"
+                 else
+                   "  ✗ #{dep.name.ljust(18)} no rule for this host (described: #{dep.hosts.keys.join(', ')})"
+                 end
+      end
+      lines.join("\n")
+    end
+
+    def rule_note(rule)
+      rule['install'] || "(verify only: #{rule['verify']})"
+    end
+
+    def join_selectors
+      @selectors.join(' > ')
+    end
   end
 end

data/lib/crossbuild/platform.rb

@@ -36,5 +36,38 @@ module Crossbuild
     def self.display_arch(arch)
       arch == :x86_64 ? 'amd64' : arch.to_s
     end
+
+    # Distro id from /etc/os-release ("ubuntu", "fedora", ...), nil off Linux.
+    def self.distro
+      return nil unless os == :linux
+
+      facts = os_release
+      facts['ID']
+    end
+
+    # Ordered host selectors for the deps: matrix of build.yaml — distro id,
+    # then ID_LIKE tokens (Linux only), then the os, then "*" as the final
+    # wildcard. The first selector with a matching rule wins.
+    def self.selectors
+      sel = []
+      if os == :linux
+        facts = os_release
+        sel << facts['ID'] if facts['ID']
+        sel.concat(facts['ID_LIKE'].to_s.split)
+      end
+      sel << os.to_s << '*'
+    end
+
+    # Parses /etc/os-release into a Hash (ID, ID_LIKE, ...); {} when absent.
+    def self.os_release(path: '/etc/os-release')
+      File.read(path).each_line.with_object({}) do |line, facts|
+        key, value = line.split('=', 2)
+        next if value.nil?
+
+        facts[key.strip] = value.strip.delete_prefix('"').delete_suffix('"')
+      end
+    rescue Errno::ENOENT
+      {}
+    end
   end
 end

data/lib/crossbuild/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Crossbuild
-  VERSION = '0.1.0'
+  VERSION = '0.4.0'
 end

data/lib/crossbuild.rb

@@ -11,17 +11,20 @@ require_relative 'crossbuild/platform'
 require_relative 'crossbuild/version_scheme'
 require_relative 'crossbuild/build_manifest'
 require_relative 'crossbuild/runner'
+require_relative 'crossbuild/dep_installer'
 require_relative 'crossbuild/distributor'
 require_relative 'crossbuild/matrix'
 require_relative 'crossbuild/builder'
 
 module Crossbuild
   # Convenience wrapper: Crossbuild.build('build.yaml') runs every
-  # host-buildable matrix entry and returns Builder::Result.
-  def self.build(manifest, entry_id: nil, root: Dir.pwd, output_base: nil, version: nil,
-                 host_os: Platform.os, host_arch: Platform.arch)
+  # host-buildable matrix entry and returns Builder::Result. target: builds
+  # the entry distributing to that target only; deps: false skips the
+  # pre-build dependency check/install pass.
+  def self.build(manifest, entry_id: nil, target: nil, root: Dir.pwd, output_base: nil, version: nil,
+                 deps: true, host_os: Platform.os, host_arch: Platform.arch)
     m = manifest.is_a?(BuildManifest) ? manifest : BuildManifest.load(manifest)
-    Builder.new(m, root: root, output_base: output_base, version: version,
-                host_os: host_os, host_arch: host_arch).run(entry_id: entry_id)
+    Builder.new(m, root: root, output_base: output_base, version: version, deps: deps,
+                host_os: host_os, host_arch: host_arch).run(entry_id: entry_id, target: target)
   end
 end

data/lib/crosspack/builds.rb

@@ -8,6 +8,10 @@ module Crosspack
   module Builds
     ARCH_DIR_RE = /\A(amd64|x86_64|x64|arm64|aarch64)\z/i.freeze
 
+    # Written by `crosspack build <target>` into every builds/<target>/
+    # directory; `crosspack pack <target>` reads it as the default version.
+    STAMP_NAME = '.crosspack-build'
+
     # Returns [Target] for every target directory found under root.
     def self.available(root)
       return [] unless File.directory?(root)
@@ -30,6 +34,14 @@ module Crosspack
       lines.join("\n")
     end
 
+    # The version stamped by `crosspack build <target>` into the target's
+    # builds/ directory, or nil when the directory has no stamp (packed by
+    # an older build or never built through the stage pipeline).
+    def self.version_for(target, root)
+      stamp = File.join(target.output_dir(root.to_s, target.format), STAMP_NAME)
+      File.exist?(stamp) ? File.read(stamp).strip : nil
+    end
+
     private
 
     def self.scan_family(dir, family)

data/lib/crosspack/manifest.rb

@@ -33,9 +33,15 @@ module Crosspack
 
   # Parses and validates deps.yaml. Root keys are canonical dependency
   # names; each maps to { targets: { family: { "version": [pkgs] } } } or a
-  # scalar verdict for a whole family.
+  # scalar verdict for a whole family. A reserved top-level `version:` key
+  # declares the schema version (see SCHEMA_VERSION).
   class Manifest
-    attr_reader :path, :deps, :errors, :warnings
+    # The deps.yaml schema version this crosspack understands. Files
+    # declaring a newer version are rejected at load time with an upgrade
+    # hint; older (or absent) versions are accepted.
+    SCHEMA_VERSION = 1
+
+    attr_reader :path, :deps, :schema_version, :errors, :warnings
 
     def self.load(path)
       unless File.file?(path)
@@ -54,10 +60,12 @@ module Crosspack
 
     def initialize(path, raw)
       @path = path
-      @deps = raw.is_a?(Hash) ? raw : {}
-      @raw = raw
+      @schema_version = raw.is_a?(Hash) ? raw['version'] : nil
       @errors = []
       @warnings = []
+      check_schema_version!
+      @deps = raw.is_a?(Hash) ? raw.reject { |key, _| key == 'version' } : {}
+      @raw = raw
       validate
     end
 
@@ -90,6 +98,26 @@ module Crosspack
 
     private
 
+    # A schema version newer than this crosspack supports is a hard, loud
+    # error at load time — every command (resolve, matrix, pack) reports it,
+    # not just validate. Malformed versions (not an integer >= 1) are
+    # ordinary schema errors.
+    def check_schema_version!
+      v = @schema_version
+      return if v.nil?
+
+      unless v.is_a?(Integer) && v >= 1
+        @errors << Issue.new('version', "schema version must be an integer >= 1, got #{v.inspect}")
+        return
+      end
+      return if v <= SCHEMA_VERSION
+
+      raise InvalidManifestError,
+            "#{@path}: deps.yaml declares schema version #{v}, " \
+            "but this crosspack (#{Crosspack::VERSION}) supports up to #{SCHEMA_VERSION}. " \
+            'Update the gem (gem update crosspack) or lower the declared version.'
+    end
+
     def validate
       unless @raw.is_a?(Hash) && !@raw.empty?
         @errors << Issue.new(
@@ -98,7 +126,7 @@ module Crosspack
         )
         return
       end
-      @raw.each { |name, body| validate_dep(name.to_s, body) }
+      @raw.each { |name, body| validate_dep(name.to_s, body) unless name == 'version' }
     end
 
     def validate_dep(name, body)

data/lib/crosspack/packer.rb

@@ -8,8 +8,10 @@ module Crosspack
   # package.yaml), resolves dependencies for the target (per deps.yaml) and
   # produces a native package under output_base/<family>/<version>/<arch>/.
   # The builder is chosen by the target format — deb, rpm or PKGBUILD.
+  # version: when omitted, the version stamped by `crosspack build <target>`
+  # (.crosspack-build in the target's builds/ directory) is used.
   class Packer
-    def self.pack(manifest:, deps:, target:, version:, root: Dir.pwd,
+    def self.pack(manifest:, deps:, target:, version: nil, root: Dir.pwd,
                   output_base: 'crosspacks')
       new(manifest: manifest, deps: deps, target: target, version: version,
           root: root, output_base: output_base).pack
@@ -19,15 +21,16 @@ module Crosspack
       @pkg_path = manifest
       @deps_path = deps
       @target = target
-      @version = version.to_s
+      @version = version && version.to_s
       @root = root
-      @output_base = output_base
+      @output_base = output_base || 'crosspacks'
     end
 
     def pack
       @pkg = PackageManifest.load(@pkg_path)
       @deps = Manifest.load(@deps_path)
       validate_both!
+      resolve_version!
       @pkg_data = build_layout
 
       case @target.format
@@ -49,6 +52,21 @@ module Crosspack
 
     private
 
+    # --version wins; otherwise the version recorded by the build stage.
+    def resolve_version!
+      return unless @version.nil? || @version.strip.empty?
+
+      stamped = Builds.version_for(@target, File.expand_path(@pkg.sources, @root))
+      if stamped.nil? || stamped.strip.empty?
+        raise BuildError,
+              "No version for target #{@target}: no --version given and no build stamp " \
+              "(#{Builds::STAMP_NAME}) in #{@pkg.sources}. " \
+              "Run: crosspack build #{@target} — or pass --version explicitly."
+      end
+
+      @version = stamped
+    end
+
     def validate_both!
       errors = []
       errors << @pkg.error_report unless @pkg.valid?
@@ -70,10 +88,10 @@ module Crosspack
         hint = available.empty? ? 'no built targets at all.' :
                "available builds: #{available.map { |t| "#{t} (#{t.output_dir(@pkg.sources, t.format)})" }.join(', ')}."
         raise BuildError,
-              "No compiled artifacts for target #{@target}: expected them in #{src_dir}.\n" \
+              "Build stage not done for target #{@target}: expected compiled artifacts in #{src_dir}.\n" \
               "The builds tree (#{@pkg.sources}) mirrors the output tree: builds/<family>/<version>/<arch>/. " \
               "Currently #{hint}\n" \
-              'Build the application for this target first, then pack.'
+              "Run: crosspack build #{@target}"
       end
 
       lib_dst = File.join(@pkg.prefix, @pkg.lib_dir)

data/lib/crosspack/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Crosspack
-  VERSION = '0.2.1'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,35 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: crosspack
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Oleg Orlov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-13 00:00:00.000000000 Z
 dependencies: []
-description: 'Two cooperating commands: crossbuild runs the build steps of a project
-  from a build.yaml matrix and fans the produced artifacts out into the per-target
-  builds/ tree; crosspack turns that tree into native packages, driven by a cross-distro
-  deps.yaml. Both share the same target vocabulary so the trees never drift apart.'
+description: 'One command, one target vocabulary: crosspack deps <target> verifies
+  and installs the build host dependencies, crosspack build <target> runs the build.yaml
+  matrix entry and fans artifacts into builds/, crosspack pack <target> turns that
+  tree into a native package. Stages are gated — no packing before building — and
+  keyed by the same target strings throughout.'
 email:
 - orelcokolov@gmail.com
 executables:
 - crosspack
-- crossbuild
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
-- exe/crossbuild
 - exe/crosspack
 - lib/crossbuild.rb
 - lib/crossbuild/build_manifest.rb
 - lib/crossbuild/builder.rb
+- lib/crossbuild/dep_installer.rb
 - lib/crossbuild/distributor.rb
 - lib/crossbuild/matrix.rb
 - lib/crossbuild/platform.rb
@@ -74,5 +74,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Cross-platform build orchestrator and native package builder (deb/rpm/PKGBUILD/winget/cask)
+summary: 'Staged cross-platform pipeline: deps → build → pack native packages (deb/rpm/PKGBUILD/winget/cask)'
 test_files: []

data/exe/crossbuild

@@ -1,76 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'optparse'
-
-begin
-  require 'crossbuild'
-rescue LoadError
-  require_relative '../lib/crossbuild'
-end
-
-def abort_with(message)
-  warn message
-  exit 1
-end
-
-options = { file: 'build.yaml', root: Dir.pwd, target: nil, version: nil, output_base: nil }
-parser = OptionParser.new do |opts|
-  opts.banner = "crossbuild #{Crossbuild::VERSION} — cross-platform build orchestrator\n" \
-                "Usage: crossbuild <command> [options]\n" \
-                'Commands: validate, matrix, version, build, targets'
-
-  opts.on('-f', '--file PATH', 'path to build.yaml (default: ./build.yaml)') { |v| options[:file] = v }
-  opts.on('--target ID', 'matrix entry to build, e.g. linux/amd64 (default: every host-buildable entry)') { |v| options[:target] = v }
-  opts.on('--version VERSION', 'override the version scheme for build') { |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: the manifest output, builds)') { |v| options[:output_base] = v }
-  opts.on('-h', '--help', 'show help') do
-    puts opts
-    exit
-  end
-end
-parser.parse!
-
-command = ARGV.shift
-abort_with 'No command given. See: crossbuild --help' if command.nil?
-
-# Positional file path: crossbuild validate path/to/build.yaml
-options[:file] = ARGV.shift if ARGV.first && !ARGV.first.start_with?('-')
-
-file = File.expand_path(options[:file], options[:root])
-begin
-  manifest = Crossbuild::BuildManifest.load(file)
-rescue Crossbuild::InvalidManifestError => e
-  abort_with e.message
-end
-
-case command
-when 'validate'
-  puts manifest.error_report
-  exit(manifest.valid? ? 0 : 1)
-when 'matrix'
-  abort_with 'Schema is invalid — the matrix cannot be rendered. Run: crossbuild validate' unless manifest.valid?
-  puts Crossbuild::Matrix.new(manifest).render
-when 'version'
-  abort_with 'Schema is invalid. Run: crossbuild validate' unless manifest.valid?
-  begin
-    puts Crossbuild::VersionScheme.new(manifest.version).compute(root: options[:root])
-  rescue Crossbuild::VersionScheme::Error => e
-    abort_with e.message
-  end
-when 'build'
-  begin
-    result = Crossbuild::Builder.new(manifest, root: options[:root], output_base: options[:output_base],
-                                     version: options[:version]).run(entry_id: options[: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 <target> --version ' + result.version
-when 'targets'
-  base = options[:output_base] || manifest.output
-  puts Crosspack::Builds.report(File.expand_path(base, options[:root]))
-else
-  abort_with "Unknown command #{command.inspect}. Available: validate, matrix, version, build, targets"
-end