Skip to content

Commit

Permalink
feat: update logo and add content
Browse files Browse the repository at this point in the history
  • Loading branch information
ronaldtse committed Jul 27, 2024
1 parent 18bb694 commit 99ed788
Show file tree
Hide file tree
Showing 6 changed files with 332 additions and 5 deletions.
25 changes: 25 additions & 0 deletions _pages/about.adoc
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.
105 changes: 105 additions & 0 deletions _pages/faq.adoc
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.
186 changes: 186 additions & 0 deletions _pages/features.adoc
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.
13 changes: 9 additions & 4 deletions assets/css/style.scss
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@
$font-family: Quicksand, Verdana, sans-serif;
$hero-title-font-weight: 500;

$primary-color: #ffa200;
$accent-color: #8b5937;
$warning-color: #c5bf1e;
$important-color: #981919;
$primary-color: #f44c32;
$accent-color: #0e6493;
$warning-color: #a30202;
$important-color: #5b7393;

$main-background: linear-gradient(135deg, $primary-color 0%, $accent-color 100%);

Expand All @@ -33,6 +33,11 @@ $main-background: linear-gradient(135deg, $primary-color 0%, $accent-color 100%)
// }
// }

body > .underlay > header .site-logo svg {
height: 48px;
width: 48px;
margin-right: 1em;
}

// body.layout--home {
// > main .custom-intro .summary {
Expand Down
2 changes: 1 addition & 1 deletion assets/symbol.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 6 additions & 0 deletions nav-links.html
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,10 @@

{% include nav-page-link.html htmlclass="blog" url="/blog/" title="Blog" active_for_nested=true %}

{% include nav-page-link.html htmlclass="features" url="/features/" title="Features" active_for_nested=true %}

{% include nav-page-link.html htmlclass="faq" url="/faq/" title="FAQ" active_for_nested=true %}

{% include nav-page-link.html htmlclass="about" url="/about/" title="About" active_for_nested=true %}

<!-- <a href="javascript: void 0;" class="search" aria-label="site search button"><i class="fas fa-search"></i></a> -->

0 comments on commit 99ed788

Please sign in to comment.