ocran 1.4.6 → 1.5.1

data/README.md

@@ -1,12 +1,29 @@
-# OCRAN
+# OCRAN — turn Ruby scripts into standalone executables (.exe) for Windows, Linux and macOS
 
-![OCRAN: ship your Ruby app as one file, no Ruby needed to run it](docs/social/twitter-card.png)
+![OCRAN: ship your Ruby app as one file, no Ruby needed to run it](https://raw.githubusercontent.com/Largo/ocran/master/docs/social/twitter-card.png)
 
-[OCRAN (One-Click Ruby Application Next)](https://github.com/largo/ocran) packages Ruby applications for
+[![Gem Version](https://badge.fury.io/rb/ocran.svg)](https://rubygems.org/gems/ocran)
+
+**OCRAN (One-Click Ruby Application Next) is a Ruby-to-executable packager:
+`ocran app.rb` turns a Ruby script into a single `.exe` (Windows) or native
+binary (Linux, macOS) that runs on machines without Ruby installed.** It is
+the maintained successor of [OCRA](https://github.com/larsch/ocra) for
+Ruby 3.3 and newer.
+
+[OCRAN](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.
 
+Quick start:
+
+```
+gem install ocran
+ocran app.rb          # → app.exe on Windows, ./app on Linux/macOS
+```
+
+See the [FAQ](#faq) and the [comparison with other Ruby packagers](#comparison-with-other-ruby-packagers).
+
 OCRAN supports four output formats, all cross-platform:
 
 * **Self-extracting executable** — bundles everything into a single binary that unpacks and runs transparently, with no Ruby installation required. Produces a `.exe` on Windows, and a native executable on Linux and macOS.
@@ -15,7 +32,7 @@ OCRAN supports four output formats, all cross-platform:
 * **Zip archive** (`--output-zip`) — same as directory output, packed into a `.zip`.
 
 OCRAN is a fork of [OCRA](https://github.com/larsch/ocra) maintained for
-Ruby 3.2+ compatibility.
+Ruby 3.3+ compatibility.
 
 If you run into errors while using OCRAN, please check the [OCRAN issues](https://github.com/largo/ocran/issues) first.
 
@@ -76,7 +93,7 @@ This repository includes `lzma.exe` from the
 [official ip7z/7zip release](https://github.com/ip7z/7zip/releases)
 (version 22.01, from `lzma2201.7z`), used to compress Windows executables.
 
-`stub.exe`, `stubw.exe`, and `edicon.exe` are compiled from source in this
+`stub.exe`, `stubw.exe` and the Linux/macOS `stub` are compiled from source in this
 repository.
 
 ## Installation
@@ -153,7 +170,7 @@ These options control which files from included gems are added to the output.
 * `--gem-guess[=gem1,..]`: Include loaded scripts and a best guess of other needed files (DEFAULT).
 * `--gem-all[=gem1,..]`: Include all scripts and important files from the gem.
 * `--gem-full[=gem1,..]`: Include every file in the gem directory.
-* `--gem-spec[=gem1,..]`: Include files listed in the gemspec (not compatible with newer RubyGems).
+* `--gem-spec[=gem1,..]`: Include the files listed in the gemspec.
 
 Fine-tuning flags:
 
@@ -163,7 +180,7 @@ Fine-tuning flags:
 
 #### Auto-detection options:
 
-* `--no-dep-run`: Skip running the script to detect dependencies. Use this if your script has side effects during load or if you are manually specifying all dependencies. Requires `--add-all-core` and `--gem-full`.
+* `--no-dep-run`: Skip running the script to detect dependencies. Use this if your script has side effects during load or if you are manually specifying all dependencies. Nothing the script loads is detected then, so you usually need `--add-all-core` for the standard library and `--gemfile` with `--gem-full` (or `--gem-all`) for gems; OCRAN warns when they are missing.
 * `--no-autoload`: Do not attempt to load `autoload`ed constants.
 * `--no-autodll`: Disable automatic detection of runtime DLL dependencies.
 
@@ -188,8 +205,126 @@ Fine-tuning flags:
 * `--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).
 
+#### Windows resource options:
+
+These set the PE resources of the generated executable, with the same names
+as [rcedit](https://github.com/electron/rcedit). They apply to the
+self-extracting `.exe` and to the wrapper `.exe` of `--output-dir`,
+`--output-zip` and `--innosetup`. All are opt-in: without them the
+executable is built as before. (Windows only)
+
+* `--set-version-string <key> <value>` (alias `--version-string`): Add a `StringFileInfo` entry such as `CompanyName`, `ProductName`, `FileDescription` or `LegalCopyright`. Repeat for each key.
+* `--set-file-version <x.y.z.w>` (alias `--file-version`): Set the numeric and string file version.
+* `--set-product-version <x.y.z.w>` (alias `--product-version`): Set the numeric and string product version.
+* `--set-resource-string <id> <value>` (alias `--resource-string`): Set an entry of the `RT_STRING` table by its numeric id.
+* `--set-requested-execution-level <level>` (alias `--uac-level`): Set the UAC level in the manifest: `asInvoker` (the default), `highestAvailable` or `requireAdministrator`.
+* `--application-manifest <file>` (alias `--manifest`): Replace the built-in application manifest with the given file. `--set-requested-execution-level` still applies to it.
+
+```
+ocran app.rb --set-version-string CompanyName "Example Ltd" \
+  --set-version-string ProductName "Example App" \
+  --set-version-string FileDescription "Example App" \
+  --set-file-version 1.2.0.0 --set-product-version 1.2.0.0
+```
+
+An unsigned executable with no version information, which extracts files
+to `%TEMP%` and runs them, is what antivirus and EDR heuristics expect of a
+malware packer. Version information, an icon and a code signature give it
+an identity instead. [docs/av-edr-false-positives.md](docs/av-edr-false-positives.md)
+goes through these steps in order of impact.
+
 #### Experimental options:
 
+* `--static-runtime <runtime-dir>`: Build a single executable for Windows,
+  Linux or macOS that runs the application **without extracting anything**:
+  no temporary directory, no DLLs or shared libraries written to disk. The
+  executable is a statically linked Ruby (the *static runtime*) with the
+  application as a plain ZIP archive: appended on Windows and Linux, in a
+  section of its own on macOS (`__OCRAN,__zip`), where appended data would
+  break the code signature. The Linux runtime is linked against musl and
+  fully static, so it runs on any x86_64 distribution.
+
+  ```
+  ocran app.rb --static-runtime path/to/runtime   # app.exe (Windows) or app (Linux, macOS)
+  unzip -l app.exe                          # lists exactly what will run (Linux: app)
+  unzip -p app.exe ocran/manifest.sha256    # SHA-256 of the runtime and every file
+
+  segedit app -extract __OCRAN __zip app.zip   # macOS: the archive is a section
+  unzip -l app.zip
+  ```
+
+  The runtime directory holds `ocran-runtime(.exe)`, its own standard
+  library and bundled gems (`lib/ruby/`) and `runtime.json`; build one with
+  `runtime/build-runtime.sh` (Windows, MinGW, on Linux), the scripts in
+  `runtime/mswin/` (Windows, Visual Studio Build Tools) or
+  `runtime/linux/build-runtime.sh` (Linux x86_64, musl) or
+  `runtime/macos/build-runtime.sh` (macOS, on a Mac). The Windows
+  runtimes import only DLLs that ship with Windows and need no VC++
+  redistributable; the Linux runtime imports nothing at all; the macOS
+  runtime links only libraries of macOS itself (libSystem, libiconv,
+  CoreFoundation). On macOS every executable is linked at packaging time,
+  with its archive, so packaging for macOS needs a Mac with clang (Xcode or
+  the Command Line Tools); the linker signs the result ad hoc, and it can
+  be signed again with `codesign`. Which system
+  the executable is for follows from the runtime, not from the build host:
+  a Linux build host can package for Windows and the other way round, as
+  long as the application does not depend on platform-specific gems. See
+  [runtime/README.md](runtime/README.md) for how it works and how it is
+  built. CI builds and tests the three runtimes and publishes each as a
+  reproducible archive (a zip for Windows, a tarball otherwise) with a
+  signed build provenance attestation
+  (`gh attestation verify <archive> -R Largo/ocran`); releases from 1.5.1
+  on have them attached.
+
+  Dependency detection runs as usual, under the build host's Ruby, which
+  must have the runtime's API version (e.g. 4.0.0). The standard library
+  and the gems the runtime ships come from the runtime, so that they match
+  its interpreter; OCRAN says when one replaces a different version on the
+  build host. C extensions are linked into the executable, since nothing
+  can be loaded from inside it: those the runtime has (openssl, psych,
+  zlib, fiddle, win32ole, bigdecimal, ...) are used as they are; any other
+  gem's extension is built from the gem's source against the runtime's
+  SDK (`sdk/` in the runtime directory) and linked into a runtime of the
+  application's own. That needs a compiler for the runtime: for a MinGW
+  runtime `x86_64-w64-mingw32ucrt-gcc` on Linux, or on Windows
+  RubyInstaller's MSYS2 GCC named with `OCRAN_RUNTIME_CC=gcc` (with
+  `ucrt64\bin` and `usr\bin` on PATH); for an mswin runtime `cl` and
+  `nmake` of Visual Studio Build Tools, from a developer prompt; for a
+  Linux runtime `musl-gcc`; for macOS clang. Gems that
+  need a C library get the one the SDK provides: nokogiri uses its
+  libxml2/libxslt, tiny_tds its FreeTDS. A precompiled platform gem is
+  built from its source gem of the same version, which OCRAN fetches from
+  the configured gem sources into `~/.cache/ocran/gems`, together with the
+  gems its build needs that are not installed (nokogiri's extconf.rb needs
+  mini_portile2), installed there for the build only. Failing that, it is
+  built from the C sources it carries, if any (`gem install <gem>
+  --platform ruby` installs the source gem).
+
+  **Licenses:** the executable is statically linked - Ruby, OpenSSL and
+  the other libraries are inside it, and their license texts are packed
+  into it as `ocran/licenses/`. Two optional libraries are under the LGPL
+  (GNU libiconv, FreeTDS: used by nokogiri and tiny_tds), which asks that
+  users can replace them; `--runtime-dll iconv,sybdb` ships them as DLLs
+  next to the executable instead. Read
+  [runtime/LICENSES.md](runtime/LICENSES.md) before distributing.
+
+  OpenSSL verifies certificates against the Windows certificate store, as
+  Windows itself does, and on Linux and macOS against the system's CA
+  bundle - no CA file is packed or needed. The application reads its own files as
+  usual (`require`, `require_relative`, `autoload`, `File.read`,
+  `Dir.glob`, `__dir__`, `DATA`); their paths lie inside the executable
+  (`C:/app/tool.exe/src/tool.rb`) and cannot be written. Files next to the
+  executable are found through `ENV["OCRAN_EXECUTABLE"]`. `--windows` makes
+  a GUI-subsystem executable; `--icon` and the version-resource options
+  work as for the stub, on any build host (OCRAN writes the resources in
+  Ruby). `--dll` and the output-directory formats do not apply.
+  Experimental.
+
+* `--runtime-dll <lib,...>`: With `--static-runtime`, link these C libraries of the
+  runtime's SDK as DLLs shipped next to the executable rather than into it
+  (the SDK has DLL builds of `iconv` and `sybdb`, the LGPL libraries).
+  OCRAN copies them, and the DLLs they need, next to the executable.
+
 * `--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
@@ -256,7 +391,8 @@ Fine-tuning flags:
     `__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.
+    executable, since the application directory does not exist on disk;
+    `--chdir-exe-dir` does the same.
   * 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
@@ -345,6 +481,147 @@ Fine-tuning flags:
     launcher stub, not to the bundled application. See
     `docs/cosmocc-port-plan.md` for status.
 
+#### Native compilation (experimental):
+
+Instead of packaging the interpreter, these options compile the program
+ahead of time with [Spinel](https://github.com/matz/spinel), Matz's Ruby
+AOT compiler. The result is a native executable that needs no Ruby at all.
+Spinel compiles a *subset* of Ruby (no `eval` of strings, no
+`method_missing`, no runtime class building, only the standard library it
+ships itself), so this works for some programs and not others. When it
+does not, OCRAN tells you why.
+
+* `--spinel`: Compile `script.rb` with Spinel:
+
+  ```
+  ocran app.rb --spinel                 # -> ./app (app.exe on Windows)
+  ocran app.rb --spinel --output myapp
+  ```
+
+  The script is not run at build time. OCRAN scans the program statically
+  (the script, the files it requires, and the source of every gem it
+  requires) and passes Spinel the `-I` roots it needs for your `lib/` and
+  for pure-Ruby gems. If Spinel cannot compile the program, OCRAN prints
+  the compiler's error, then a report of what stands in the way, grouped
+  into your code and each gem. Gems with C extensions and standard
+  libraries Spinel does not provide are named as incompatible. If
+  `spinel-doctor` is installed next to the compiler, its report is shown
+  too. If Spinel is not installed, OCRAN explains how to install it and
+  still shows the report, so you can see whether installing it is worth
+  it. Use `--spinel-opt <arg>` (repeatable) to pass flags to the compiler,
+  for example `--spinel-opt --int-overflow=promote` or
+  `--spinel-opt --defer-refusals`. With `--debug` the binary is built
+  with `-g`. Only code is compiled in; data files have to ship next to
+  the executable.
+
+* `--roundhouse`: Compile a **Rails application** into a native server
+  binary with [Roundhouse](https://github.com/rubys/roundhouse), which
+  lowers the app to the Ruby subset Spinel compiles. OCRAN runs the
+  transpile, the generated project's asset step (`make assets`, with
+  only the Gemfile's assets group bundled) and `spin build`:
+
+  ```
+  ocran --roundhouse path/to/rails/app   # -> ./app-spinel/
+  ```
+
+  The output is a directory (`<app>-spinel` by default, or `--output` /
+  `--output-dir`) that contains the binary plus the `static/`, `public/`,
+  `db/` and `config/` files it reads at run time, and a `storage/` for
+  the SQLite database. On the first build the database is created from
+  `db/seed.sql` when the `sqlite3` command is available. Rebuilding keeps
+  `storage/`. If Roundhouse does not cover the app yet, OCRAN shows the
+  useful parts of `roundhouse check --continue`: the gem census (which of
+  the app's gems Roundhouse does not model), the first errors, and the
+  list of unsupported constructs. Pass flags to Roundhouse with
+  `--roundhouse-opt <arg>`, for example
+  `--roundhouse-opt --survey --roundhouse-opt --allow-unsupported`.
+
+**Installing the compilers.** Neither is a gem. OCRAN looks for `spinel`,
+`spin` and `roundhouse` in the `SPINEL`, `SPIN` and `ROUNDHOUSE`
+environment variables (the command or the directory that contains it), then
+in `PATH`, then in their usual install locations (`~/.local/bin`,
+`/usr/local/bin`, `~/.cargo/bin`). When one is missing, OCRAN prints how to
+install it:
+
+```
+git clone https://github.com/matz/spinel && cd spinel
+make deps && make && make install PREFIX=$HOME/.local
+
+curl --proto '=https' --tlsv1.2 -LsSf \
+  https://github.com/rubys/roundhouse/releases/latest/download/roundhouse-installer.sh | sh
+```
+
+Apps compiled with Roundhouse also need the SQLite and jemalloc
+development headers (`libsqlite3-dev libjemalloc-dev`, or
+`brew install sqlite jemalloc`). OCRAN puts the directory `pkg-config`
+reports for the allocator on `LIBRARY_PATH` for the build, so a Homebrew
+jemalloc on Apple Silicon (under `/opt/homebrew/lib`, which the linker does
+not search by default) links. The asset step needs Bundler, and Node.js
+with npm when the app builds Tailwind.
+
+**Windows.** Spinel does not build natively on Windows yet, and
+Roundhouse's Windows build is untested. For now, run OCRAN inside WSL,
+where both work as they do on Linux; you get a Linux binary. Nothing in
+OCRAN is tied to a platform here: once the compilers run on Windows,
+`--spinel` and `--roundhouse` work there as they are and produce `.exe`
+files.
+
+#### WebAssembly export (experimental):
+
+`--wasm` exports the application as a web page that runs it in the browser.
+The output is a folder (`<scriptname>-wasm` by default, or `--output-dir`)
+or a zip archive (`--output-zip`, or an `--output` name that ends in
+`.zip`). It contains `index.html`, the runtime and your program. The page
+shows the program's standard output and errors. Use the `js` library to
+work with the page itself. Browsers only load WebAssembly over HTTP, so
+serve the folder instead of opening the file:
+
+```
+ocran app.rb --wasm                       # -> app-wasm/
+ocran app.rb --wasm=picoruby --output app.zip
+python3 -m http.server -d app-wasm 8000   # then open http://localhost:8000
+```
+
+There are two runtimes:
+
+* `--wasm` (or `--wasm=ruby`): [ruby.wasm](https://github.com/ruby/ruby.wasm),
+  CRuby compiled to WebAssembly, with its whole standard library (about
+  30 MB). It needs `rbwasm` from the `ruby_wasm` gem (`gem install ruby_wasm`;
+  OCRAN also uses `RBWASM` when it is set).
+  * OCRAN packs your files into the prebuilt interpreter from npm, which
+    takes seconds. Gems must be listed in the application's Gemfile and
+    installed (`bundle install`); pure-Ruby gems are packed in beside your
+    files, at `/gems`, and put on the load path in place of
+    `bundler/setup`, so `require "bundler/setup"` in your program is fine.
+  * Only when a gem has a C extension does OCRAN run `rbwasm build`. Its
+    first run compiles CRuby and the gems for WebAssembly, which takes
+    several minutes, and is cached in `~/.cache/ocran/ruby_wasm`. The
+    extensions are cross-compiled for WASI, and the ones that link system
+    libraries usually fail.
+  * The Ruby version follows the Ruby you run OCRAN with. Use
+    `--wasm-ruby 3.4` to choose another one. Pass extra flags to
+    `rbwasm build` with `--wasm-opt <arg>`.
+* `--wasm=picoruby` (or `--picoruby`): [PicoRuby](https://github.com/picoruby/picoruby),
+  the mruby-based Ruby for microcontrollers.
+  * Its runtime is about 2 MB, and nothing needs to be installed.
+  * PicoRuby has its own small library (`js`, `json`, `yaml`, `base64`, ...)
+    and no RubyGems. In the browser it cannot read your files, so OCRAN
+    bundles the program's files into one script, in the order they are
+    required.
+
+In both cases the script is not run at build time. OCRAN scans the program
+and reports what may not work on the chosen runtime, grouped into your code
+and each gem:
+
+* gems the runtime cannot load;
+* threads, processes, sockets and `gets`;
+* for PicoRuby, also CRuby standard libraries it does not have.
+
+The build goes ahead anyway, since the program only fails if it reaches
+those parts. The runtimes are downloaded from the npm registry once, checked
+against the integrity hash the registry publishes, and cached in
+`~/.cache/ocran/npm`.
+
 ### Compilation:
 
 * OCRAN runs your script (using `Kernel#load`) and builds the output when it exits.
@@ -384,6 +661,41 @@ On Windows, run the batch file:
 
     myapp\script.bat
 
+### Running as a Windows service
+
+The self-extracting `.exe`, the wrapper `.exe` and the launch script all
+start the packed `ruby.exe` as a child process. The Windows service control
+manager accepts the service dispatcher only from the process it started
+itself, so a service registered through any of them fails with error 1063
+("The service process could not connect to the service controller").
+
+Build with `--output-dir` (or `--innosetup`) instead and register the packed
+interpreter directly, e.g. with `sc create` or the
+[win32-service](https://github.com/chef/win32-service) gem's
+`Win32::Service.create`:
+
+    ocran service.rb --output-dir C:\MyService
+    sc create MyService binPath= "C:\MyService\bin\ruby.exe C:\MyService\src\service.rb"
+
+That bare `ruby.exe` still gets the package's environment: OCRAN packs a
+RubyGems startup hook (`lib/ruby/site_ruby/<version>/rubygems/defaults/operating_system.rb`)
+that sets `GEM_HOME`, `GEM_PATH`, `RUBYLIB`, `SSL_CERT_FILE` and the other
+variables of the launch script to the directory's actual location, unless
+they are already set, clears those the launch script clears
+(`BUNDLE_GEMFILE`), and then loads the Ruby installation's own one
+(RubyInstaller's). OCRAN leaves the hook out, and warns, when the building
+Ruby has such a file in its `site_ruby` already or keeps `site_ruby` outside
+its installation directory; then set those variables in the service's
+environment yourself. The hook does not change the working directory (a service
+starts in `C:\Windows\System32`), so find your files from `__dir__`. If the
+script the launch script runs is a generated `ocran-rubyopt-launcher.rb`
+(`-I`/`-r` in `RUBYOPT`), register that one.
+
+OCRAN runs the script at build time, where the service's `mainloop` cannot
+work: skip it with `defined?(Ocran)` (see "Detecting OCRAN at build time")
+and `require` there what the service only loads later, such as `net/http`,
+so that it gets packed.
+
 ### Pitfalls:
 
 * Avoid modifying load paths at runtime. Use `-I` or `RUBYLIB` if needed, but don't expect OCRAN to preserve them for runtime. OCRAN may pack sources into other directories than you
@@ -500,10 +812,10 @@ Notes:
 
 ## Requirements
 
-* Ruby 3.2+
-* For building Windows `.exe`: Windows with [RubyInstaller DevKit](https://rubyinstaller.org/downloads/) (mingw-w64), or Wine on Linux/macOS
+* Ruby 3.3+
+* For building Windows `.exe`: Windows with [RubyInstaller DevKit](https://rubyinstaller.org/downloads/) (mingw-w64), or Wine on Linux/macOS. An mswin Ruby (built with Visual C++, see [mswin Ruby](#mswin-ruby-visual-c)) works as well.
 * For building Linux and MacOS binaries: the respective build tools
-* For `--output-dir` / `--output-zip`: any platform with Ruby 3.2+
+* For `--output-dir` / `--output-zip`: any platform with Ruby 3.3+
 * For `--output-zip` on Linux/macOS: the `zip` command must be available
 * For `--output-zip` on Windows: PowerShell (included in Windows 8+)
 
@@ -515,6 +827,32 @@ The architecture of the generated executable matches the Ruby interpreter used t
 
 * **Windows on ARM (Windows 11 ARM)** — RubyInstaller recently started shipping ARM64 builds; Installing the ARM64 RubyInstaller on a Windows ARM machine and running OCRAN from it will produce an ARM64 `.exe`. These run on ARM Windows natively. Installing the standard x86-64 RubyInstaller on a Windows ARM machine and running OCRAN from it will (probably?) produce an x86-64 `.exe`. These run on ARM Windows via the built-in x86-64 emulation layer, so the executables work on both ARM and x86-64 Windows targets. If you use `--no-lzma`, note that `lzma.exe` (the bundled compressor) is also x86-64 and relies on the same emulation.
 
+### mswin Ruby (Visual C++)
+
+OCRAN also packages with an mswin Ruby (`x64-mswin64_140`), the Ruby built
+with Microsoft Visual C++ instead of MinGW, e.g. the official builds from
+<https://cache.ruby-lang.org/pub/ruby/binaries/mswin64/> or
+`ruby/setup-ruby` with `ruby-version: mswin`. There is no MSYS2 devkit:
+
+* The source gem (and `rake build` in a checkout) compiles the stubs with
+  `nmake -f src/Makefile.mswin`, so run it from a Visual Studio developer
+  prompt (`vcvars64.bat`, Build Tools with the C++ workload), as for any
+  native gem on mswin. The stubs link the C runtime statically.
+* The Ruby DLL of an mswin Ruby links the Visual C++ runtime
+  (`vcruntime140.dll`), which is not part of Windows: without the
+  [VC++ Redistributable](https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist)
+  `ruby.exe` cannot start. OCRAN bundles the VC++ runtime DLLs next to the
+  packed `ruby.exe` (app-local deployment), so the executable runs on a
+  machine without the Redistributable.
+* The libraries an mswin Ruby uses from vcpkg (gmp, libffi, OpenSSL,
+  libyaml, zlib) live next to `ruby.exe`. OCRAN reads the import tables of
+  `ruby.exe`, the Ruby DLL and the packed extensions and bundles the DLLs
+  they need from there, even with `--no-autodll` (as it packs RubyInstaller's
+  `ruby_builtin_dlls`).
+* If the packed interpreter still cannot load a DLL, the executable says so
+  (`The Ruby interpreter could not start: a DLL it needs was not found`)
+  instead of exiting silently with status 0xC0000135.
+
 ## Development
 
 ### Quick start
@@ -536,7 +874,7 @@ The architecture of the generated executable matches the Ruby interpreter used t
 
 | Task         | Purpose                                                                |
 |--------------|------------------------------------------------------------------------|
-| `rake build` | Compile stub(.exe) (requires MSVC or mingw-w64 + DevKit or Unix build tools)                |
+| `rake build` | Compile stub(.exe) (requires mingw-w64 + DevKit, MSVC with an mswin Ruby, or Unix build tools) |
 | `rake clean` | Remove generated binaries                                              |
 | `rake test`  | Execute all unit & integration tests                                   |
 
@@ -1035,10 +1373,176 @@ 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
+## FAQ
+
+### How do I convert a Ruby script into an .exe?
 
-- [State of Ruby Packagers](https://gist.github.com/YOU54F/3775e66e6090e0371c11601e6b75c305)
-- [Traveling Ruby](https://github.com/trubygems/traveling-ruby)
+Install OCRAN on Windows and run it on your entry script:
+
+    gem install ocran
+    ocran app.rb
+
+The result is `app.exe`, which contains your script, the Ruby interpreter,
+the gems it loaded and the DLLs they need. On Linux and macOS the same
+command produces a native executable `./app`.
+
+### Does the target machine need Ruby installed?
+
+No. The executable carries its own Ruby interpreter, standard library,
+gems and native libraries.
+
+### Can I build a Windows .exe on Linux or macOS?
+
+Not with the default mode: OCRAN bundles the Ruby of the machine it runs
+on, so build a Windows `.exe` on Windows (for example on a GitHub Actions
+Windows runner, see
+[Building for multiple platforms](#building-for-multiple-platforms-with-github-actions)),
+or run a Windows Ruby and OCRAN under Wine on Linux/macOS.
+Two experimental modes package without the target's own Ruby:
+`--static-runtime` with a Windows runtime builds a Windows `.exe` on
+Linux (and the other way round), and `--cosmo-ruby` packages a
+cosmopolitan Ruby into one file that runs on Windows, Linux and macOS.
+
+### What is the difference between OCRA and OCRAN?
+
+OCRAN is a maintained fork of OCRA. OCRA targets Windows only and is no
+longer updated for current Ruby versions; OCRAN supports Ruby 3.3+, builds
+for Windows, Linux and macOS, and adds directory, zip, macOS `.app` and
+Inno Setup output. To migrate, call `ocran` instead of `ocra` and replace
+`OCRA_EXECUTABLE` with `OCRAN_EXECUTABLE` in your code.
+
+### Which gems and native extensions are supported?
+
+OCRAN runs your script once at build time and records every file that
+`require` and `load` pull in, including compiled extensions and the DLLs
+or shared libraries they link. In the default mode, gems with native extensions
+(for example `sqlite3`, `pg`, `nokogiri`) are packaged along with their
+libraries; the experimental `--cosmo-ruby` mode only supports the native
+extensions built into its interpreter. Use
+`--gemfile` to include everything from a Bundler `Gemfile`, and the
+[gem detection modes](#gem-content-detection-modes) to include extra files.
+
+### Can I package a Rails, GUI or command-line app?
+
+Yes. Command-line tools work out of the box, GUI apps can use
+`--windows` to hide the console on Windows, and Rails apps with SQLite are
+covered in [Packaging a Rails application](#packaging-a-rails-application).
+
+### Why does my packaged app start slowly?
+
+The default self-extracting executable unpacks Ruby to a temporary
+directory on every launch. Use `--output-dir`, `--output-zip` or
+`--innosetup` to install the files once, `--static-runtime` for a single
+executable that runs without extracting, or `--cosmo-ruby` with an
+interpreter that supports ZIP packaging (CosmoRuby `v4.0.6-cosmo3` or
+newer) to run without extracting; with other interpreters `--cosmo-ruby`
+falls back to a launcher stub that extracts on every start.
+
+### My antivirus flags the generated .exe. What can I do?
+
+Self-extracting executables that unpack an interpreter are a common
+heuristic trigger. Sign the executable (OCRAN output is code-signing
+compatible, e.g. with `signtool` on Windows), ship an
+installer built with `--innosetup`, or ship a plain directory with
+`--output-dir`.
+
+## Comparison with other Ruby packagers
+
+| Tool | Output | Platforms | Single file | Maintained for current Ruby |
+|------|--------|-----------|-------------|--------------------------|
+| **OCRAN** | `.exe` / native binary, directory, zip, macOS `.app`, Inno Setup installer | Windows, Linux, macOS | Yes | Yes |
+| [OCRA](https://github.com/larsch/ocra) | `.exe` | Windows only | Yes | No |
+| [Traveling Ruby](https://github.com/trubygems/traveling-ruby) | Prebuilt Ruby runtime you ship next to your app | Windows, Linux, macOS | No | Yes |
+| [Tebako](https://github.com/tamatebako/tebako) | Single binary with an embedded filesystem | Windows, Linux, macOS | Yes | Yes |
+| [ruby-packer](https://github.com/pmq20/ruby-packer) | Single binary with Ruby compiled from source | Windows, Linux, macOS | Yes | No |
+
+OCRAN's distinguishing features are that, in its default mode, it needs no
+C compiler to package an app (it reuses your installed Ruby), detects dependencies by running
+your script, and can produce installers and macOS app bundles directly.
+
+See also: [State of Ruby Packagers](https://gist.github.com/YOU54F/3775e66e6090e0371c11601e6b75c305).
+
+## Security, dependencies and reproducibility
+
+A packager decides which interpreter, libraries and gems end up on your
+users' machines, so where those come from matters as much as the
+packaging itself. OCRAN is built so that nothing reaches the executable
+that you did not install, run and test yourself, and so that you can
+check what went in.
+
+**No hidden downloads.** In its default mode OCRAN makes no network
+requests: it does not fetch an interpreter, prebuilt runtime, patched
+Ruby source or library tarball while packaging. The executables it
+produces, in every mode, never download a runtime when they start. Some
+packaging approaches ship a small launcher that pulls the actual runtime
+from the internet on first launch; the app then depends on a server
+being reachable and trustworthy long after you released it. An OCRAN
+executable carries the interpreter, gems and libraries it runs; whether
+your app uses the network is up to your own code. The opt-in modes that
+do fetch say so and verify what they get:
+
+* `--wasm` downloads the ruby.wasm or PicoRuby package from the npm
+  registry once, checks it against the SHA-512 integrity the registry
+  publishes, and caches it, so later builds run offline.
+* `--static-runtime` fetches the source gem of a precompiled platform gem
+  from your configured gem sources when it has to build that gem's
+  extension for the runtime.
+
+**Your Ruby, from the source you already trust.** By default OCRAN
+packages the Ruby interpreter installed on the build machine —
+RubyInstaller, a distribution package, `ruby-build`, `ruby/setup-ruby` in
+CI, or your own build. It does not substitute a separately built or
+patched interpreter from a third party. Security fixes reach your app the
+same way they reach your development machine: update Ruby, rebuild.
+Packagers that embed their own copy of Ruby and its C libraries (OpenSSL,
+zlib, libyaml, libffi, ...) freeze those versions at whatever the
+packager last shipped, and fall behind on security fixes when the
+packager stops being updated. The `--static-runtime` runtimes are built
+by scripts in this repository (`runtime/`) that you can run yourself;
+OCRAN checks a runtime against the SHA-256 recorded in its
+`runtime.json`.
+
+**Exactly the gems and libraries you tested.** Dependencies are not
+resolved again at packaging time. OCRAN runs your script, records the
+files Ruby actually loaded, and packs those files from your installed
+gems — the versions pinned in your `Gemfile.lock` when you build under
+Bundler. Native libraries are taken from the same installation your
+extensions were loaded from. There is no second dependency resolution
+that could pick a different version than the one you ran.
+
+**Reproducible builds.** The bundled interpreter and dependencies are
+determined by three things you control: the Ruby installation (or static
+runtime), the installed gems (or `Gemfile.lock`) and the OCRAN version;
+the rest of the artifact follows from your application source and the
+OCRAN options you pass. Pin them — e.g. a fixed `ruby-version` in
+`ruby/setup-ruby` plus a committed `Gemfile.lock` — and every build
+packages the same interpreter, gems and libraries. OCRAN's own stubs are
+built reproducibly (no timestamps in the PE header), the Windows, Linux
+and macOS static runtimes are reproducible, and `--static-runtime`
+executables are byte-reproducible on all three systems; CI packages a
+test application twice and requires the same bytes.
+
+**Inspect what went in.** Build with `--output-dir` and look at the
+directory, or run an executable with `--debug-extract`. A
+`--static-runtime` executable is a plain ZIP archive behind the runtime:
+`unzip -l app.exe` lists exactly what will run, and
+`ocran/manifest.sha256` inside it records the SHA-256 of the runtime and
+of every file.
+
+**Verifiable OCRAN releases.** The launcher stubs (`stub.exe`,
+`stubw.exe` and the Linux/macOS `stub`) are about 4,000 lines of C in
+`src/`, compiled from this repository by GitHub Actions. Released gems
+and the CI-built static runtimes carry signed build provenance
+attestations (`gh attestation verify <file> -R Largo/ocran`); from 1.5.1
+on, each GitHub release has the three runtimes attached next to the gems,
+and gems are pushed to rubygems.org with Sigstore attestations. The only
+third-party binary is `lzma.exe`, taken unmodified from the official
+7-Zip release (see [Safety](#safety)).
+
+The trade-off: keeping the bundled Ruby patched is your job, just as it
+is for the Ruby you develop with. The experimental `--cosmo-ruby` mode
+packages a cosmopolitan interpreter file you choose, such as a CosmoRuby
+release, as given.
 
 ## Credits
 

data/ext/extconf.rb

@@ -2,7 +2,11 @@ gem_root = File.expand_path('..', __dir__)
 src_dir  = File.join(gem_root, 'src')
 stub_dir = File.join(gem_root, 'share', 'ocran')
 
-if Gem.win_platform?
+if RUBY_PLATFORM.include?('mswin')
+  # Visual C++ (needs a Visual Studio developer prompt, as any mswin gem build)
+  Dir.chdir(src_dir) { system('nmake', '-nologo', '-f', 'Makefile.mswin', 'install') } ||
+    abort('Build failed (run from a Visual Studio developer prompt / vcvars64.bat)')
+elsif Gem.win_platform?
   system('ridk', 'exec', 'make', '-C', src_dir, 'install') ||
     system('make', '-C', src_dir, 'install') ||
     abort('Build failed')