Inside the container:

An on-file filesystem (OFFS) containing all the project files and dependencies in DwarFS format ("application")
A runtime environment that includes the the necessary libraries and interpreters, with patched filesystem calls that redirect access of project files to the on-file filesystem ("runtime")

Tebako is capable to create a single file that contains both runtime and application or place runtime and application to separate files. In the latter case the runtime can be used with different applications or versions of the same application.

Please refer to mode option below that controls Tebako output.

== Supported runtimes, platforms and architectures

Tebako artifacts can be built and executed on the following platforms and architectures.

.Supported platforms and architectures [cols="3", options="header"] |=== | Platform and version | Architectures | Build system

|===

[NOTE]

Windows build caveats:

Tebako may face errors related to CMake path length limitations (https://gitlab.kitware.com/cmake/cmake/-/issues/25936). This error may affect not Tebako itself but the gems that need to be package and use CMake to build native extensions. There is no workaround for this issue as it looks like is a limitation of the manifest used to build CMake executable.
MSys strip utility creates broken executable when Tebako image is processed. Linking with -s flag produces unusable executables as well. Until this issue (https://github.com/tamatebako/tebako/issues/172) is resolved we plan to produce a Windows executable with debug information unstripped. You can opt to run strip -S manually, it most cases it works.

MacOS build caveats:

We saw clang compiler segmentation fault when packaging of very large projects with XCode 14.3.1. This issue is not reproducible with XCode 15.0.1 or higher. ====

.Supported Ruby versions [cols="2", options="header"] |=== | Ruby version | Supported platforms

| 2.7.8 | Linux, macOS | 3.0.7 | Linux, macOS | 3.1.6 | Linux, macOS, Windows | 3.2.{4,5,6,7} | Linux, macOS, Windows | 3.3.{3,4,5,6,7} | Linux, macOS, Windows | 3.4.{1,2} | Linux, macOS, Windows

|===

NOTE: Our goal is to support all maintained Ruby releases, including minor versions.

== Package portability

=== General

Tebako packages are designed to be "forward portable" across different operating systems and architectures to allow for easy distribution and deployment.

Forward portability means that a package created on a specific platform can be executed on a newer version of the same platform.

=== macOS

macOS packages are forward portable across different macOS versions.

[example] A Tebako executable package built on macOS 13 (Ventura) can be executed on macOS 14 (Sonoma), but not vice versa.

macOS packages compiled on x86_64 can be run on Apple M (ARM64/aarch64) systems.

=== Linux distributions using musl

Packages built for the https://musl.libc.org[`musl` implementation of the C standard library] (such as https://alpinelinux.org[Alpine Linux]) are forward portable.

[example] A Tebako executable package built on Alpine 3.17 can be executed on Alpine 3.19.

Usage of the https://github.com/tamatebako/tebako-ci-containers[Tebako Docker containers] for packaging is encouraged since it eliminates the effort needed for toolchain setup and configuration.

=== Linux distributions using glibc

Packages built for the https://sourceware.org/glibc[`glibc` implementation of the C standard library] are forward portable if the --patchelf experimental option is enabled.

The --patchelf option allows these packages to be portable to Linux GNU distributions with GLIBC version 2.31 and above.

[example] A Tebako executable package built on Ubuntu 20.04 with --patchelf option can be executed on Rocky Linux 9.

Usage of the https://github.com/tamatebako/tebako-ci-containers[Tebako Docker containers] for packaging is encouraged since it eliminates the effort needed for toolchain setup and configuration.

.Minimum versions of GLIBC Linux distributions that support Tebako packages with forward portability [cols="3", options="header"] |=== | Distribution | Minimal supported version | GLIBC version

|===

== Future plans

Downloading new DwarFS images to be stored in the local home directory
Allowing loading multiple DwarFS images in a stacked way
Supporting a COW mechanism that the newly written files are stored in a separate image that can be loaded on top of the read-only file systems.

== FAQ

=== Why use Tebako?

Tebako is particularly useful for developers who need to:

Distribute applications without requiring users to have specific runtimes installed.
Simplify the deployment process by packaging all dependencies into one binary.
Ensure consistency across different environments by using a single executable.
Flexibility to support different runtime versions on the user's machine.

=== How do I know I need Tebako?

You might need Tebako if you:

Want to package your application into a single, self-contained binary.
Want to avoid the complexities of managing runtime environments on target machines.
Distribute software to environments where installing runtimes and their dependencies is challenging.
Require a streamlined way to deliver applications to end-users.
Need to ensure that your application runs consistently across different environments and architectures.

=== What is DwarFS?

https://github.com/mhx/dwarfs[DwarFS] is a fast, high compression read-only user-land file system designed for efficient storage and access of large collections of files.

It is used by Tebako to package applications into a compact and efficient format.

Tebako uses https://github.com/tamatebako/libdwarfs[libdwarfs], the library form of https://github.com/mhx/dwarfs[DwarFS], developed for the Tebako project.

=== When is Tebako better than comparable solutions?

Tebako offers several advantages over comparable solutions for supported interpretive languages.

They are listed in order of the degree of virtualization below.

Tebako stands out by providing a lightweight runtime bundling approach that simplifies distribution and deployment while offering flexibility and efficiency.

It eliminates the need for users to have specific runtimes installed and ensures consistency across different environments.

With Tebako, you can package your entire project with a bundled runtime into a single, performant, executable binary.

[cols="a,3a,3a"] |=== | Solution | Pros | Cons

| Virtual machines (VMs) |

Provides full isolation and compatibility across environments |
Requires a separate VM installation for each application
Heavy resource consumption for virtualization

| Docker |

Provides portable containers
Isolates entire applications and their dependencies
Supports easy deployment and scalability |
Requires Docker installation and management
Requires administrative rights on machine
Containerization overhead

| Tebako |

Packages all files and dependencies into a single binary
Supports multiple operating systems and architectures
Provides efficient packaging and execution with DwarFS
Offers security features like signing on macOS
Simplifies distribution and deployment
Native running speed |
Initial packaging time longer than Ruby gems
Minor runtime overhead

| Ruby Gems |

Easy installation of Ruby libraries
Provides user-side version control and dependency management |
Requires Ruby installation and gem management
Runtime execution dependent on the user's installed Ruby version and gems

|===

== Installation

=== General

Tebako installation is only required for packaging applications.

Users who run packaged applications do not need to install anything.

Tebako can be used for packaging in two ways:

Through the link:https://github.com/tamatebako/tebako-ci-containers[Tebako CI docker containers]
Through local installation

Installation for both GNU and musl Linux distributions may heavily depend on the OS version, so we recommend using link:https://github.com/tamatebako/tebako-ci-containers[Tebako CI docker containers] for Linux packaging.

=== Local installation

To use Tebako on macOS or Windows, you need to install it locally.

On Linux, there may be cases where Docker is not suitable for your needs, such as:

Administrative privileges: Running Docker requires administrative privileges, which may not be available to all users on their machines.
Performance impact: Docker introduces performance overhead due to containerization. This can be a concern when packaging complex applications that require significant memory resources.

In such cases, you can choose to install Tebako locally on Linux as well.

Please refer to the separate document link:INSTALLATION.adoc[INSTALLATION.adoc] for instructions on how to install Tebako.

== Usage

=== Command-line interface

Tebako works by packaging your project into a single executable binary that includes all the necessary dependencies.

You interact with Tebako through its command-line interface (CLI), which provides the following commands:

Basic use:

press:: Packages a project into a single executable binary. See <> section for details.

Advanced use:

setup:: Runs post-install setup and creates the Tebako packaging environment. See <> section for details.

clean:: Removes Tebako artifacts. See <> section for details.

clean_ruby:: Removes Tebako Ruby artifacts. See <<clean_ruby>> section for details.

hash:: Calculates the Tebako script hash for use as a cache key in CI/CD environments. See <> section for details.

help:: Displays the help message.

== Packaging

=== Commands

Tebako provides several commands to manage the packaging and deployment process.

==== Press

This command "presses" a Ruby project using the Tebako components built in the Tebako root folder (<tebako-root-folder>).

[NOTE]

The first invocation of the `press` command can take up to an hour as it sets up the packaging environment and collects the required dependencies. Subsequent invocations are much faster.

Upon the next invocation, Tebako will use previously created packaging environment. The press process itself takes minutes.

You can manage setup of packaging environment manually; please refer to description of setup and clean commands below.

$

Although patches have been proposed (e.g., https://github.com/rails/rails/issues/39583), there is currently no way to change the paths for temporary files, caches, and sockets.