From 84b6b72d356c33fa4cb43f42f686eab71e84dbc5 Mon Sep 17 00:00:00 2001 From: "Maxim [maxirmx] Samsonov" Date: Sat, 11 Jan 2025 22:32:28 +0300 Subject: [PATCH] Lesson2 [12] --- .github/workflows/tutorial.yml | 28 +++--- .../Lesson-2.adoc | 94 ++++++++++--------- .../gemfile.sample/Gemfile | 0 .../gemfile.sample/ticker.rb | 0 .../gemspec.sample/exe/tebako-table-cli | 0 .../gemspec.sample/lib/tebako-table.rb | 0 .../gemspec.sample/lib/version.rb | 0 .../gemspec.sample/tebako-table.gemspec | 0 .../gemspec_and_gemfile.sample/Gemfile | 0 .../exe/tebako-table-cli | 0 .../lib/tebako-table.rb | 0 .../gemspec_and_gemfile.sample/lib/version.rb | 0 .../tebako-table.gemspec | 0 13 files changed, 62 insertions(+), 60 deletions(-) rename tutorial/{2_scenarios => 2_packaging_scenarios}/Lesson-2.adoc (61%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemfile.sample/Gemfile (100%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemfile.sample/ticker.rb (100%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemspec.sample/exe/tebako-table-cli (100%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemspec.sample/lib/tebako-table.rb (100%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemspec.sample/lib/version.rb (100%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemspec.sample/tebako-table.gemspec (100%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemspec_and_gemfile.sample/Gemfile (100%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemspec_and_gemfile.sample/exe/tebako-table-cli (100%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemspec_and_gemfile.sample/lib/tebako-table.rb (100%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemspec_and_gemfile.sample/lib/version.rb (100%) rename tutorial/{2_scenarios => 2_packaging_scenarios}/gemspec_and_gemfile.sample/tebako-table.gemspec (100%) diff --git a/.github/workflows/tutorial.yml b/.github/workflows/tutorial.yml index 5fd64dd..8cf5032 100644 --- a/.github/workflows/tutorial.yml +++ b/.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 diff --git a/tutorial/2_scenarios/Lesson-2.adoc b/tutorial/2_packaging_scenarios/Lesson-2.adoc similarity index 61% rename from tutorial/2_scenarios/Lesson-2.adoc rename to tutorial/2_packaging_scenarios/Lesson-2.adoc index d605c0a..5c3fba9 100644 --- a/tutorial/2_scenarios/Lesson-2.adoc +++ b/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 = ["open.source@ribose.com"] s.files = Dir.glob("lib/**/*") + Dir.glob("exe/**/*") @@ -101,7 +102,7 @@ Gem::Specification.new do |s| end ---- -trivial Gemfile +Trivial Gemfile: [source,Ruby] ---- @@ -109,9 +110,9 @@ 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,14 +177,14 @@ 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 @@ -191,13 +192,12 @@ but now Tebako recognizes that it packages a gem and applies diffent deployment ... 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. diff --git a/tutorial/2_scenarios/gemfile.sample/Gemfile b/tutorial/2_packaging_scenarios/gemfile.sample/Gemfile similarity index 100% rename from tutorial/2_scenarios/gemfile.sample/Gemfile rename to tutorial/2_packaging_scenarios/gemfile.sample/Gemfile diff --git a/tutorial/2_scenarios/gemfile.sample/ticker.rb b/tutorial/2_packaging_scenarios/gemfile.sample/ticker.rb similarity index 100% rename from tutorial/2_scenarios/gemfile.sample/ticker.rb rename to tutorial/2_packaging_scenarios/gemfile.sample/ticker.rb diff --git a/tutorial/2_scenarios/gemspec.sample/exe/tebako-table-cli b/tutorial/2_packaging_scenarios/gemspec.sample/exe/tebako-table-cli similarity index 100% rename from tutorial/2_scenarios/gemspec.sample/exe/tebako-table-cli rename to tutorial/2_packaging_scenarios/gemspec.sample/exe/tebako-table-cli diff --git a/tutorial/2_scenarios/gemspec.sample/lib/tebako-table.rb b/tutorial/2_packaging_scenarios/gemspec.sample/lib/tebako-table.rb similarity index 100% rename from tutorial/2_scenarios/gemspec.sample/lib/tebako-table.rb rename to tutorial/2_packaging_scenarios/gemspec.sample/lib/tebako-table.rb diff --git a/tutorial/2_scenarios/gemspec.sample/lib/version.rb b/tutorial/2_packaging_scenarios/gemspec.sample/lib/version.rb similarity index 100% rename from tutorial/2_scenarios/gemspec.sample/lib/version.rb rename to tutorial/2_packaging_scenarios/gemspec.sample/lib/version.rb diff --git a/tutorial/2_scenarios/gemspec.sample/tebako-table.gemspec b/tutorial/2_packaging_scenarios/gemspec.sample/tebako-table.gemspec similarity index 100% rename from tutorial/2_scenarios/gemspec.sample/tebako-table.gemspec rename to tutorial/2_packaging_scenarios/gemspec.sample/tebako-table.gemspec diff --git a/tutorial/2_scenarios/gemspec_and_gemfile.sample/Gemfile b/tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/Gemfile similarity index 100% rename from tutorial/2_scenarios/gemspec_and_gemfile.sample/Gemfile rename to tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/Gemfile diff --git a/tutorial/2_scenarios/gemspec_and_gemfile.sample/exe/tebako-table-cli b/tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/exe/tebako-table-cli similarity index 100% rename from tutorial/2_scenarios/gemspec_and_gemfile.sample/exe/tebako-table-cli rename to tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/exe/tebako-table-cli diff --git a/tutorial/2_scenarios/gemspec_and_gemfile.sample/lib/tebako-table.rb b/tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/lib/tebako-table.rb similarity index 100% rename from tutorial/2_scenarios/gemspec_and_gemfile.sample/lib/tebako-table.rb rename to tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/lib/tebako-table.rb diff --git a/tutorial/2_scenarios/gemspec_and_gemfile.sample/lib/version.rb b/tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/lib/version.rb similarity index 100% rename from tutorial/2_scenarios/gemspec_and_gemfile.sample/lib/version.rb rename to tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/lib/version.rb diff --git a/tutorial/2_scenarios/gemspec_and_gemfile.sample/tebako-table.gemspec b/tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/tebako-table.gemspec similarity index 100% rename from tutorial/2_scenarios/gemspec_and_gemfile.sample/tebako-table.gemspec rename to tutorial/2_packaging_scenarios/gemspec_and_gemfile.sample/tebako-table.gemspec