Lesson2 [12]

.github/workflows/tutorial.yml

@@ -31,7 +31,7 @@ jobs:
 
     - name: Package 1_hello_world
       run: |
-        tebako press --root=tutorial/1_hello_world/hellow_world.sample --entry=hello_world.rb
+        tebako press --root=tutorial/1_hello_world/hello_world.sample --entry=hello_world.rb
 
     - name: Run packaged 1_hello_world application
       run: |
@@ -46,36 +46,36 @@ jobs:
       run: |
         ./lesson-1
 
-    - name: Package 2_scenarios gemfile sample
+    - name: Package 2_packaging_scenarios gemfile sample
       run: |
-        tebako press -r tutorial/2_scenarios/gemfile.sample -e ticker.rb -o ticker.tebako.
+        tebako press -r tutorial/2_packaging_scenarios/gemfile.sample -e ticker.rb -o ticker.tebako.
 
       # Cannot run this sample since GH Actions does not allow such websocket connection to the outside world
 
-    - name: Package 2_scenarios gemspec and gemfile sample
+    - name: Package 2_packaging_scenarios gemspec and gemfile sample
       run: |
-        tebako press -r tutorial/2_scenarios/gemspec_and_gemfile.sample -e tebako-table-cli -o table.tebako
+        tebako press -r tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample -e tebako-table-cli -o table.tebako
 
-    - name: Run packaged 2_scenarios gemspec and gemfile sample
+    - name: Run packaged 2_packaging_scenarios gemspec and gemfile sample
       run: |
         ./table.tebako
 
-    - name: Package 2_scenarios gemspec sample
+    - name: Package 2_packaging_scenarios gemspec sample
       run: |
-        tebako press -r tutorial/2_scenarios/gemspec.sample -e tebako-table-cli -o table.tebako
+        tebako press -r tutorial/2_packaging_scenarios/gemspec.sample -e tebako-table-cli -o table.tebako
 
-    - name: Run packaged 2_scenarios gemspec sample
+    - name: Run packaged 2_packaging_scenarios gemspec sample
       run: |
         ./table.tebako
 
-    - name: Package 2_scenarios gem sample
+    - name: Package 2_packaging_scenarios gem sample
       run: |
-        mkdir -p tutorial/2_scenarios/gem.sample
-        pushd tutorial/2_scenarios/gemspec.sample
+        mkdir -p tutorial/2_packaging_scenarios/gem.sample
+        pushd tutorial/2_packaging_scenarios/gemspec.sample
         gem build tebako-table.gemspec -o ../gem.sample/tebako-test-0.0.2.gem
         popd
-        tebako press -r tutorial/2_scenarios/gem.sample -e tebako-table-cli -o table.tebako
+        tebako press -r tutorial/2_packaging_scenarios/gem.sample -e tebako-table-cli -o table.tebako
 
-    - name: Run packaged 2_scenarios gems sample
+    - name: Run packaged 2_packaging_scenarios gems sample
       run: |
         ./table.tebako

tutorial/2_scenarios/Lesson-2.adoc → tutorial/2_packaging_scenarios/Lesson-2.adoc

@@ -1,8 +1,9 @@
-= Tebako tutorial - Lesson 2. "Packaging scenarios"
+= Tebako Tutorial - Lesson 2: "Packaging Scenarios"
 
-In the Lesson 1 we have packaged simple script without dependencies. Now we will talk about more complex scenarios.
+In Lesson 1, we packaged a simple script without dependencies. Now we will discuss more complex scenarios.
+In this lesson, we show how to use Tebako for different layouts of solutions to be packaged.
 
-== Packaging a bundle
+== Packaging a Bundle
 
 Let's package a script that has external dependencies.
 
@@ -15,23 +16,23 @@ require "async/websocket"
 URL = "wss://stream.binance.com:9443/ws/btcusdt@bookTicker"
 
 Signal.trap("INT") do
-	puts "\n\nStopping..."
-	exit(0)
+  puts "\n\nStopping..."
+  exit(0)
 end
 
 Async do |task|
-	endpoint = Async::HTTP::Endpoint.parse(URL, alpn_protocols: Async::HTTP::Protocol::HTTP11.names)
+  endpoint = Async::HTTP::Endpoint.parse(URL, alpn_protocols: Async::HTTP::Protocol::HTTP11.names)
 
-	Async::WebSocket::Client.connect(endpoint) do |connection|
-		while message = connection.read
-			puts message.parse
-		end
-	end
+  Async::WebSocket::Client.connect(endpoint) do |connection|
+    while message = connection.read
+      puts message.parse
+    end
+  end
 end
 ----
 
-This script recieves the BTC/USDT ticker from the Binance exchange and outputs it to the console.
-It uses the `async`, `async-http`, and `async-websocket` gems, so I will add a Gemfile to manage dependencies:
+This script receives the BTC/USDT ticker from the Binance exchange and outputs it to the console.
+It uses the `async`, `async-http`, and `async-websocket` gems, so we add a Gemfile to manage dependencies:
 
 [source,Ruby]
 ----
@@ -42,19 +43,19 @@ gem "async-http"
 gem "async-websocket"
 ----
 
-We put the script into the `gemfile.sample/ticker.rb` file and the Gemfile into the `gemfile.sample/Gemfile` file and package it with tebako.
-I will use short aliases for the parameters:
+We put the script into the `gemfile.sample/ticker.rb` file and the Gemfile into the `gemfile.sample/Gemfile` file. We then package it with Tebako.
+Short aliases for the parameters are used:
 
 [source,sh]
 ----
 tebako press -r gemfile.sample -e ticker.rb -o ticker.tebako
 ----
 
-Note, that we do not run `bundle install` before packaging. Tebako creates its own environment that is isolated from the system where we package.
-It works similar to rbenv. When packaging starts the environment is initialized with tebako-patched Ruby and `bundle install` is executed by tebako
+Note that we do not run `bundle install` before packaging. Tebako creates its own environment, isolated from the system where we package.
+It works similarly to rbenv. When packaging starts, the environment is initialized with Tebako-patched Ruby, and `bundle install` is executed by Tebako
 against this environment.
 
-You can see this sequence in tebako console log:
+You can see this sequence in the Tebako console log:
 
 [source]
 ----
@@ -73,13 +74,13 @@ You can see this sequence in tebako console log:
    ... stripping the output
 ----
 
-== Packaging a gem
+== Packaging a Gem
 
-The most common entity for packaging is previously developed gem. Note that tebako is an executable packager. That implies that we can package
-a gem as an application but not as a library. Practicaly it means that tebako package runs of the gem executables which serves as the package
+The most common entity for packaging is a previously developed gem. Note that Tebako is an executable packager. This means that we can package
+a gem as an application but not as a library. Practically, it means that Tebako packages runs of the gem executables, which serve as the package's
 entry point.
 
-We will use the following gem specification  (`gemfile.sample/tebako-table.gemspec`)
+We will use the following gem specification (`gemfile.sample/tebako-table.gemspec`):
 
 [source,Ruby]
 ----
@@ -88,7 +89,7 @@ require_relative "lib/version"
 Gem::Specification.new do |s|
   s.name        = "tebako-test"
   s.version     = Test::VERSION
-  s.summary     = "A simple gem for tebako testing"
+  s.summary     = "A simple gem for Tebako testing"
   s.authors     = ["Ribose"]
   s.email       = ["[email protected]"]
   s.files       = Dir.glob("lib/**/*") + Dir.glob("exe/**/*")
@@ -101,17 +102,17 @@ Gem::Specification.new do |s|
 end
 ----
 
-trivial Gemfile
+Trivial Gemfile:
 
 [source,Ruby]
 ----
 source "https://rubygems.org"
 gemspec
 ----
 
-and three source files
+And three source files:
 
-1. `gemspec_and_gemfile.sample/exe/tebako-table-cli`
+1. `gemspec_and_gemfile.sample/exe/tebako-table-cli`:
 
 [source,Ruby]
 ----
@@ -122,7 +123,7 @@ instance = Test::TebakoTable.new
 instance.run
 ----
 
-2. `gemspec_and_gemfile.sample/lib/tebako-table.rb`
+2. `gemspec_and_gemfile.sample/lib/tebako-table.rb`:
 
 [source,Ruby]
 ----
@@ -151,7 +152,7 @@ module Test
 end
 ----
 
-3. `gemspec_and_gemfile.sample/lib/version.rb`
+3. `gemspec_and_gemfile.sample/lib/version.rb`:
 
 [source,Ruby]
 ----
@@ -160,14 +161,14 @@ module Test
 end
 ----
 
-Press command does not change:
+The `press` command does not change:
 
 [source,sh]
 ----
 tebako press -r gemspec_and_gemfile.sample -e tebako-table-cli -o table.tebako
 ----
 
-but now Tebako recognizes that it packages a gem and applies diffent deployment scenario:
+But now Tebako recognizes that it packages a gem and applies a different deployment scenario:
 
 [source]
 ----
@@ -176,28 +177,27 @@ but now Tebako recognizes that it packages a gem and applies diffent deployment
 -- Running deploy script
    ... installing tebako-runtime gem
    ... @ /Users/runner/.tebako/o/s/bin/gem install tebako-runtime --no-document --install-dir /Users/runner/.tebako/o/s/lib/ruby/gems/3.2.0
-   ... collecting gem from gemspec /Users/runner/work/tebako-samples/tebako-samples/tutorial/2_scenarios/gemspec_and_gemfile.sample/tebako-table.gemspec and Gemfile
+   ... collecting gem from gemspec /Users/runner/work/tebako-samples/tebako-samples/tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/tebako-table.gemspec and Gemfile
    ... @ /Users/runner/.tebako/o/s/bin/bundle config set --local build.ffi --disable-system-libffi
    ... @ /Users/runner/.tebako/o/s/bin/bundle config set --local build.nokogiri --no-use-system-libraries
    ... @ /Users/runner/.tebako/o/s/bin/bundle config set --local force_ruby_platform false
    *** It may take a long time for a big project. It takes REALLY long time on Windows ***
    ... @ /Users/runner/.tebako/o/s/bin/bundle install --jobs=3
    ... @ /Users/runner/.tebako/o/s/bin/bundle exec /Users/runner/.tebako/o/s/bin/gem build
-         /Users/runner/work/tebako-samples/tebako-samples/tutorial/2_scenarios/gemspec_and_gemfile.sample/tebako-table.gemspec
+         /Users/runner/work/tebako-samples/tebako-samples/tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/tebako-table.gemspec
    ... installing /Users/runner/.tebako/o/r/tebako-test-0.0.2.gem
    ... @ /Users/runner/.tebako/o/s/bin/gem install /Users/runner/.tebako/o/r/tebako-test-0.0.2.gem --no-document
          --install-dir /Users/runner/.tebako/o/s/lib/ruby/gems/3.2.0 --bindir /Users/runner/.tebako/o/s/bin
    ... target entry point will be at /__tebako_memfs__/bin/tebako-table-cli
    ... stripping the output
 ----
 
-Tebako now installs the gem to its Ruby environment and assumes that the entry point is the wrapper created by gem command in the `binary` directory.
-Note that entrypoint script shall be explicitly specified as one of gem executables.
+Tebako installs the gem into its Ruby environment and assumes the entry point is the wrapper created by the `gem` command in the `binary` directory.
+Note that the entry point script must be explicitly specified as one of the gem executables.
 
-== Packaging a gem without bundle
+== Packaging a Gem Without Bundling
 
-Tebako also supports gems defined without Gemfile (not bundled). We can copy the previous example, specify dependencies in gemspec,
-remove Gemfile and do tebako packaging
+Tebako also supports gems defined without a Gemfile (not bundled). We can copy the previous example, specify dependencies in the gemspec, remove the Gemfile, and package it with Tebako:
 
 [source,sh]
 ----
@@ -211,20 +211,20 @@ tebako press -r gemspec.sample -e tebako-table-cli -o table.tebako
 -- Running deploy script
    ... installing tebako-runtime gem
    ... @ /Users/runner/.tebako/o/s/bin/gem install tebako-runtime --no-document --install-dir /Users/runner/.tebako/o/s/lib/ruby/gems/3.2.0
-   ... collecting gem from gemspec /Users/runner/work/tebako-samples/tebako-samples/tutorial/2_scenarios/gemspec.sample/tebako-table.gemspec
-   ... @ /Users/runner/.tebako/o/s/bin/gem build /Users/runner/work/tebako-samples/tebako-samples/tutorial/2_scenarios/gemspec.sample/tebako-table.gemspec
+   ... collecting gem from gemspec /Users/runner/work/tebako-samples/tebako-samples/tutorial/2_packaging_scenarios/gemspec.sample/tebako-table.gemspec
+   ... @ /Users/runner/.tebako/o/s/bin/gem build /Users/runner/work/tebako-samples/tebako-samples/tutorial/2_packaging_scenarios/gemspec.sample/tebako-table.gemspec
    ... installing /Users/runner/.tebako/o/r/tebako-test-0.0.2.gem
    ... @ /Users/runner/.tebako/o/s/bin/gem install /Users/runner/.tebako/o/r/tebako-test-0.0.2.gem --no-document
          --install-dir /Users/runner/.tebako/o/s/lib/ruby/gems/3.2.0 --bindir /Users/runner/.tebako/o/s/bin
    ... target entry point will be at /__tebako_memfs__/bin/tebako-table-cli
 ----
 
-This approach is faster but may fail for gems with native extensions since Tebako won't have enough control to correctly configure them.
-We primarily support it for backwords compatibility.
+This approach is faster but may fail for gems with native extensions since Tebako lacks sufficient control to configure them correctly.
+We primarily support this for backward compatibility.
 
-== Packaging built gem
+== Packaging a Built Gem
 
-Tebako can also package a gem or gems, i.e.: one or several `*.gem` files
+Tebako can package one or several prebuilt `*.gem` files:
 
 [source,sh]
 ----
@@ -235,8 +235,10 @@ popd
 tebako press -r gem.sample -e tebako-table-cli -o table.tebako
 ----
 
+The same limitations apply as in the previous option. This scenario may fail for gems with native extensions due to Tebako's limited control during configuration.
+It is supported primarily for backward compatibility.
 
-== Live example
+== Live Example
 
-You can find the complete code of this lesson in the `tutorial/2_dependencies` directory of the tebako-samples repository.
-The code is running on GHA via the `tutorial.yml` workflow.
+You can find the complete code for this lesson in the `tutorial/2_dependencies` directory of the `tebako-samples` repository.
+The code runs on GitHub Actions via the `tutorial.yml` workflow.