tebako 0.12.15 → 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"]
 
-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"]
+3+|*Tools Tests*
 
-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"]
+|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*
+
+|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"]
+
+|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,453 +307,79 @@ 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`).
-
-
-==== 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`).
+Tebako installation is only required for packaging applications.
 
+Users who run packaged applications do not need to install anything.
 
-Once inside, run the `tebako press` command:
+Tebako can be used for packaging in two ways:
 
-[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.
-
-If you use Docker, there is no need to set up these prerequisites.
-
-===== Ubuntu 20.04
-
-====== General
-
-There are several prerequisites that need to be installed on Ubuntu 20.04 for
-Tebako to work correctly.
-
-
-====== 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.
+To use Tebako on macOS or Windows, you need to install it locally.
 
-====== APK packages
+On Linux, there may be cases where Docker is not suitable for your needs, such as:
 
-Run the following command to install all prerequisites.
+1. Administrative privileges: Running Docker requires administrative privileges,
+which may not be available to all users on their machines.
 
-[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.
-
-[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
-brew bundle
-----
-
-Additionaly tebako repository includes `Brewfile` that can be used with
-`brew bundle` command.
-
-[source,sh]
-----
-brew bundle
-----
-
-====== 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}`.
+2. Performance impact: Docker introduces performance overhead due to
+containerization. This can be a concern when packaging complex
+applications that require significant memory resources.
 
-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
-
-The following instructions work for:
-
-* Windows 10, 11
-* Windows Server 2019, 2022
-
-====== Ruby
-
-To run Tebako you need to have Ruby installed.
-It is simplest to use the Ruby development environment provided by
-https://rubyinstaller.org[RubyInstaller].
-
-For example, Ruby+Devkit 3.1.4-1.
-
-====== MinGW ucrt64
-
-Enable MinGW ucrt64 and install the necessary packages.
-
-The `ridk` command originates from the RubyInstaller installation.
-
-[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
-----
+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
 
-== Packaging
+=== Command-line interface
 
-[[root-folder-selection]]
-=== Tebako root folder (aka prefix) selection
+Tebako works by packaging your project into a single executable binary that
+includes all the necessary dependencies.
 
-The Tebako prefix determines the base directory for the Tebako setup.
+You interact with Tebako through its command-line interface (CLI),
+which provides the following commands:
 
-It is an essential part of configuring how Tebako operates within your system.
+Basic use:
 
-The selection of the Tebako prefix follows a specific order of precedence to
-ensure flexibility and ease of use:
+`press`::
+Packages a project into a single executable binary.
+See <<press>> section for details.
 
-. *User-specified prefix*:
-The most direct way to set the root folder is by specifying it through a
-command-line argument.
+Advanced use:
 
-. *Current Working Directory (PWD)*:
-If the prefix option is explicitly set to `PWD`, Tebako uses the current working
-directory as Tebako root folder.
+`setup`::
+Runs post-install setup and creates the Tebako packaging environment.
+See <<setup>> section for details.
 
-. *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.
+`clean`::
+Removes Tebako artifacts.
+See <<clean>> section for details.
 
-. *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.
+`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.
 
-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 `~`.
+`help`::
+Displays the help message.
 
+== Packaging
 
 === Commands
 
@@ -766,7 +413,7 @@ tebako press \
   [-R|--Ruby=<ruby-version>] \
   [-o|--output=<packaged-file-name>] \
   [-l|--log-level=<error|warn|debug|trace>] \
-  [-c|--cwd=<package current working directory>]
+  [-c|--cwd=<package-current-working-directory>] \
   [-D|--devmode] \
   [-P|--patchelf] \
   [-m|--mode=<bundle|both|application|runtime>] \
@@ -776,56 +423,70 @@ tebako press \
 
 Where:
 
-`<tebako-root-folder>`::
+`--entry-point=<entry-point>`::
+an executable file (binary executable or script) that shall be started when
+packaged file is called. This parameter is not required if the operation mode is `runtime`.
+
+`--prefix=<tebako-root-folder>`::
 the Tebako root folder (see details: <<root-folder-selection>>)
 
-`Ruby`::
+`--Ruby=<ruby-version>`::
 this parameter defines Ruby version that will be packaged (optional, defaults to
 `3.3.7`)
 
-`project-root`::
+`--root=<project-root-folder>`::
 a folder at the host source file system where project files are located.
 This parameter is not required if the operation mode is `runtime`.
 
-`entry-point`::
-an executable file (binary executable or script) that shall be started when
-packaged file is called. This parameter is not required if the operation mode is `runtime`.
-
-`output`::
+`--output=<packaged-file-name>`::
 (optional)
 the output file name.
 +
-Defaults to `<current folder>/<entry point base name>`.
-+
-On Windows output file will have `exe` extension.
-If the application is to be a separate file (`both` or `application` mode), it
-will have the same name with the `.tebako` extension.
+On Windows, the output file is automatically appended the `.exe` extension.
+
+** If the `-o` option is not specified:
+
+*** in `runtime` mode, the runtime package is created at `tebako-runtime`.
+*** in `application` mode, the application package is created at `<current-folder>/<entry-point-base-name>`.
+*** in `bundle` mode, the bundled package is created at `<current-folder>/<entry-point-base-name>`.
+*** in `both` mode, the runtime package is created at `<current-folder>/<entry-point-base-name>`,
+and the application package is created at `<current-folder>/<entry-point-base-name>.tebako`.
 
-`log-level`::
-logging level for the Tebako built-in memory filesystem driver
+** If the `-o` option is specified:
+
+*** in `runtime` mode, the runtime package is named according to the `-o` option.
+*** in `application` mode, the application package is named according to the `-o` option.
+*** in `bundle` mode, the bundled package is named according to the `-o` option.
+*** in `both` mode, the runtime package is named according to the `-o` option,
+and the application package is named according to the `-o` option with the `.tebako` extension.
+
+
+`--log-level=<error|warn|debug|trace>`::
 (optional, defaults to `error`)
+logging level for the Tebako built-in memory filesystem driver.
 
-`cwd`::
+`--cwd=<package-current-working-directory>`::
 (optional)
-a folder within Tebako memfs where the packaged application will start. This folder should be specified relative to the memfs root.
+A folder within Tebako memfs where the packaged application will start. This
+folder should be specified relative to the memfs root.
 +
 If not provided, the application will start within the current folder of the
 host (i.e., at `$PWD`).
 +
 This argument is required because it is not possible to change the directory to
 a memfs folder until the package is started, as opposed to any host folder that
-can be set as the current directory before Tebako package invocation.  Tebako
+can be set as the current directory before Tebako package invocation. Tebako
 saves the original working directory in a global Ruby variable
 `$tebako_original_pwd`.
 
-`devmode`:: flag that activates development mode, in which Tebako's cache and
+`--devmode`:: flag that activates development mode, in which Tebako's cache and
 packaging consistency checks are relaxed.
 
-`patchelf`::
+`--patchelf`::
 Allows forward-compatibility of Tebako packages with Linux GNU distributions.
 +
 Specifically, this is a flag that removes a reference to the `GLIBC_PRIVATE`
-version of `libpthread` from a Tebako package.  This allows Linux GNU packages
+version of `libpthread` from a Tebako package. This allows Linux GNU packages
 to run against versions of `libpthread` that differ from the version used for
 packaging.
 +
@@ -836,32 +497,36 @@ For example, a package created at Ubuntu 20 system can be used on Ubuntu 22.
 +
 NOTE: The feature is exeprimental, we may consider another approach in the future.
 
-`mode`::
-output mode for tebako package (optional, defaults to `bundle`).
+`--mode=<mode>`::
+(optional, defaults to `bundle`)
+Package output mode, determines whether the runtime and/or application are
+to be separately packaged.
+
+`bundle`::: Create a single package bundling both the runtime and application. The output file is named according to the `-o` option.
+`both`::: Create separate packages for the runtime and application. Outputs two separate files: one for the runtime at the location specified at the `-o {filename}` and one for the application at `{filename}.package`.
+`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.
 
-`bundle`::: place runtime and application to a single file
-`both`::: create both run-rime and application
-`application`::: create appplication only
-`runtime`::: create runtime only
+More information on the `mode` option is available in the <<Tebako runtime and application packages. Splitting and bundling.>> section.
 
-`ref`::
+`--ref`::
 (optional)
 Defaults to `tebako-runtime`.
 When a Tebako application package is created on Windows, it is linked against a
 Tebako runtime file name. The `ref` parameter allows to specify the name of the
 runtime file.
 +
-NOTE: The `ref` option specificies the name of the runtime -- the runtime file
+NOTE: The `--ref` option specifies the name of the runtime -- the runtime file
 can be recreated or changed but not renamed.
 
-`tebafile`::
+`--tebafile=<path>`::
 the tebako configuration file (optional, defaults to `$PWD/.tebako.yml`).
 Please refer to the separate section below for description of the tebafile.
 +
 NOTE: Development mode is *not intended for production use* and should only be
 used during development.
 +
-NOTE: `entry-point` and `project-root-folder` are required parameters and may be
+NOTE: `--entry-point` and `--project-root-folder` are required parameters and may be
 provided either via command-line or in the tebafile.
 
 [example]
@@ -877,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 \
@@ -903,16 +567,18 @@ $ tebako setup \
 
 Where:
 
-`<tebako-root-folder>`:: the Tebako root folder (see details: <<root-folder-selection>>)
+`--prefix=<tebako-root-folder>`:: the Tebako root folder (see details: <<root-folder-selection>>)
 
-`Ruby`:: parameter defines package Ruby version (optional). This version is used in conjuction with requirements
-from the Gemfile as explained below in 'Package Ruby version selection rules' section.
+`--Ruby=<ruby-version>`::
+parameter defines package Ruby version (optional).
+This version is used in conjunction with requirements from the `Gemfile` as
+explained below in <<ruby-and-bundler-versions>>.
 
-`tebafile`::
+`--tebafile=<path>`::
 the tebako configuration file (optional, defaults to `$PWD/.tebako.yml`).
 Please refer to the separate section below for tebafile description.
 
-`devmode`:: flag activates development mode, in which Tebako's cache and packaging consistency checks are relaxed.
+`--devmode`:: flag activates development mode, in which Tebako's cache and packaging consistency checks are relaxed.
 Please note that this mode is not intended for production use and should only be used during development.
 
 ==== Clean
@@ -931,9 +597,9 @@ $ tebako clean \
 
 Where:
 
-`<tebako-root-folder>`:: the Tebako root folder (see details: <<root-folder-selection>>)
+`--prefix=<tebako-root-folder>`:: the Tebako root folder (see details: <<root-folder-selection>>)
 
-`tebafile`::
+`--tebafile=<path>`::
 the tebako configuration file (optional, defaults to `$PWD/.tebako.yml`).
 Please refer to the separate section below for tebafile description.
 
@@ -945,7 +611,7 @@ tebako clean --prefix='~/.tebako'
 ----
 ====
 
-
+<<clean_ruby>>
 ==== Clean Ruby
 
 This command cleans up only the Ruby artifacts from the specified prefix
@@ -968,13 +634,14 @@ $ tebako clean_ruby
 
 Where:
 
-`<tebako-root-folder>`::
+`--prefix=<tebako-root-folder>`::
 the Tebako setup folder (optional, defaults to current folder)
 
-`Ruby`::
-defines Ruby version that will cleaned (optional, cleans all versions by default)
+`--Ruby=<ruby-version>`::
+(optional, cleans all versions by default)
+defines Ruby version that will be cleaned.
 
-`tebafile`::
+`--tebafile=<path>`::
 the tebako configuration file (optional, defaults to `$PWD/.tebako.yml`).
 Please refer to the separate section below for tebafile description.
 
@@ -986,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
@@ -996,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
@@ -1026,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.
@@ -1036,11 +828,11 @@ samller order means higher proirity.
 | Order | Mode | Option source | Applicability
 
 | 1 | All | Command-line | All options
-| 2 | All |Tebako configuration file | All option except ``--tebafile`` (you can not specify new tebafile in a tebafile)
-.2+| 3 .2+| All .2+| Environment variable | TEBAKO_PREFIX to set ``--prefix`` option
-| LG_VADDR to set ``--with-lg-vaddr`` jemalloc parameter
-.2+| 4 | ``runtime`` | Tebako defaults | All options except ``--entry-point`` and ``--root`` that are mandatory
-| ``bundle``, ``both``, ``application`` | Tebako defaults | All options
+| 2 | All |Tebako configuration file | All option except `--tebafile` (you can not specify new tebafile in a tebafile)
+.2+| 3 .2+| All .2+| Environment variable | TEBAKO_PREFIX to set `--prefix` option
+| LG_VADDR to set `--with-lg-vaddr` jemalloc parameter
+.2+| 4 | `runtime` | Tebako defaults | All options except `--entry-point` and `--root` that are mandatory
+| `bundle`, `both`, `application` | Tebako defaults | All options
 
 |===
 
@@ -1075,6 +867,7 @@ operation. The following table lists the possible exit codes and their meanings.
 | 116  | Ruby version does not satify Gemfile requirements
 |===
 
+[[ruby-and-bundler-versions]]
 == Ruby and bundler versions selection
 
 During packaging tebako creates its own Ruby execution environment that is independent from the host Ruby environment.
@@ -1191,88 +984,220 @@ 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.
+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
+
+Tebako provides a method to create and manage a bundle package, which simplifies
+the process of packaging dependencies along with the application.
+
+[source,sh]
+----
+$ tebako bundle create -o <bundle-package> -r <project-root-folder> [-R <ruby-version>]
+----
+
+To run the bundle package, use the following command:
+
+[source,sh]
+----
+$ <bundle-package>
+----
 
 [example]
 ====
-For example, if the package was created with the following command
+[source,sh]
+----
+$ tebako bundle create -o myproject-bundle -r ~/projects/myproject -R 3.4.1
+# => creates `myproject-bundle`, a bundle package for Ruby 3.4.1
+$ myproject-bundle
+# => runs the bundle package
+----
+====
+
+=== Creating separate runtime and application packages
+
+Tebako allows creating separate runtime and application packages that can be used
+to run a Tebako application package.
 
 [source,sh]
 ----
-tebako press \
-  --root='~/projects/myproject' \
-  --entry=start.rb \
-  --output=/temp/myproject.tebako
+$ tebako press -m both \
+  -o <tebako-runtime-package> \
+  -e <entry-point> \
+  -r <project-root-folder> \
+  [-R <ruby-version>]
 ----
-running
+
+The resulting packages will be generated in the current directory as:
+
+* Tebako runtime package at the `-o` location, i.e. `<tebako-runtime-package>`.
+* Tebako application package. The name of the application package will be the
+  same as the runtime package with the `.package` extension.
+
+
+=== Creating a Tebako runtime package
+
+Tebako allows creating a Tebako runtime package that can be used to run a Tebako
+application package.
 
 [source,sh]
 ----
-/temp/myproject.tebako --option --parameter value
+$ tebako press -m runtime -o <tebako-runtime-package> [-R <ruby-version>]
 ----
 
-will be translated by Tebako bootstrap code to
+[example]
+====
+[source,sh]
+----
+$ tebako press -o tebako-ruby-3.4.1 -R 3.4.1
+# => creates `tebako-ruby-3.4.1`, a Tebako runtime package for Ruby 3.4.1
+----
+====
+
+=== Creating a Tebako application package
+
+Tebako allows creating a Tebako application package that can be run with a
+Tebako runtime package.
 
 [source,sh]
 ----
-myproject --option --parameter value
+$ tebako press -m application \
+    -o <tebako-application-package> \
+    -e <entry-point> \
+    -r <project-root-folder> \
+    [-R <ruby-version>]
+----
+
+[example]
+====
+[source,sh]
+----
+$ tebako press -m application \
+    -o tebako-application-package \
+    -e start.rb \
+    -r ~/projects/myproject \
+    -R 3.4.1
+# => creates `tebako-application-package`, a Tebako application package for Ruby 3.4.1
 ----
 ====
 
-However there are several command-line parameters that are intercepted processed
-by Tebako bootstrap code as described below.
 
-=== Running tebako image by tebako runtime (`--tebako-run` option)
+=== Running Tebako application using a Tebako runtime (`--tebako-run` option)
 
-Tebako provides an option to an extract its DwarFS filesystem from a package to
-a local folder for verification or execution.
+The Tebako application package can be executed by a Tebako runtime package.
 
 [source,sh]
 ----
-$ <tebako-runtime> --tebako-run [<tebako application>]
+$ <tebako-runtime-package> --tebako-run [<tebako-application-package>]
 ----
 
 Where,
 
-`<tebako runtime>`::
-The tebako runtime in ```runtime``` or ```both``` mode
+`<tebako-runtime-package>`::
+The Tebako runtime package file created using in `runtime` or `both` mode.
 
-`<tebako application>`::
-The tebako application package created in ```application``` or ```both``` mode
+`<tebako-application-package>`::
+The Tebako application package created in `application` or `both` mode.
 
 [example]
 ====
-Creating separate runtime and application and running it:
+Given a Ruby application at `hello.rb`:
+
+[source,Ruby]
+----
+puts "Hello, #{ARGV[0]}!"
+----
+
+Create separate runtime and application packages:
 
 [source,sh]
 ----
-tebako press -m runtime -o tebako-runtime
-tebako press -m application -o tebako-application -e hello.rb -r test
-tabako-runtime --tebako-run tebako-application Maxim
+tebako press -m runtime -o tebako-runtime-package
+tebako press -m application -o tebako-application-package -e hello.rb -r test
 ----
-where hello.rb is the Ruby application
-[source,Ruby]
+
+Run the application using the pre-packaged runtime:
+
+[source,sh]
+----
+tebako-runtime-package --tebako-run tebako-application-package Maxim
 ----
-# frozen_string_literal: true
 
-puts "Hello, #{ARGV[0]}!"
+The expected output is:
+
+[source]
+----
+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
 ----
-And expected output from ```tabako-runtime --tebako-run tebako-application Maxim``` is
+running
+
 [source,sh]
 ----
-Hello, Maxim!
+/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 an extract its DwarFS filesystem from a package to
-a local folder for verification or execution.
+Tebako provides an option to extract its DwarFS filesystem from a package to
+a local folder for verification or examination.
 
 [source,sh]
 ----
@@ -1325,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]
 ====
@@ -1354,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
 
@@ -1372,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.