tebako 0.15.1 → 0.15.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 349d5b0a59f98021f05bae37a7c62efd9282900f5d4c161e8567424a082d21a1
-  data.tar.gz: 74dabe977337bcbe8b63a82cc82653242e852542e629a8698f3f6828c59cebf3
+  metadata.gz: 40cccec56036f14133e05046f858915c7f6ae657c11f3560b647d791c2cc952a
+  data.tar.gz: 79022b3acb1d0457a996f671ca93e69ac024107156f31445f27159a1d81ac7da
 SHA512:
-  metadata.gz: eed8e60a9fe1c1185478c7f9c70d4a4e1af7c5f24c853c6a1ac85527c04bb7b281c5efdbc3cb9afd2ee31dd56e4d5a6d0e7975388ea180dc03d93fa4d703b845
-  data.tar.gz: 1355806d02bbe169d73d6ca746a5052d24dba4f49c398f514d25d8c35592b2d451f97629e60801d656ad755b70356d201a1211dd882a611fe1a083900b28c0e1
+  metadata.gz: 318cab0bce4b6528efe1e1c215b473344311f68fcef2bc7ac379cdc81248c06afac942fff0b55a9dd5e45b88f5989031597ef633c4e6e6d69ed2478a83138b13
+  data.tar.gz: 0f3b13569b1ffd26de43d6233bfb2579fe91e1d6107b51370562c64e2f0f87021813bb1129eaafaae9f68202e0c37d9d03cf9d439ce5610ff857493278fe6838

data/CMakeLists.txt

@@ -175,7 +175,7 @@ string(CONCAT RUBY_API_VER ${RUBY_VER_BASE} ".0")
 # NOTE: the env override in def_ext_prj_g (tebako-tools) is currently broken
 # (`if (DEFINED ENV{${TAG})` is missing a closing brace, so the test never
 # fires); this default is the operative tag selection.
-def_ext_prj_g(DWARFS_WR "v0.12.8")
+def_ext_prj_g(DWARFS_WR "v0.12.9")
 
 # Provisions libtfs (prebuilt package or vcpkg toolchain for the source
 # build), the prebuilt mkdwarfs, and -- for the prebuilt path -- the

data/README.adoc

@@ -420,7 +420,7 @@ tebako press \
   [-c|--cwd=<package-current-working-directory>] \
   [-D|--devmode] \
   [-P|--patchelf] \
-  [-m|--mode=<bundle|both|application|runtime>] \
+  [-m|--mode=<lean|fat|classic|bundle|both|application|runtime>] \
   [-u|--ref=<runtime-reference>] \
   [-t|--tebafile=<path-to-tebafile>]
 ----
@@ -452,6 +452,7 @@ On Windows, the output file is automatically appended the `.exe` extension.
 
 *** in `runtime` mode, the runtime package is created at `tebako-runtime`.
 *** in `application` mode, the application package is created at `<current-folder>/<entry-point-base-name>`.
+*** in `lean`, `fat` and `classic` modes, the package is created at `<current-folder>/<entry-point-base-name>`.
 *** in `bundle` mode, the bundled package is created at `<current-folder>/<entry-point-base-name>`.
 *** in `both` mode, the runtime package is created at `<current-folder>/<entry-point-base-name>`,
 and the application package is created at `<current-folder>/<entry-point-base-name>.tebako`.
@@ -460,6 +461,7 @@ and the application package is created at `<current-folder>/<entry-point-base-na
 
 *** in `runtime` mode, the runtime package is named according to the `-o` option.
 *** in `application` mode, the application package is named according to the `-o` option.
+*** in `lean`, `fat` and `classic` modes, the package is named according to the `-o` option.
 *** in `bundle` mode, the bundled package is named according to the `-o` option.
 *** in `both` mode, the runtime package is named according to the `-o` option,
 and the application package is named according to the `-o` option with the `.tebako` extension.
@@ -502,10 +504,13 @@ For example, a package created at Ubuntu 20 system can be used on Ubuntu 22.
 NOTE: The feature is exeprimental, we may consider another approach in the future.
 
 `--mode=<mode>`::
-(optional, defaults to `bundle`)
-Package output mode, determines whether the runtime and/or application are
-to be separately packaged.
+(optional, defaults to `lean`)
+Package output mode, determines the package layout (three-part or runtime-stitched)
+and whether the runtime and/or application are separately packaged.
 
+`lean`::: Create a three-part package: the tebako-bootstrap launcher plus the application image slot(s) and a tpkg manifest trailer carrying the runtime reference. At first run the bootstrap resolves (downloads, verifies and caches) the referenced prebuilt runtime into the machine-wide cache (`~/.tebako` or `$TEBAKO_HOME`); subsequent runs of any lean package built for the same runtime share that cache entry. The output file is named according to the `-o` option.
+`fat`::: Like `lean`, but the runtime package is also embedded as a payload slot. The first run installs it into the cache without network access (works with `TEBAKO_OFFLINE=1`). The output file is named according to the `-o` option.
+`classic`::: Stitch the application image onto a prebuilt runtime package (the Stage-3A layout; identical to `bundle` with the default `--runtime prebuilt`). The output file is named according to the `-o` option.
 `bundle`::: Create a single package bundling both the runtime and application. The output file is named according to the `-o` option.
 `both`::: Create separate packages for the runtime and application. Outputs two separate files: one for the runtime at the location specified at the `-o {filename}` and one for the application at `{filename}.package`.
 `application`::: Create the application package only. The output file is named according to the `-o` option.

data/cmake/tebako-libtfs.cmake

@@ -82,9 +82,7 @@ endif()
 if(IS_GNU)
   set(LIBTFS_PLATFORM "linux-gnu-${__LIBTFS_ARCH}")
 elseif(IS_MUSL)
-  if(NOT __LIBTFS_ARCH STREQUAL "x86_64")
-    message(FATAL_ERROR "No prebuilt libtfs package for linux-musl-${__LIBTFS_ARCH}; use -DDWARFS_PRELOAD=OFF (source build)")
-  endif()
+  # musl-arm64 prebuilt packages first ship in libtfs v0.12.9
   set(LIBTFS_PLATFORM "linux-musl-${__LIBTFS_ARCH}")
 elseif(IS_DARWIN)
   set(LIBTFS_PLATFORM "macos-${__LIBTFS_ARCH}")

data/include/tebako/tpkg.h

@@ -48,9 +48,9 @@
  *     offset  size  field
  *        0     8    u64 offset (image start, absolute file offset)
  *        8     8    u64 size   (image length in bytes)
- *       16     4    u32 format_id (0=auto(magic), 1=dwarfs, 2=squashfs, 3=zip)
+ *       16     4    u32 format_id (0=auto(magic), 1=dwarfs, 2=squashfs, 3=zip, 4=runtime payload)
  *       20     4    u32 flags
- *       24   256    char mount_point[256] (UTF-8, NUL-padded)
+ *       24   256    char mount_point[256] (UTF-8, NUL-padded; empty for runtime payloads)
  *
  * Reader algorithm: read the fixed-size header at EOF - TPKG_HEADER_SIZE,
  * check the magic, verify header_crc32, then read slot_count slot records at
@@ -108,6 +108,9 @@ extern "C" {
 #define TPKG_FORMAT_DWARFS 1u
 #define TPKG_FORMAT_SQUASHFS 2u
 #define TPKG_FORMAT_ZIP 3u
+/* runtime payload slot of a fat package: the bootstrap installs it into the
+ * shared cache at first run; it is never mounted as a filesystem image */
+#define TPKG_FORMAT_RUNTIME 4u
 
 /* ---- error codes (returned by tpkg_errno) -------------------------------- */
 
@@ -157,7 +160,7 @@ int tpkg_read_mem(const void* data, size_t size, tpkg_manifest* out);
 int tpkg_write_fd(int fd, const tpkg_manifest* m);
 
 /* Magic-independent structural checks: version supported, slot_count in
- * 1..TPKG_MAX_SLOTS, offset+size non-overflowing, format_id <= TPKG_FORMAT_ZIP,
+ * 1..TPKG_MAX_SLOTS, offset+size non-overflowing, format_id <= TPKG_FORMAT_RUNTIME,
  * runtime_ref and mount_points NUL-terminated within their fixed fields. */
 int tpkg_validate(const tpkg_manifest* m);
 
@@ -397,7 +400,7 @@ int tpkg_validate(const tpkg_manifest* m)
     if (s->size > UINT64_MAX - s->offset) {
       return tpkg__fail(TPKG_ERR_INVALID);
     }
-    if (s->format_id > TPKG_FORMAT_ZIP) {
+    if (s->format_id > TPKG_FORMAT_RUNTIME) {
       return tpkg__fail(TPKG_ERR_INVALID);
     }
     if (tpkg__strnlen(s->mount_point, TPKG_MOUNT_POINT_LEN) == TPKG_MOUNT_POINT_LEN) {

data/lib/tebako/bootstrap_manager.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 [Ribose Inc](https://www.ribose.com).
+# All rights reserved.
+# This file is a part of the Tebako project.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS
+# BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+require_relative "runtime_manager"
+
+# Tebako - an executable packager
+module Tebako
+  # Resolution, download, verification and machine-wide caching of the
+  # tebako-bootstrap launcher binaries published by tamatebako/tebako-bootstrap.
+  # The launcher is the base binary of lean/fat three-part packages.
+  #
+  # Cache layout (rooted at $TEBAKO_HOME or ~/.tebako, shared with the
+  # runtime package cache):
+  #   bootstraps/tebako-bootstrap-<version>-<platform>/
+  #     tebako-bootstrap-<version>-<platform>[.exe]
+  #     sha256    -- digest the installed file was verified against
+  #     origin    -- URL the binary was downloaded from
+  #
+  # All download/verify/lock machinery is inherited from RuntimeManager; only
+  # the release-shape specifics (asset naming, manifest.json object format,
+  # SHA256SUMS index name, mirror env var) differ.
+  class BootstrapManager < RuntimeManager
+    DEFAULT_MIRROR = "https://github.com/tamatebako/tebako-bootstrap/releases/download"
+    BOOTSTRAPS_DIR = "bootstraps"
+    INDEX_FILES = ["manifest.json", "SHA256SUMS"].freeze
+
+    # tebako-bootstrap release consumed by default (TEBAKO_BOOTSTRAP_VERSION
+    # overrides). 0.2.0 is the first release that installs a fat package's
+    # runtime payload slot into the cache at first run.
+    BOOTSTRAP_VERSION = "0.2.0"
+    PAYLOAD_MIN_VERSION = "0.2.0"
+
+    class << self
+      def default_version
+        version = ENV.fetch("TEBAKO_BOOTSTRAP_VERSION", nil)
+        version.nil? || version.empty? ? BOOTSTRAP_VERSION : version.sub(/\Av/, "")
+      end
+
+      def resolve(platform, bootstrap_version: default_version)
+        new.resolve(platform, bootstrap_version: bootstrap_version)
+      end
+    end
+
+    def resolve(platform, bootstrap_version: self.class.default_version)
+      super(bootstrap_version, platform, tebako_version: bootstrap_version)
+    end
+
+    private
+
+    def default_mirror
+      DEFAULT_MIRROR
+    end
+
+    def mirror_env_var
+      "TEBAKO_BOOTSTRAP_MIRROR"
+    end
+
+    def index_files
+      INDEX_FILES
+    end
+
+    def cache_subdir
+      BOOTSTRAPS_DIR
+    end
+
+    def release_name
+      "tebako-bootstrap"
+    end
+
+    def entry_dir(_version, platform, bootstrap_version)
+      File.join(@cache_root, BOOTSTRAPS_DIR, "tebako-bootstrap-#{bootstrap_version}-#{platform}")
+    end
+
+    def runtime_filename(_version, platform, bootstrap_version)
+      suffix = platform.start_with?("windows") ? ".exe" : ""
+      "tebako-bootstrap-#{bootstrap_version}-#{platform}#{suffix}"
+    end
+
+    def runtime_ref(_version, platform, bootstrap_version)
+      "tebako-bootstrap@#{bootstrap_version} (#{platform})"
+    end
+
+    def find_entry(index, _version, platform, bootstrap_version)
+      entry = index.find { |candidate| candidate["platform"] == platform }
+      return entry if entry
+
+      platforms = index.map { |candidate| candidate["platform"] }
+      Tebako.packaging_error(131, "no tebako-bootstrap package for #{platform} (bootstrap #{bootstrap_version}). " \
+                                  "Available: #{platforms.join(", ")}.")
+    end
+
+    def offline_check(ref, bootstrap_version)
+      return unless offline?
+
+      Tebako.packaging_error(132, "#{ref} is not cached and downloads are disabled " \
+                                  "(release index: #{index_urls(bootstrap_version).join(", ")}; " \
+                                  "#{mirror_env_var}=#{@mirror})")
+    end
+
+    # tebako-bootstrap's manifest.json is an object
+    # ({name:, version:, assets: [{platform:, file:, sha256:}]}), not the
+    # entry array tebako-runtime-ruby publishes
+    def parse_manifest(body, _bootstrap_version)
+      manifest_assets(body)
+        .select { |asset| asset["platform"] && asset["file"] && asset["sha256"] }
+        .map { |asset| manifest_entry(asset) }
+    end
+
+    def manifest_assets(body)
+      data = JSON.parse(body)
+      assets = data.is_a?(Hash) ? data["assets"] : nil
+      raise IndexUnavailable, "manifest.json has no assets array" unless assets.is_a?(Array)
+
+      assets
+    rescue JSON::ParserError
+      raise IndexUnavailable, "manifest.json is not valid JSON"
+    end
+
+    def manifest_entry(asset)
+      { "platform" => asset["platform"], "filename" => asset["file"], "sha256" => asset["sha256"].downcase }
+    end
+
+    def parse_sha256sums(body, bootstrap_version)
+      pattern = /\Atebako-bootstrap-#{Regexp.escape(bootstrap_version)}-(.+?)(?:\.exe)?\z/
+      body.each_line.filter_map do |line|
+        sha256, file = line.strip.split(/\s+/, 2)
+        match = file && pattern.match(file.sub(/\A\*/, ""))
+        next unless match
+
+        { "platform" => match[1], "filename" => file.sub(/\A\*/, ""), "sha256" => sha256.downcase }
+      end
+    end
+  end
+end

data/lib/tebako/cli.rb

@@ -174,9 +174,10 @@ module Tebako
     DESC
 
     RUNTIME_DESCRIPTION = <<~DESC
-      Runtime provenance: 'prebuilt' resolves/downloads a prebuilt tebako runtime package and stitches the
-      #{" " * 65}# application image onto it (default for the 'bundle' mode); 'source' keeps the Stage-2 source build.
-      #{" " * 65}# Modes other than 'bundle' always build from source.
+      Runtime provenance: 'prebuilt' resolves/downloads a prebuilt tebako runtime package (default for the
+      #{" " * 65}# 'bundle', 'classic', 'lean' and 'fat' modes); 'source' keeps the Stage-2 source build
+      #{" " * 65}# (not available for 'lean'/'fat' -- the bootstrap resolves tebako-runtime-ruby releases
+      #{" " * 65}# at run time). Modes other than those always build from source.
     DESC
 
     IMAGE_DESCRIPTION = <<~DESC
@@ -184,6 +185,16 @@ module Tebako
       #{" " * 65}# must be distinct. Prebuilt runtime only.
     DESC
 
+    MODE_DESCRIPTION = <<~DESC
+      Tebako press mode, 'lean' by default.
+      #{" " * 65}# 'lean' presses a three-part package (tebako-bootstrap + application image(s) + tpkg trailer);
+      #{" " * 65}# the runtime is resolved into the shared cache at first run.
+      #{" " * 65}# 'fat' is 'lean' plus the runtime package as a payload slot -- the first run installs it
+      #{" " * 65}# into the cache without network access.
+      #{" " * 65}# 'classic' stitches the application image onto a prebuilt runtime (Stage-3A layout);
+      #{" " * 65}# 'bundle', 'both', 'application' and 'runtime' keep their legacy behaviors.
+    DESC
+
     desc "press", "Press tebako image"
     method_option :cwd, type: :string, aliases: "-c", required: false, desc: CWD_DESCRIPTION
     method_option :"log-level", type: :string, aliases: "-l", required: false, enum: %w[error warn debug trace],
@@ -197,8 +208,9 @@ module Tebako
                          enum: Tebako::RubyVersion::RUBY_VERSIONS.keys,
                          desc: "Tebako package Ruby version, #{Tebako::RubyVersion::DEFAULT_RUBY_VERSION} by default"
     method_option :patchelf, aliases: "-P", type: :boolean, desc: RGP_DESCRIPTION
-    method_option :mode, type: :string, aliases: "-m", required: false, enum: %w[bundle both runtime application],
-                         desc: "Tebako press mode, 'bundle' by default"
+    method_option :mode, type: :string, aliases: "-m", required: false,
+                         enum: %w[lean fat classic bundle both runtime application],
+                         desc: MODE_DESCRIPTION
     method_option :ref, type: :string, aliases: "-u", required: false, desc: REF_DESCRIPTION
     method_option :runtime, type: :string, required: false, enum: %w[prebuilt source], desc: RUNTIME_DESCRIPTION
     method_option :"build-runtime", type: :boolean, required: false,

data/lib/tebako/cli_helpers.rb

@@ -25,13 +25,16 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 
+require "digest"
 require "etc"
 require "fileutils"
 require "pathname"
 require "rbconfig"
 
+require_relative "bootstrap_manager"
 require_relative "codegen"
 require_relative "error"
+require_relative "launcher_abi"
 require_relative "options_manager"
 require_relative "runtime_manager"
 require_relative "scenario_manager"
@@ -86,8 +89,13 @@ module Tebako
       options_manager.process_gemfile(scenario_manager.gemfile_path) if scenario_manager.with_gemfile
       check_warnings(options_manager)
       puts options_manager.press_announce(scenario_manager.msys?)
+      dispatch_press(options_manager, scenario_manager)
+    end
 
-      if options_manager.prebuilt_runtime?
+    def dispatch_press(options_manager, scenario_manager)
+      if options_manager.three_part?
+        do_press_three_part(options_manager, scenario_manager)
+      elsif options_manager.prebuilt_runtime?
         do_press_prebuilt(options_manager, scenario_manager)
       else
         do_press_source(options_manager, scenario_manager)
@@ -113,6 +121,66 @@ module Tebako
       puts "Created tebako #{options_manager.output_type_first} at \"#{package}\""
     end
 
+    # Press a three-part package (Stage 3B): tebako-bootstrap + application
+    # image slot(s) + tpkg trailer with the runtime reference (launcher ABI
+    # v1). 'lean' (the default) resolves the runtime into the shared cache at
+    # first run; 'fat' additionally embeds the runtime package as a payload
+    # slot, so the first run installs it without any network access.
+    def do_press_three_part(options_manager, scenario_manager)
+      bootstrap_path, runtime_path = resolve_three_part_parts(options_manager)
+      app_image = Tebako::Packager.build_app_image(options_manager, scenario_manager)
+      images = three_part_images(options_manager, scenario_manager, app_image, runtime_path)
+      package = "#{options_manager.package}#{scenario_manager.exe_suffix}"
+      runtime_sha256 = runtime_path && Digest::SHA256.file(runtime_path).hexdigest
+      Tebako::Stitcher.stitch(bootstrap_path, images: images, output: package, lean: true,
+                                              ruby_version: options_manager.ruby_ver,
+                                              launcher_abi: Tebako::LauncherAbi::VERSION,
+                                              runtime_sha256: runtime_sha256)
+      puts "Created tebako #{options_manager.output_type_first} at \"#{package}\""
+    end
+
+    # Validate the options and the packaging environment, then resolve the
+    # bootstrap (and, for fat, the runtime payload) into the shared cache
+    def resolve_three_part_parts(options_manager)
+      options_manager.runtime_source # validates the mode/provenance combination
+      check_bootstrap_version!(options_manager)
+      Tebako::Packager.check_prebuilt_env!(options_manager.stash_dir, options_manager.deps_bin_dir)
+      runtime_path = fat_runtime_path(options_manager)
+      [Tebako::BootstrapManager.resolve(options_manager.host_platform), runtime_path]
+    end
+
+    def fat_runtime_path(options_manager)
+      return nil unless options_manager.fat?
+
+      Tebako::RuntimeManager.resolve(options_manager.ruby_ver, options_manager.host_platform)
+    end
+
+    def three_part_images(options_manager, scenario_manager, app_image, runtime_path)
+      images = [{ path: app_image, mount_point: scenario_manager.fs_mount_point,
+                  format_id: Tebako::Stitcher::FORMAT_DWARFS }] + options_manager.images
+      images << { path: runtime_path, mount_point: "", format_id: Tebako::Stitcher::FORMAT_RUNTIME } if runtime_path
+      images
+    end
+
+    # The fat payload slot is installed by the bootstrap at first run — a
+    # capability added in tebako-bootstrap 0.2.0
+    def check_bootstrap_version!(options_manager)
+      return unless options_manager.fat?
+
+      version = Tebako::BootstrapManager.default_version
+      minimum = Tebako::BootstrapManager::PAYLOAD_MIN_VERSION
+      return if payload_capable?(version, minimum)
+
+      Tebako.packaging_error(134, "fat mode requires tebako-bootstrap >= #{minimum} (selected: #{version}; " \
+                                  "set TEBAKO_BOOTSTRAP_VERSION to a payload-capable release)")
+    end
+
+    def payload_capable?(version, minimum)
+      Gem::Version.new(version) >= Gem::Version.new(minimum)
+    rescue ArgumentError
+      false
+    end
+
     def do_press_application(options_manager, scenario_manager)
       return unless %w[both application].include?(options_manager.mode)
 
@@ -121,7 +189,7 @@ module Tebako
     end
 
     def do_press_runtime(options_manager, scenario_manager)
-      return unless %w[both runtime bundle].include?(options_manager.mode)
+      return unless %w[both runtime bundle classic].include?(options_manager.mode)
 
       generate_files(options_manager, scenario_manager)
       merged_env = ENV.to_h.merge(scenario_manager.b_env)

data/lib/tebako/error.rb

@@ -57,6 +57,9 @@ module Tebako
     127 => "Stitch input file is not accessible",
     128 => "Prebuilt runtime press requires the packaging environment (run 'tebako setup' first)",
     130 => "Option combination is not supported",
+    131 => "No tebako-bootstrap package for the requested platform",
+    132 => "TEBAKO_OFFLINE is set and the requested tebako-bootstrap package is not cached",
+    134 => "Fat mode requires a payload-capable tebako-bootstrap release",
     201 => "Warning. Could not create cache version file"
   }.freeze
 

data/lib/tebako/launcher_abi.rb

@@ -30,6 +30,12 @@ module Tebako
   # three-part package model (spec §4.4).
   #
   # A lean package is [tebako-bootstrap][.tfs image slots][tpkg trailer].
+  # A fat package has the same layout plus the runtime package itself as a
+  # payload slot (format_id TPKG_FORMAT_RUNTIME, empty mount point,
+  # ";sha256=<hex>" appended to the trailer's runtime_ref): at first run the
+  # bootstrap installs the payload into the shared cache instead of
+  # downloading it. Payload slots are never handed over as --tebako-image.
+  #
   # The bootstrap (tamatebako/tebako-bootstrap) parses the trailer of its own
   # executable, resolves the language runtime into the shared cache, and
   # execs it as:

data/lib/tebako/options_manager.rb

@@ -41,6 +41,13 @@ require_relative "version"
 module Tebako
   # Cli helpers
   class OptionsManager # rubocop:disable Metrics/ClassLength
+    # Press modes producing three-part packages (tebako-bootstrap + image
+    # slots + tpkg trailer): 'lean' resolves the runtime at first run, 'fat'
+    # additionally embeds it as a payload slot (self-installing, offline)
+    THREE_PART_MODES = %w[lean fat].freeze
+    # Modes whose default runtime provenance is a prebuilt runtime package
+    PREBUILT_DEFAULT_MODES = %w[bundle classic lean fat].freeze
+
     def initialize(options)
       @options = options
       @rv = Tebako::RubyVersion.new(@options["Ruby"])
@@ -157,14 +164,24 @@ module Tebako
     end
 
     def mode
-      @mode ||= @options["mode"].nil? ? "bundle" : @options["mode"]
+      @mode ||= @options["mode"].nil? ? "lean" : @options["mode"]
+    end
+
+    def three_part?
+      THREE_PART_MODES.include?(mode)
+    end
+
+    def fat?
+      mode == "fat"
     end
 
     # Runtime provenance: "prebuilt" (resolve/download a prebuilt runtime
-    # package and stitch the application image onto it) or "source" (the
-    # Stage-2 source build). Default is "prebuilt" for the bundle mode;
-    # other modes always build from source, and --build-runtime forces the
-    # source path everywhere (back-compat alias for '--runtime source').
+    # package) or "source" (the Stage-2 source build). Default is "prebuilt"
+    # for the bundle/classic/lean/fat modes; other modes always build from
+    # source, and --build-runtime forces the source path everywhere it is
+    # allowed (back-compat alias for '--runtime source'). The three-part
+    # modes (lean/fat) require prebuilt runtime packages: the bootstrap
+    # resolves tebako-runtime-ruby releases at run time.
     def runtime_source
       @runtime_source ||= checked_runtime_source(requested_runtime_source)
     end
@@ -246,7 +263,7 @@ module Tebako
         press_announce_application(is_msys)
       when "both"
         press_announce_both
-      when "bundle"
+      when "bundle", "classic", "lean", "fat"
         press_announce_bundle
       when "runtime"
         press_announce_runtime
@@ -290,7 +307,7 @@ module Tebako
     def press_announce_bundle
       <<~ANN
         Running tebako press at #{prefix}
-           Mode:                      'bundle'
+           Mode:                      '#{mode}'
            Ruby version:              '#{@ruby_ver}'
            Project root:              '#{root}'
            Application entry point:   '#{fs_entrance}'
@@ -374,14 +391,19 @@ module Tebako
     def requested_runtime_source
       explicit = @options["runtime"]
       return "source" if @options["build-runtime"]
-      return mode == "bundle" ? "prebuilt" : "source" if explicit.nil?
+      return PREBUILT_DEFAULT_MODES.include?(mode) ? "prebuilt" : "source" if explicit.nil?
 
       explicit
     end
 
     def checked_runtime_source(source)
-      if source == "prebuilt" && mode != "bundle"
-        Tebako.packaging_error(130, "--runtime prebuilt is supported in bundle mode only (mode: '#{mode}')")
+      if source == "prebuilt" && !PREBUILT_DEFAULT_MODES.include?(mode)
+        Tebako.packaging_error(130, "--runtime prebuilt is supported in bundle, classic, lean and fat modes only " \
+                                    "(mode: '#{mode}')")
+      end
+      if source == "source" && three_part?
+        Tebako.packaging_error(130, "mode '#{mode}' requires a prebuilt runtime package " \
+                                    "(the bootstrap resolves tebako-runtime-ruby releases at first run)")
       end
       source
     end
@@ -399,7 +421,7 @@ module Tebako
 
     def host_arch_id(arch)
       case arch
-      when /^(x86_64|amd64)$/ then "x86_64"
+      when /^(x86_64|amd64|x64)$/ then "x86_64"
       when /^(aarch64|arm64)$/ then "arm64"
       else
         Tebako.packaging_error(112, arch)

data/lib/tebako/packager/pass1_patch.rb

@@ -203,6 +203,21 @@ module Tebako
           "/* tebako patched */ static const struct vktable *console_win32_vk(const char *, size_t);"
       }.freeze
 
+      # Ruby's win32.c defines clock_gettime/clock_getres fallbacks with no
+      # HAVE_* configure guard (at least through 3.4); modern mingw-w64
+      # winpthreads headers (pthread_time.h, pulled in by time.h) carry
+      # static-inline definitions of the same symbols, so the toolchain
+      # build fails with redefinition errors. Rename ruby's fallbacks
+      # before the toolchain build; the CRT/winpthreads implementations
+      # (which configure detects) serve the calls. Pass2 re-applies the
+      # same rename from pristine sources for the final build.
+      WIN32_WIN32_C_CLOCK_PATCH = {
+        "clock_gettime(clockid_t clock_id, struct timespec *sp)" =>
+          "_dummy_clock_gettime(clockid_t clock_id, struct timespec *sp)",
+        "clock_getres(clockid_t clock_id, struct timespec *sp)" =>
+          "_dummy_clock_getres(clockid_t clock_id, struct timespec *sp)"
+      }.freeze
+
       def patch_map
         pm = msys_patches
         pm.merge!(super)
@@ -246,7 +261,11 @@ module Tebako
           "ext/openssl/extconf.rb" => OPENSSL_EXTCONF_RB_PATCH,
           # ....................................................
           # Fix the signature of console_win32_vk
-          "ext/io/console/win32_vk.inc" => EXT_IO_CONSOLE_WIN32_VK_INC_PATCH
+          "ext/io/console/win32_vk.inc" => EXT_IO_CONSOLE_WIN32_VK_INC_PATCH,
+          # ....................................................
+          # Rename ruby's clock_gettime/clock_getres fallbacks before the
+          # toolchain build (winpthreads static-inline collision)
+          "win32/win32.c" => WIN32_WIN32_C_CLOCK_PATCH
         }
       end
 

data/lib/tebako/packager/pass2msys_patch.rb

@@ -114,6 +114,9 @@ module Tebako
       "#if defined _MSC_VER && _MSC_VER <= 1200" =>
         "#{PatchLiterals::C_FILE_SUBST_LESS}\n#if defined _MSC_VER && _MSC_VER <= 1200",
       "len = GetCurrentDirectoryW(0, NULL);" => WIN32_WIN32_C_MSYS_SUBST,
+      # Keep the clock renames in sync with Pass1MSysPatch::WIN32_WIN32_C_CLOCK_PATCH:
+      # pass1 applies them for the toolchain build, this pass re-applies them
+      # from pristine sources for the final build
       "clock_gettime(clockid_t clock_id, struct timespec *sp)" =>
         "_dummy_clock_gettime(clockid_t clock_id, struct timespec *sp)",
       "clock_getres(clockid_t clock_id, struct timespec *sp)" =>

data/lib/tebako/packager/patch_helpers.rb

@@ -76,7 +76,9 @@ module Tebako
 
         def recreate(dirname)
           FileUtils.rm_rf(dirname, noop: nil, verbose: nil, secure: true)
-          FileUtils.mkdir(dirname)
+          # mkdir_p: in three-part/prebuilt press flows no cmake configure runs,
+          # so the parent output folder may not exist yet
+          FileUtils.mkdir_p(dirname)
         end
 
         def restore_and_save(fname, strict: true)

data/lib/tebako/runtime_manager.rb

@@ -87,7 +87,7 @@ module Tebako
 
     def initialize(cache_root: nil, mirror: nil, lock_timeout: LOCK_TIMEOUT, retry_delay: RETRY_DELAY)
       @cache_root = cache_root || self.class.default_cache_root
-      @mirror = (mirror || ENV.fetch("TEBAKO_RUNTIME_MIRROR", nil) || DEFAULT_MIRROR).sub(%r{/+\z}, "")
+      @mirror = (mirror || ENV.fetch(mirror_env_var, nil) || default_mirror).sub(%r{/+\z}, "")
       @lock_timeout = lock_timeout
       @retry_delay = retry_delay
     end
@@ -106,7 +106,7 @@ module Tebako
     end
 
     def entries
-      base = File.join(@cache_root, RUNTIMES_DIR)
+      base = File.join(@cache_root, cache_subdir)
       return [] unless Dir.exist?(base)
 
       Dir.children(base).sort.filter_map do |name|
@@ -131,6 +131,29 @@ module Tebako
 
     private
 
+    # ---- extension points for BootstrapManager (tebako-bootstrap release
+    # resolution); overridden there, everything else is shared machinery ----
+
+    def default_mirror
+      DEFAULT_MIRROR
+    end
+
+    def mirror_env_var
+      "TEBAKO_RUNTIME_MIRROR"
+    end
+
+    def index_files
+      INDEX_FILES
+    end
+
+    def cache_subdir
+      RUNTIMES_DIR
+    end
+
+    def release_name
+      "tebako-runtime-ruby"
+    end
+
     def install(executable, ruby_version, platform, tebako_version)
       ref = runtime_ref(ruby_version, platform, tebako_version)
       offline_check(ref, tebako_version)
@@ -146,7 +169,7 @@ module Tebako
 
       Tebako.packaging_error(123, "#{ref} is not cached and downloads are disabled " \
                                   "(release index: #{index_urls(tebako_version).join(", ")}; " \
-                                  "TEBAKO_RUNTIME_MIRROR=#{@mirror})")
+                                  "#{mirror_env_var}=#{@mirror})")
     end
 
     def find_entry(index, ruby_version, platform, tebako_version)
@@ -178,14 +201,14 @@ module Tebako
 
     def fetch_index(tebako_version)
       tried = []
-      INDEX_FILES.each do |name|
+      index_files.each do |name|
         return parse_index(name, fetch_text(index_url(name, tebako_version)), tebako_version)
       rescue IndexUnavailable
         tried << index_url(name, tebako_version)
       rescue DownloadFailed => e
         Tebako.packaging_error(122, e.message)
       end
-      Tebako.packaging_error(124, "tebako-runtime-ruby release v#{tebako_version} provides no usable package " \
+      Tebako.packaging_error(124, "#{release_name} release v#{tebako_version} provides no usable package " \
                                   "index (tried: #{tried.join(", ")})")
     end
 
@@ -333,7 +356,7 @@ module Tebako
     end
 
     def index_urls(tebako_version)
-      INDEX_FILES.map { |name| index_url(name, tebako_version) }
+      index_files.map { |name| index_url(name, tebako_version) }
     end
 
     def package_url(filename, tebako_version)

data/lib/tebako/stitcher.rb

@@ -75,7 +75,10 @@ module Tebako
     FORMAT_DWARFS = 1
     FORMAT_SQUASHFS = 2
     FORMAT_ZIP = 3
-    FORMAT_IDS = (FORMAT_AUTO..FORMAT_ZIP).freeze
+    # Runtime payload slot of a fat package: installed into the shared cache
+    # by the bootstrap at first run, never mounted (tpkg.h TPKG_FORMAT_RUNTIME)
+    FORMAT_RUNTIME = 4
+    FORMAT_IDS = (FORMAT_AUTO..FORMAT_RUNTIME).freeze
 
     # Header field offsets
     OFF_PACKAGE_FLAGS = 14
@@ -89,17 +92,21 @@ module Tebako
       # copy of the runtime at +runtime_path+, writing +output+.
       # lean: true marks the package LEAN and records runtime_ref
       # ("ruby@<ruby_version>;tebako=<tebako_version>"); classic packages
-      # carry an empty runtime_ref.
+      # carry an empty runtime_ref. runtime_sha256 appends ";sha256=<hex>" to
+      # the runtime_ref — the checksum the bootstrap verifies a fat package's
+      # runtime payload slot against before installing it into the cache.
       def stitch(runtime_path, images:, output:, lean: false, ruby_version: nil, # rubocop:disable Metrics/ParameterLists
-                 tebako_version: Tebako::VERSION, launcher_abi: 0)
+                 tebako_version: Tebako::VERSION, launcher_abi: 0, runtime_sha256: nil)
         images = normalize_images(images)
         validate_inputs!(runtime_path, images, lean, ruby_version)
+        validate_runtime_sha256!(runtime_sha256)
 
         FileUtils.mkdir_p(File.dirname(output))
         FileUtils.cp(runtime_path, output)
         FileUtils.chmod(0o755, output)
 
-        append(images, output, package_flags(lean), runtime_ref(lean, ruby_version, tebako_version), launcher_abi)
+        append(images, output, package_flags(lean), runtime_ref(lean, ruby_version, tebako_version, runtime_sha256),
+               launcher_abi)
         resign_if_needed(output)
         output
       end
@@ -157,6 +164,8 @@ module Tebako
         seen = {}
         images.each do |image|
           validate_image!(image)
+          next if image[:format_id] == FORMAT_RUNTIME # payload slots are never mounted
+
           mount = image[:mount_point]
           Tebako.packaging_error(126, "duplicate mount point '#{mount}'") if seen[mount]
 
@@ -166,7 +175,7 @@ module Tebako
 
       def validate_image!(image)
         unless FORMAT_IDS.cover?(image[:format_id])
-          Tebako.packaging_error(126, "invalid format_id #{image[:format_id]} (0..3 expected)")
+          Tebako.packaging_error(126, "invalid format_id #{image[:format_id]} (0..4 expected)")
         end
         return unless image[:mount_point].bytesize >= MOUNT_POINT_LEN
 
@@ -174,14 +183,21 @@ module Tebako
                                "mount point '#{image[:mount_point][0, 32]}...' exceeds #{MOUNT_POINT_LEN - 1} bytes")
       end
 
+      def validate_runtime_sha256!(runtime_sha256)
+        return if runtime_sha256.nil? || runtime_sha256.match?(/\A[0-9a-f]{64}\z/)
+
+        Tebako.packaging_error(126, "runtime_sha256 must be 64 lowercase hex characters")
+      end
+
       def package_flags(lean)
         lean ? FLAG_LEAN : 0
       end
 
-      def runtime_ref(lean, ruby_version, tebako_version)
+      def runtime_ref(lean, ruby_version, tebako_version, runtime_sha256)
         return "" unless lean
 
         ref = "ruby@#{ruby_version};tebako=#{tebako_version}"
+        ref += ";sha256=#{runtime_sha256}" if runtime_sha256
         if ref.bytesize >= RUNTIME_REF_LEN
           Tebako.packaging_error(126, "runtime_ref '#{ref}' exceeds #{RUNTIME_REF_LEN - 1} bytes")
         end

data/lib/tebako/version.rb

@@ -26,5 +26,5 @@
 # POSSIBILITY OF SUCH DAMAGE.
 
 module Tebako
-  VERSION = "0.15.1"
+  VERSION = "0.15.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tebako
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.15.2
 platform: ruby
 authors:
 - Ribose Inc.
@@ -212,6 +212,7 @@ files:
 - include/tebako/tebako-prism.h
 - include/tebako/tpkg.h
 - lib/tebako.rb
+- lib/tebako/bootstrap_manager.rb
 - lib/tebako/build_helpers.rb
 - lib/tebako/cache_manager.rb
 - lib/tebako/cli.rb