Skip to content
All posts
2 min readtebakopackagingtutorial

Basic payloads: Package a Ruby application (3 of 5)

The basic payloads series, hands-on: package a ruby application.

The Tebako team

github.com/tamatebako
Note

Post 3 of 5 in the series Basic payloads.

○ ○ ● ○ ○

  1. Basic payloads: Run your first package

  2. Basic payloads: Data payloads: make one, read one

  3. Basic payloads: Package a Ruby application (this post)

  4. Basic payloads: Package a Rails or Sinatra application

  5. Basic payloads: Publish to your users
Note

Reference guide: Package a Ruby app.

A Ruby application becomes one executable. The subject of this post is pressing an application — and the choices a packager makes at press time: what the executable carries, and which platforms it targets.

Package a Ruby application your source myapp/ bin/myapp lib/… Gemfile provides: [myapp] tebako press resolve · slice · stitch the trailer fat payload carried inside — one self-contained file runtime resolves on first run lean everything resolved at run time — smallest file same bytes, same behavior your users never tell the difference and per platform: one universal build for pure ruby, one per triplet for native

Figure 1 — Press turns a source tree into an executable; fat carries the payload, lean resolves everything at run time, and the packager builds one universal file for pure Ruby or one per platform for native code.

Press the application

Give tebako press the source tree, the entrypoint, and a name:

$ tebako press -r ./myapp -e bin/myapp -o myapp
$ ./myapp

The application’s gems are resolved at press time and travel inside the payload slice; users receive a file that runs without Ruby installed. If the application’s entrypoint should become a command on the users' PATH — the shim introduced in the first post — declare it in the manifest:

provides:
  commands:
    - myapp

One entrypoint per command: a CLI with myapp and myapp-db gets two shims.

The first choice: fat or lean

  • Fat — the payload is carried inside the executable, so the result is one self-contained file and the simplest artifact to hand to a user.

  • Lean — the executable references the payload, and everything resolves at run time; the result is the smallest file with the same bytes and behavior.

Users cannot tell the difference at run time; the difference is where the bytes come from on the first run.

The second choice: which platforms

  • Pure Ruby presses once, universal — one file runs on every supported platform.

  • Native extensions — gems with compiled C — press once per triplet: macos-arm64, macos-x86_64, linux-gnu-x86_64, linux-gnu-aarch64, linux-musl-x86_64, linux-musl-aarch64, windows-ucrt-x86_64. The compilation happens on the packager’s machine or CI, and users compile nothing.

The advanced series covers native code in depth — including the case where shipping prebuilt binaries is the entire point.

What you can do now

This post has pressed a Ruby application into a fat or lean executable, chosen its platforms, and declared the commands it provides. The next post does the same for a web application.

Note

Continue with part 4 of 5: Package a Rails or Sinatra application.