feat: tutorial lesson 1

.github/workflows/tutorial.yml

@@ -0,0 +1,41 @@
+name: MacOS
+
+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: |
+        cd tutotrial/1_hello_world
+        tebako press --root=sample --entry=hello_world.rb
+
+    - name: Run packaged application
+      run: |
+        cd tutotrial/1_hello_world
+        ./hello_world
+        otool -L hello_world

tutorial/1_hello_world/Lesson-1.adoc

@@ -0,0 +1,96 @@
+
+= 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 the necessary libraries and interpreters,
+with patched filesystem calls that redirect access of project files to the
+on-file filesystem ("runtime")
+
+Tebako is capable to create a single file that contains both runtime and
+application or place runtime and application to separate files. In the latter
+case the runtime can be used with different applications or versions of the same
+application.
+
+== Environment
+
+Tebako is comaptible with MacOS, Linux and Windows.
+The first lessons of this tutorial use MacOS environment. This is arbitrary choice with
+no special reason. Other operating systems differ only in the way how to install Tebako prerequisites
+and we will discuss it later.
+
+== Setup
+
+Tebako itself is a Ruby gem and can be easily installed with `gem` or `bundler`.
+However, creation of embedded packages requires a complex configuration of additional tools and libraries
+that MacOS breaks setup into two steps:
+
+1. Install homebrew prerequisites. Note that this sample uses `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 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 pust 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 to mandatory parameters `--root` and `--entry`.
+The first one specifies the root directory of the project. Tebako packages all files in this directory and its subdirectories.
+The root may be specified either as relative path or as absolute path.
+The second one specifies the entry point of the application. It can a relative path to the root directory or an absolute path.
+
+The command creates an executable file 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 may 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
+----

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!"