ocran 1.4.4 → 1.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79aa33b2625758b6cce7b1175d45d73c5c60209b996a6d5ab03a4df55acbae28
-  data.tar.gz: 3d53ff8c8b7a31448080f105f33af4968dea8f9a8fd559aa92a9e87db31db0dd
+  metadata.gz: 85cce39e5b93c48ccd16ecc3ad73f214a2349c2b203ff242fb1d478a78fbd5b9
+  data.tar.gz: f6ac990c20617164a68d70cd91e38e42afd12889c247f82204684d1843bb26ae
 SHA512:
-  metadata.gz: e9975e649595c77397e49649544fad56b209917a55f7ea6d7ff7acf748a14608165013fbe1e43908946b0cba1badbae22da7b73aac4ba2661fb092162d333386
-  data.tar.gz: 67007f4112f91a8bb6a01564a8b5b4b54edd2b852a629f78d1bc12bd9062e3a71771fe0a802bc9f3133560cd0aa7da18fa912f0eb0f2f8337288ea226be308b2
+  metadata.gz: 598cfd6fa803707a732ec8c10687f221b2a0618570377655a7414bcb94d9744d59364ade26ddc5b379fd72daf40adf8d001eccdac3d7af0ab20a69dfbafe1500
+  data.tar.gz: 83311e9e259a7c91f99ab6860529bd3ede2d706b3737451707f7488291679ae0ceb49bddb110128b6413f7d99b38f4b06bdd0a2362acf56a0afb9269bb41ae82

data/CHANGELOG.txt

@@ -1,3 +1,21 @@
+=== 1.4.5
+- Windows: detected DLLs are now also bundled into bin, next to ruby.exe, whenever they are not already resolvable from where they get packed. The Windows loader resolves a native extension's imports from the extension's own directory, ruby.exe's application directory (bin) plus its ruby_builtin_dlls SxS assembly, and the system directories - PATH is not consulted on hardened systems, and the AddDllDirectory route gems take through ruby_installer/runtime does not exist in a packed app. A DLL loaded from a gem's own tree (e.g. FreeTDS, which tiny_tds ships under ports/), from a devkit's msys64 tree inside the Ruby prefix, or from outside the prefix entirely was packed only at that original location, which the loader never searches, so the packaged application died at require time with a misleading LoadError on machines where a rich PATH did not mask the gap - the out-of-prefix case was skipped entirely by a guard that made its copy_to_bin branch unreachable. DLLs from the Windows directory keep coming from the target system and are never bundled. Companion DLLs found next to native extensions (e.g. libssl-3-x64.dll beside openssl.so in archdir) go into bin as well: 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.
+- `--cosmo-ruby`: a native gem now also counts as provided by the payload when the payload can resolve the gem's primary feature, not only when the payload has a gemspec of that name. A gemspec is not what makes a library requirable - an extension linked into the APE, or a library in the interpreter's embedded stdlib, answers `require` with nothing under /zip/lib/ruby/gems/*/specifications - so gems such as cgi and pathname (both compiled into CosmoRuby, and both ordinary native gems on Ruby 3.4+) were reported incompatible and refused builds that work. The probe runs the payload once using $LOAD_PATH.resolve_feature_path, which searches exactly as require does, built-in extensions included, but executes none of the code it finds.
+- A Rails application with SQLite now packages into a single Actually Portable Executable with `--cosmo-ruby` alone (no compiler at all), given an interpreter with sqlite3, nokogiri, puma, nio4r, bigdecimal and racc linked in: 39.0 MB, serving its first request 1.8s after launch, against 50.4 MB and 1.5s for the same application as a native OCRAN executable, and with nothing unpacked at run time. test/test_rails.rb drives the same HTTP assertions - scaffold CRUD through SQLite with CSRF token and session cookie, dynamically added controllers, persistence across a restart - through both builds. The one remaining limitation is cryptographic and belongs to the interpreter: its openssl is an MbedTLS shim with no cipher, HMAC or PBKDF2 surface, and Rails names those at load time, so the application must fill the gap itself, set SECRET_KEY_BASE, ship no config/credentials.yml.enc, and keep the session out of the (encrypted) cookie. See the Rails section of README.md.
+- New `--chdir-exe-dir` option (issue #32): the packaged executable starts the script with its working directory set to the directory containing the executable itself, so relative file access (e.g. reading data files placed next to the .exe) works regardless of how the executable is invoked. Implemented as a new CHDIR_TO_EXE_DIR (0x40) stub header flag; the stub passes `-C <exe dir>` to the packed Ruby interpreter. Mutually exclusive with `--chdir-first`.
+- README: document that `__FILE__`/`__dir__`/`$0` point into the temporary extraction directory at runtime (the cause of issue #32) and show the supported `ENV["OCRAN_EXECUTABLE"]` pattern for locating files next to the executable.
+- `--gemfile <path>` now governs the dependency run too, not just the Gemfile scan that follows it. The script is loaded inside the OCRAN process, so whatever BUNDLE_GEMFILE the environment carried used to win: running OCRAN from inside another project's `bundle exec` made the script's own `require "bundler/setup"` activate that project's bundle, and gems only the application's Gemfile provides went missing. Local development gems declared with `path:` or `gemspec` always did, since they exist nowhere but that Gemfile, so packaging them (issue #34) failed with a LoadError before anything could be packed. OCRAN now points BUNDLE_GEMFILE at the given Gemfile before loading the script, and when a different bundle has already been set up through RUBYOPT it drops Bundler's memoized state so the application's Gemfile is the one that takes effect.
+- Test suite: build and run steps assert through a new assert_system helper that captures the child's stdout and stderr and puts them in the failure message. A failing build used to report nothing but "Expected false to be truthy" while its diagnostics scrolled past in the runner's output.
+- `--cosmo-ruby <ruby.com>` now packages without any compiler when the given cosmopolitan Ruby runs an embedded /zip/main.rb (issue #26). Instead of compiling an APE launcher stub, OCRAN copies the interpreter and injects the application into the interpreter's own ZIP store, so the executable IS the interpreter: no cosmocc, no make, and nothing is unpacked at run time. Startup drops from 0.79s to 0.23s on Linux and from 1.52s to 0.49s on Windows for a 4-gem CLI, no temporary directory is created at all (so none can be leaked when the process is killed), and the executable is about twice as large because it cannot be LZMA-compressed. The mode is selected automatically - `--cosmo-ruby <ruby.com>` alone remains the whole command line - by detecting the capability in the binary; interpreters without it still get the launcher stub, and an explicit `--cosmo <toolchain>` (or --output-dir/--output-zip/--innosetup/--macosx-bundle) forces it. No new command line option.
+- Behavior differences of the ZIP packaging mode, documented in README: the application runs from inside the executable, so $0, __FILE__ and __dir__ point into /zip/ocran/src instead of a temporary directory (files shipping next to the executable are still found via OCRAN_EXECUTABLE, which is unchanged); --chdir-first changes into the executable's directory; of RUBYOPT only -I and -r can be replayed; --icon and --debug-extract have no effect.
+- ZIP packaging now passes the whole command line to the application and reports exact exit codes, including on Windows, given a cosmopolitan Ruby with the 2026-08 interpreter fixes. Previously the interpreter parsed leading option-shaped arguments as its own ("app.com --verbose" failed with "invalid option --verbose", only "app.com -- --verbose" worked) and multiplied Windows exit codes by 256 ("exit 3" arrived as 768). Both were interpreter bugs that also affected plain "ruby.com script.rb"; "--" is now an ordinary argument and interpreter options are reachable through RUBYOPT.
+- The APE launcher stub sets COSMORUBY_WAIT_STATUS_EXIT=1 for the packaged interpreter. The stub is itself a cosmopolitan program: it fork/execs the interpreter and reads the result with WEXITSTATUS(), so with the interpreter's Windows exit-code fix in place an unmarked child's "exit 3" came back as 131 (128 + signal 3). The variable asks the interpreter to keep cosmopolitan's wait-status encoding for this one caller; the stub still reports the plain status to its own native parent.
+- New Ocran::ZipWriter: a minimal, dependency-free ZIP appender (Zlib only) used to inject the application into the APE without shelling out to the zip command, which Windows build hosts do not have. It rewrites the central directory in place, refuses ZIP64 and archives with trailing data, rejects entries that would shadow an existing member, and writes UNIX file-type bits in the external attributes - without S_IFREG/S_IFDIR the members are readable but Ruby's load refuses to open them and directory listings come back empty.
+- New experimental `--cosmo <path>` option (alias `--cosmo-toolchain`): build the launcher stub from its C sources with a Cosmopolitan Libc toolchain (cosmocc) at packaging time and package the application with the resulting Actually Portable Executable (APE) stub instead of the pre-built stub (issue #26). `<path>` is the cosmocc executable or the toolchain directory (containing bin/cosmocc). Console applications only (`--windows` is rejected); requires make and a Linux/macOS build host. The default output name uses the `.com` extension (APE convention); an explicit `--output` is used verbatim. Compiled stubs are cached in ~/.cache/ocran keyed on the toolchain and stub sources; compile errors surface the compiler output.
+- Ship the stub C sources (src/) in the binary platform gems so `--cosmo` can rebuild the stub from an installed gem, not only from a source checkout.
+- `--cosmo-ruby <ruby.com>` is a complete command line on its own: the cosmocc toolchain that builds the APE launcher stub is now discovered on the build host instead of having to be named with `--cosmo` (issue #26). Search order: the COSMOCC environment variable (the cosmocc executable or its install directory; a value that does not resolve is an error, not a silent fallback), cosmocc in PATH, then 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). `--cosmo <path>` remains an explicit override that always wins and still works on its own. When no toolchain is found, option parsing fails - before the dependency run - with a message naming the environment variable, PATH, the conventional locations, the download URL and the `--cosmo` flag.
+- New experimental `--cosmo-ruby <ruby.com>` option: package a cosmopolitan-built Ruby APE as the bundled interpreter instead of the host Ruby, so the produced `.com` contains both an APE stub and an APE Ruby and runs with no host-native code (issue #26). The payload's embedded stdlib (in its /zip store) is used at runtime instead of the host's, its embedded gem directory is appended to GEM_PATH, pure-Ruby gems are packed as usual, and native-extension gems are skipped when the payload provides them (json, psych, ...) or abort the build otherwise. The payload is validated by running it once on the build host; a warning is printed when host and payload Ruby versions differ. Verified end-to-end on Linux; console-only, POSIX build hosts only.
+
 === 1.4.4
 - Fix crash on distro-packaged and Homebrew Ruby when a default gem (e.g. fiddle, singleton) has a gemspec but no materialized gem directory: file collection now treats the missing directory as an empty set instead of raising Errno::ENOENT from Find.find (issue #44). The gem's files, which live in the stdlib, are still packed via the load path.
 - Pack the real Ruby interpreter when bindir/ruby is a dispatcher script (e.g. Fedora's rubypick): the running interpreter binary (/proc/self/exe) is packed under the expected name instead, so the packed executable no longer requires Ruby on the target system.

data/README.md

@@ -31,6 +31,20 @@ If using Windows you can use  the Inno Setup
 option (`--innosetup`) to produce a proper installer that extracts once to a
 permanent directory.
 
+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).
 
@@ -166,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.
@@ -180,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.
@@ -443,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:
@@ -516,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
@@ -614,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)