ocran 1.4.3 → 1.4.5

data/lib/ocran/direction.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require "rbconfig"
 require "pathname"
+require "set"
 require_relative "refine_pathname"
 require_relative "host_config_helper"
 require_relative "command_output"
@@ -17,26 +18,123 @@ module Ocran
     # - /ruby/vendor_ruby/3.0.0/
     RUBY_LIBRARY_PATH_REGEX = %r{/(ruby/(?:site_ruby/|vendor_ruby/)?\d+\.\d+\.\d+)/?$}i
 
+    # Core libraries provided by glibc and the dynamic loader. These must
+    # never be bundled: they are tightly coupled to the target system's
+    # ld.so, and shipping a foreign copy breaks the dynamic linker. The
+    # libnss_* plugins are dlopened by the target's glibc and must match it.
+    LINUX_SYSTEM_LIBRARY_RE = /\A(?:ld-linux|ld64|libc\.so|libm\.so|libdl\.so|libpthread\.so|librt\.so|libutil\.so|libnsl\.so|libresolv\.so|libmvec\.so|libanl\.so|libBrokenLocale\.so|libnss_)/
+
     include BuildConstants, CommandOutput, HostConfigHelper
 
+    # Packed name of the interpreter when a cosmopolitan Ruby payload is
+    # used (--cosmo-ruby); the source APE is packed under this name.
+    COSMO_RUBY_EXE = "ruby.com"
+
+    # File name extensions of loadable native binaries that a gem may
+    # ship or build. None of them can be loaded by the cosmopolitan Ruby
+    # payload, which is statically linked and has no dlopen.
+    NATIVE_BINARY_EXTENSIONS = %w[.so .bundle .dll].freeze
+
+    # Native binaries a gem ships or has had built for it, i.e. the files
+    # that make it unusable under the cosmopolitan Ruby payload.
+    #
+    # spec.extensions alone does NOT identify a native gem: a precompiled
+    # platform gem (e.g. sqlite3-2.9.5-x86_64-linux-gnu) has an empty
+    # extensions array because nothing is compiled at install time, yet it
+    # ships a prebuilt sqlite3_native.so inside its lib directory. Both the
+    # gem directory and the extension directory (where RubyGems puts the
+    # products of a source build) are scanned.
+    def self.gem_native_binaries(spec)
+      ext_dir =
+        begin
+          spec.extension_dir
+        rescue StandardError
+          nil
+        end
+      pattern = "**/*{#{NATIVE_BINARY_EXTENSIONS.join(",")}}"
+      [spec.gem_dir, ext_dir].compact.uniq.flat_map { |dir|
+        next [] unless File.directory?(dir)
+
+        Dir.glob(pattern, base: dir).map { |rel| Pathname(File.join(dir, rel)) }
+      }.uniq
+    end
+
+    # The feature names a gem is required by, i.e. what has to answer
+    # inside the payload for the payload's own copy to serve in place of
+    # the host gem. RubyGems' convention maps a dash in a gem name to a
+    # directory separator in its primary feature (io-console provides
+    # "io/console"), and both spellings are seen in the wild, so both are
+    # offered as candidates.
+    def self.cosmo_gem_features(spec)
+      [spec.name, spec.name.tr("-", "/")].uniq
+    end
+
+    # Decides how a gem detected on the build host has to be treated when
+    # a cosmopolitan Ruby payload is packed (--cosmo-ruby). Returns a pair
+    # of a disposition and the gem's native binaries:
+    #
+    #   [:pack, []]                  pure Ruby gem, pack it as usual
+    #   [:payload_provides, files]   native, but the payload provides the
+    #                                same library itself: skip the host copy
+    #                                and let the payload's own version serve
+    #   [:incompatible, files]       native and not provided by the payload:
+    #                                the build must fail
+    #
+    # A gem counts as provided by the payload when the payload has a
+    # gemspec of that name, OR when the payload can resolve the gem's
+    # primary feature (+provides_feature+, normally
+    # CosmoToolchain.resolvable_features against the payload). The second
+    # test matters because a gemspec is not what makes a library
+    # requirable: an extension statically linked into the APE, or a
+    # library in its embedded stdlib rather than in /zip/lib/ruby/gems,
+    # answers require with no gemspec at all. Keying only on gemspec names
+    # reports such a library as incompatible and refuses a build that would
+    # have worked - which is what happens to cgi and pathname, both
+    # compiled into the interpreter and both regular native gems on a
+    # recent host Ruby.
+    def self.cosmo_gem_disposition(spec, payload_gem_names, provides_feature = nil)
+      native_files = gem_native_binaries(spec)
+      return [:pack, native_files] if spec.extensions.empty? && native_files.empty?
+
+      if payload_gem_names.include?(spec.name) ||
+         (provides_feature && provides_feature.call(cosmo_gem_features(spec)))
+        [:payload_provides, native_files]
+      else
+        [:incompatible, native_files]
+      end
+    end
+
+    # Human readable reason why a gem counts as native, for build messages.
+    def self.cosmo_native_reason(spec, native_files)
+      reasons = []
+      reasons << "declares native extensions" if spec.extensions.any?
+      if native_files.any?
+        names = native_files.map { |file| File.basename(file) }.uniq
+        reasons << "ships prebuilt binaries (#{names.join(", ")})"
+      end
+      reasons.join(" and ")
+    end
+
     attr_reader :ruby_executable, :rubyopt
 
     def initialize(post_env, pre_env, option)
       @post_env, @pre_env, @option = post_env, pre_env, option
-      @ruby_executable = @option.windowed? ? rubyw_exe : ruby_exe
+      @ruby_executable =
+        if @option.cosmo_ruby
+          COSMO_RUBY_EXE
+        else
+          @option.windowed? ? rubyw_exe : ruby_exe
+        end
 
       # Initializes @rubyopt with the user-intended RUBYOPT environment variable.
       # This ensures that RUBYOPT matches the user's initial settings before any
       # modifications that may occur during script execution.
+      #
+      # -I and -r entries that refer to build-machine paths (including the
+      # `-r<abs path>/bundler/setup` that Bundler adds under `bundle exec`
+      # since Ruby 3.2) are translated or removed at build time by
+      # RubyoptProcessor in #construct.
       @rubyopt = @option.rubyopt || pre_env.env["RUBYOPT"] || ""
-
-      # Remove any absolute path to bundler/setup from RUBYOPT.
-      # When building under `bundle exec`, RUBYOPT contains `-r/absolute/path/bundler/setup`.
-      # That path doesn't exist inside the packed executable's environment, causing Ruby to
-      # print "RubyGems were not loaded" / "did_you_mean was not loaded" warnings on startup.
-      # We strip the flag regardless of install prefix because the gem may live in a user gem
-      # directory that doesn't share a prefix with RbConfig::TOPDIR (e.g. on CI runners).
-      @rubyopt = @rubyopt.gsub(/-r\S*\/bundler\/setup/, "").strip
     end
 
     # Resolves the common root directory prefix from an array of absolute paths.
@@ -65,7 +163,16 @@ module Ocran
 
     def detect_dlls
       if Gem.win_platform?
-        require_relative "library_detector"
+        begin
+          require_relative "library_detector"
+        rescue LoadError => e
+          # LibraryDetector needs fiddle, a bundled gem since Ruby 3.5. In a
+          # Bundler context (e.g. building with --gemfile) requiring it is
+          # refused unless the Gemfile lists fiddle, so degrade to no DLL
+          # auto-detection instead of aborting the build.
+          warning "DLL auto-detection disabled (#{e.message}). Add fiddle to the Gemfile, or use --dll to include DLLs manually."
+          return []
+        end
       else
         require_relative "library_detector_posix"
       end
@@ -84,7 +191,8 @@ module Ocran
         end
       end
       if defined?(Gem)
-        specs += Gem.loaded_specs.values
+        foreign = foreign_bundle_gem_names
+        specs += Gem.loaded_specs.each_value.reject { |spec| foreign.include?(spec.name) }
         # Now, we also detect gems that are not included in Gem.loaded_specs.
         # Therefore, we look for any loaded file from a gem path.
         specs += GemSpecQueryable.detect_gems_from(features, verbose: @option.verbose?)
@@ -94,6 +202,83 @@ module Ocran
       specs
     end
 
+    # The gems RubyGems had already activated for a bundle that is not the
+    # application's, by the time OCRAN started.
+    #
+    # `bundle exec` activates every gem of its bundle before the command it
+    # runs executes a single line, so Gem.loaded_specs describes the build
+    # environment as much as the application. When the two bundles are the
+    # same - `bundle exec ocran app.rb` from the application's own directory,
+    # the ordinary case - that is exactly right and nothing is dropped. When
+    # they differ, packing the build environment's bundle adds tens of
+    # megabytes of code the application can never load: the packaged app runs
+    # under its own Gemfile, so gems from a foreign bundle are dead weight
+    # even when they are packed.
+    #
+    # Only activation is discounted, not use: anything the dependency run
+    # actually loaded is still found through $LOADED_FEATURES by
+    # detect_gems_from, and everything the application's Gemfile names is
+    # added by the Gemfile scan. This is the same rule that already applies
+    # to a build outside Bundler, where --gemfile is what pulls in gems the
+    # dependency run does not load.
+    def foreign_bundle_gem_names
+      @foreign_bundle_gem_names ||=
+        if foreign_build_bundle?
+          verbose "Ignoring #{@pre_env.activated_gems.size} gems activated by the build environment's bundle " \
+                  "#{@pre_env.env["BUNDLE_GEMFILE"]}"
+          @pre_env.activated_gems.to_set
+        else
+          Set.new
+        end
+    end
+
+    # Whether OCRAN itself was started under a bundle other than the one the
+    # application runs under.
+    def foreign_build_bundle?
+      return false unless @pre_env.bundler_setup_loaded?
+
+      build_gemfile = @pre_env.env["BUNDLE_GEMFILE"]
+      return false if build_gemfile.nil? || build_gemfile.empty?
+
+      app_gemfile = @option.application_gemfile
+      return true if app_gemfile.nil?
+
+      !same_file?(build_gemfile, app_gemfile)
+    end
+
+    def same_file?(a, b)
+      File.identical?(a, b) || File.expand_path(a) == File.expand_path(b)
+    end
+
+    # Packed name of the file BUNDLER_SETUP is pointed at.
+    BUNDLER_SETUP_NOOP = Pathname("no_bundler_setup.rb")
+
+    # Keeps the environment of whoever launches the packaged application
+    # from dragging Bundler into it.
+    #
+    # A packaged application carries its own gems and its own Gemfile; the
+    # bundle of the machine it is started from means nothing to it, and
+    # anything of that bundle that survives into the process is fatal rather
+    # than merely wrong - Bundler aborts with GemNotFound as soon as it
+    # cannot materialize gems that were never packed. RUBYOPT is already
+    # overwritten wholesale, but that alone stopped being enough: RubyGems
+    # now requires the file named by BUNDLER_SETUP at interpreter startup,
+    # which is how current Bundler versions set a process up, and
+    # BUNDLE_GEMFILE would still send the application's own
+    # `require "bundler/setup"` at the wrong Gemfile.
+    #
+    # BUNDLER_SETUP names a file to require, so it cannot simply be blanked
+    # - an empty value is still truthy and RubyGems would raise trying to
+    # require it. It is pointed at an empty packed file instead. Bundler
+    # does treat empty BUNDLE_GEMFILE and BUNDLE_LOCKFILE as unset, which is
+    # what lets the application find the Gemfile packed beside it.
+    def neutralize_bundler_env(builder)
+      builder.touch(BUNDLER_SETUP_NOOP)
+      builder.set_env_path("BUNDLER_SETUP", BUNDLER_SETUP_NOOP)
+      builder.export("BUNDLE_GEMFILE", "")
+      builder.export("BUNDLE_LOCKFILE", "")
+    end
+
     def normalized_features
       features = @post_env.loaded_features.map { |feature| Pathname(feature) }
 
@@ -107,10 +292,12 @@ module Ocran
       # because rubygems.rb uses require_relative to load it.
       kernel_require_rel = "rubygems/core_ext/kernel_require.rb"
       unless features.any? { |f| f.to_posix.end_with?(kernel_require_rel) }
-        # Prefer the location alongside the actually-loaded rubygems.rb, fall back to rubylibdir
-        rubygems_feature = features.find { |f| f.to_posix.end_with?("/rubygems.rb") }
-        candidate_dirs = []
-        candidate_dirs << rubygems_feature.dirname if rubygems_feature
+        # Prefer the location alongside the actually-loaded rubygems.rb, fall back to
+        # rubylibdir. Consider every feature ending in "/rubygems.rb", because a plain
+        # suffix match can also hit unrelated files such as bundler's
+        # lib/bundler/source/rubygems.rb (loaded before rubygems.rb under bundle exec);
+        # the existence check below skips candidates without the core_ext file.
+        candidate_dirs = features.select { |f| f.to_posix.end_with?("/rubygems.rb") }.map(&:dirname)
         candidate_dirs << Pathname(RbConfig::CONFIG["rubylibdir"])
         candidate_dirs.each do |base_dir|
           kernel_require_path = base_dir / kernel_require_rel
@@ -140,17 +327,54 @@ module Ocran
       end
     end
 
+    # True when the packed cosmopolitan Ruby can resolve any of the given
+    # features itself, i.e. when a host gem providing them does not have
+    # to be packed. Answers are memoized per feature: probing costs one
+    # run of the payload interpreter, and only native gems the payload has
+    # no gemspec for ever get here.
+    def cosmo_payload_provides_feature?(features)
+      @cosmo_feature_cache ||= {}
+      unknown = features.reject { |feature| @cosmo_feature_cache.key?(feature) }
+      unless unknown.empty?
+        resolved = CosmoToolchain.resolvable_features(@option.cosmo_ruby, unknown)
+        unknown.each { |feature| @cosmo_feature_cache[feature] = resolved.include?(feature) }
+      end
+      features.any? { |feature| @cosmo_feature_cache[feature] }
+    end
+
     def construct(builder)
       # Store the currently loaded files
       features = normalized_features
 
+      # With --cosmo-ruby, run the payload interpreter once on the build
+      # host: this validates that it works, provides its embedded gem
+      # directory (needed for GEM_PATH below) and its version for the
+      # host-vs-payload skew warning. Dependency detection has already
+      # run under the *host* Ruby, so stdlib/gem resolution may differ
+      # when the versions diverge.
+      if @option.cosmo_ruby
+        # Kernel#load, matching Option#load_cosmo_toolchain: the file may
+        # already have been loaded that way at option-parse time, and
+        # require_relative would then run it a second time.
+        load File.expand_path("cosmo_toolchain.rb", __dir__) unless defined? CosmoToolchain
+        @cosmo_ruby_info = CosmoToolchain.query_ruby(@option.cosmo_ruby)
+        say "Packaging cosmopolitan Ruby #{@cosmo_ruby_info[:version]} (#{@option.cosmo_ruby})"
+        if RUBY_VERSION.split(".").take(2) != @cosmo_ruby_info[:version].split(".").take(2)
+          warning "Dependency detection ran under the host Ruby #{RUBY_VERSION}, but the packed cosmopolitan Ruby is #{@cosmo_ruby_info[:version]}; stdlib and gem behavior may differ between these versions"
+        end
+      end
+
       # If net/http was loaded but openssl wasn't (it is only required lazily
       # at the point of an actual HTTPS connection), require it now inside the
       # OCRAN build process so that every transitive dependency — openssl.rb,
       # digest.so, and any other files pulled in by the extension — appears in
       # $LOADED_FEATURES and gets bundled alongside the application.
+      # Skipped with --cosmo-ruby: the payload interpreter carries its own
+      # (statically linked) openssl, and the host's files would be excluded
+      # from the package anyway.
       openssl_so = Pathname(RbConfig::CONFIG["archdir"]) / "openssl.so"
-      if openssl_so.exist? &&
+      if !@option.cosmo_ruby &&
+          openssl_so.exist? &&
           features.any? { |f| f.to_posix.end_with?("/net/http.rb") } &&
           features.none? { |f| f == openssl_so }
         say "Auto-loading openssl (net/http loaded but openssl not yet required)"
@@ -168,40 +392,94 @@ module Ocran
 
       # Add the ruby executable and DLL
       say "Adding ruby executable #{ruby_executable}"
-      builder.copy_to_bin(bindir / ruby_executable, ruby_executable)
-      if libruby_so
-        # On POSIX systems, libruby.so is in libdir; on Windows, it's in bindir
-        libruby_src = Gem.win_platform? ? bindir / libruby_so : libdir / libruby_so
-        builder.copy_to_bin(libruby_src, libruby_so)
-
-        # On POSIX systems, create symlinks (aliases) for libruby.so
-        unless Gem.win_platform?
-          libruby_aliases.each do |libruby_alias|
-            builder.symlink_in_bin(libruby_so, libruby_alias)
+      if @option.cosmo_ruby
+        # The cosmopolitan Ruby APE is fully self-contained: a static
+        # binary with the standard library embedded in its ZIP store
+        # (/zip/lib/ruby/...). No libruby, no shared libraries and no
+        # LD_LIBRARY_PATH are needed — pack the single file and be done.
+        #
+        # Except in ZIP packaging mode, where the output IS that binary and
+        # the application is injected into it: packing a copy of the
+        # interpreter into itself would double the size of the executable
+        # for nothing.
+        if @option.cosmo_zip?
+          say "Injecting the application into the ZIP store of #{@option.cosmo_ruby}"
+        else
+          builder.copy_to_bin(Pathname(@option.cosmo_ruby), ruby_executable)
+        end
+      else
+        ruby_source = bindir / ruby_executable
+        if !Gem.win_platform? && File.binread(ruby_source, 2) == "#!"
+          # On some distros (e.g. Fedora), bindir/ruby is a dispatcher shell
+          # script ("rubypick") rather than the interpreter itself, which
+          # cannot run on a system without Ruby. Pack the currently running
+          # interpreter binary under the expected name instead.
+          real_ruby = Pathname("/proc/self/exe")
+          raise "#{ruby_source} is a wrapper script and the real interpreter could not be determined" unless real_ruby.exist?
+
+          say "#{ruby_source} is a wrapper script; packing #{real_ruby.realpath} instead"
+          builder.copy_to_bin(real_ruby.realpath, ruby_executable)
+        else
+          builder.copy_to_bin(ruby_source, ruby_executable)
+        end
+        if libruby_so
+          # On POSIX systems, libruby.so is in libdir; on Windows, it's in bindir
+          libruby_src = Gem.win_platform? ? bindir / libruby_so : libdir / libruby_so
+          builder.copy_to_bin(libruby_src, libruby_so)
+
+          # On POSIX systems, create symlinks (aliases) for libruby.so
+          unless Gem.win_platform?
+            libruby_aliases.each do |libruby_alias|
+              builder.symlink_in_bin(libruby_so, libruby_alias)
+            end
           end
         end
-      end
 
-      # On POSIX systems, set LD_LIBRARY_PATH to find bundled shared libraries
-      unless Gem.win_platform?
-        extract_bin = File.join(EXTRACT_ROOT, BINDIR.to_s)
-        builder.export("LD_LIBRARY_PATH", extract_bin)
-        if RUBY_PLATFORM.include?("darwin")
-          builder.export("DYLD_LIBRARY_PATH", extract_bin)
+        # On POSIX systems, set LD_LIBRARY_PATH to find bundled shared libraries
+        unless Gem.win_platform?
+          extract_bin = File.join(EXTRACT_ROOT, BINDIR.to_s)
+          builder.export("LD_LIBRARY_PATH", extract_bin)
+          if RUBY_PLATFORM.include?("darwin")
+            builder.export("DYLD_LIBRARY_PATH", extract_bin)
+          end
         end
       end
 
       # Windows-only: Add detected DLLs
       if Gem.win_platform? && @option.auto_detect_dlls?
+        # The Windows loader resolves the imports of a native extension from
+        # the extension's own directory, the application directory of the
+        # packed ruby.exe (bin) plus its SxS assembly (ruby_builtin_dlls),
+        # and the system directories. PATH is not consulted on hardened
+        # systems, and the AddDllDirectory mechanism gems use through
+        # ruby_installer/runtime is not available in a packed app. A detected
+        # DLL that lives anywhere else - a gem's bundled library (e.g.
+        # FreeTDS under tiny_tds' ports/), a devkit's msys64 tree inside the
+        # Ruby prefix, or a directory outside the prefix entirely - is packed
+        # only at a location the loader never searches, and the application
+        # dies with LoadError on machines where nothing masks the gap. So
+        # additionally bundle a copy of every such DLL into bin, next to
+        # ruby.exe, mirroring what the Linux branch below achieves with
+        # LD_LIBRARY_PATH. DLLs from the Windows directory always come from
+        # the target system and are never bundled.
+        windows_dir = Pathname(ENV["SystemRoot"] || "C:/Windows")
+        dlls_in_bin = Set.new
+        add_dll_to_bin = proc do |dll|
+          next if dll.subpath?(bindir) || !dlls_in_bin.add?(dll.basename.to_s.downcase)
+
+          say "Adding detected DLL #{dll} to bin"
+          builder.copy_to_bin(dll, dll.basename)
+        end
+
         detect_dlls.each do |dll|
-          next unless dll.subpath?(exec_prefix) && dll.extname?(".dll") && dll.basename != libruby_so
+          next unless dll.extname?(".dll") && dll.basename != libruby_so
+          next if dll.subpath?(windows_dir)
 
-          say "Adding detected DLL #{dll}"
           if dll.subpath?(exec_prefix)
+            say "Adding detected DLL #{dll}"
             builder.duplicate_to_exec_prefix(dll)
-          else
-            builder.copy_to_bin(dll, dll.basename)
           end
+          add_dll_to_bin.call(dll)
         end
 
         # Proactively include companion DLLs for loaded native extensions.
@@ -209,7 +487,10 @@ module Ocran
         # directory (e.g., libssl-3-x64.dll alongside openssl.so) that are
         # loaded lazily on first use. Scanning .so directories ensures those
         # DLLs are bundled even when the extension is required but not
-        # exercised during the OCRAN dependency scan.
+        # exercised during the OCRAN dependency scan. They also go into bin:
+        # a copy in archdir only helps extensions in archdir itself, while
+        # the same extension packed at a gem path (openssl and psych are
+        # gems since Ruby 3.x) resolves its imports from bin.
         features.select { |f| f.extname?(".so") && f.subpath?(exec_prefix) }
                 .map(&:dirname).uniq
                 .each do |dir|
@@ -217,6 +498,45 @@ module Ocran
             next unless path.file? && path.extname?(".dll")
             say "Adding companion DLL #{path}"
             builder.duplicate_to_exec_prefix(path)
+            add_dll_to_bin.call(path)
+          end
+        end
+      end
+
+      # Linux: bundle detected shared libraries (e.g. libyaml, libssl,
+      # libcrypt) next to libruby so the executable also runs on systems
+      # where they are missing or have different sonames (the stub already
+      # points LD_LIBRARY_PATH at the packed bin directory). Core glibc
+      # libraries and the loader are never bundled - they must come from the
+      # target system. Ruby native extensions are packed as features, not
+      # here. Not needed with --cosmo-ruby: the APE payload is static.
+      if RUBY_PLATFORM.include?("linux") && @option.auto_detect_dlls? && !@option.cosmo_ruby
+        feature_set = features.to_set
+        feature_realpaths = features.filter_map { |f| f.realpath rescue nil }.to_set
+        # Ruby native extensions live in these directories and are packed as
+        # features; they must not be duplicated into bin.
+        ruby_arch_dirs = RbConfig::CONFIG.values_at("archdir", "sitearchdir", "vendorarchdir")
+          .compact.map { |dir| Pathname(dir) }
+        detect_dlls.each do |dll|
+          basename = dll.basename.to_s
+          next unless basename.match?(/\.so(\.|\z)/)
+          next if basename.match?(LINUX_SYSTEM_LIBRARY_RE)
+          # libruby is packed with its aliases already
+          next if basename.start_with?("libruby")
+          next if feature_set.include?(dll) || feature_realpaths.include?(dll)
+          next if ruby_arch_dirs.any? { |dir| dll.subpath?(dir) } || dll.to_posix.match?(%r{/gems/})
+          next unless dll.file?
+
+          say "Adding detected shared library #{dll}"
+          builder.copy_to_bin(dll, basename)
+          # The loader may request a library by a less specific soname than
+          # the fully versioned file name recorded in the memory map (e.g.
+          # libssl.so.3 for libssl.so.3.2.4). Provide symlink aliases for
+          # each shorter version suffix.
+          alias_name = basename
+          while (shorter = alias_name.sub(/\.\d+[^.]*\z/, "")) != alias_name && shorter.include?(".so")
+            builder.symlink_in_bin(basename, shorter)
+            alias_name = shorter
           end
         end
       end
@@ -261,6 +581,11 @@ module Ocran
         end
       end
 
+      # Gem directories whose packing was skipped because the cosmopolitan
+      # Ruby payload provides the gem itself; loaded features from these
+      # directories must not be packed either.
+      cosmo_skipped_gem_dirs = []
+
       # Searches for features that are loaded from gems, then produces a
       # list of files included in those gems' manifests. Also returns a
       # list of original features that caused those gems to be included.
@@ -275,13 +600,119 @@ module Ocran
           next []
         end
 
+        if @option.cosmo_ruby
+          # Default gems of the *host* Ruby are part of its stdlib; the
+          # cosmopolitan Ruby ships its own stdlib and default/bundled
+          # gems in its embedded ZIP store, so do not pack them (a host
+          # 3.x copy would shadow the payload's version).
+          if spec.respond_to?(:default_gem?) && spec.default_gem?
+            verbose "Skipping default gem #{spec.full_name} (provided by the cosmopolitan Ruby's embedded stdlib)"
+            next []
+          end
+          # Native gems compile (or were precompiled) against a host Ruby
+          # ABI and platform; they cannot load under the x86_64-cosmo
+          # payload, which is statically linked and cannot dlopen. This
+          # covers both source-installed gems (spec.extensions) and
+          # precompiled platform gems, which declare no extensions but
+          # ship their .so inside the gem directory.
+          # When the payload provides the same gem itself (e.g. json,
+          # psych are statically linked into the APE), skip the host copy
+          # so the payload's own version is used — packing the host .rb
+          # files would shadow the payload's and could mismatch the
+          # linked-in C extension. Otherwise fail clearly rather than
+          # produce a broken executable.
+          disposition, native_files = self.class.cosmo_gem_disposition(
+            spec, @cosmo_ruby_info[:gem_names], method(:cosmo_payload_provides_feature?)
+          )
+          if disposition != :pack
+            reason = self.class.cosmo_native_reason(spec, native_files)
+            if disposition == :payload_provides
+              provided =
+                if @cosmo_ruby_info[:gem_names].include?(spec.name)
+                  "its own #{spec.name}"
+                else
+                  "#{spec.name} without a gemspec (linked in, or part of its embedded stdlib)"
+                end
+              say "Skipping native gem #{spec.full_name} (#{reason}): the cosmopolitan Ruby provides #{provided}"
+              cosmo_skipped_gem_dirs << Pathname(spec.gem_dir) if File.directory?(spec.gem_dir)
+              ext_dir =
+                begin
+                  spec.extension_dir
+                rescue StandardError
+                  nil
+                end
+              cosmo_skipped_gem_dirs << Pathname(ext_dir) if ext_dir && File.directory?(ext_dir)
+              next []
+            end
+            raise "Gem #{spec.full_name} is native (#{reason}) and cannot run under the packed cosmopolitan Ruby (x86_64-cosmo, static): exclude the gem or package without --cosmo-ruby"
+          end
+        end
+
         # Add gemspec files
+        local_gem_dir = nil
         if spec_file.subpath?(exec_prefix)
           builder.duplicate_to_exec_prefix(spec_file)
         elsif (gem_path = GemSpecQueryable.find_gem_path(spec_file))
           builder.duplicate_to_gem_home(spec_file, gem_path)
         else
-          raise "Gem spec #{spec_file} does not exist in the Ruby installation. Don't know where to put it."
+          # Local development gems (Bundler `gemspec` or `path:` directives)
+          # keep their gemspec inside the project tree, outside both the Ruby
+          # installation and every gem path, so there is no installed gem
+          # layout to mirror. Pack them into GEMDIR as if they were installed
+          # there: generate the spec from the in-memory specification (the
+          # on-disk gemspec often uses dynamic constructs such as
+          # `git ls-files` that would fail in the packed app) and pack the
+          # gem's files under gems/<full_name>/ below.
+          say "Including local development gem #{spec.full_name} from #{spec_file.dirname}"
+          local_gem_dir = Pathname(spec.gem_dir)
+          builder.copy_to_gem(generate_gemspec_file(spec), Pathname("specifications") / "#{spec.full_name}.gemspec")
+          # RubyGems refuses to activate a gem with extensions unless its
+          # gem.build_complete marker exists. The extension files themselves
+          # are packed via the loaded features or the extension-dir mirroring
+          # below.
+          if spec.extensions.any?
+            api_version = Gem.respond_to?(:extension_api_version) ? Gem.extension_api_version : Gem.ruby_api_version
+            builder.touch(GEMDIR / "extensions" / Gem::Platform.local.to_s / api_version / spec.full_name / "gem.build_complete")
+          end
+        end
+
+        spec_dir = spec_file.dirname
+        default_spec = spec_dir.basename.to_s == "default"
+        # The gem's base directory: specs live in <base_dir>/specifications[/default]
+        base_dir = default_spec ? spec_dir.dirname.dirname : spec_dir.dirname
+        # Relative packed location of base_dir; nil when the gem lives outside
+        # the Ruby prefix, in which case its files are packed under GEMDIR
+        # with the same layout.
+        packed_base = base_dir.subpath?(exec_prefix) ? base_dir.relative_path_from(exec_prefix) : GEMDIR
+
+        # Default gemspecs live in a "specifications/default" directory, which
+        # RubyGems only scans under Gem.default_dir. On rubies with a
+        # compiled-in absolute prefix (e.g. distro Ruby on Fedora), that path
+        # points to the build host and does not exist on the target system, so
+        # activating such a gem (e.g. via a binstub) fails. Also place a copy
+        # in the regular specifications directory of the same packed base
+        # directory, where GEM_PATH makes it discoverable and its require
+        # paths resolve to the packed gem files.
+        if !Gem.win_platform? && default_spec
+          builder.cp(spec_file, packed_base / "specifications" / spec_file.basename)
+        end
+
+        # Native-extension gems record successful builds in a gem.build_complete
+        # marker under <base_dir>/extensions/...; without it RubyGems refuses to
+        # activate the gem ("Ignoring x because its extensions are not built").
+        # The marker can be absent from the packed tree either because the
+        # distro relocates it (e.g. Fedora keeps it under /usr/lib64/gems/ruby
+        # via a default_ext_dir_for override) or because the gem is a default
+        # gem, which is exempt from the check on the host while its packed
+        # regular-spec copy is not. Recreate the marker where RubyGems expects
+        # it at runtime.
+        if !Gem.win_platform? && spec.extensions.any?
+          api_version = Gem.respond_to?(:extension_api_version) ? Gem.extension_api_version : Gem.ruby_api_version
+          packed_ext_dir = Pathname("extensions") / Gem::Platform.local.to_s / api_version / spec.full_name
+          host_marker = Pathname(spec.gem_build_complete_path)
+          if default_spec || (File.exist?(host_marker) && !host_marker.subpath?(base_dir))
+            builder.touch(packed_base / packed_ext_dir / "gem.build_complete")
+          end
         end
 
         # Determine which set of files to include for this particular gem
@@ -292,6 +723,9 @@ module Ocran
 
         verbose "\tgem_dir: #{spec.gem_dir}"
         verbose "\tgem_dir exists: #{File.directory?(spec.gem_dir)}"
+        unless File.directory?(spec.gem_dir)
+          verbose "\tGem directory does not exist (default gem?); packing loaded files via load path instead"
+        end
         loaded_matches = include.include?(:loaded) ? features.select { |f| f.subpath?(spec.gem_dir) } : []
         verbose "\t:loaded candidates in features: #{loaded_matches.size}"
         loaded_matches.each { |f| verbose "\t  loaded: #{f}" }
@@ -299,6 +733,20 @@ module Ocran
         verbose "\t:files (resource_files) count: #{resource_count}"
 
         actual_files = spec.find_gem_files(include, features)
+
+        # Safety net: gems reaching this point are pure Ruby as far as
+        # their gem and extension directories go (see the disposition
+        # check above), but a file list can still pull in a native binary
+        # from elsewhere. It cannot load under the cosmopolitan payload,
+        # so exclude it loudly.
+        if @option.cosmo_ruby
+          native_files = actual_files.select { |f| NATIVE_BINARY_EXTENSIONS.any? { |ext| f.extname?(ext) } }
+          if native_files.any?
+            warning "Gem #{spec.full_name} contains native binaries that cannot run under the packed cosmopolitan Ruby; excluding: #{native_files.map(&:basename).join(", ")}"
+            actual_files -= native_files
+          end
+        end
+
         say "\t#{actual_files.size} files, #{actual_files.sum(0, &:size)} bytes"
 
         # Decide where to put gem files, either the system gem folder, or
@@ -308,19 +756,86 @@ module Ocran
             builder.duplicate_to_exec_prefix(gemfile)
           elsif (gem_path = GemSpecQueryable.find_gem_path(gemfile))
             builder.duplicate_to_gem_home(gemfile, gem_path)
+          elsif local_gem_dir && gemfile.subpath?(local_gem_dir)
+            # Mirror local development gem files into the packed GEM_HOME
+            # under the gem directory matching the generated specification.
+            builder.copy_to_gem(gemfile, Pathname("gems") / spec.full_name / gemfile.relative_path_from(local_gem_dir))
           else
             raise "Don't know where to put gemfile #{gemfile}"
           end
         end
 
+        # When a distro builds native extensions outside the gem's base_dir
+        # and loads them from there (e.g. Fedora's /usr/lib64/gems/ruby), the
+        # loaded .so would be packed at a mirror path that is never on the
+        # runtime load path. Pack such loaded extension files ONLY into the
+        # extension directory RubyGems computes at runtime, which gem
+        # activation puts on the load path. Appended to actual_files after
+        # the generic copy above so they are claimed as gem files (and thus
+        # excluded from the plain feature packing, where a bare .so on
+        # RUBYLIB would shadow the gem) without also being mirrored at their
+        # host location. The extension dir and the load location may be
+        # aliased via symlinks in either direction, so match features against
+        # the extension dir by realpath both ways.
+        if !Gem.win_platform? && spec.extensions.any?
+          host_ext_dir = Pathname(spec.extension_dir)
+          if host_ext_dir.directory? && !host_ext_dir.subpath?(base_dir)
+            alias_map = {}
+            host_ext_dir.find.select(&:file?).each do |entry|
+              real = begin
+                entry.realpath
+              rescue SystemCallError
+                next
+              end
+              alias_map[real] = entry
+            end
+            features.each do |feature|
+              real = begin
+                feature.realpath
+              rescue SystemCallError
+                feature
+              end
+              entry = if feature.subpath?(host_ext_dir)
+                        feature
+                      elsif real.subpath?(host_ext_dir)
+                        real
+                      else
+                        alias_map[feature] || alias_map[real]
+                      end
+              next unless entry
+
+              builder.cp(feature, packed_base / packed_ext_dir / entry.relative_path_from(host_ext_dir))
+              actual_files << feature
+            end
+          end
+        end
+
         actual_files
       end
       gem_files.uniq!
 
-      features -= gem_files
+      # On some distros parts of a gem are reachable through symlinks at other
+      # locations (e.g. Fedora symlinks /usr/share/ruby/psych.rb into the
+      # psych gem directory), so a feature and a packed gem file can denote
+      # the same file under different paths. Compare realpaths when removing
+      # gem files from the feature list; otherwise a stdlib-level duplicate
+      # would be packed as well and shadow the packed gem at runtime.
+      gem_file_set = (gem_files + gem_files.filter_map { |file| file.realpath rescue nil }).to_set
+      features = features.reject do |feature|
+        next true if gem_file_set.include?(feature)
+
+        real = begin
+          feature.realpath
+        rescue SystemCallError
+          nil
+        end
+        real && gem_file_set.include?(real)
+      end
 
       # If requested, add all ruby standard libraries
-      if @option.add_all_core?
+      if @option.add_all_core? && @option.cosmo_ruby
+        say "Skipping host core libraries (--add-all-core): the cosmopolitan Ruby embeds its own standard library"
+      elsif @option.add_all_core?
         say "Will include all ruby core libraries"
         all_core_dir.each do |path|
           # Match the load path against standard library, site_ruby, and vendor_ruby paths
@@ -336,7 +851,10 @@ module Ocran
       end
 
       # Include encoding support files
-      if @option.add_all_encoding?
+      if @option.cosmo_ruby
+        # Encoding extensions are statically linked into the payload.
+        say "Encoding support is embedded in the cosmopolitan Ruby"
+      elsif @option.add_all_encoding?
         @post_env.load_path.each do |load_path|
           load_path = Pathname(@post_env.expand_path(load_path))
           next unless load_path.subpath?(exec_prefix)
@@ -374,6 +892,23 @@ module Ocran
       pre_working_directory = Pathname(@pre_env.pwd)
       working_directory = Pathname(@post_env.pwd)
       features.each do |feature|
+        # With --cosmo-ruby, files of the host Ruby installation must not
+        # be packed: the payload interpreter resolves the standard library
+        # from its embedded ZIP store, and a packed host-version copy (or
+        # a host-ABI native extension) would be wrong for it.
+        if @option.cosmo_ruby
+          if feature.subpath?(exec_prefix)
+            verbose "\tlibfile: #{feature} -> skipped (host Ruby installation; the cosmopolitan Ruby uses its embedded stdlib)"
+            next
+          elsif cosmo_skipped_gem_dirs.any? { |dir| feature.subpath?(dir) }
+            verbose "\tlibfile: #{feature} -> skipped (gem provided by the cosmopolitan Ruby)"
+            next
+          elsif feature.extname?(".so") || feature.extname?(".bundle")
+            warning "Excluding native extension file #{feature}: native extensions cannot run under the packed cosmopolitan Ruby"
+            next
+          end
+        end
+
         load_path = @post_env.find_load_path(feature)
         if load_path.nil?
           verbose "\tlibfile: #{feature} -> src (no load path)"
@@ -488,8 +1023,24 @@ module Ocran
         end
       end
 
+      # Translate -I and -r entries in RUBYOPT that refer to build-machine
+      # paths into the packed layout (GitHub issue #20). Ruby cannot parse
+      # quoted arguments inside RUBYOPT and the runtime extraction directory
+      # may contain spaces, so instead of rewriting the paths inside RUBYOPT
+      # the translated entries are applied by a generated launcher script
+      # (see generate_rubyopt_launcher) where they become plain Ruby string
+      # literals.
+      require_relative "rubyopt_processor"
+      rubyopt_result = RubyoptProcessor.new(rubyopt).translate do |path|
+        packed_rubyopt_path(Pathname(path).cleanpath, inst_src_prefix)
+      end
+      rubyopt_result.dropped.each do |entry|
+        say "Removing #{entry} from RUBYOPT (path is not part of the package)"
+      end
+
       # Set environment variable
-      builder.export("RUBYOPT", rubyopt)
+      builder.export("RUBYOPT", rubyopt_result.rubyopt)
+      neutralize_bundler_env(builder)
       # Add the load path that are required with the correct path after
       # src_prefix was adjusted.
       load_path = src_load_path.map { |path| SRCDIR / path.relative_path_from(inst_src_prefix) }.uniq
@@ -499,14 +1050,19 @@ module Ocran
       # host, which doesn't exist on other systems (e.g., Docker with no Ruby).
       # By adding the extract-dir equivalents of rubylibdir, sitelibdir, etc. to
       # RUBYLIB, Ruby can find rubygems and the standard library in the packed tree.
-      unless Gem.win_platform?
-        core_lib_paths = all_core_dir
+      # Not with --cosmo-ruby: the host stdlib is not packed at all, and the
+      # payload finds its own stdlib in its embedded ZIP store.
+      unless Gem.win_platform? || @option.cosmo_ruby
+        # Use the build Ruby's actual default load path in addition to the
+        # RbConfig directories: some distros compile in extra entries that
+        # RbConfig does not expose (e.g. Fedora's /usr/share/rubygems, where
+        # rubygems.rb lives outside rubylibdir).
+        default_load_paths = @pre_env.load_path.map { |dir| Pathname(@pre_env.expand_path(dir)) }
+        archdir = Pathname(RbConfig::CONFIG["archdir"])
+        core_lib_paths = (default_load_paths + all_core_dir + [archdir])
           .select { |dir| dir.subpath?(exec_prefix) }
           .map { |dir| dir.relative_path_from(exec_prefix) }
-        archdir = Pathname(RbConfig::CONFIG["archdir"])
-        if archdir.subpath?(exec_prefix)
-          core_lib_paths << archdir.relative_path_from(exec_prefix)
-        end
+          .uniq
         load_path = core_lib_paths + load_path
       end
 
@@ -515,23 +1071,117 @@ module Ocran
 
       gem_paths = [GEMDIR]
       # Gems installed under the Ruby prefix (exec_prefix) have their specs and
-      # extension dirs placed there via duplicate_to_exec_prefix. Include
-      # Gem.default_dir (relative to exec_prefix) in GEM_PATH so RubyGems can
-      # find and activate them at runtime. This is required on both Windows
-      # (e.g. fxruby/fox16 whose fox16_c.so lives in extension_dir under the
-      # Ruby prefix) and POSIX (e.g. error_highlight default gems).
-      default_gem_dir = Pathname(Gem.default_dir)
-      if default_gem_dir.subpath?(exec_prefix)
-        gem_paths << default_gem_dir.relative_path_from(exec_prefix)
+      # extension dirs placed there via duplicate_to_exec_prefix. Include every
+      # Gem.path entry located under exec_prefix (relative to it) in GEM_PATH so
+      # RubyGems can find and activate them at runtime. This is required on both
+      # Windows (e.g. fxruby/fox16 whose fox16_c.so lives in extension_dir under
+      # the Ruby prefix) and POSIX (e.g. error_highlight default gems). Distros
+      # can split gems over several such directories - e.g. Fedora uses
+      # /usr/share/gems for RPM-packaged (default) gems and /usr/local/share/gems
+      # for user-installed ones - so Gem.default_dir alone is not enough.
+      prefix_gem_dirs = (Gem.path.map { |dir| Pathname(dir) } + [Pathname(Gem.default_dir)])
+        .select { |dir| dir.subpath?(exec_prefix) }
+        .map { |dir| dir.relative_path_from(exec_prefix) }
+        .uniq
+      gem_paths += prefix_gem_dirs
+      # RubyGems probes the default gem dir for writability at startup and
+      # prints "Can't determine writability of default gem path" on stderr
+      # when the directory does not exist in the packed layout - so always
+      # create the packed prefix gem dirs, even when no specs landed there.
+      prefix_gem_dirs.each { |dir| builder.mkdir(dir) }
+      if @option.cosmo_ruby
+        # When GEM_PATH is set, RubyGems no longer scans its compiled-in
+        # default directory — which for the cosmopolitan Ruby is the /zip
+        # store inside the binary, where its bundled gems live. Keep it
+        # reachable by appending it explicitly.
+        gem_paths << @cosmo_ruby_info[:default_gem_dir]
       end
       builder.set_env_path("GEM_PATH", *gem_paths)
 
       # Add the opcode to launch the script
       installed_ruby_exe = BINDIR / ruby_executable
       target_script = builder.resolve_source_path(@option.script, inst_src_prefix)
+      if rubyopt_result.translated?
+        target_script = generate_rubyopt_launcher(builder, target_script, rubyopt_result)
+      end
       builder.exec(installed_ruby_exe, target_script, *@option.argv)
     end
 
+    # Maps an absolute build-machine path to its location (relative to the
+    # extraction root) inside the packed application, mirroring where
+    # #construct places files. Returns nil when the path is not packed.
+    def packed_rubyopt_path(path, src_prefix)
+      require_relative "gem_spec_queryable"
+
+      if path.subpath?(exec_prefix)
+        path.relative_path_from(exec_prefix)
+      elsif (gem_path = GemSpecQueryable.find_gem_path(path))
+        GEMDIR / path.relative_path_from(gem_path)
+      elsif path.subpath?(src_prefix)
+        SRCDIR / path.relative_path_from(src_prefix)
+      end
+    end
+    private :packed_rubyopt_path
+
+    RUBYOPT_LAUNCHER_NAME = "ocran-rubyopt-launcher.rb"
+
+    # Writes a launcher script next to the packed application script that
+    # applies the translated RUBYOPT -I/-r entries (as plain Ruby string
+    # literals resolved against the extraction directory at runtime) and
+    # then loads the original script. Returns the packed path of the
+    # launcher, which becomes the script the stub executes.
+    def generate_rubyopt_launcher(builder, target_script, result)
+      say "Generating launcher script for RUBYOPT entries with translated paths"
+      launcher_target = target_script.dirname / RUBYOPT_LAUNCHER_NAME
+
+      # Relative path from the launcher's directory up to the extraction root.
+      depth = target_script.dirname.each_filename.count { |name| name != "." }
+      root_rel = depth.zero? ? "." : ([".."] * depth).join("/")
+
+      lines = []
+      lines << "# frozen_string_literal: true"
+      lines << "# Generated by OCRAN. Applies -I/-r options that were given in RUBYOPT"
+      lines << "# with build-machine paths, translated to the extraction directory."
+      lines << "# They cannot remain in RUBYOPT because Ruby does not support quoting"
+      lines << "# there and the extraction path may contain spaces."
+      lines << "ocran_root = File.expand_path(#{root_rel.dump}, __dir__)"
+      lines << "$0 = File.expand_path(#{target_script.basename.to_s.dump}, __dir__)"
+      result.load_paths.reverse_each do |dir|
+        lines << "$LOAD_PATH.unshift(File.expand_path(#{dir.to_posix.dump}, ocran_root))"
+      end
+      result.requires.each do |feature|
+        lines << "require File.expand_path(#{feature.to_posix.dump}, ocran_root)"
+      end
+      lines << "load $0"
+
+      require "tempfile"
+      launcher_file = Tempfile.new(["ocran-rubyopt-launcher", ".rb"])
+      launcher_file.write(lines.join("\n") + "\n")
+      launcher_file.close
+      verbose File.read(launcher_file.path)
+      # Keep a reference so the temporary file survives until the build
+      # finishes; the Inno Setup builder reads source files only when the
+      # installer is compiled, after #construct has returned.
+      @rubyopt_launcher_file = launcher_file
+
+      builder.cp(launcher_file.path, launcher_target)
+      launcher_target
+    end
+    private :generate_rubyopt_launcher
+    # Writes the in-memory gem specification to a temporary file and returns
+    # the file's path, for packing gemspecs that cannot be copied verbatim
+    # from disk (e.g. local development gems). The Tempfile object is
+    # retained because some builders (e.g. InnoSetupScriptBuilder) read
+    # their source files only after construction has completed.
+    def generate_gemspec_file(spec)
+      require "tempfile"
+      file = Tempfile.new(["#{spec.full_name}-", ".gemspec"])
+      file.write(spec.to_ruby)
+      file.close
+      (@generated_gemspec_files ||= []) << file
+      file.path
+    end
+
     def to_proc
       method(:construct).to_proc
     end
@@ -546,8 +1196,13 @@ module Ocran
         title: @option.output_executable.basename.sub_ext("")
       )
 
+      # Record the launch events (exports + exec) so they can be replayed
+      # into the wrapper stub executable below.
+      require_relative "launcher_event_recorder"
+      recorder = LauncherEventRecorder.new(launcher_builder)
+
       require_relative "build_facade"
-      builder = BuildFacade.new(iss_builder, launcher_builder)
+      builder = BuildFacade.new(iss_builder, recorder)
 
       if @option.icon_filename
         builder.cp(@option.icon_filename, File.basename(@option.icon_filename))
@@ -560,22 +1215,84 @@ module Ocran
       verbose File.read(launcher_path)
       builder.cp(launcher_path, "launcher.bat")
 
-      say "Build inno setup script file"
-      iss_path = iss_builder.build
-      verbose File.read(iss_path)
+      require "tmpdir"
+      Dir.mktmpdir("ocran") do |tmpdir|
+        if @option.wrapper_exe?
+          # Wrapper executable (pre-1.4/OCRA behavior): a small stub without
+          # embedded files that runs the installed application directly from
+          # {app}. It is installed next to the application files so that user
+          # Inno Setup scripts can reference it by the --output name, e.g. in
+          # [Run]/[UninstallRun] entries or for Windows service registration.
+          wrapper_path = Pathname(tmpdir) / @option.output_executable.basename
+          build_wrapper_exe(wrapper_path) { |stub| recorder.replay(stub) }
+          builder.cp(wrapper_path, wrapper_path.basename)
+        end
+
+        say "Build inno setup script file"
+        iss_path = iss_builder.build
+        verbose File.read(iss_path)
 
-      say "Running Inno Setup Command-Line compiler (ISCC)"
-      iss_builder.compile(verbose: @option.verbose?)
+        say "Running Inno Setup Command-Line compiler (ISCC)"
+        iss_builder.compile(verbose: @option.verbose?)
+      end
 
       say "Finished building installer file"
     end
 
+    # Returns the path to the stub built from source with cosmocc when
+    # --cosmo was given, or nil to use the pre-built stub shipped with
+    # the gem. The build result is memoized (and CosmoToolchain caches
+    # compiled stubs across runs), so multiple stubs per build (e.g.
+    # wrapper executables) compile at most once.
+    def cosmo_stub_path
+      return nil unless @option.cosmo_cc
+
+      @cosmo_stub_path ||= begin
+        load File.expand_path("cosmo_toolchain.rb", __dir__) unless defined? CosmoToolchain
+        say "Building launcher stub from source with cosmocc (#{@option.cosmo_cc})"
+        path = CosmoToolchain.build_stub(@option.cosmo_cc)
+        say "Using APE stub #{path}"
+        path
+      end
+    end
+
+    # Builds the small RUN_IN_EXE_DIR wrapper stub that starts the deployed
+    # application directly from the directory the wrapper resides in.
+    def build_wrapper_exe(wrapper_path)
+      require_relative "stub_builder"
+      say "Build wrapper executable #{wrapper_path.basename}"
+      StubBuilder.new(wrapper_path,
+                      chdir_before: @option.chdir_before?,
+                      chdir_to_exe_dir: @option.chdir_exe_dir?,
+                      debug_mode: @option.enable_debug_mode?,
+                      gui_mode: @option.windowed?,
+                      icon_path: @option.icon_filename,
+                      run_in_exe_dir: true,
+                      stub_path: cosmo_stub_path) do |stub|
+        yield(stub)
+      end
+    end
+
     def build_output_dir(path)
       require_relative "dir_builder"
 
       path = Pathname(path)
       say "Building directory #{path}"
-      DirBuilder.new(path, &to_proc)
+      builder = DirBuilder.new(path, &to_proc)
+
+      if @option.wrapper_exe?
+        # Same wrapper as in Inno Setup builds: a doubleclickable executable
+        # next to the launch script, usable e.g. for Windows service
+        # registration from an unpacked zip. Disable with --no-wrapper-exe.
+        build_wrapper_exe(path / @option.output_executable.basename) do |stub|
+          builder.env.each { |name, value| stub.export(name, value) }
+          if builder.exec_args
+            image, script, argv = builder.exec_args
+            stub.exec(image, script, *argv)
+          end
+        end
+      end
+
       say "Finished building directory #{path}"
     end
 
@@ -609,11 +1326,13 @@ module Ocran
 
       StubBuilder.new(executable_path,
                       chdir_before: @option.chdir_before?,
+                      chdir_to_exe_dir: @option.chdir_exe_dir?,
                       debug_extract: @option.enable_debug_extract?,
                       debug_mode: @option.enable_debug_mode?,
                       enable_compression: @option.enable_compression?,
                       gui_mode: false,
                       icon_path: nil,
+                      stub_path: cosmo_stub_path,
                       &to_proc) => builder
 
       if @option.icon_filename
@@ -649,6 +1368,40 @@ module Ocran
       say "Finished building #{bundle_path} (#{builder.data_size} bytes decompressed)"
     end
 
+    # Builds the executable by copying the cosmopolitan Ruby and injecting
+    # the application into its ZIP store (--cosmo-ruby with an interpreter
+    # that runs an embedded /zip/main.rb). No compiler runs, no launcher
+    # stub is involved, and the resulting binary unpacks nothing when it
+    # starts.
+    def build_cosmo_zip_exe
+      require_relative "zip_payload_builder"
+
+      output = @option.output_executable
+      ZipPayloadBuilder.new(output,
+                            cosmo_ruby: @option.cosmo_ruby,
+                            chdir_before: @option.chdir_before?,
+                            debug_mode: @option.enable_debug_mode?,
+                            &to_proc) => builder
+
+      builder.ignored_symlinks.each do |link_path, target|
+        verbose "Skipping symlink #{link_path} -> #{target} (ZIP members cannot be symlinks)"
+      end
+
+      if @option.icon_filename
+        warning "--icon has no effect in this mode: the executable is a copy of the cosmopolitan Ruby, whose resources OCRAN does not rewrite"
+      end
+      if @option.enable_debug_extract?
+        warning "--debug-extract has no effect in this mode: nothing is extracted, the application is read from the executable's own ZIP store"
+      end
+
+      _, _, unsupported = ZipPayloadBuilder.parse_rubyopt(rubyopt)
+      unless unsupported.empty?
+        warning "RUBYOPT #{unsupported.join(" ")} cannot be applied when the application is packed into the interpreter's ZIP store (the interpreter is already running); only -I and -r are replayed"
+      end
+
+      say "Finished building #{output} (#{output.size} bytes, #{builder.data_size} bytes of application data)"
+    end
+
     def build_stab_exe
       require_relative "stub_builder"
 
@@ -658,11 +1411,13 @@ module Ocran
 
       StubBuilder.new(@option.output_executable,
                       chdir_before: @option.chdir_before?,
+                      chdir_to_exe_dir: @option.chdir_exe_dir?,
                       debug_extract: @option.enable_debug_extract?,
                       debug_mode: @option.enable_debug_mode?,
                       enable_compression: @option.enable_compression?,
                       gui_mode: @option.windowed?,
                       icon_path: @option.icon_filename,
+                      stub_path: cosmo_stub_path,
                       &to_proc) => builder
       say "Finished building #{@option.output_executable} (#{@option.output_executable.size} bytes)"
       say "After decompression, the data will expand to #{builder.data_size} bytes."