feat: tutorial lesson 1

.github/workflows/tutorial.yml

@@ -0,0 +1,47 @@
+name: Tutorial
+
+on:
+  push:
+    branches:  [ main ]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.job }}-${{ github.head_ref || github.ref_name }}'
+  cancel-in-progress: true
+
+jobs:
+  lesson-1:
+    runs-on: macos-latest
+    steps:
+
+    - name: Brew install
+      run: |
+        pushd $(mktemp -d)
+        curl https://raw.githubusercontent.com/tamatebako/tebako/refs/heads/main/Brewfile > Brewfile
+        brew bundle -f
+        popd
+        echo "$(brew --prefix bison)/bin" >> $GITHUB_PATH
+
+    - name: Install gem
+      run: gem install tebako
+
+    - name: Checkout sample
+      uses: actions/checkout@v4
+
+    - name: Package
+      run: |
+        tebako press --root=tutorial/1_hello_world/sample --entry=hello_world.rb
+
+    - name: Run packaged application
+      run: |
+        ./hello_world
+        otool -L hello_world
+
+    - name: Package with a difefrent name
+      run: |
+        tebako press --root=tutorial/1_hello_world/sample --entry=hello_world.rb --output=lesson-1
+
+    - name: Run packaged application with a diffeernt name
+      run: |
+        ./lesson-1

.gitignore

@@ -43,4 +43,8 @@ ror-data/*
 !ror-data/storage/.keep
 
 Gemfile.lock
-log
+log
+
+# Tutorila
+hello_world
+source_filesystem/

tutorial/1_hello_world/Lesson-1.adoc

@@ -0,0 +1,114 @@
+= Tebako tutorial - Lesson 1. "Hello, World!" with Tebako
+
+== Foreword
+
+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.
+
+A Tebako package is effectively a self-executing container-in-a-file.
+
+The package contains the following components:
+
+* An on-file filesystem (OFFS) containing all the project files and dependencies in DwarFS format ("application")
+* A runtime environment that includes the necessary libraries and interpreters, with patched filesystem calls that redirect access to project files in the on-file filesystem ("runtime")
+
+== Environment
+
+Tebako is compatible with macOS, Linux, and Windows.
+
+The first lessons of this tutorial use a macOS environment. This is an arbitrary choice with no special reason. Other operating systems differ only in how to install Tebako prerequisites, which we will discuss later.
+
+== Setup
+
+Tebako itself is a Ruby gem and can be easily installed with `gem` or `bundler`.
+
+However, creating embedded packages requires a complex configuration of additional tools and libraries. On macOS, the setup is broken into two steps:
+
+1. Install Homebrew prerequisites. Note that this example uses a `Brewfile` available from the Tebako repository.
+
+[source,sh]
+----
+    pushd $(mktemp -d)
+    curl https://raw.githubusercontent.com/tamatebako/tebako/refs/heads/main/Brewfile > Brewfile
+    brew bundle -f
+    popd
+
+    echo 'export PATH=$(brew --prefix bison)/bin:$PATH' >> ~/.zshrc
+    source ~/.zshrc
+----
+
+2. Install the Tebako gem:
+
+[source,sh]
+----
+gem install tebako
+----
+
+== Hello, World!
+
+Let's create a simple "Hello, World!" application in Ruby and package it with Tebako.
+We place the following code into `sample/hello_world.rb`:
+
+[source,Ruby]
+----
+puts "Hello, World!"
+----
+
+Now we can package it with Tebako:
+
+[source,sh]
+----
+tebako press --root=sample --entry=hello_world.rb
+----
+
+This command uses two mandatory parameters: `--root` and `--entry`.
+The first specifies the root directory of the project. Tebako packages all files in this directory and its subdirectories.
+The root may be specified either as a relative path or as an absolute path.
+The second specifies the entry point of the application. It can be a relative path to the root directory or an absolute path.
+
+The command creates an executable file `hello_world` that contains the runtime, the Ruby library files, and the application.
+The application will be placed in the folder of the on-file filesystem named `local`.
+
+We can now run the application:
+
+[source,sh]
+----
+./hello_world
+----
+
+and check that it does not have any dependencies other than the macOS runtime:
+
+[source,sh]
+----
+otool -L hello_world
+----
+
+== Caveats
+
+Note that we are not packaging in-place. We do not recommend packaging the project in the project directory for a simple reason.
+If we do something like this:
+
+[source,sh]
+----
+tebako press --root=$PWD --entry=hello_world.rb
+----
+
+then on the second run, the package will contain the package itself. This is not an error and can be done, but it does not seem like a valid action.
+To avoid this, we recommend always creating the Tebako package outside of the project directory.
+
+== Changing package name
+
+We can use `--output` to specify the name of the package:
+
+[source,sh]
+----
+tebako press --root=sample --entry=hello_world.rb --output=lesson-1
+----
+
+This command creates an executable file `lesson-1` that contains the runtime, the Ruby library files, and the application.
+
+== Live example
+
+You can find the complete code of this lesson in the `tutorial/1_hello_world` directory of the tebako-samples repository.
+The code is running on GHA via the `tutorial.yml` workflow.

tutorial/1_hello_world/sample/hello_world.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2023-2025 [Ribose Inc](https://www.ribose.com).
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS
+# BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+# Tebako tutorial: Lesson 1
+
+puts "Hello, World!"