diff --git a/_pages/about.adoc b/_pages/about.adoc new file mode 100644 index 0000000..58d69e7 --- /dev/null +++ b/_pages/about.adoc @@ -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. \ No newline at end of file diff --git a/_pages/faq.adoc b/_pages/faq.adoc new file mode 100644 index 0000000..d7aad47 --- /dev/null +++ b/_pages/faq.adoc @@ -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. diff --git a/_pages/features.adoc b/_pages/features.adoc new file mode 100644 index 0000000..b68771d --- /dev/null +++ b/_pages/features.adoc @@ -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 `` with all sub-folders to packaged filesystem +| `/local/` +| No +| No +| No + + +| 2 +| Packaged gem +| Install the gem with `gem install` to packaged filesystem +| `/bin/` (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 + +| `/bin/` (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 + +| `/bin/` (i.e., binstub is expected) +| One +| One +| Any + + +| 5 +| Rails project +| Deploy project to packaged filesystem using `bundle install` +| `/local/` +| 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. diff --git a/assets/css/style.scss b/assets/css/style.scss index bc28f5b..4a65da5 100644 --- a/assets/css/style.scss +++ b/assets/css/style.scss @@ -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%); @@ -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 { diff --git a/assets/symbol.svg b/assets/symbol.svg index f78f589..ff1f48a 100644 --- a/assets/symbol.svg +++ b/assets/symbol.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/nav-links.html b/nav-links.html index e383107..64ab5e1 100644 --- a/nav-links.html +++ b/nav-links.html @@ -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 %} +