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, one executable. This post’s subject is pressing your app — and the choices you make 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 you build 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

Your gems are resolved at press time and travel inside the payload slice; your users get a file that runs without Ruby installed. If your app’s entrypoint should become a command on your users' PATH — the shim you met 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. One self-contained file, the simplest thing to hand someone.

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

Your 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 your machine or your CI, and your users never compile anything.

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

What you can do now

You can press a Ruby application into a fat or lean executable, choose its platforms, and declare 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.