tebako 0.12.16 → 0.13.0

data/README.adoc

@@ -1,20 +1,38 @@
 = Tebako: An advanced image packager for interpretive languages
 
-Platform tests on GitHub:
-image:https://github.com/tamatebako/tebako/actions/workflows/ubuntu.yml/badge.svg["Ubuntu amd64", link="https://github.com/tamatebako/tebako/actions/workflows/ubuntu.yml"]
-image:https://github.com/tamatebako/tebako/actions/workflows/alpine.yml/badge.svg["Alpine", link="https://github.com/tamatebako/tebako/actions/workflows/alpine.yml"]
-image:https://github.com/tamatebako/tebako/actions/workflows/macos.yml/badge.svg["macOS amd64", link="https://github.com/tamatebako/tebako/actions/workflows/macos.yml"]
-image:https://github.com/tamatebako/tebako/actions/workflows/windows-msys.yml/badge.svg["Windows msys", link="https://github.com/tamatebako/tebako/actions/workflows/windows-msys.yml"]
+.Continuous Integration Status
+[cols="1,1,3"]
+|===
+|*Platform Tests* |Architecture |Status
+
+.2+|Ubuntu
+|amd64 | image:https://github.com/tamatebako/tebako/actions/workflows/ubuntu.yml/badge.svg["Ubuntu amd64", link="https://github.com/tamatebako/tebako/actions/workflows/ubuntu.yml"]
+|arm64 |image:https://api.cirrus-ci.com/github/tamatebako/tebako.svg?branch=main&task=ubuntu-aarch64["Ubuntu aarch64", link="https://cirrus-ci.com/github/tamatebako/tebako"]
+
+|Alpine
+|amd64 |image:https://github.com/tamatebako/tebako/actions/workflows/alpine.yml/badge.svg["Alpine", link="https://github.com/tamatebako/tebako/actions/workflows/alpine.yml"]
+
+|macOS
+|amd64 + arm64
+|image:https://github.com/tamatebako/tebako/actions/workflows/macos.yml/badge.svg["macOS amd64 + arm64", link="https://github.com/tamatebako/tebako/actions/workflows/macos.yml"]
+
+|Windows MSYS2
+|amd64 |image:https://github.com/tamatebako/tebako/actions/workflows/windows-msys.yml/badge.svg["Windows MSYS2", link="https://github.com/tamatebako/tebako/actions/workflows/windows-msys.yml"]
+
+3+|*Tools Tests*
+
+|Tebako containers
+| |image:https://github.com/tamatebako/tebako-ci-containers/actions/workflows/build-containers.yml/badge.svg["Tebako containers", link="https://github.com/tamatebako/tebako-ci-containers/actions/workflows/build-containers.yml"]
+
+3+|*Quality*
 
-Platform tests on Cirrus:
-image:https://api.cirrus-ci.com/github/tamatebako/tebako.svg?branch=main&task=ubuntu-aarch64["Ubuntu aarch64", link="https://cirrus-ci.com/github/tamatebako/tebako"]
+|Lint and RSpec
+| |image:https://github.com/tamatebako/tebako/actions/workflows/lint-and-rspec.yml/badge.svg["Lint and RSpec", link="https://github.com/tamatebako/tebako/actions/workflows/lint-and-rspec.yml"]
 
-Tools tests on GitHub:
-image:https://github.com/tamatebako/tebako-ci-containers/actions/workflows/build-containers.yml/badge.svg["Tebako cobtainers", link="https://github.com/tamatebako/tebako-ci-containers/actions/workflows/build-containers.yml"]
+|Code Coverage
+| |image:https://codecov.io/gh/tamatebako/tebako/graph/badge.svg?token=XD3emQ5qsY["Tebako CLI RSpec coverage", link="https://codecov.io/gh/tamatebako/tebako"]
+|===
 
-Quality:
-image:https://github.com/tamatebako/tebako/actions/workflows/lint-and-rspec.yml/badge.svg["lint and rspec", link="https://github.com/tamatebako/tebako/actions/workflows/lint-and-rspec.yml"]
-image:https://codecov.io/gh/tamatebako/tebako/graph/badge.svg?token=XD3emQ5qsY["Tebako cli rspec coverage", link="https://codecov.io/gh/tamatebako/tebako"]
 
 == Purpose
 
@@ -56,6 +74,8 @@ architectures.
 
 3+| **Linux**
 | Ubuntu 20.04 | amd64, aarch64 | gcc/g+\+: 10; clang/clang++: 12
+| Ubuntu 22.04 | amd64, aarch64 | gcc/g+\+: 10; clang/clang++: 12
+| Ubuntu 24.04 | amd64, aarch64 | gcc/g+\+: 10; clang/clang++: 12
 | Alpine 3.17 | amd64 | gcc/g+\+: default; clang/clang++: default
 
 3+| **macOS**
@@ -106,7 +126,7 @@ higher.
 | 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 | Linux, macOS, Windows
+| 3.4.{1,2} | Linux, macOS, Windows
 
 |===
 
@@ -131,7 +151,8 @@ macOS packages are forward portable across different macOS versions.
 A Tebako executable package built on macOS 13 (Ventura) can be executed on
 macOS 14 (Sonoma), but not vice versa.
 
-`x86_64` macOS packages can be run on Apple M (ARM) systems.
+macOS packages compiled on `x86_64` can be run on Apple M (ARM64/aarch64)
+systems.
 
 
 === Linux distributions using `musl`
@@ -286,456 +307,80 @@ single, performant, executable binary.
 |===
 
 
-== Usage
-
-=== Command-line interface
-
-Tebako works by packaging your project into a single executable binary that
-includes all the necessary dependencies.
-
-The way to work with Tebako is through its command-line interface (CLI).
-It provides the following commands:
-
-`setup`::
-Prepares the Tebako packaging environment.
-
-`press`::
-Packages a project into a single executable binary.
-
-`clean`::
-Removes Tebako artifacts.
-
-`clean_ruby`::
-Removes Tebako Ruby artifacts.
-
-`hash`::
-Calculates the Tebako script hash for use as a cache key in CI/CD environments.
-
-`version`::
-Displays the Tebako version.
-
-`help`::
-Displays the help message.
-
-
-== Usage
-
-=== General
-
-Tebako can be used in two ways:
-
-* Through the Tebako container
-* Local installation
-
-Please refer to the <<installation>> section on how to install Tebako.
-
-
-[[installation]]
 == Installation
 
 === General
 
-Installation of Tebako is only needed in order to package an application.
-
-There is no need to install anything for users who run the packaged application.
-
-
-=== Using Docker
-
-==== General
-
-If you have Docker installed and available, the easiest way to run Tebako is
-through the official Docker containers.
-
-Docker containers with preinstalled Tebako packaging environments for Ubuntu and
-Alpine Linux are available at
-https://github.com/tamatebako/tebako-ci-containers[tebako-ci-containers].
-
-
-==== Pull the container
-
-Pull the Tebako container image.
-
-[source,sh]
-----
-docker pull ghcr.io/tamatebako/tebako-<container_tag>:latest
-----
-
-`<container_tag>`:: is the desired image tag (e.g., `ubuntu-20.04` or `alpine-3.17`).
+Tebako installation is only required for packaging applications.
 
+Users who run packaged applications do not need to install anything.
 
-==== Running Tebako commands in the container
+Tebako can be used for packaging in two ways:
 
-Simply prefix the Tebako command with `docker run` and the container image.
-
-[source,sh]
-----
-docker run -v <application_folder>:/mnt/w \
-  -t ghcr.io/tamatebako/tebako-<container_tag>:latest \
-  tebako {command} {parameters}
-----
-
-==== Packaging from outside the container
-
-To package your application from outside the container, just run a single Docker
-command.
-
-This command mounts the application folder into the container and runs the
-`tebako press` command, specifying the application root, entry point, output
-location, and Ruby version.
-
-[source,sh]
-----
-docker run -v <application_folder>:/mnt/w \
-  -t ghcr.io/tamatebako/tebako-<container_tag>:latest \
-  tebako press <tebako-press-parameters>
-----
-
-`<application_folder>`:: is the path to your application folder.
-
-`<container_tag>`:: is the desired image tag (e.g., `ubuntu-20.04` or `alpine-3.17`).
-
-
-[example]
-====
-Assume that you have a Ruby application in the `fontist` folder of the current
-directory.
-
-You can package it to `./fontist-package` using the following command:
-
-[source,sh]
-----
-docker run -v $PWD:/mnt/w \
-  -t ghcr.io/tamatebako/tebako-ubuntu-20.04:latest \
-  tebako press --root=/mnt/w/fontist --entry-point=fontist --output=/mnt/w/fontist-package --Ruby=3.2.4
-----
-====
-
-==== Packaging from inside the container
-
-It is also possible to package an application from inside the Tebako container.
-
-Start and enter the container interactively.
-
-[source,sh]
-----
-docker run -it --rm -v <application_folder>:/mnt/w \
-  ghcr.io/tamatebako/tebako-<container_tag>:latest bash
-----
-
-`<application_folder>`:: is the path to your application folder.
-
-`<container_tag>`:: is the desired image tag (e.g., `ubuntu-20.04` or `alpine-3.17`).
-
-
-Once inside, run the `tebako press` command:
-
-[source,sh]
-----
-tebako press <tebako press parameters>
-----
-
-[example]
-====
-Assume that you have a Ruby application in the `fontist` folder of the current
-directory.
-
-You can package it to `./fontist-package` using the following command:
-
-[source,sh]
-----
-$ docker run -it --rm -v $PWD:/mnt/w ghcr.io/tamatebako/tebako-<container_tag>:latest bash
-
-# Inside the container:
-$ tebako press --root=/mnt/w/fontist --entry-point=fontist --output=/mnt/w/fontist-package --Ruby=3.2.4
-----
-====
+* 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
 
-==== General
-
-There are cases where Docker may not be suitable for your needs, such as:
-
-. Admin privileges: Running Docker requires administrative privileges, which
-means Docker may not be available to users on their machines.
-
-. Performance penalty: Docker introduces a performance penalty due to the
-overhead of running containers. This can be a concern when packaging complex
-applications that require heavy memory usage.
-
-In such cases, you can choose to install Tebako locally.
-
-Tebako is distributed as a Ruby gem. A Ruby environment is necessary.
-
-
-[source,sh]
-----
-$ gem install tebako
-----
-
-
-==== Prerequisites
-
-These prerequisites are needed only for users who want to install Tebako on
-their machine and build all Tebako components locally.
+To use Tebako on macOS or Windows, you need to install it locally.
 
-If you use Docker, there is no need to set up these prerequisites.
+On Linux, there may be cases where Docker is not suitable for your needs, such as:
 
-===== Ubuntu 20.04
+1. Administrative privileges: Running Docker requires administrative privileges,
+which may not be available to all users on their machines.
 
-====== General
+2. Performance impact: Docker introduces performance overhead due to
+containerization. This can be a concern when packaging complex
+applications that require significant memory resources.
 
-There are several prerequisites that need to be installed on Ubuntu 20.04 for
-Tebako to work correctly.
+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.
 
-====== GNU C/C++ 10+ or Clang C/C++ 12+
-
-[source,sh]
-----
-apt install -y gcc-10 g++-10
-update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 10
-update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 10
-----
-
-or
-
-[source,sh]
-----
-apt install -y clang-12
-update-alternatives --install /usr/bin/clang clang /usr/bin/clang-12 150
-update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-12 150
-----
-
-====== CMake version 3.20+
-
-Tebako requires CMake at a version of at least 3.20+.
-
-If such CMake version is not available as a default package, set it up as
-follows.
-
-.Installing CMake 3.20+
-[source,sh]
-----
-apt-get remove --purge --auto-remove cmake
-apt-get update
-apt-get install -y software-properties-common lsb-release curl
-apt-get clean all
-curl https://apt.kitware.com/kitware-archive.sh | bash
-apt-get install cmake
-----
-
-====== Other development tools and libraries
-
-[source,sh]
-----
-apt-get -y install sudo git curl build-essential pkg-config bison flex autoconf  \
-   binutils-dev libevent-dev acl-dev libfmt-dev libjemalloc-dev libiberty-dev    \
-   libdouble-conversion-dev liblz4-dev liblzma-dev libssl-dev libunwind-dev      \
-   libboost-filesystem-dev libboost-program-options-dev libboost-system-dev      \
-   libboost-iostreams-dev  libboost-date-time-dev libboost-context-dev           \
-   libboost-regex-dev libboost-thread-dev libbrotli-dev libdwarf-dev libelf-dev  \
-   libgoogle-glog-dev libffi-dev libgdbm-dev libyaml-dev libncurses-dev          \
-   libreadline-dev libncurses-dev libreadline-dev ruby-dev ruby-bundler          \
-   libutfcpp-dev
-----
-
-===== Alpine 3.17
-
-====== General
-
-There are several prerequisites that need to be installed on Alpine 3.17 for
-Tebako to work correctly.
-
-====== APK packages
-
-Run the following command to install all prerequisites.
-
-[source,sh]
-----
-apk --no-cache --upgrade add build-base cmake git bash autoconf boost-static   \
-   boost-dev flex-dev bison make binutils-dev libevent-dev acl-dev sed python3 \
-   pkgconfig lz4-dev openssl-dev zlib-dev xz ninja zip unzip curl libdwarf-dev \
-   libunwind-dev gflags-dev elfutils-dev libevent-static openssl-libs-static   \
-   lz4-static xz-dev zlib-static libunwind-static acl-static tar libffi-dev    \
-   gdbm-dev yaml-dev yaml-static ncurses-dev ncurses-static readline-dev       \
-   readline-static p7zip ruby-dev gcompat gettext-dev gperf brotli-dev         \
-   brotli-static jemalloc-dev fmt-dev xz-static
-----
-
-===== macOS
-
-====== General
-
-There are several prerequisites that need to be installed on macOS for Tebako to work correctly.
-
-The following instructions work for:
-
-* macOS 13 (Ventura) through macOS 15 (Sequoia)
-
-
-====== Homebrew packages
-
-We use Homebrew to install the necessary packages on macOS.
-
-Tebako provides a `Brewfile` at the repository root that you can install all
-dependencies using the `brew bundle` command.
-
-[source,sh]
-----
-$ brew bundle
-----
-
-Alternatively, you can install the packages manually.
-
-[source,sh]
-----
-$ brew update
-$ brew install gnu-sed bash pkg-config bison flex binutils libffi gdbm zlib \
-  ncurses double-conversion boost jemalloc fmt glog libevent libsodium lz4 xz \
-  libyaml openssl@3
-----
-
-====== Bison 3+
-
-Tebako requires Bison 3+.
-
-On macOS 14, the default Bison version is 2.3, and the Homebrew formula is
-keg-only, which means that the full path to the Bison binary must be used to
-utilize the correct version.
-
-Run the following command prior to using Tebako, or add it into your shell
-profile.
-
-[source,sh]
-----
-export PATH="$(brew --prefix bison)/bin:$PATH"
-----
-
-====== jemalloc library build
-
-On macOS, the `libdwarfs` build script creates an additional `jemalloc`
-installation. This is done to satisfy the magic applied by folly during linking
-but uses a static library.
-
-If the `jemalloc` library is built within an emulated environment (QEMU,
-Rosetta, etc.), there are known issues
-(link:https://github.com/jemalloc/jemalloc/issues/1997[jemalloc issue #1997])
-where `jemalloc` incorrectly detects the number of significant virtual address
-bits and therefore defines them wrongly (`lg-vaddr` parameter).
-
-Technically, these issues can be fixed by explicitly setting the
-`--with-lg-vaddr` parameter for the `jemalloc` build. However, we decided not to
-automate this since we do not feel that we can provide reasonable test coverage.
-
-Instead, our build script accepts the `LG_VADDR` environment variable and passes
-it to the jemalloc build as `--with-lg-vaddr=${LG_VADDR}`.
-
-The `LG_VADDR` parameter specifies the number of significant virtual address
-bits, which can vary based on the CPU architecture and emulation status.
-
-This is a simple example script to set `LG_VADDR`.
-
-NOTE: This is provided for illustration only.
-
-[example]
-====
-[source,sh]
-----
-#!/bin/bash
-
-# Check the CPU architecture
-ARCH=$(uname -m)
-
-# Check if running under Rosetta 2 emulation
-if [[ "$ARCH" == "x86_64" && $(sysctl -n sysctl.proc_translated) == "1" ]]; then
-  echo "Running on Apple Silicon under Rosetta 2 emulation"
-  export LG_VADDR=39
-elif [[ "$ARCH" == "arm64" ]]; then
-  echo "Running on Apple Silicon"
-  export LG_VADDR=39
-else
-  echo "Running on Intel Silicon"
-  export LG_VADDR=48
-fi
-
-echo "Setting lg-vaddr to $LG_VADDR"
-----
-====
-
-
-===== Windows
-
-====== General
+== Usage
 
-The following instructions work for:
+=== Command-line interface
 
-* Windows 10, 11
-* Windows Server 2019, 2022
+Tebako works by packaging your project into a single executable binary that
+includes all the necessary dependencies.
 
-====== Ruby
+You interact with Tebako through its command-line interface (CLI),
+which provides the following commands:
 
-To run Tebako you need to have Ruby installed.
-It is simplest to use the Ruby development environment provided by
-https://rubyinstaller.org[RubyInstaller].
+Basic use:
 
-For example, Ruby+Devkit 3.1.4-1.
+`press`::
+Packages a project into a single executable binary.
+See <<press>> section for details.
 
-====== MinGW ucrt64
+Advanced use:
 
-Enable MinGW ucrt64 and install the necessary packages.
+`setup`::
+Runs post-install setup and creates the Tebako packaging environment.
+See <<setup>> section for details.
 
-The `ridk` command originates from the RubyInstaller installation.
+`clean`::
+Removes Tebako artifacts.
+See <<clean>> section for details.
 
-[source,sh]
-----
-$ ridk enable ucrt64
-$ pacman -S git tar bison flex toolchain make cmake
-          boost diffutils libevent double-conversion
-          fmt glog dlfcn gtest autotools ncurses libyaml
-----
+`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 <<hash>> section for details.
 
+`help`::
+Displays the help message.
 
 == Packaging
 
-[[root-folder-selection]]
-=== Tebako root folder (aka prefix) selection
-
-The Tebako prefix determines the base directory for the tebako packaging environment. It contain build artifacts for
-Tebako run-time, libraries and other components and is an essential part of configuring how Tebako operates within your system.
-
-The selection of the Tebako prefix follows a specific order of precedence to
-ensure flexibility and ease of use:
-
-. *User-specified prefix*:
-The most direct way to set the root folder is by specifying it through a
-command-line argument.
-
-. *Current Working Directory (PWD)*:
-If the prefix option is explicitly set to `PWD`, Tebako uses the current working
-directory as Tebako root folder.
-
-. *Environment variable (`TEBAKO_PREFIX`)*:
-In the absence of a user-specified option, Tebako looks for an environment
-variable named `TEBAKO_PREFIX`. If found, its value is used as the root folder.
-
-. *Default value*:
-If no prefix is specified and the `TEBAKO_DIR` environment variable is not set,
-Tebako defaults to using a directory named `.tebako` in the user's home
-directory.
-
-Path Expansion: Regardless of the method used to set the Tebako prefix, Tebako
-expands the provided path to an absolute path. This expansion includes resolving
-relative paths based on the current working directory and expanding user
-directory shortcuts like `~`.
-
-Please do not use Tebako prefix under your application root (`--root` parameter). It is not an error
-but it will cause Tebako to place all build-time artifacts to tebako package dramatically increasing its size.
-You do not need it unless under very special circumstances like tebako packaging tebako itself.
-
 === Commands
 
 Tebako provides several commands to manage the packaging and deployment process.
@@ -862,6 +507,8 @@ to be separately packaged.
 `application`::: Create the application package only. The output file is named according to the `-o` option.
 `runtime`::: Create the runtime package only. The output file is named according to the `-o` option.
 
+More information on the `mode` option is available in the <<Tebako runtime and application packages. Splitting and bundling.>> section.
+
 `--ref`::
 (optional)
 Defaults to `tebako-runtime`.
@@ -895,21 +542,20 @@ tebako press \
 
 ==== Setup
 
-This command sets up the Tebako packaging environment.
+Tebako requires post-install setup after gem installation .
+Post-intall setup is called automatically during the first packaging.
+There is no need run setup manually unless you need pristine Tebako
+packaging environment to implement caching strategy.
+We recommended to build cache based on `tebako setup` output. Building cache
+based on `tebako press` may create inconsistent environment upon restore.
+
 
-Collects required packages, builds the and creates packaging environment. This
+Setup collects required packages, builds the and creates packaging environment. This
 is a lengthy task that can take significant time, up to 1 hour.
 
 Tebako supports several configurations at a single system given that their root
 directories differ and multiple Ruby versions within single configuration
 
-This command is optional, tebako creates packaging environment automatically
-upon the first invocation of press command.
-
-However, if you plan to use tebako in CI/CD environment with caching it is
-highly recommended to build cache based on `tebako setup` output. Building cache
-based on `tebako press` may create inconsistent environment upon restore.
-
 [source,sh]
 ----
 $ tebako setup \
@@ -965,7 +611,7 @@ tebako clean --prefix='~/.tebako'
 ----
 ====
 
-
+<<clean_ruby>>
 ==== Clean Ruby
 
 This command cleans up only the Ruby artifacts from the specified prefix
@@ -1007,6 +653,7 @@ tebako clean_ruby --prefix='~/.tebako'
 ----
 ====
 
+<<hash>>
 ==== Build script hash
 
 This command outputs a hash value for the Tebako build script, which can be used
@@ -1017,6 +664,117 @@ as a cache key in CI/CD pipelines.
 $ tebako hash
 ----
 
+=== Using Docker
+
+==== General
+
+If you have Docker installed and available, the easiest way to run Tebako is
+through the official Docker containers.
+
+Docker containers with preinstalled Tebako packaging environments for Ubuntu and
+Alpine Linux are available at
+https://github.com/tamatebako/tebako-ci-containers[tebako-ci-containers].
+
+
+==== Pull the container
+
+Pull the Tebako container image.
+
+[source,sh]
+----
+docker pull ghcr.io/tamatebako/tebako-<container_tag>:latest
+----
+
+`<container_tag>`:: is the desired image tag (e.g., `ubuntu-20.04` or `alpine-3.17`).
+
+
+==== Running Tebako commands in the container
+
+Simply prefix the Tebako command with `docker run` and the container image.
+
+[source,sh]
+----
+docker run -v <application_folder>:/mnt/w \
+  -t ghcr.io/tamatebako/tebako-<container_tag>:latest \
+  tebako {command} {parameters}
+----
+
+==== Packaging from outside the container
+
+To package your application from outside the container, just run a single Docker
+command.
+
+This command mounts the application folder into the container and runs the
+`tebako press` command, specifying the application root, entry point, output
+location, and Ruby version.
+
+[source,sh]
+----
+docker run -v <application_folder>:/mnt/w \
+  -t ghcr.io/tamatebako/tebako-<container_tag>:latest \
+  tebako press <tebako-press-parameters>
+----
+
+`<application_folder>`:: is the path to your application folder.
+
+`<container_tag>`:: is the desired image tag (e.g., `ubuntu-20.04` or `alpine-3.17`).
+
+
+[example]
+====
+Assume that you have a Ruby application in the `fontist` folder of the current
+directory.
+
+You can package it to `./fontist-package` using the following command:
+
+[source,sh]
+----
+docker run -v $PWD:/mnt/w \
+  -t ghcr.io/tamatebako/tebako-ubuntu-20.04:latest \
+  tebako press --root=/mnt/w/fontist --entry-point=fontist --output=/mnt/w/fontist-package --Ruby=3.2.4
+----
+====
+
+==== Packaging from inside the container
+
+It is also possible to package an application from inside the Tebako container.
+
+Start and enter the container interactively.
+
+[source,sh]
+----
+docker run -it --rm -v <application_folder>:/mnt/w \
+  ghcr.io/tamatebako/tebako-<container_tag>:latest bash
+----
+
+`<application_folder>`:: is the path to your application folder.
+
+`<container_tag>`:: is the desired image tag (e.g., `ubuntu-20.04` or `alpine-3.17`).
+
+
+Once inside, run the `tebako press` command:
+
+[source,sh]
+----
+tebako press <tebako press parameters>
+----
+
+[example]
+====
+Assume that you have a Ruby application in the `fontist` folder of the current
+directory.
+
+You can package it to `./fontist-package` using the following command:
+
+[source,sh]
+----
+$ docker run -it --rm -v $PWD:/mnt/w ghcr.io/tamatebako/tebako-<container_tag>:latest bash
+
+# Inside the container:
+$ tebako press --root=/mnt/w/fontist --entry-point=fontist --output=/mnt/w/fontist-package --Ruby=3.2.4
+----
+====
+
 === Tebako configuration file
 
 It is possible to provide all or some options for the `tebako
@@ -1047,7 +805,20 @@ options:
 ----
 ====
 
-=== Options prefernce order
+[[root-folder-selection]]
+=== Tebako root folder (aka prefix) selection
+
+The Tebako prefix determines the base directory for the tebako packaging environment. It contain build artifacts for
+Tebako run-time, libraries and other components and is an essential part of configuring how Tebako operates within your system.
+
+The selection of the Tebako prefix follows a specific order of precedence to
+ensure flexibility and ease of use as described in the next section.
+
+Please do not use Tebako prefix under your application root (`--root` parameter). It is not an error
+but it will cause Tebako to place all build-time artifacts to tebako package dramatically increasing its size.
+You do not need it unless under very special circumstances like tebako packaging tebako itself.
+
+=== Options preference order
 
 Tebako supports several methods to set options. The table below show preference order and limitations for specific options.
 samller order means higher proirity.
@@ -1213,41 +984,12 @@ Here is a summary of the scenarios:
 
 These scenarios determine how the project is packaged and where the entry point is located within the packaged filesystem.
 
-== Run-time options
+== Tebako runtime and application packages. Splitting and bundling.
 
 === General
 
-Generally Tebako package passes command line options to the packaged application.
-
-[example]
-====
-For example, if the package was created with the following command
-
-[source,sh]
-----
-tebako press \
-  --root='~/projects/myproject' \
-  --entry=start.rb \
-  --output=/temp/myproject.tebako
-----
-running
-
-[source,sh]
-----
-/temp/myproject.tebako --option --parameter value
-----
-
-will be translated by Tebako bootstrap code to
-
-[source,sh]
-----
-myproject --option --parameter value
-----
-====
-
-However there are several command-line parameters that are intercepted processed
-by Tebako bootstrap code as described below.
-
+Tebako provides a method either to create a single bundle package that contains  Ruby run-time and the application or create separate
+reusable runtime package and application package that can be deployed without a runtime.
 
 === Creating a bundle package
 
@@ -1394,10 +1136,68 @@ Hello, Maxim!
 ----
 ====
 
+== Packaging Ruby Gems with Post-Installation Requirements
+
+Unlike the traditional approach to Ruby program distribution, Tebako is designed with a clear separation between the build and
+target environments. We assume that a Tebako package created in the build environment should remain independent of it and run unchanged
+in the target environment.
+
+While this approach is appealing, it imposes certain limitations on some Ruby gems, including Tebako itself. Specifically, gems that
+require a post-installation setup step often establish a strong dependency on the target environment. This setup might involve installing
+native libraries, linking to existing system components, or otherwise relying on the target system’s configuration.
+
+To be packaged by Tebako, gems that require post-installation setup must meet two additional requirements:
+
+1. *Ability to run post-installation setup from a read-only filesystem, outside the gem installation folder.*
+   For example, Tebako uses the location specified by the `prefix` parameter to create any necessary files during post-installation.
+
+2. *Automatic execution of the post-installation setup when required.*
+   For instance, when the `tebako press` command is executed, it first checks whether `tebako setup` has been run and triggers it if necessary.
+
+By adhering to these principles, gems that require post-installation setup will not only be compatible with Tebako but will also provide a more
+robust and consistent runtime experience, allowing them to run seamlessly across different environments.
+
+
+== Run-time options
+
+=== General
+
+Generally, Tebako packages pass command line options to the packaged application.
+
+[example]
+====
+For example, if the package was created with the following command
+
+[source,sh]
+----
+tebako press \
+  --root='~/projects/myproject' \
+  --entry=start.rb \
+  --output=/temp/myproject.tebako
+----
+running
+
+[source,sh]
+----
+/temp/myproject.tebako --option --parameter value
+----
+
+will be translated by Tebako bootstrap code to
+
+[source,sh]
+----
+myproject --option --parameter value
+----
+====
+
+However, there are several command-line parameters that are intercepted and processed
+by Tebako bootstrap code as described below.
+
+
 === Image extraction (`--tebako-extract` option)
 
 Tebako provides an option to extract its DwarFS filesystem from a package to
-a local folder for verification or execution.
+a local folder for verification or examination.
 
 [source,sh]
 ----
@@ -1450,11 +1250,11 @@ change the paths for temporary files, caches, and sockets.
 To address this inevitable limitation for Ruby applications,
 Tebako provides an option to mount a host folder to the memfs tree.
 
-When using Tebako, consider the packaging scenario mentioned above, as it
-defines the layout of the application tree.
+When using Tebako, be aware of how your application's directory structure is packaged,
+as this affects which paths may need mounting.
 
-The `--tebako-extract` option may be useful for understanding the placement of
-files and folders.
+You can use the `--tebako-extract` option described earlier to better understand
+your application's file structure before deciding which folders to mount.
 
 [example]
 ====
@@ -1479,8 +1279,8 @@ The `--tebako-mount` option has the following syntax:
 The `--tebako-mount` option can be repeated multiple times to mount more than
 one object. The `memfs path` is relative to the memfs root, and it is
 recommended to use absolute paths for host objects. Both directories and files
-can be mounted in this way. Tebako allows overlaying existing memfs objects, so
-there are no significant limitations.
+can be mounted in this way. Tebako allows you to overlay host directories on existing memfs objects,
+providing a flexible solution for handling read-write requirements in packaged applications.
 
 == Trivia: origin of name
 
@@ -1497,11 +1297,16 @@ Since "tamatebako" is rather long for the non-Japanese speaker, we use "tebako"
 
 == Contributing
 
-We welcome contributions! Please see our contributing guidelines for more
-information.
+We welcome contributions!
+
+Please see our link:CONTRIBUTING.adoc[contribution guidelines] and our
+link:CODE_OF_CONDUCT.adoc[code of conduct] for more information,.
+
+NOTE: Our guidelines are aligned with the contribution guidelines from the RNP project.
 
 == License
 
 Copyright Ribose. All rights reserved.
 
-Tebako is released under the BSD 2-Clause License. See the LICENSE file for details.
+Tebako is released under the BSD 2-Clause License. See the
+link:LICENSE.md[LICENSE.md] file for details.