ruby-project-setup.md

Ruby Project Setup

A useful guide to start with is found here.

Install rbenv and ruby

UNIX OS

1. Install rbenv

2. Check the available versions of Ruby:

   rbenv install -l

3. Install the required version:

   rbenv install <version>

4. Set the Ruby to the required version:

   rbenv global <version>   # set the default Ruby version for this machine
   # or:
   rbenv local <version>    # set the Ruby version for this directory

Windows OS: rbenv for PowerShell

The first option is to install rbenv for Windows, which only works with PowerShell.

The setup is the same as rbenv installation for UNIX-like OSs.

Windows OS: RubyInstaller (Preferred Option)

1. install RubyInstaller as a non-admin installation. Also make sure Ruby is added to the PATH.

2. Install MSYS2 and MinGW when asked.

3. Open the command line and run:

   ridk enable

VSCode Extension

1. Add .vscode/extensions.json with the following contents:

   {
     "recommendations": [
       "ghbozz.hashtag",
       "formulahendry.code-runner",
       "kaiwood.endwise",
       "esbenp.prettier-vscode",
       "Shopify.ruby-lsp",
       "sorbet.sorbet-vscode-extension",
       "KoichiSasada.vscode-rdbg",
       "ms-vscode.test-adapter-converter",
       "hbenl.vscode-test-explorer"
     ]
   }

2. Add .vscode/settings.json with the following contents:

       "[ruby]": {
           "editor.defaultFormatter": "esbenp.prettier-vscode"
       },

Project Setup

1. Create the root directory.

2. In the root directory, run:

   gem install bundler
   bundle gem .

3. On RubyGems.org, search for rspec and copy the GEMFILE script and paste it to the end of local Gemfile.

4. Do similar thing for packages REPL: irb, pry, debug: debug, and documentation: rdoc.

5. Do similar thing for optional packages: test-unit, rubocop, rbs, and rake.

6. Install all gems:

   bundler install

7. The only boilerplate code you may need is version.rb that contains the version of the gem or in this case the project. Put the file in lib/version.rb.

   # frozen_string_literal: true
   
   module Ruby
       module MyGem
           VERSION = "0.1.0"
       end
   end

8. Update the project_name.gemspec file:

   require_relative 'lib/version'
   #...
        spec.version = Ruby::MyGem::VERSION
   #...

Code Structure

1. Create the library (module) file in lib folder with the following structure:

   # my_gem.rb
   
    module MyGem
        def self.greet(name = 'Ruby')
            "Hello, #{name}!"
        end
    end

   or

   # my_gem.rb
   
   class MyGem
        def greet(name = 'Ruby')
            "Hello, #{name}!"
        end
   end

2. Create the main function in bin folder:

   # main.rb
   require "my_gem"
   
   def main(param)
       param.each do |name|
       puts MyGem.greet(name)
       end
   end
   
   main(ARGV)

3. To run the main function:

   ruby -I lib bin/main.rb [arguments list]

4. To package the library:

   gem build project_name.gemspec

Test Code

Test Code Using RSpec Gem

1. Add the unit test file to spec/my_gem_spec.rb folder:

   # my_gem_spec.rb
   
   require "my_gem"
   
   RSpec.describe MyGem do
       it "greets with default name" do
           expect(MyGem.greet).to eq "Hello, Ruby!"
       end
   
       it "greets a custom name" do
           expect(MyGem.greet("World")).to eq "Hello, World!"
       end
   end

2. To run a specific test:

   rspec spec/my_gem_spec.rb

3. To run all tests:

   rspec

Test Code Using test-unit Gem

1. Add the unit test file to tests/ruby_test.rb folder:

   # ruby_test.rb
   
   require "test/unit"
   require "my_gem"
   
   class Test_Gem < Test::Unit::TestCase
       def test_1
           assert_equal("Hello, ME!", MyGem.greet("ME"))
       end
   
       def test_2
           refute_nil(MyGem.greet("ME"), "object shouldn't be nil")
       end
   end

2. To run the test:

   ruby -I lib tests/ruby_test.rb [-n test_method_to_run]

Type Signature File Generation: rbs

1. To generate the rbs file, run:

   rbs prototype rb --out-dir=sig lib

   The prototype files will be created in sig folder and often needs modifying and adjusting the types, etc.

2. To update the type signature files while skipping the already existing ones, run the command again.

Documentation

1. To write documentation for RDoc, place a comment above the class, module, method, constant, or attribute you want documented.

2. You can also use POD style documentation for block comments using:

   =begin rdoc
   documents
   =end

3. To generate HTML document from the folder:

   rdoc lib

Example using markdown

# :markup: markdown

#--
# The comments here are ignored.
# my_gem.rb
# The comments after the next line are processed.
#++
# This class uses **Markdown** for documentation.
module MyGem
=begin rdoc
Documentation for **greet** function.
_name_ is the input argument.
=end
    def self.greet(name = 'Ruby')
        "Hello, #{name}!"
    end
end

Example using RDoc

#--
# The comments here are ignored.
# my_gem.rb
# The comments after the next line are processed.
#++
# This class uses <b>Markdown</b> for documentation.
module MyGem
=begin rdoc
Documentation for <b>greet</b> function.
<i>name</i> is the input argument.
=end
    def self.greet(name = 'Ruby')
        "Hello, #{name}!"
    end
end