ocran 1.4.3 → 1.4.5

data/README.md

@@ -1,11 +1,6 @@
-# ocran
+# OCRAN
 
-home   :: https://github.com/largo/ocran/
-issues :: http://github.com/largo/ocran/issues
-
-## Description
-
-OCRAN (One-Click Ruby Application Next) packages Ruby applications for
+[OCRAN (One-Click Ruby Application Next)](https://github.com/largo/ocran) packages Ruby applications for
 distribution. It bundles your script, the Ruby interpreter, gems, and native
 libraries into a single self-contained artifact that runs without requiring
 Ruby to be installed on the target machine.
@@ -20,6 +15,8 @@ OCRAN supports four output formats, all cross-platform:
 OCRAN is a fork of [OCRA](https://github.com/larsch/ocra) maintained for
 Ruby 3.2+ compatibility.
 
+If you run into errors while using OCRAN, please check the [OCRAN issues](https://github.com/largo/ocran/issues) first.
+
 ## Recommended usage
 
 The most common use-case is shipping a program to users running Windows / Linux / macOS
@@ -34,7 +31,22 @@ If using Windows you can use  the Inno Setup
 option (`--innosetup`) to produce a proper installer that extracts once to a
 permanent directory.
 
-You can easily generate binaries for the supported Operating Systems with GitHub Actions.
+If you want **one** binary that runs on all three systems and starts
+without extracting anything, package a cosmopolitan Ruby with
+`--cosmo-ruby <ruby.com>` (experimental, see
+[Experimental options](#experimental-options)). Grab the interpreter from
+[CosmoRuby releases](https://github.com/Largo/cosmoruby/releases/latest)
+and point OCRAN at it:
+
+```
+ocran app.rb --cosmo-ruby ./ruby.com
+```
+
+It needs no compiler and no installer, and the same file runs on Linux,
+macOS and Windows, on x86-64 and ARM.
+
+You can easily generate binaries for the supported Operating Systems with GitHub
+Actions — see [Building for multiple platforms with GitHub Actions](#building-for-multiple-platforms-with-github-actions).
 
 ## Features
 
@@ -168,11 +180,169 @@ Fine-tuning flags:
 * `--windows`: Force a Windows GUI application (uses `rubyw.exe`). (Windows only)
 * `--console`: Force a console application (uses `ruby.exe`). (Windows only)
 * `--chdir-first`: Change working directory to the app's extraction directory before the script starts.
+* `--chdir-exe-dir`: Change working directory to the directory containing the executable before the script starts. Use this when your app reads or writes files that live next to the `.exe` using relative paths. Cannot be combined with `--chdir-first`.
 * `--icon <ico>`: Replace the default icon with a custom `.ico` file.
 * `--rubyopt <str>`: Set `RUBYOPT` when the executable runs.
 * `--debug`: Enable verbose output when the generated executable runs.
 * `--debug-extract`: Unpack to a local directory and do not delete after execution (useful for troubleshooting).
 
+#### Experimental options:
+
+* `--cosmo-ruby <ruby.com>`: Package a cosmopolitan-built Ruby (an APE)
+  as the bundled interpreter instead of the host Ruby. The produced
+  `.com` contains no host-native code at all and runs on Linux, Windows
+  and macOS, on x86-64 and ARM:
+
+  ```
+  ocran app.rb --cosmo-ruby /path/to/ruby.com
+  ```
+
+  **Where to get `ruby.com`.** Download a release from
+  [CosmoRuby](https://github.com/Largo/cosmoruby/releases/latest) — one
+  file, no installation:
+
+  ```
+  curl -L -o ruby.com https://github.com/Largo/cosmoruby/releases/latest/download/ruby.com
+  chmod +x ruby.com
+  ocran app.rb --cosmo-ruby ./ruby.com
+  ```
+
+  Any self-contained cosmopolitan Ruby works, but CosmoRuby is what this
+  option is developed and tested against. Releases from `v4.0.6-cosmo3`
+  onwards also support the ZIP packaging mode described below, which
+  needs no C compiler at all; earlier releases fall back to building a
+  launcher stub, which needs `cosmocc`. Building your own is documented
+  in [CosmoRuby's BUILDING.md](https://github.com/Largo/cosmoruby/blob/main/BUILDING.md).
+
+  This one option is the whole command line. The payload APE must be
+  fully self-contained, i.e. carry its standard library in its embedded
+  ZIP store (`/zip/lib/ruby/...`) — upstream cosmopolitan Ruby builds
+  do.
+
+  **Two ways of producing the executable.** OCRAN picks the better one
+  automatically, from the interpreter you give it:
+
+  | | ZIP packaging (default when supported) | APE launcher stub (fallback) |
+  |---|---|---|
+  | How | the executable **is** the interpreter, with your application injected into its ZIP store | an APE stub carries the interpreter and your application as a payload |
+  | Compiler | none | `cosmocc` (located automatically) |
+  | At every start | nothing is unpacked | ~21 MB unpacked into a temp directory |
+  | Startup (see below) | 0.23 s Linux / 0.49 s Windows | 0.79 s Linux / 1.5 s Windows |
+  | Temp directory | never created | created per run, leaked if the process is killed |
+  | Size | interpreter + application | LZMA-compressed, roughly half |
+  | `__dir__` of your script | `/zip/ocran/src` (inside the executable) | the temp directory |
+
+  ZIP packaging is used when the given interpreter runs an embedded
+  `/zip/main.rb` on startup (CosmoRuby builds do; OCRAN detects it by
+  inspecting the binary). Otherwise OCRAN falls back to the launcher
+  stub and locates a `cosmocc` toolchain for it (see `--cosmo` below).
+  Passing `--cosmo <toolchain>` explicitly always selects the launcher
+  stub, as do `--output-dir`, `--output-zip`, `--innosetup` and
+  `--macosx-bundle`, which are not single binaries.
+
+  **What changes for your application under ZIP packaging** (nothing
+  below applies to the launcher stub):
+  * Your files are not on disk at run time. `$0`, `__FILE__` and
+    `__dir__` point into the executable's archive
+    (`/zip/ocran/src/...`), on every platform and with `/` separators.
+    Reading, `require`, `require_relative` and `Dir.glob` all work
+    there; **writing does not**, and the archive cannot be a working
+    directory (`Dir.chdir("/zip")` fails).
+  * Files that ship **next to the executable** are unaffected: resolve
+    them through `ENV["OCRAN_EXECUTABLE"]`, which is the full path of
+    the running `.com` exactly as before (issue #32). Do not use
+    `__dir__` for that — it never meant "next to the exe" in either
+    mode, but here it is obviously wrong instead of subtly wrong.
+  * `--chdir-first` changes into the directory containing the
+    executable, since the application directory does not exist on disk.
+  * The whole command line reaches `ARGV`, unchanged. The interpreter
+    claims none of it, so `app.com --version`, `app.com -v` and
+    `app.com -- x` behave exactly as they would for a natively compiled
+    program (`--` is an ordinary argument, not a separator). This needs
+    a cosmopolitan Ruby with the fix from 2026-08; older builds parsed
+    leading option-shaped arguments themselves and failed with
+    `invalid option --verbose`.
+  * `RUBYOPT` is applied as far as it can be from inside the process:
+    `-I` and `-r` are replayed, other flags are reported at build time
+    and dropped (the interpreter has already started).
+  * `--icon` and `--debug-extract` have no effect and are reported.
+  * The executable is not compressed (it has to stay runnable), so
+    `--no-lzma` makes no difference to its size; individual packed files
+    are deflated.
+  * Exit codes are your application's, exactly, on every platform
+    including Windows. (Cosmopolitan encodes a POSIX wait status into
+    the Windows process exit code, so `exit 3` used to arrive as 768;
+    both the interpreter and the launcher stub now report the plain
+    status.)
+
+  Notes that apply to both:
+  * The payload is run once on the build host (via `/bin/sh`, using the
+    APE's shell-script self-bootstrap) to validate it and to query its
+    version and embedded gem directory.
+  * Dependency detection still runs under the **host** Ruby. Standard
+    library requires resolve at runtime from the payload's embedded
+    stdlib (the host stdlib is not packed); a warning is printed when
+    host and payload Ruby versions differ.
+  * Pure-Ruby application files and pure-Ruby gems are packed as usual
+    and activated via `GEM_PATH`. Native gems cannot work (the payload
+    is a statically linked `x86_64-cosmo` binary that cannot `dlopen`):
+    gems that the payload provides itself (e.g. `json`, `psych`,
+    `sqlite3`) are simply not packed, so the payload's own copy serves;
+    any other native gem aborts the build. This covers gems built from
+    source (`spec.extensions`) as well as **precompiled platform gems**
+    (e.g. `sqlite3-2.9.5-x86_64-linux-gnu`), which declare no
+    extensions but ship a prebuilt `.so` in their `lib` directory.
+  * `--add-all-core` and encoding-support packing are no-ops (the
+    payload embeds its complete stdlib and encodings).
+  * Linux/macOS build hosts only, console applications only
+    (`--windows` is rejected — cosmocc has no GUI `stubw` equivalent).
+    The launcher-stub fallback additionally needs `make`. The default
+    output name uses the `.com` extension (APE convention), e.g.
+    `app.rb` → `app.com`; an explicit `--output` is used verbatim.
+
+  **Measured** with a 8-file CLI using four pure-Ruby gems (thor,
+  terminal-table, rainbow, unicode-display_width) and cosmopolitan Ruby
+  4.0.6, average of 10 runs:
+
+  | Build | Size | Startup (Linux) | Startup (Windows 11) |
+  |---|---|---|---|
+  | ZIP packaging | 21.5 MB | 0.23 s | 0.49 s |
+  | Launcher stub, `--no-lzma` | 22.8 MB | 0.24 s | 1.09 s |
+  | Launcher stub, LZMA (default) | 11.3 MB | 0.79 s | 1.52 s |
+
+  The stub's cost is unpacking ~21 MB per run, which LZMA turns into
+  decompression time: on Linux with a warm page cache an uncompressed
+  stub build is nearly as fast, on Windows it is not. ZIP packaging
+  trades the smaller, compressed artifact for constant startup and no
+  disk writes at all.
+
+* `--cosmo <path>` (alias `--cosmo-toolchain`): Name the
+  [Cosmopolitan Libc](https://github.com/jart/cosmopolitan) `cosmocc`
+  toolchain that builds the APE launcher stub from its C sources at
+  packaging time, overriding the automatic lookup. `<path>` is either
+  the `cosmocc` executable itself or the toolchain directory (one
+  containing `bin/cosmocc`, e.g. an unpacked
+  [cosmocc.zip](https://cosmo.zip/pub/cosmocc/cosmocc.zip)).
+  Notes:
+  * With `--cosmo-ruby`, naming a toolchain explicitly is also how you
+    ask for the launcher stub instead of ZIP packaging (for the
+    extraction semantics: a real on-disk application directory, and
+    `ARGV` untouched by the interpreter's option parser).
+  * When a toolchain is needed but not named, `--cosmo-ruby` looks for
+    one in this order: the `COSMOCC` environment variable (the `cosmocc` executable
+    or its install directory), `cosmocc` in `PATH`, and finally the
+    conventional install locations `~/.cosmocc/*/bin/cosmocc`,
+    `~/cosmocc/*/bin/cosmocc`, `/opt/cosmocc/*/bin/cosmocc`,
+    `/opt/cosmo/bin/cosmocc` and `/usr/local/cosmocc/bin/cosmocc`
+    (newest version first). If none is found the build stops with a
+    message naming all three mechanisms.
+  * Compiled stubs are cached in `~/.cache/ocran` (keyed on the
+    toolchain and stub sources), so only the first build compiles.
+  * Given **without** `--cosmo-ruby`, the packaged Ruby runtime is still
+    the host platform's Ruby — the APE property then applies to the
+    launcher stub, not to the bundled application. See
+    `docs/cosmocc-port-plan.md` for status.
+
 ### Compilation:
 
 * OCRAN runs your script (using `Kernel#load`) and builds the output when it exits.
@@ -182,8 +352,9 @@ Fine-tuning flags:
 
 ### Running your application:
 
-* The working directory is not changed by OCRAN unless you use `--chdir-first`. You must change to the installation or temporary
-  directory yourself. See also below.
+* The working directory is not changed by OCRAN unless you use `--chdir-first`
+  (extraction directory) or `--chdir-exe-dir` (directory containing the
+  executable). See "Working directory" below.
 * When a `.exe` is running, `OCRAN_EXECUTABLE` points to the `.exe` with its full path.
 * The temporary location of the script is available via `$0`.
 * OCRAN does not set up the include path. Add `$:.unshift File.dirname($0)` at the start of your script if you need to `require` additional files from the same directory as your main script.
@@ -238,7 +409,92 @@ OCRAN on the same platform (and architecture) as the intended target**:
 There is no support for building a Windows `.exe` from a Linux or macOS host,
 or vice versa. If you need builds for multiple platforms, run OCRAN in CI on
 each target platform separately (e.g., a Windows runner for `.exe` builds and
-a Linux runner for Linux builds).
+a Linux runner for Linux builds). See
+[Building for multiple platforms with GitHub Actions](#building-for-multiple-platforms-with-github-actions)
+for a ready-made setup.
+
+### Linux binary portability (glibc)
+
+On Linux, OCRAN bundles the shared libraries your application loaded during
+the build (libyaml, libssl, libcrypt, libgmp, libz, ...) next to the bundled
+Ruby, so the executable also runs on distributions where those libraries are
+missing or have different sonames. It works with distro-packaged Ruby too
+(e.g. `dnf install ruby` on Fedora), including its split gem layout and
+`rubypick` wrapper.
+
+One thing can never be bundled: **glibc itself** (and its dynamic loader).
+Those always come from the target system, and glibc is only
+backward-compatible. In practice:
+
+* A Linux binary runs on any distribution whose glibc is **at least as new**
+  as the build machine's.
+* Build on the **oldest** distribution you want to support. For example, a
+  binary built on the oldest available `ubuntu-*` GitHub runner runs on that
+  Ubuntu version and everything newer, while a binary built on a
+  cutting-edge distribution (e.g. `fedora:latest`) will not run on older
+  Debian/Ubuntu releases (`` version `GLIBC_2.4x' not found ``).
+
+Use `--no-autodll` to disable shared library bundling.
+
+## Building for multiple platforms with GitHub Actions
+
+Since OCRAN is not a cross-compiler, the recommended way to ship your app for
+Windows, Linux, and macOS is a GitHub Actions matrix that runs OCRAN natively
+on each platform. A minimal workflow:
+
+```yaml
+name: Build binaries
+
+on:
+  push:
+    tags: ['v*']      # build releases from version tags
+  workflow_dispatch:   # allow manual runs
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-latest   # x86-64 Windows .exe
+          - os: ubuntu-22.04     # x86-64 Linux; oldest runner = widest glibc compatibility
+          - os: macos-14         # Apple Silicon macOS
+          - os: macos-15-intel   # Intel macOS
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true    # if your app has a Gemfile
+
+      - run: gem install ocran
+
+      # Run OCRAN on your entry script. Add "-- <args>" if your script needs
+      # arguments to exit cleanly during the dependency-detection run.
+      - run: ocran myapp.rb --output myapp
+        # produces myapp.exe on Windows, myapp on Linux/macOS
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: myapp-${{ matrix.os }}
+          path: myapp*
+```
+
+Notes:
+
+* Pick the **oldest** `ubuntu-*` runner GitHub offers for the Linux build so
+  the binary runs on as many distributions as possible (see
+  [Linux binary portability](#linux-binary-portability-glibc)).
+* On macOS, each architecture needs its own build: `macos-14` (and newer
+  numbered ARM runners) produce Apple Silicon binaries, `macos-15-intel`
+  produces Intel binaries.
+* Swap the `ocran` invocation for `--output-dir`, `--output-zip`,
+  `--macosx-bundle`, or `--innosetup` depending on how you want to ship
+  (see [Recommended usage](#recommended-usage)).
+* For tag pushes you can attach the artifacts to a GitHub release with a
+  follow-up job (e.g. `softprops/action-gh-release`).
 
 ## Requirements
 
@@ -320,8 +576,12 @@ If your script uses `Kernel#autoload`, OCRAN will attempt to load those
 constants so they are included in the output. Missing modules are ignored
 with a warning.
 
-Dynamic link libraries (.dll files, for example WxWidgets, or other
-source files) will be detected and included by OCRAN.
+Dynamic link libraries are detected and included by OCRAN: `.dll` files on
+Windows (for example WxWidgets), and on Linux the non-glibc shared libraries
+the process loaded (libyaml, libssl, libcrypt, ...), which are placed next to
+the bundled Ruby with appropriate soname symlinks (see
+[Linux binary portability](#linux-binary-portability-glibc)). Disable with
+`--no-autodll`.
 
 ### Including libraries non-automatically
 
@@ -356,6 +616,55 @@ Four modes:
 If files are missing from the output, try `--gem-all=gemname` first, then
 `--gem-full=gemname`. Use `--gem-full` to include everything for all gems.
 
+### Using OCRAN under `bundle exec`
+
+OCRAN loads your script inside its own process to find out what it depends
+on, so the bundle OCRAN itself runs under is the bundle that dependency run
+sees. That matters as soon as the two are not the same.
+
+**Running `bundle exec ocran app.rb` requires `ocran` in the application's
+Gemfile.** This is Bundler's rule, not OCRAN's: `bundle exec` refuses to run
+a command the bundle does not contain ("ocran is not currently included in
+the bundle"). Add `gem "ocran"` to the Gemfile, or install OCRAN with `gem
+install ocran` and call `ocran` without `bundle exec`. Be aware that every
+gem the Gemfile lists is packed into the application when you build with
+`--gemfile`, OCRAN included.
+
+**From the application's own directory it just works.** `bundle exec ocran
+app.rb`, with or without `--gemfile Gemfile`, packages the application
+against its own bundle - including gems declared with `path:` or `gemspec`,
+which exist nowhere but that Gemfile.
+
+**Packaging one project from inside another project's bundle needs
+`--gemfile`.** If the bundle you are in is not the application's, pass
+`--gemfile path/to/app/Gemfile`. It governs the dependency run as well as
+the gem list, so a `require "bundler/setup"` in your script sets up the
+application's bundle and not the one you happen to be standing in. Without
+it the script is loaded under the wrong bundle and usually dies with a
+`LoadError` for one of its own gems; OCRAN warns when it can see that this
+is what you are doing.
+
+Gems that the surrounding bundle merely activated are not packed. The
+contents are decided by the application's own Gemfile and by what the
+dependency run actually loads, so building a small application from inside a
+large development bundle does not drag that bundle along.
+
+**The packaged executable is independent of Bundler.** It carries its own
+gems and its own Gemfile, and it clears the variables through which Bundler
+hands a bundle to a child process (`BUNDLER_SETUP`, `BUNDLE_GEMFILE`,
+`BUNDLE_LOCKFILE`, `RUBYOPT`), so it runs correctly even when started from a
+`bundle exec` shell, from a Rakefile, or from another Ruby program.
+
+**Exception: executables built with `--cosmo-ruby` cannot do that.** There
+the cosmopolitan Ruby *is* the executable, so its RubyGems has already acted
+on `BUNDLER_SETUP` before any packed code can run, and the application
+aborts with `Bundler::GemNotFound` over gems of the bundle it was launched
+from. Start such an executable outside a bundle, or clear the variables
+first - `Bundler.with_original_env { system("./app.com") }` from Ruby, or
+`env -u BUNDLER_SETUP -u BUNDLE_GEMFILE ./app.com` from a shell. Building
+with `--cosmo-ruby` under `bundle exec` is fine; only launching the result
+from inside a bundle is not.
+
 ### Code-signing a macOS app bundle
 
 After building with `--macosx-bundle`, sign the bundle with your Developer ID:
@@ -429,26 +738,51 @@ output, `OCRAN_EXECUTABLE` is set to the full path of the running executable:
 
 ### Working directory
 
-The OCRAN executable does not change the working directory when it starts. It only changes the working directory when you use
-`--chdir-first`.
-
-You should not assume that the current working directory when invoking
-an executable built with .exe is the location of the source script. It
-can be the directory where the executable is placed (when invoked
-through the Windows Explorer), the users' current working directory
-(when invoking from the Command Prompt), or even
-`C:\\WINDOWS\\SYSTEM32` when the executable is invoked through
-a file association.
-
-With `--chdir-first`, the working directory is always the common parent
-directory of your source files. Do not use this if your application takes
-filenames as command-line arguments.
+By default the OCRAN executable does not change the working directory when it
+starts. Two opt-in build options change this:
+
+* `--chdir-first`: the working directory is always the common parent
+  directory of your source files inside the extraction directory. Do not use
+  this if your application takes filenames as command-line arguments.
+* `--chdir-exe-dir`: the working directory is the directory that contains the
+  executable itself. Use this when your application reads or writes files that
+  are placed next to the `.exe` (config files, spreadsheets, output folders,
+  ...) using relative paths. Note that relative filenames passed as
+  command-line arguments will then also resolve against the executable's
+  directory instead of the invoker's current directory.
+
+Without these options, you should not assume anything about the current
+working directory when your executable is invoked. It can be the directory
+where the executable is placed (when invoked through the Windows Explorer),
+the users' current working directory (when invoking from the Command Prompt),
+or even `C:\\WINDOWS\\SYSTEM32` when the executable is invoked through a file
+association.
 
 To `require` additional files from the source directory while keeping the
 user's working directory:
 
     $LOAD_PATH.unshift File.dirname($0)
 
+### Finding files next to the executable
+
+Be aware that `__FILE__`, `__dir__` and `$0` inside a packaged application
+point to the extracted copy of your script in the temporary extraction
+directory — not to the directory containing the `.exe`. Anchoring paths on
+`__dir__` (e.g. `APP_ROOT = File.expand_path(__dir__)`) therefore makes the
+application look for its data files inside the temporary directory, which is
+usually not what you want.
+
+To locate files relative to the executable, either build with
+`--chdir-exe-dir` and use plain relative paths, or anchor your paths on the
+`OCRAN_EXECUTABLE` environment variable, which is always set to the full path
+of the running executable:
+
+    APP_ROOT = if ENV["OCRAN_EXECUTABLE"]
+                 File.dirname(ENV["OCRAN_EXECUTABLE"])
+               else
+                 __dir__   # plain `ruby myapp.rb` during development
+               end
+
 ### Detecting OCRAN at build time
 
 Check for the `Ocran` constant to detect whether OCRAN is currently building
@@ -527,6 +861,178 @@ file:
       end
     end
 
+### Packaging a Rails application
+
+A Rails application with a SQLite database packages into a single
+executable that serves HTTP. `test/test_rails.rb` builds one from scratch
+on every run (`rails new`, `bin/rails generate scaffold`, plus controllers
+and views written on the fly), packages it and drives a full CRUD round
+trip through the resulting binary; read it as the worked example. It is
+opt-in — run it with `OCRAN_RAILS_TEST=1 ruby -Itest test/test_rails.rb`.
+
+Write a small entry script next to `config/` (Rails' own `config.ru` is
+for a Rack server, not for OCRAN) and point OCRAN at it together with the
+directories Rails reads at run time:
+
+    ocran server.rb app config db public --no-autoload --gem-all
+
+Four things are worth knowing before you try it.
+
+**`--no-autoload` is required.** OCRAN's autoload walker sweeps every
+`Module` in `ObjectSpace` and tries to `const_get` each autoloaded
+constant. Under Rails that means dragging in `I18n::Tests`,
+`Prism::Translation` and everything else the framework declares but never
+loads — minutes of output ending in an error. In production Rails eager
+loads the application itself, so the walker has nothing to contribute.
+
+**`--gem-all` is required.** Dependency detection is `$LOADED_FEATURES`
+based, and Rails reads a great deal it never `require`s. The first thing
+to break without it is `activesupport/lib/active_support/locale/en.rb`,
+which I18n reads as a data file during boot. For the same reason the
+application's own `app`, `config`, `db` and `public` directories have to
+be named on the command line: ERB templates, `database.yml`, locale files
+and migrations are not `require`d and so are invisible to the dependency
+run.
+
+**Gems Rails declares but never loads still have to be inside.** OCRAN
+packs the gemspec of every gem it detects, and RubyGems activates the
+complete declared dependency graph of a gemspec, not just the code you
+actually load. `activesupport` declares `minitest` and `drb`, `railties`
+declares `rake`; a running server loads none of them, so nothing puts them
+in the package, and the executable then dies at startup with
+`Gem::MissingSpecError`. Require them from the entry script:
+
+    begin
+      gem "minitest", "~> 5.0"  # 5.x has no dependencies of its own
+    rescue Gem::LoadError
+    end
+    require "minitest"  # activesupport
+    require "drb"       # activesupport
+    require "rake"      # railties
+
+To find the equivalent list for your own application, boot it and diff the
+declared dependencies against what is loaded:
+
+    Gem.loaded_specs.each_value do |spec|
+      spec.runtime_dependencies.each do |dep|
+        puts "#{dep.name} <- #{spec.name}" unless Gem.loaded_specs.key?(dep.name)
+      end
+    end
+
+**Bundler.** The dependency run happens inside the OCRAN process, so a
+`bundler/setup` in `config/boot.rb` confines it to your bundle; use
+`--gemfile` to point OCRAN at the same `Gemfile`. The test takes the other
+route and removes Bundler from the generated application entirely, letting
+RubyGems activate the gems, which is why it needs neither `bundle install`
+nor the network.
+
+#### Where the database goes
+
+**Not inside the package.** With the native stub the application directory
+is a temporary directory that is created at every start and deleted when
+the process exits: a database written there is thrown away. With
+`--cosmo-ruby` it is a read-only ZIP store inside the executable and the
+write simply fails.
+
+Put mutable state next to the executable instead, using
+`ENV["OCRAN_EXECUTABLE"]` (see [Environment variables](#environment-variables)),
+and tell Rails about it before `config/environment` is loaded:
+
+    base = ENV["OCRAN_EXECUTABLE"] ? File.dirname(File.expand_path(ENV["OCRAN_EXECUTABLE"])) : __dir__
+    data_dir = File.join(base, "myapp-data")
+    FileUtils.mkdir_p(data_dir)
+
+    ENV["DATABASE_URL"] ||= "sqlite3:#{File.join(data_dir, "app.sqlite3")}"
+
+`DATABASE_URL` is the cleanest lever, because `config/database.yml`
+resolves relative paths against `Rails.root`, which is inside the package.
+The same applies to everything else Rails writes:
+
+* **tmp** (cache, pids, sockets) — set `config.paths["tmp"]`, or avoid it
+  altogether with `config.cache_store = :memory_store`.
+* **log** — the generated production environment already logs to stdout;
+  if yours does not, set `config.logger` explicitly.
+* **Active Storage** — point `config.active_storage.service` at a root
+  under your data directory.
+
+Ship the schema in the package and apply it on first run, rather than
+shipping a prebuilt database file:
+
+    ActiveRecord::MigrationContext.new(Rails.root.join("db/migrate").to_s).migrate
+
+Calling this during the dependency run as well is what gets
+`db/migrate/*.rb` into `$LOADED_FEATURES`, and therefore into the package.
+
+#### Rails as a single portable executable (`--cosmo-ruby`)
+
+The same application packages into one Actually Portable Executable that
+runs on Linux, macOS, Windows and the BSDs without an installed Ruby:
+
+    ocran server.rb app config db public --no-autoload --gem-all \
+      --cosmo-ruby /path/to/ruby.com
+
+No compiler is involved: `--cosmo-ruby` on its own selects the ZIP mode,
+in which the application is injected into the interpreter's own ZIP store.
+Nothing is unpacked at run time — the application is read straight out of
+the executable. A Rails 8.1 application built this way measures **39.0 MB
+and answers its first request 1.8 s after launch**, against 50.4 MB and
+1.5 s for the same application in a native OCRAN executable.
+
+An APE cannot `dlopen`, so **every native extension has to be compiled
+into the interpreter you point at**. For Rails that is `sqlite3`,
+`nokogiri` (and with it libxml2 and libxslt), `puma`, `nio4r`,
+`bigdecimal` and `racc`. CosmoRuby has had all of them since 4.0.6;
+against an interpreter that has not, the build stops before producing
+anything, naming the gem:
+
+    ERROR: Gem nokogiri-1.19.4-x86_64-linux-gnu is native (ships prebuilt
+    binaries (nokogiri.so)) and cannot run under the packed cosmopolitan
+    Ruby (x86_64-cosmo, static)
+
+OCRAN drops the host copy of each gem the payload provides and lets the
+payload's own serve. It recognises those either by a gemspec in the
+payload or, failing that, by asking the payload whether it can resolve the
+gem's primary feature at all: an extension linked into the binary, or a
+library in its embedded stdlib (`cgi` and `pathname` are both), answers
+`require` with no gemspec anywhere.
+
+**One real limitation remains, and it is cryptographic.** CosmoRuby's
+`openssl` is a shim over MbedTLS: no `OpenSSL::Cipher`, no
+`OpenSSL::HMAC`, no PBKDF2, no `OpenSSL::Digest` class hierarchy. Rails
+does not merely use those, it *names* them at load time — `require "rails"`
+by itself dies on
+
+    active_support/message_encryptor.rb:116:in '<class:MessageEncryptor>':
+    uninitialized constant OpenSSL::Cipher (NameError)
+
+so an application packaged for such an interpreter has to do three things.
+`test/rails_app_generator.rb` does all three, and the file it writes,
+`openssl_gap.rb`, is a no-op on a Ruby with a complete `openssl`:
+
+* **Fill in the missing pieces before Rails loads.** HMAC, PBKDF2,
+  `OpenSSL.fixed_length_secure_compare` and an `OpenSSL::Digest` class
+  hierarchy are a few lines each on top of Ruby's own `Digest`, and they
+  are the real algorithms. `OpenSSL::Cipher` is not: it exists so that
+  Rails can name the constant, and raises if anything tries to encrypt
+  with it. A fake cipher would be worse than no cipher.
+* **Set `SECRET_KEY_BASE`, and ship no `config/credentials.yml.enc`.**
+  Reading credentials decrypts them with AES-256-GCM and fails with
+  `OpenSSL::Cipher::CipherError`. Dropping the file is the right move in
+  any case: packaging it means packaging `config/master.key` beside it,
+  i.e. handing the key to everyone who gets a copy of the executable.
+* **Keep the session off the cookie.** Rails' default `CookieStore`
+  encrypts the session cookie, so it cannot work either;
+  `config.session_store :cache_store` keeps the session server-side and
+  puts only its id in the cookie. Signed cookies, the CSRF token and
+  everything else that needs no more than an HMAC keep working, and a full
+  scaffold CRUD round trip with CSRF token and session cookie is what the
+  test drives through the packaged `.com`.
+
+Active Record encryption, encrypted cookies and anything else that
+actually encrypts stay out of reach until CosmoRuby's `openssl` grows a
+cipher surface — mbedtls has AES, GCM and PKCS5, so it is a bounded job;
+it is tracked in `PORTING-NOTES.md` in the CosmoRuby repository.
+
 ## See elsewhere
 
 - [State of Ruby Packagers](https://gist.github.com/YOU54F/3775e66e6090e0371c11601e6b75c305)
@@ -534,10 +1040,12 @@ file:
 
 ## Credits
 
-Lars Christensen and contributors for the OCRA project which this is forked from.
+[Andi Idogawa](https://github.com/largo), [Shinokaro](https://github.com/shinokaro)
+[Lars Christensen](https://github.com/larsch) and contributors for the OCRA project which this is forked from.
+
+Special thanks to Ruby on Windows maintainers such as [Nobuyoshi Nakada](https://github.com/nobu), [Lars Kanis](https://github.com/larskanis), and [MSP-Greg](https://github.com/MSP-Greg)
 
-Kevin Walzer of codebykevin, Maxim Samsonov for ocra2, John Mair for
-codesigning support.
+[Kevin Walzer](https://github.com/codebykevin) of codebykevin, [Maxim Samsonov](https://github.com/maxirmx), and [John Mair](https://github.com/banister) for codesigning support.
 
 Igor Pavlov for the LZMA compressor and decompressor (Public Domain).
 
@@ -551,7 +1059,7 @@ http://ruby.morphball.net/vit-ruby-ico_en.html).
 (The MIT License)
 
 Copyright (c) 2009-2020 Lars Christensen
-Copyright (c) 2020-2025 The OCRAN Committers Team
+Copyright (c) 2020-2026 The OCRAN Committers Team
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/lib/ocran/build_facade.rb

@@ -10,6 +10,8 @@ module Ocran
 
     def cp(...) = @filer.__send__(__method__, ...)
 
+    def symlink(...) = @filer.__send__(__method__, ...)
+
     def export(...) = @launcher.__send__(__method__, ...)
 
     def exec(...) = @launcher.__send__(__method__, ...)