-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
6 changed files
with
332 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
--- | ||
title: About | ||
description: About Tebako | ||
layout: post | ||
--- | ||
|
||
== Origin | ||
|
||
Tebako was originally created to produce a single-binary version of | ||
https://www.metanorma.org[Metanorma], | ||
which uses Ruby. | ||
|
||
|
||
== Origin of name | ||
|
||
"tamatebako" (玉手箱) is the treasure box given to Urashima Taro in the Ryugu, | ||
for which he was asked not to open if he wished to return. He opened the box | ||
upon the shock from his return that three hundred years has passed. Apparently | ||
what was stored in the box was his age. | ||
|
||
This packager was made to store Ruby and its gems, and therefore named after | ||
the said treasure box (storing gems inside a treasure box). | ||
|
||
Since "tamatebako" is rather long for the non-Japanese speaker, we use "tebako" | ||
(手箱, also "tehako") instead, the generic term for a personal box. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,105 @@ | ||
--- | ||
title: Frequently Asked Questions (FAQ) | ||
description: FAQ on Tebako | ||
layout: post | ||
--- | ||
|
||
== 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 | ||
|
||
|=== | ||
|
||
|
||
== What are the future plans for Tebako? | ||
|
||
* 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,186 @@ | ||
--- | ||
title: Features | ||
description: Features of Tebako | ||
layout: post | ||
--- | ||
|
||
Tebako is an advanced executable packager designed for applications written in | ||
interpretive languages. | ||
|
||
It simplifies distribution and deployment by packaging your entire project with | ||
a bundled runtime into a single, performant, executable binary. | ||
|
||
|
||
== Architecture | ||
|
||
A Tebako-packaged binary is effectively a self-executing container-in-a-file. | ||
|
||
The packaged binary contains the following components: | ||
|
||
* An on-file filesystem (OFFS) containing all the project files and | ||
dependencies in DwarFS format. | ||
|
||
* A runtime environment that includes the necessary libraries and interpreters, | ||
with patched filesystem calls that redirect access of project files to the | ||
on-file filesystem. | ||
|
||
* An executable loader that loads the on-file filesystem in memory and executes | ||
the project. | ||
|
||
|
||
== 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 | ||
|
||
3+| **Linux** | ||
| Ubuntu 20.04 | amd64, aarch64 | gcc/g+\+: 10; clang/clang++: 12 | ||
| Alpine 3.17 | amd64 | gcc/g+\+: default; clang/clang++: default | ||
|
||
3+| **macOS** | ||
| macOS 12 (Monterey) | amd64 | xcode: [13.1, 14.3.1] | ||
| macOS 13 (Ventura) | amd64, aarch64 | xcode: [13.1, 14.3.1] | ||
| macOS 14 (Sonoma) | amd64, aarch64 | xcode: [13.1, 14.3.1, 15.4] | ||
|
||
3+| **Windows** | ||
| Windows 10 | amd64 | MinGW ucrt64 | ||
| Windows 11 | amd64 | MinGW ucrt64 | ||
| Windows Server 2019 | amd64 | MinGW ucrt64 | ||
| Windows Server 2022 | amd64 | MinGW ucrt64 | ||
|
||
|=== | ||
|
||
[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 it may affect the gems that need | ||
to be packaged 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 a CMake executable. | ||
. The MSys strip utility creates broken executable when tebako image is processed. | ||
** Linking with '-s' flag produces unusable executables as well. | ||
** Until this issue (#172) is resolved we plan to produce an Windows executable | ||
with debug information unstripped. | ||
** You can opt to run 'strip -S' manually, it most cases it works. | ||
==== | ||
|
||
|
||
.Supported Ruby versions | ||
[cols="2", options="header"] | ||
|=== | ||
| Ruby version | Supported platforms | ||
|
||
| 2.7.8 | Linux, macOS | ||
| 3.0.7 | Linux, macOS | ||
| 3.1.{4,5,6} | Linux, macOS, Windows | ||
| 3.2.{3,4} | Linux, macOS, Windows | ||
| 3.3.{3,4} | Linux, macOS, Windows | ||
|
||
|=== | ||
|
||
NOTE: Our goal is to support all maintained Ruby releases, including minor versions. | ||
|
||
== Packaging scenarios for Ruby | ||
|
||
Tebako for Ruby supports the following packaging scenarios. | ||
|
||
This is high-level description of the Tebako Ruby packaging mechanism. | ||
|
||
NOTE: These scenarios were inspired by the `ruby-packer` approach. | ||
|
||
NOTE: Tebako Ruby is created independently from `ruby-packer`, no line of code | ||
was copied from `ruby-packer`. | ||
|
||
Depending on the configuration files that are present in the root project folder, the Tebako Ruby packager supports different packaging scenarios. | ||
|
||
These scenarios differ in what files are packaged and where the entry point is located. | ||
|
||
Here is a summary of the scenarios: | ||
|
||
[cols="a,2a,4a,3a,a,a,a"] | ||
|=== | ||
| Scenario | Description | Packaging | Entry point | `*.gemspec` | `Gemfile` | `*.gem` | ||
|
||
| 1 | ||
| Simple ruby script | ||
| Copy `<project-root>` with all sub-folders to packaged filesystem | ||
| `<mount_point>/local/<entry_point base name>` | ||
| No | ||
| No | ||
| No | ||
|
||
|
||
| 2 | ||
| Packaged gem | ||
| Install the gem with `gem install` to packaged filesystem | ||
| `<mount_point>/bin/<entry_point base name>` (i.e., binstub is expected) | ||
| No | ||
| No | ||
| One | ||
|
||
|
||
| 3 | ||
| Gem source, no `bundler` | ||
| | ||
. Build the gem using `gem build` command at the host | ||
. Install it with `gem install` to packaged filesystem | ||
|
||
| `<mount_point>/bin/<entry_point base name>` (i.e., binstub is expected) | ||
| One | ||
| No | ||
| Any | ||
|
||
|
||
| 4 | ||
| Gem source, `bundler` | ||
| | ||
. Collect dependencies at the host with `bundle install` | ||
. Build the gem using `gem build` command | ||
. Install it with `gem install` to packaged file system | ||
|
||
| `<mount_point>/bin/<entry_point base name>` (i.e., binstub is expected) | ||
| One | ||
| One | ||
| Any | ||
|
||
|
||
| 5 | ||
| Rails project | ||
| Deploy project to packaged filesystem using `bundle install` | ||
| `<mount_point>/local/<entry_point base name>` | ||
| No | ||
| One | ||
| Any | ||
|
||
|
||
| Error | ||
| Error: Two or more `*.gem` files present | ||
| - | ||
| - | ||
| No | ||
| No | ||
| Two or more | ||
|
||
|
||
| Error | ||
| Error: Two or more `*.gemspec` files present | ||
| - | ||
| - | ||
| Two or more | ||
| Any | ||
| Any | ||
|
||
|=== | ||
|
||
|
||
These scenarios determine how the project is packaged and where the entry point | ||
is located within the packaged filesystem. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters