ocran 1.4.4 → 1.4.5

data/lib/ocran/zip_payload_builder.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+require "pathname"
+require "fileutils"
+require_relative "build_constants"
+require_relative "zip_writer"
+
+module Ocran
+  # Builder that packages an application by INJECTING it into the ZIP store
+  # of a cosmopolitan Ruby APE, instead of building a launcher stub that
+  # unpacks a temporary directory at every start.
+  #
+  # A CosmoRuby build auto-runs the member /zip/main.rb of its own archive
+  # when there is one, passing the command line through as ARGV. So a
+  # complete application is: a byte-for-byte copy of ruby.com, plus the
+  # application's files, plus a generated main.rb that prepares the
+  # environment and loads the real script. Nothing is compiled at packaging
+  # time (no cosmocc) and nothing is written to disk at run time (no
+  # extraction, no temp directory).
+  #
+  # Layout inside the archive:
+  #
+  #   /zip/main.rb                generated bootstrap, the entry point
+  #   /zip/ocran/src/...          the application's own files
+  #   /zip/ocran/gems/...         packed pure-Ruby gems (GEM_HOME/GEM_PATH)
+  #   /zip/ocran/lib/ruby/...     files packed relative to the Ruby prefix
+  #
+  # Everything except main.rb lives under the "ocran/" prefix because the
+  # interpreter's own standard library already occupies /zip/lib/ruby and
+  # /zip/bin: a shared namespace would let a packed file shadow part of the
+  # interpreter. The prefix makes collisions structurally impossible, and
+  # it is the same tree the extraction mode would have written to a temp
+  # directory, so Direction needs no separate layout.
+  class ZipPayloadBuilder
+    include BuildConstants
+
+    # Where the interpreter maps its embedded archive.
+    ZIP_ROOT = "/zip"
+    # Root of the packed application inside the archive.
+    APP_ROOT = "#{ZIP_ROOT}/ocran"
+    # Archive member the interpreter runs on startup.
+    MAIN_SCRIPT = "main.rb"
+
+    # Uncompressed size of everything packed, for the build summary.
+    attr_reader :data_size
+
+    def initialize(path, cosmo_ruby:, chdir_before: false, debug_mode: false)
+      @path = Pathname(path)
+      @cosmo_ruby = Pathname(cosmo_ruby)
+      @chdir_before = chdir_before
+      @debug_mode = debug_mode
+      @entries = []
+      @names = {}
+      @env = {}
+      @exec_args = nil
+      @ignored_symlinks = []
+      @data_size = 0
+
+      yield(self) if block_given?
+
+      finalize
+    end
+
+    # Symlinks the extraction mode would create (libruby aliases). A ZIP
+    # member cannot be a symlink zipos would follow, and none are needed:
+    # the packed interpreter is a single static binary.
+    attr_reader :ignored_symlinks
+
+    def mkdir(target)
+      add(Entry.new(name: "#{archive_name(target)}/"))
+    end
+
+    def cp(source, target)
+      source = source.to_s
+      add(Entry.new(name: archive_name(target), source: source, mode: file_mode(source),
+                    mtime: File.mtime(source)))
+      @data_size += File.size(source)
+    end
+
+    def symlink(link_path, target)
+      @ignored_symlinks << [link_path.to_s, target.to_s]
+    end
+
+    def export(name, value)
+      @env[name.to_s] = replace_root(value.to_s)
+    end
+
+    # The image argument is the packed interpreter the extraction mode
+    # would spawn; here the running interpreter IS that binary, so only the
+    # script and its arguments matter.
+    def exec(image, script, *argv)
+      raise "Script is already set" if @exec_args
+      @exec_args = [in_archive(image), in_archive(script), argv.map { |arg| replace_root(arg.to_s) }]
+    end
+
+    private
+
+    Entry = ZipWriter::Entry
+
+    def add(entry)
+      return if @names[entry.name]
+
+      @names[entry.name] = true
+      @entries << entry
+    end
+
+    # Archive member name for a target path of the extraction layout. The
+    # targets Direction emits are relative to the extraction root, so they
+    # only need the application prefix; an absolute target would escape the
+    # archive and is a bug.
+    def archive_name(target)
+      name = target.to_s.tr("\\", "/").delete_prefix("./")
+      raise "cannot pack the absolute path #{name} into a ZIP archive" if name.start_with?("/")
+
+      "ocran/#{name}".chomp("/")
+    end
+
+    # Rewrites the extraction-root placeholder ("|", see BuildConstants)
+    # that Direction puts into environment values and exec arguments: in
+    # this mode the application root is not a temporary directory but a
+    # fixed path inside the archive.
+    def replace_root(value)
+      value.gsub("#{EXTRACT_ROOT}/", "#{APP_ROOT}/").gsub(/\A#{Regexp.escape(EXTRACT_ROOT.to_s)}\z/, APP_ROOT)
+    end
+
+    # Absolute path inside the archive for a path Direction emits relative
+    # to the extraction root.
+    def in_archive(path)
+      path = replace_root(path.to_s).tr("\\", "/")
+      path.start_with?("/") ? path : "#{APP_ROOT}/#{path}"
+    end
+
+    # Executable bits are the only permission worth carrying over; packed
+    # files are read-only inside the archive anyway.
+    def file_mode(source)
+      File.executable?(source) ? 0o755 : 0o644
+    end
+
+    def finalize
+      raise "No script to run was recorded" unless @exec_args
+
+      FileUtils.cp(@cosmo_ruby.to_s, @path.to_s)
+      File.chmod(0o755, @path.to_s)
+
+      add(Entry.new(name: MAIN_SCRIPT, data: bootstrap_source, mode: 0o644))
+      ZipWriter.append(@path.to_s, @entries)
+    end
+
+    # The generated /zip/main.rb. It has to do what the C stub does after
+    # extracting: set up the environment, then run the script.
+    #
+    # Environment variables cannot simply be exported here, because the
+    # interpreter is already running by the time main.rb executes and has
+    # long since read RUBYLIB, RUBYOPT and GEM_PATH. So each is applied by
+    # its runtime equivalent: RUBYLIB by unshifting onto $LOAD_PATH,
+    # GEM_HOME/GEM_PATH by setting them and telling RubyGems to re-read
+    # them, RUBYOPT's -I/-r by acting on them directly. The variables are
+    # also exported so that child processes see the same configuration.
+    def bootstrap_source
+      script = @exec_args[1]
+      build_argv = @exec_args[2]
+
+      sections = [
+        <<~RUBY.chomp,
+          # Generated by OCRAN. Entry point of the packaged application: the
+          # cosmopolitan Ruby interpreter this file is embedded in runs it on
+          # startup, with the command line in ARGV.
+        RUBY
+        (%{$stderr.puts "OCRAN: main.rb starting, ARGV=\#{ARGV.inspect}"} if @debug_mode),
+        <<~RUBY.chomp,
+          # Full path of the running executable. The interpreter resolves its
+          # own image path, which for a packaged application IS the executable
+          # the user started - the same meaning OCRAN_EXECUTABLE has in the
+          # extraction mode.
+          executable = RbConfig.ruby
+          ENV["OCRAN_EXECUTABLE"] = executable
+        RUBY
+        chdir_source,
+        env_source,
+        load_path_source,
+        gem_path_source,
+        rubyopt_source,
+        (<<~RUBY.chomp unless build_argv.empty?),
+          # Arguments recorded at packaging time ("ocran app.rb -- a b") come
+          # before the ones the user passes at run time.
+          ARGV.unshift(#{build_argv.map(&:inspect).join(", ")})
+        RUBY
+        <<~RUBY.chomp,
+          # Kernel#load, not require: the script must run with $0 and __FILE__
+          # set to itself, so that "if __FILE__ == $0" guards fire and files
+          # packed next to it are found through __dir__.
+          $PROGRAM_NAME = #{script.inspect}
+          load #{script.inspect}
+        RUBY
+      ]
+
+      sections.compact.reject(&:empty?).join("\n\n") + "\n"
+    end
+
+    # --chdir-first cannot mean "change into the application directory"
+    # here: the application lives inside the archive and zipos cannot be a
+    # working directory. The directory holding the executable is the
+    # closest equivalent, and the one an application that keeps data next
+    # to itself actually wants.
+    def chdir_source
+      return "" unless @chdir_before
+
+      <<~RUBY.chomp
+        # --chdir-first: the archive cannot be a working directory, so use
+        # the directory the executable was started from.
+        Dir.chdir(File.dirname(executable))
+      RUBY
+    end
+
+    # Environment variables other than the load-path ones, exported as is.
+    def env_source
+      plain = @env.reject { |name, _| %w[RUBYLIB RUBYOPT GEM_HOME GEM_PATH].include?(name) }
+      return "" if plain.empty?
+
+      plain.map { |name, value| "ENV[#{name.inspect}] = #{value.inspect}" }.join("\n")
+    end
+
+    def load_path_source
+      paths = split_paths(@env["RUBYLIB"])
+      return "" if paths.empty?
+
+      <<~RUBY.chomp
+        # RUBYLIB equivalent: the interpreter read the variable before this
+        # file ran, so the entries are put on the load path directly. They
+        # are also exported for child processes.
+        ENV["RUBYLIB"] = #{@env["RUBYLIB"].inspect}
+        $LOAD_PATH.unshift(*#{paths.inspect})
+      RUBY
+    end
+
+    def gem_path_source
+      home, path = @env["GEM_HOME"], @env["GEM_PATH"]
+      return "" unless home || path
+
+      <<~RUBY.chomp
+        # RubyGems has already computed its paths from the environment it
+        # started with; point it at the packed gems and make it re-read them.
+        ENV["GEM_HOME"] = #{home.inspect}
+        ENV["GEM_PATH"] = #{path.inspect}
+        Gem.clear_paths
+      RUBY
+    end
+
+    # RUBYOPT is likewise too late to export. -I and -r are replayed; every
+    # other flag is reported at build time (see Direction) and dropped.
+    def rubyopt_source
+      rubyopt = @env["RUBYOPT"].to_s
+      return "" if rubyopt.strip.empty?
+
+      includes, requires = self.class.parse_rubyopt(rubyopt)
+      lines = ["ENV[\"RUBYOPT\"] = #{rubyopt.inspect}"]
+      lines << "$LOAD_PATH.unshift(*#{includes.inspect})" unless includes.empty?
+      requires.each { |lib| lines << "require #{lib.inspect}" }
+      lines.join("\n")
+    end
+
+    def split_paths(value)
+      value.to_s.split(File::PATH_SEPARATOR).reject(&:empty?)
+    end
+
+    # Splits a RUBYOPT string into the -I directories and -r libraries that
+    # can be replayed from inside the script, and the flags that cannot.
+    # Returns [includes, requires, unsupported].
+    def self.parse_rubyopt(rubyopt)
+      includes, requires, unsupported = [], [], []
+
+      rubyopt.split(/\s+/).reject(&:empty?).each do |token|
+        case token
+        when /\A-I(.+)\z/ then includes << $1
+        when /\A-r(.+)\z/ then requires << $1
+        else unsupported << token
+        end
+      end
+
+      [includes, requires, unsupported]
+    end
+  end
+end

data/lib/ocran/zip_writer.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+require "zlib"
+
+module Ocran
+  # Minimal ZIP archive appender, used to inject an application into the
+  # ZIP store of a cosmopolitan Ruby APE (see ZipPayloadBuilder).
+  #
+  # Why not shell out to the `zip` command: OCRAN packages applications on
+  # Windows build hosts too, where `zip` generally does not exist, and even
+  # on POSIX it is not guaranteed to be installed. Why not rubyzip: OCRAN
+  # has exactly one runtime dependency (fiddle) and adding a gem just to
+  # append a few hundred stored/deflated entries is not worth it. Zlib is
+  # part of the standard library, and the format below is the 1989-era
+  # subset (no ZIP64, no encryption, no data descriptors) that
+  # Cosmopolitan's zipos reads.
+  #
+  # Appending, specifically: an APE already contains a ZIP archive (the
+  # interpreter's own standard library lives in it), and the existing
+  # entries must keep working. The layout of a ZIP file is
+  #
+  #   [local header + data]*  [central directory]  [end of central directory]
+  #
+  # and the central directory records absolute offsets of the local
+  # headers. So the append is: cut the file at the start of the central
+  # directory, write the new local headers there, write the ORIGINAL
+  # central directory bytes unchanged (every offset it holds is still
+  # valid, because nothing before it moved), then the central directory
+  # records for the new entries, then a fresh end-of-central-directory
+  # record. This is what the `zip` command does when it appends to an
+  # archive with a non-ZIP prefix, and it leaves the executable part of the
+  # APE - which lives before all of this - byte-identical.
+  module ZipWriter
+    # End of central directory record: signature plus 18 bytes of fixed
+    # fields; a trailing archive comment may follow.
+    EOCD_SIGNATURE = "PK\x05\x06".b
+    EOCD_SIZE = 22
+    # A ZIP archive comment can be up to 0xffff bytes, so the record can
+    # start at most that far from the end of the file.
+    MAX_EOCD_SEARCH = 0xffff + EOCD_SIZE
+
+    # Markers of the ZIP64 format extensions. OCRAN never writes them; an
+    # input archive that uses them is rejected rather than corrupted.
+    ZIP64_EOCD_LOCATOR_SIGNATURE = "PK\x06\x07".b
+
+    CENTRAL_SIGNATURE = "PK\x01\x02".b
+    LOCAL_SIGNATURE = "PK\x03\x04".b
+
+    # "Made by" field: UNIX (3) in the high byte so the external file
+    # attributes below are read as UNIX permission bits, ZIP spec 2.0 in
+    # the low byte.
+    VERSION_MADE_BY = (3 << 8) | 20
+    # Version needed to extract: 2.0 is what DEFLATE requires.
+    VERSION_NEEDED = 20
+    # General purpose bit 11: file name is UTF-8.
+    FLAG_UTF8 = 0x0800
+
+    METHOD_STORED = 0
+    METHOD_DEFLATED = 8
+
+    # MS-DOS directory attribute, set in the low byte of the external file
+    # attributes for directory entries.
+    MSDOS_DIR_ATTRIBUTE = 0x10
+
+    # UNIX st_mode file type bits, stored in the high word of the external
+    # file attributes together with the permission bits. They are NOT
+    # optional: Cosmopolitan's zipos reports the external attributes as
+    # st_mode, and a member without S_IFREG is not a regular file - Ruby's
+    # own require/load refuse to open it (they check S_ISREG), and a
+    # directory without S_IFDIR cannot be traversed, so Dir.glob comes back
+    # empty even though File.read on the exact path works. This mismatch is
+    # what makes an otherwise valid archive unusable inside an APE.
+    S_IFREG = 0o100000
+    S_IFDIR = 0o040000
+    DEFAULT_FILE_MODE = 0o644
+    DEFAULT_DIRECTORY_MODE = 0o755
+
+    # An archive member to add. +name+ is the archive-relative path (with
+    # forward slashes, no leading slash); a name ending in "/" is a
+    # directory entry with no content. +source+ is a path to read the
+    # content from, +data+ is the content itself; exactly one of them is
+    # given for a file entry.
+    Entry = Struct.new(:name, :source, :data, :mode, :mtime, keyword_init: true) do
+      def directory? = name.end_with?("/")
+
+      def content
+        return "".b if directory?
+
+        (data || File.binread(source)).b
+      end
+    end
+
+    module_function
+
+    # Appends the given entries to the ZIP archive at the end of +path+,
+    # in place. Returns the number of bytes the file grew by.
+    #
+    # Raises when the file has no readable central directory, when it uses
+    # ZIP64, or when an entry would shadow a name the archive already
+    # contains (a duplicate name is not a format error, but for the APE it
+    # would mean an application file silently overriding part of the
+    # interpreter's own standard library).
+    def append(path, entries)
+      entries = entries.reject(&:nil?)
+      return 0 if entries.empty?
+
+      File.open(path, "r+b") do |io|
+        eocd = read_eocd(io, path)
+        central = read_central_directory(io, eocd)
+        existing = central_directory_names(central)
+
+        entries.each do |entry|
+          if existing.include?(entry.name)
+            raise "cannot add #{entry.name} to #{path}: the archive already contains an entry with that name"
+          end
+        end
+
+        entries = with_parent_directories(entries, existing)
+
+        before = io.size
+        io.truncate(eocd[:cd_offset])
+        io.seek(eocd[:cd_offset])
+
+        records = entries.map { |entry| write_local(io, entry) }
+
+        cd_offset = io.pos
+        io.write(central)
+        records.each { |record| io.write(central_record(record)) }
+        cd_size = io.pos - cd_offset
+
+        io.write(end_of_central_directory(eocd[:total_entries] + records.size, cd_size, cd_offset))
+        io.size - before
+      end
+    end
+
+    # Returns the entries with an explicit directory entry inserted before
+    # every member for each parent directory that neither the archive nor
+    # the entry list already provides. A ZIP archive does not require them,
+    # but zipos builds its directory listings from the members it can see,
+    # so without them Dir.glob and Dir.entries do not find the packed tree.
+    def with_parent_directories(entries, existing)
+      seen = existing.dup
+      entries.each { |entry| seen[entry.name] = true }
+
+      entries.flat_map { |entry|
+        parents = entry.name.split("/")[0...-1].inject([]) { |acc, part|
+          acc << "#{acc.last}#{part}/"
+        }
+        missing = parents.reject { |name| seen[name] }
+        missing.each { |name| seen[name] = true }
+        missing.map { |name| Entry.new(name: name) } << entry
+      }
+    end
+
+    # Locates and decodes the end-of-central-directory record. The record
+    # is searched for from the end of the file because a ZIP archive is
+    # identified by its tail, which is what allows one to be appended to an
+    # executable in the first place.
+    def read_eocd(io, path)
+      size = io.size
+      tail_size = [size, MAX_EOCD_SEARCH].min
+      io.seek(size - tail_size)
+      tail = io.read(tail_size)
+
+      offset = tail.rindex(EOCD_SIGNATURE)
+      unless offset
+        raise "#{path} does not end in a ZIP archive (no end-of-central-directory record found); " \
+              "it cannot be a cosmopolitan APE with an embedded ZIP store"
+      end
+
+      if tail.rindex(ZIP64_EOCD_LOCATOR_SIGNATURE)
+        raise "#{path} uses the ZIP64 format extensions, which OCRAN cannot append to"
+      end
+
+      _signature, _disk, _cd_disk, _disk_entries, total_entries, cd_size, cd_offset, comment_length =
+        tail.byteslice(offset, EOCD_SIZE).unpack("a4vvvvVVv")
+
+      eocd_start = size - tail_size + offset
+      unless eocd_start + EOCD_SIZE + comment_length == size
+        raise "#{path} has trailing data after its ZIP archive; OCRAN cannot append to it"
+      end
+
+      { cd_offset: cd_offset, cd_size: cd_size, total_entries: total_entries }
+    end
+
+    def read_central_directory(io, eocd)
+      io.seek(eocd[:cd_offset])
+      return "".b if eocd[:cd_size].zero?
+
+      central = io.read(eocd[:cd_size]).to_s.b
+      unless central.bytesize == eocd[:cd_size] && central.start_with?(CENTRAL_SIGNATURE)
+        raise "the ZIP central directory is truncated or malformed"
+      end
+      central
+    end
+
+    # Names of the entries already in the archive, so an application file
+    # cannot silently shadow one of them.
+    def central_directory_names(central)
+      names = {}
+      pos = 0
+      while central.byteslice(pos, 4) == CENTRAL_SIGNATURE
+        name_length, extra_length, comment_length = central.byteslice(pos, 46).unpack("x28vvv")
+        names[central.byteslice(pos + 46, name_length)] = true
+        pos += 46 + name_length + extra_length + comment_length
+      end
+      names
+    end
+
+    # Writes one local file header plus its data at the current position
+    # and returns the bookkeeping the central directory record needs.
+    def write_local(io, entry)
+      content = entry.content
+      crc = Zlib.crc32(content)
+      compressed, method = compress(content)
+
+      name = entry.name.b
+      flags = name.ascii_only? ? 0 : FLAG_UTF8
+      dos_time, dos_date = dos_timestamp(entry.mtime || Time.now)
+      offset = io.pos
+
+      io.write([LOCAL_SIGNATURE, VERSION_NEEDED, flags, method, dos_time, dos_date,
+                crc, compressed.bytesize, content.bytesize, name.bytesize, 0]
+                 .pack("a4vvvvvVVVvv"))
+      io.write(name)
+      io.write(compressed)
+
+      { name: name, flags: flags, method: method, dos_time: dos_time, dos_date: dos_date,
+        crc: crc, compressed_size: compressed.bytesize, size: content.bytesize,
+        offset: offset, mode: st_mode(entry), directory: entry.directory? }
+    end
+
+    # The UNIX st_mode an extractor (and zipos) should report for the
+    # entry: the permission bits plus the file type.
+    def st_mode(entry)
+      if entry.directory?
+        S_IFDIR | (entry.mode || DEFAULT_DIRECTORY_MODE)
+      else
+        S_IFREG | (entry.mode || DEFAULT_FILE_MODE)
+      end
+    end
+
+    # DEFLATE unless it does not pay off. Raw deflate streams (negative
+    # window bits) are what the ZIP format stores - Zlib.deflate would add
+    # a zlib header that no unzipper expects.
+    def compress(content)
+      return ["".b, METHOD_STORED] if content.empty?
+
+      deflater = Zlib::Deflate.new(Zlib::BEST_COMPRESSION, -Zlib::MAX_WBITS)
+      deflated = begin
+        deflater.deflate(content, Zlib::FINISH)
+      ensure
+        deflater.close
+      end
+      deflated.bytesize < content.bytesize ? [deflated, METHOD_DEFLATED] : [content, METHOD_STORED]
+    end
+
+    def central_record(record)
+      external = (record[:mode] << 16) | (record[:directory] ? MSDOS_DIR_ATTRIBUTE : 0)
+
+      [CENTRAL_SIGNATURE, VERSION_MADE_BY, VERSION_NEEDED, record[:flags], record[:method],
+       record[:dos_time], record[:dos_date], record[:crc], record[:compressed_size],
+       record[:size], record[:name].bytesize, 0, 0, 0, 0, external, record[:offset]]
+        .pack("a4vvvvvvVVVvvvvvVV") + record[:name]
+    end
+
+    def end_of_central_directory(total_entries, cd_size, cd_offset)
+      if total_entries > 0xffff
+        raise "too many ZIP entries (#{total_entries}); OCRAN does not write ZIP64 archives"
+      end
+      if cd_offset + cd_size > 0xffffffff
+        raise "the packaged archive would exceed 4 GiB; OCRAN does not write ZIP64 archives"
+      end
+
+      [EOCD_SIGNATURE, 0, 0, total_entries, total_entries, cd_size, cd_offset, 0]
+        .pack("a4vvvvVVv")
+    end
+
+    # MS-DOS packed time and date. The format has two-second resolution and
+    # starts in 1980, so earlier timestamps are clamped.
+    def dos_timestamp(time)
+      time = time.getlocal
+      year = [time.year, 1980].max
+      [(time.hour << 11) | (time.min << 5) | (time.sec / 2),
+       ((year - 1980) << 9) | (time.month << 5) | time.day]
+    end
+  end
+end

data/src/Makefile

@@ -1,4 +1,9 @@
 # Detect host OS
+#
+# Experimental: the POSIX stub also builds with Cosmopolitan Libc
+# (https://github.com/jart/cosmopolitan) into an Actually Portable
+# Executable:  make CC=cosmocc
+# See ../docs/cosmocc-port-plan.md for status and caveats.
 UNAME           := $(shell uname -s 2>/dev/null || echo Windows)
 IS_POSIX        := $(filter $(UNAME),Linux Darwin)
 
@@ -67,6 +72,10 @@ endif
 clean:
 	rm -f $(BINARIES) $(COMMON_OBJS) $(CONSOLE_OBJS) $(WINDOW_OBJS) \
 	      $(RESOURCE_OBJ)
+	# cosmocc (CC=cosmocc) byproducts
+	rm -f $(addsuffix .com.dbg, $(PROG_NAMES)) \
+	      $(addsuffix .aarch64.elf, $(PROG_NAMES))
+	rm -rf .aarch64 lzma/.aarch64
 
 install: $(BINARIES)
 	mkdir -p $(BINDIR)

data/src/script_info.c

@@ -163,7 +163,8 @@ static char **shallow_merge_argv(char *argv1[], char *argv2[])
     return outv;
 }
 
-bool RunScript(char *argv[], bool is_chdir_to_script_dir, int *exit_code)
+bool RunScript(char *argv[], bool is_chdir_to_script_dir,
+               const char *chdir_dir, int *exit_code)
 {
     if (!IsScriptInfoSet()) {
         APP_ERROR("Script info is not initialized");
@@ -202,6 +203,7 @@ bool RunScript(char *argv[], bool is_chdir_to_script_dir, int *exit_code)
         goto cleanup;
     }
 
+    const char *target_dir = NULL;
     if (is_chdir_to_script_dir) {
         script_dir = GetParentPath(script_name);
         if (!script_dir) {
@@ -213,8 +215,19 @@ bool RunScript(char *argv[], bool is_chdir_to_script_dir, int *exit_code)
             "Changing working directory to script directory '%s'",
             script_dir
         );
+        target_dir = script_dir;
+    } else if (chdir_dir) {
+        DEBUG(
+            "Changing working directory to '%s'",
+            chdir_dir
+        );
+        target_dir = chdir_dir;
+    }
 
-        char *ruby_optv[5] = { script_info[0], "-C", script_dir, "--", NULL };
+    if (target_dir) {
+        char *ruby_optv[5] = {
+            script_info[0], "-C", (char *)target_dir, "--", NULL
+        };
         char **new_argv = shallow_merge_argv(ruby_optv, merged_argv + 1);
         if (!new_argv) {
             APP_ERROR("Failed to merge script arguments with extra arguments");

data/src/script_info.h

@@ -4,4 +4,18 @@
 char **GetScriptInfo(void);
 bool SetScriptInfo(const char *info, size_t info_size);
 void FreeScriptInfo(void);
-bool RunScript(char *argv[], bool is_chdir_to_script_dir, int *exit_code);
+/**
+ * Launches the packaged script.
+ *
+ * @param argv                    Original argv of the stub; elements after
+ *                                argv[0] are appended to the script arguments.
+ * @param is_chdir_to_script_dir  When true, the script starts with its working
+ *                                directory set to the extracted script's
+ *                                directory (--chdir-first).
+ * @param chdir_dir               When non-NULL (and is_chdir_to_script_dir is
+ *                                false), the script starts with its working
+ *                                directory set to this path (--chdir-exe-dir).
+ * @param exit_code               Receives the script's exit code.
+ */
+bool RunScript(char *argv[], bool is_chdir_to_script_dir,
+               const char *chdir_dir, int *exit_code);