DEV Community: Vinicius Stock

Make a Ruby gem configurable

Vinicius Stock — Tue, 21 Jul 2020 13:32:50 +0000

In the Ruby ecosystem, a well established way of customizing gem behavior is by using configuration blocks. Most likely, you came across code that looked like this.

MyGem.configure do |config|
  config.some_config = true
  config.some_class = MyApp
  config.some_lambda = ->(variable) { do_important_stuff(variable) }
end

This standard way of configuring gems runs once, usually when starting an application, and allows developers to tailor the gem's functionality to their needs.

Adding the configuration block to a gem

Let's take a look at how this style of configuration can be implemented. We'll divide our implementation in two steps: writing a configuration class and exposing it to users.

Writing the configuration class

The configuration class is responsible for keeping all the available options and their defaults. It is composed of two things: an initialize method where defaults are set and attribute readers/writers.

Let's take a look at an example, where we can configure an animal and the sound that it makes. If the sound does not match the expected, we want to raise an error while configuring our gem. We'll then access what is configured for animal and sound and use it in our logic.

# lib/my_gem/configuration.rb

module MyGem
  class Configuration
    # Custom error class for sounds that don't
    # match the expected animal
    class AnimalSoundMismatch < StandardError; end

    # Animal sound map
    ANIMAL_SOUND_MAP = {
      "Dog" => "Barks",
      "Cat" => "Meows"
    }

    # Writer + reader for the animal instance variable. No fancy logic
    attr_accessor :animal

    # Reader only for the sound instance variable.
    # The writer contains custom logic
    attr_reader :sound

    # Initialize every configuration with a default.
    # Users of the gem will override these with their
    # desired values
    def initialize
      @animal = "Dog"
      @sound = "Barks"
    end

    # Custom writer for sound.
    # If the sound variable is not exactly what is
    # mapped in our hash, raise the custom error
    def sound=(sound)
      raise AnimalSoundMismatch, "A #{@animal} can't #{sound}" if SOUND_MAP[@animal] != sound

      @sound = sound
    end
  end
end

Exposing the configuration

To expose the configuration means both letting users configure it and allowing the gem itself to read the value of each option.

This is done with a singleton of our Configuration class and a few utility methods.

# lib/my_gem.rb

module MyGem
  class << self
    # Instantiate the Configuration singleton
    # or return it. Remember that the instance
    # has attribute readers so that we can access
    # the configured values
    def configuration
      @configuration ||= Configuration.new
    end

    # This is the configure block definition.
    # The configuration method will return the
    # Configuration singleton, which is then yielded
    # to the configure block. Then it's just a matter
    # of using the attribute accessors we previously defined
    def configure
      yield(configuration)
    end
  end
end

The gem is now set to be configured by the applications that use it.

MyGem.configure do |config|
  # Notice that the config block argument
  # is the yielded singleton of Configuration.
  # In essence, all we're doing is using the
  # accessors we defined in the Configuration class
  config.animal = "Cat"
  config.sound = "Meows"
end

Using the configuration in the gem

Now that we have the customizable Configuration singleton, we can read the values to change behavior based on it.

# lib/my_gem/make_sound.rb

module MyGem
  class AnimalSound
    def initialize
      @animal = MyGem.configuration.animal
      @sound = MyGem.configuration.sound
    end

    def make_sound
      "The #{@animal} #{@sound}"
    end
  end
end

Using lambdas for configuration

In specific scenarios, there may be a need for a configuration to not have a predetermined value, but rather to evaluate some logic as the application is running.

For these cases, it is typical to define a lambda for the configuration value. Let's go through an example. The configuration class is similar to our previous case.

# lib/my_gem/configuration.rb

module MyGem
  class Configuration
    attr_reader :key_name

    # Define no lambda as the default
    def initialize
      @key_name = nil
    end

    # Raise an error if trying to set the key_name
    # to something other than a lambda
    def key_name=(lambda)
      raise ArgumentError, "The key_name must be a lambda" unless lambda.is_a?(Proc)

      @key_name = lambda
    end
  end
end

Now we can configure the lambda to whatever we need. You could even query the database if desired inside the lambda and return values from the app's models.

MyGem.configure do |config|
  config.lambda_config = ->(model_name) { model_name == "Post" ? :posts : :articles }
end

Finally, the gem can use the lambda and get different results as the app is running.

MyGem.configuration.key_name&.call("Article")
=> :articles

MyGem.configuration.key_name&.call("Post")
=> :posts

That's about it for configuration blocks. Have you used this before to make your code/gems customizable? Do you know other strategies for configuring third party libraries? Let me know in the comments!

Changing Ruby classes at runtime with class_eval

Vinicius Stock — Fri, 10 Jul 2020 20:09:08 +0000

One of Ruby's most interesting - and useful! - features is being able to change how classes and objects behave while your app is running.

If you use Rails, then certainly you have used many runtime defined methods. Let's look at an example. Imagine a one to many association between two models: Author and Post.

If the author is already instantiated, then we can get the posts for this author by invoking

@author = Author.find(1)
@author.posts
=> #<ActiveRecord::Associations::CollectionProxy [...]>

But where does the posts method come from? This method is actually defined during runtime by the has_many method.

# app/models/author.rb

class Author < ApplicationRecord
  has_many :posts
end

When reading the author model file, Ruby will invoke the has_many methods passing the argument :posts to it. Under the hood, has_many will change the class that invoked it and add the association methods.

This is possible thanks to the magic of class_eval, a Ruby method designed to change the behavior of classes during runtime.

It's a remarkable mean to provide shared functionality to classes in an elegant way that feels almost like you're just changing a configuration file.

How class_eval works

There are two ways of using class_eval: passing it a block or passing it a string with the changes we'd like to execute to the class. Let's look at them separately.

Passing a block

When passing a block to class_eval, it will evaluate that block within the context of the class that is invoking it.

When passing blocks, it is very common to use define_method for defining methods during runtime. It is a method itself that

Accepts the name of the new method as the argument
Accepts a block to define the new method's body
Yields the new method's regular arguments and block arguments to the body

define_method("name_of_new_method") do |arg1, arg2, &block|
  # Define the behavior of the new method.
  # arg1, arg2 and &block are accessible here in the body.
end

Now, let's analyze an example where we want to add a sing method to our classes. When invoked, it will define a method with the music genre for that class that just prints a string.

# Define the method sing. This method can be put
# wherever is convenient (e.g.: a module or a parent class)

def sing(genre)
  # "Open" the class for changes
  class_eval do

    # Use the define_method method to define "rock"
    # in runtime
    define_method(genre) do |band|
      puts "I love #{band}!"
    end
  end
end

class Person
  sing :rock
end

# After evaluating the class, the new rock method exists
Person.new.rock("AC/DC")
=> I love AC/DC!

We have our rock method working!

If we wanted to add methods to a class that do not depend on the argument passed to sing, then a simple def inside the class_eval block is another option.

def sing
  class_eval do
    # This def is evaluate from the context of the class
    # so this will be defined in any class that invokes
    # sing

    def rock(band)
      puts "I love #{band}!"
    end
  end
end

class Person
  # Notice the absence of the argument
  sing
end

Person.new.rock("Queen")
=> I love Queen!

Passing a string

The second manner of using class_eval is by passing it three arguments: a string with the Ruby that will be evaluated in the class, the file where it should be evaluated and the line where it should be evaluated.

These two last arguments will typically always be the same, but they can be changed to achieve other types of behavior.

The Ruby methods __FILE__ and __LINE__ are commonly used here and they return the current file and line being evaluated, respectively.

Let's use this case as an example of how we could write has_many using class_eval. Notice that this is not the real implementation that Rails uses, but the general idea is similar.

The usual manner to use the string version of class_eval is to define a Ruby string with a HEREDOC and interpolate whatever data you need.

def has_many(resource)
  # Turn current class name into name_id
  # E.g.: NewsLetter -> news_letter_id
  # Evaluated before opening class for modification

  id_attribute_name = "#{self.name.underscore}_id"

  class_eval(<<~ASSOCIATION_METHODS, __FILE__, __LINE__ + 1)
    def #{resource}
      # Turn the argument (e.g.: :posts) into the class
      # name Post
      #{resource.to_s.singularize.camelize}.where(#{id_attribute_name}: self.id)
    end
  ASSOCIATION_METHODS
end

Now let's use this in a class and understand what the HEREDOC is evaluated to.

class Author
  # Using our version of has_many
  has_many :posts
end

# In this case, the resource argument is :posts.
# The string resulting from the HEREDOC is the one below.
# Notice that this will get evaluated within the context
# of the Author class and then will define
# the instance method posts, allowing us to
# invoke
# author.posts 

def posts
  Post.where(author_id: self.id)
end

It's important to point out that many changes can be applied in a single invocation of class_eval. For instance, the real implementation of has_many in Rails would also provide the class with a setter. Both getter and setter can be defined at the same time.

@author = Author.find(1)
@author.posts = [...]

Conclusion

Using class_eval enables developers to define behavior in runtime. This technique can be used to create methods with arguments and options passed in at a class level which results in an elegant organization of code.

Have you used this before? Let me know some use cases in the comments!

Write your own Rails generators: the basics

Vinicius Stock — Mon, 29 Jun 2020 13:23:41 +0000

What generators are

Rails generators are command line tools that are used for automating the process of creating or editing files with boiler plate code.

In essence, they execute Ruby code much like a script and create or update files based on templates, user input and whatever logic necessary.

If you've played around with Rails, surely they are not a completely foreign concept to you. Many useful generators come bundled with Rails.

The model generator produces all files needed for a new model. It accepts a list of attributes and their respective types and generates files for the model, fixtures, migrations and unit tests.

Another example is the controller generator. It spins up a new controller with a specified list actions - adding their respective routes to config/routes.rb.

Their purpose is to automate writing repetitive code that you would otherwise need to memorize or copy. Not only that, they help teams enforce standards for writing specific implementations as well as speeding up development.

For a list of all generators defined within a given application, invoke generate (alias g) with no arguments. This includes generators from gems and from your own code base.

$ bin/rails g

Let's dig a bit more into generators and then learn how to write a custom one for our own needs.

We will split generators into two types: repeated use and one-off generators. While these names are not official, they will help convey the conceptual applicability of each one of them.

Repeated use generators

Repeated use generators are meant to be used multiple times whenever a developer is doing a specific task. The model generator mentioned earlier is a great example. A developer will create many models while working on an application and the generator can be used to achieve it every time.

Let's examine an example on invoking the model generator.

$ bin/rails generate model User name age:integer group:references

invoke  active_record
    create    db/migrate/20191002201613_create_users.rb
    create    app/models/user.rb
    invoke    test_unit
    create      test/models/user_test.rb
    create      test/fixtures/users.yml

This is how this command can be broken down.

bin/rails invokes the Rails executable CLI
generate is an argument for the Rails CLI telling it to invoke a generator
model is an argument for the generate command and represents the name of the generator
User is the first argument of the model generator, which is the name of the new model
Finally, all the other arguments are attributes with their respective types for the model generator: my_attribute:my_type. Omitting the attribute type defaults to a string

Repeated use generators are great for everyday tasks that simply require certain standards or are not worth memorizing.

One-off generators

One-off generators are procedures that need to run a single time to prepare a code base for some functionality. Typically, they are used to automate project configuration and gem installation, since these changes only need to be applied once.

Gems or frameworks that require some sort of configuration in place to work properly will often provide these as install generators.

A great example is the authentication framework Devise, which provides install generators to get an application ready to use its authentication features.

For a shorter example (and a shameless plug), let's take a look at how to use the install generator of a gem of my own: Sail. It is an engine for live configuration of applications and requires three things to work properly: a table for settings, a table for profiles and a config YAML file for declaring settings.

# user@~/workspace/my_awesome_rails_app

$ bin/rails g sail:install
      create  db/migrate/20191009202801_create_sail_settings.rb
      create  db/migrate/20191009202802_create_sail_profiles.rb
      create  config/sail.yml

After running the migrations, the app is ready to take advantage of all features provided by the engine. This type of generator is an outstanding way of providing a smooth experience for developers that want to use your gem.

Instead of writing long docs on how to install your gem, consider providing an install generator that will set up their project for them. We can even make the generator ask for input from the developer to properly tailor the result to their needs.

Creating a custom generator

For our convenience, one the generators bundled in Rails is the generator generator. That's right, a generator for creating other generators (after all, who would want to memorize all the boilerplate code for that?). Let's imagine we want to create a component generator.

bin/rails g generator Component
      create  lib/generators/component
      create  lib/generators/component/component_generator.rb
      create  lib/generators/component/USAGE
      create  lib/generators/component/templates
      invoke  test_unit
      create    test/lib/generators/component_generator_test.rb

Let's zoom in into each file and explore why they exist.

Usage

This file defines the usage instructions that will be displayed when invoking the generator with no arguments. This is how it looks.

Description:
    Explain the generator

Example:
    bin/rails generate component Thing

    This will create:
        what/will/it/create

We can change the copy to explain what the generator is supposed to do and what developers can expected from it. Invoking the generator with no arguments will then print the information we wrote.

For our example, we will create a component generator that accepts the name of the component.

$ bin/rails g component

Description:
    Creates a component class

Example:
    bin/rails generate component MyComponent

    Creates the component class and unit test:
        app/components/my_component.rb
        test/components/my_component_test.rb

Component generator and its templates

The lib/generators/component/component_generator.rb file defines the class that does all the magic. Here you can write whatever Ruby code is convenient to produce the output desired.

This class automatically runs every method defined in it, so you can think that each method you define is a step of the generator. Not only that, every method defined will also be available for the generator's templates.

Let's look at the generated Ruby file.

# lib/generators/component/component_generator.rb

class ComponentGenerator < Rails::Generators::NamedBase
  source_root File.expand_path('templates', __dir__)
end

Currently, all the ComponentGenerator does is define the source_root as the templates folder. Let's add a few things to it:

The main step of evaluating the component template and creating the resulting file
An example method that can be invoked from the template. In this case, it just returns a string
A class collision check to prevent the accidental creation of files with a duplicate suffix (e.g.: MyComponentComponent)

# lib/generators/component/component_generator.rb

class ComponentGenerator < Rails::Generators::NamedBase
  source_root File.expand_path("templates", __dir__)

  check_class_collision suffix: "Component"

  def create_component_file
    # Template method
    # First argument is the name of the template
    # Second argument is where to create the resulting file. In this case, app/components/my_component.rb
    template "component.rb", File.join("app/components",  "#{file_name}.rb")
  end

  private

  # Example method that can be invoked from the template
  def my_method
    "some string"
  end
end

And now let's create a template inside the templates folder. Again, notice how the methods we add to our generator class are accessible to the template (including the ones that are defined by the parent class Rails::Generators::NamedBase).

# lib/generators/component/templates/component.rb.tt

class <%= class_name %>Component
  def initialize
    @component_identifier = "<%= my_method %>"
  end
end

At this point, our generator is working and can create components with the desired name. It also makes use of our method that returns a string.

Running
$ bin/rails g component Post

Results in
# app/component/post_component.rb

class PostComponent
  def initialize
    @component_identifier = "some string"
  end
end

The last file created for us is a unit test for the generator itself. Rails provides a parent class for generator unit tests which contains a variety of helper methods for verifying the functionality we wrote.

Basically, we can assert which files are created and match against their contents.

class ComponentGeneratorTest < Rails::Generators::TestCase
  def test_component_is_created
    run_generator ["my_component"]
    assert_file "app/components/my_component.rb" do |component|
      assert_match(/class MyComponent/, component)
    end
  end
end

Next steps

There's a lot more that we can do with generators. Accepting arguments with specific types, asking for user input as the generator is running and test framework hooks to create unit test files for our component while respecting the testing library of choice (e.g.: minitest vs rspec).

I believed that including it all in a single article could be too dense. If the feedback is positive, I can turn this post into a series and explore more generator functionality. Please, let me know what you think in the comments!

Write a simple DSL in Ruby

Vinicius Stock — Tue, 24 Sep 2019 16:42:44 +0000

What is a DSL and what is it used for?

A DSL (Domain Specific Language) can be thought of as a dialect built for a unique purpose. At the bottom, it is a set of functions that are made available to be used inside the given domain.

The syntax used in the Gemfile, Rakefile or in tests written with rspec are some examples of DSLs in the Ruby world. They aim to provide well-defined interfaces for their tasks - declaring dependencies, defining make like tasks and writing unit tests, respectively.

Let's go through how one could go about creating a super minimalistic implementation of a bundler like tool for read a Gemfile. Please notice that the intention is to grasp the concepts and not have a working version of a package manager by the end.

How to create a DSL in Ruby

Surprisingly (at least for me), it isn't complex to define your own DSL with Ruby. Quite the opposite in fact. In our package manager example, it involves the following steps:

Creating a class that defines all methods available in the DSL
Reading the Gemfile
Evaluating the Gemfile within the execution context of a given instance
Using the evaluated information for installing the gems

These steps may sound obscure at first, but sit tight and they will soon make sense. Let's begin by creating the DSL class implementation. This class will contain all the methods that will be available for the Gemfile.

For simplicity, our DSL will only contain the gem directive - used to add a dependency. The implementation for other methods such as group or optional arguments such as require: false will be left out for simplicity. However, the concepts presented here should be a good starting point to reach richer functionality.

# dsl.rb

class Dsl
  attr_reader :gems

  def initialize
    # Initialize the list of gems
    # as an empty array.
    @gems = []
  end

  def read_gemfile
    # Read the contents of the gemfile as a string.
    contents = File.read("Gemfile")

    # Evaluate the Ruby string within the context
    # of the Dsl instance. That is, execute whatever
    # code found in the Gemfile using the state of
    # the current Dsl object.
    instance_eval(contents)
  end

  private

  # Gem directive definition
  # Adds the given gem_name to the list of
  # gems to be installed.
  #
  # This is the method executed whenever the Gemfile
  # contains the directive "gem 'something'"
  def gem(gem_name)
    @gems << gem_name
  end
end

We now have a minimal implementation of our Dsl class that can read the contents of the Gemfile and execute gem directives by adding the gem names to the @gems array.

All that is needed to add new directives to the DSL is creating new methods inside the DSL class. Every method in the class is made available to be used in our Gemfile. Furthermore, we can define a custom method_missing to choose how we want to handle invocations that don't exist in our DSL.

The extra succinct Gemfile below makes use of our gem directive and also uses some regular Ruby code. Notice that because we're executing the contents of the Gemfile within the Dsl instance, any Ruby code is valid.

# Gemfile

# Add 'rails' to the list of gems in the Dsl class.
gem "rails"

# Add 'rubocop' to the list of gems only if the environment
# variable RAILS_ENV matches 'development'.
if ENV["RAILS_ENV"] == "development"
  gem "rubocop"
end

Now that we have our Dsl implementation and our example Gemfile, we can write some pseudo-code that represents the much more complex installation process performed by bundler.

# Create Dsl instance.
dsl = Dsl.new

# Read and evaluate the Gemfile populating
# the @gems variable.
dsl.read_gemfile

# For each defined gem, install it
# which usually involves download the code from
# the package registry (rubygems.org) and placing it
# inside the Ruby folder structure.
dsl.gems.each do |gem|
  Bundler.install_gem(gem)
end

Conclusion

That's all! I hope these few lines of code can shine a light on how easily a DSL can be created using Ruby. In the real world, DSLs can be much more complex, have a lot of elaborate syntax and numerous classes for achieving the full desired functionality.

Additionally, there are many security implications we haven't covered in this article. Because this approach executes Ruby code from a string, we need to be extra careful with any user input that might end up being evaluated by the DSL. Otherwise, it could lead to remote code execution and cause all sorts of vulnerabilities.

I hope this quick introduction provides enough context to play around and fosters interest around this topic. Let me know what you think in the comments. Have you written DSLs before?

Offtopic

I would like to thank everyone who reads my articles. I just reached 2000 followers and I'm stoked!

Be sure to also follow me on Twitter if you'd like bit sized programming comments or random pictures.

Before shipping a new feature

Vinicius Stock — Fri, 23 Aug 2019 22:28:58 +0000

Introduction

Shipping new features is exciting and as software developers, we want to see our code running in production. However, there are some actions, questions, and steps that one can take before delivering tasks that will help improve the quality of the new functionality.

Acts, like building the code for graceful failures, taking advantage of refactoring opportunities, understanding the impact of the features being delivered, monitoring and manually testing the changes, are only a few examples pre-release activities.

Questions to ask before delivering a feature

It is essential to always have in mind the impact new changes can potentially cause for the end customers. Reflect on what the consequences would be for the users if something went wrong regardless of how simple the commits being merged are.

Also, reflect on how important the feature being delivered to the end-users is based on their perspective. How can it be made better?

A few questions to ask before shipping our beloved code could be:

What will the user experience if this page/service breaks?

How difficult would it be to revert these changes?

How big of an impact would a break like this have on our brand's image?

What other features can leverage this one and deliver more value to our users?

What functionality could be missing in this feature?

The answers to questions like these will outline steps that can be taken to improve the quality of the shipped feature.

Before shipping checklist

Here is a checklist of actions that can be done before clicking the deploy button.

Create tests for impactful corner cases

Testing every single edge case is certainly not needed. You will most likely not cover all of them and it will get your test suite bloated.

However, corner cases that lead to impactful failures must be tested and covered with fallback functionality. For example, if a specific page relies on fetching data from an external API. What happens if the API is down? Does the page break? Is it partially populated? Does it redirect to a different page?

Exploring these most impactful edge scenarios will often prevent production headaches in the future. And if one slips through, reproduce the error in tests, fix the undesired behavior and then push it up the stacks.

Manually test changes

Unfortunately, automated tests don't always catch everything. Take the time to explore the product and the new feature being delivered. Experience it as the customers would and ask yourself if you're satisfied with the solution.

If improvements related to the feature are identified, make sure they are tracked with a user story. They might not need to be implemented right away, but if they are accessible in the backlog, eventually they will be worked on.

Get feedback from the customers

We often have ideas and opinions on how the product we develop should be used. However, what truly matters is how our customers use and perceive the features we deliver.

Getting feedback from end-users is a bittersweet feeling. It can be tough and insightful at the same time. They might criticize the product you worked hard to build while also giving you the knowledge of what they need or expect from it. Be open-minded and ready to shift focus if necessary.

Setup adequate monitoring

In software, a lot happens under the hood. It can be far from easy to tell if everything is fine just by playing around with the user interface. Logging is one of the ways used to peek into the system that is running in production and get a sense if things truly are fine.

But what would you log? That is not a trivial question. It depends on the system, the product and the team building it. Too much logging might cause an unnecessary overhead while too little will give you zero context of what is happening in the application.

Some examples of things to log are:

When expected errors happen (e.g.: inside rescue/catch block)
When an undesired, but necessary behavior occurs (e.g.: users are redirected to a 404 page)
Key metrics (e.g.: number of items processed in the background)
Business indicators (e.g.: number of users that signed up using Google)

Refactor code

Stumbling upon pieces of code that could be refactored (for quality or reusability purposes) occurs frequently. Improving the code or making it reusable for other developers might cost a little bit of time now, but it will pay off in the long run.

If no developer ever pays the price of refactoring any code, technical debt can pile up until the codebase will slow down the development of new features. At that point, you're paying the price of all the refactoring that wasn't done.

If a section of the code can be improved with some extra work, do it. Make the next developer that will touch that part of the code happier.

Conclusion

This is my take on a feature release checklist. What would you add to the list? What practices do you have in your teams? I'd love to hear it!

Creating Ruby native extensions

Vinicius Stock — Tue, 09 Apr 2019 02:13:23 +0000

Note

Since the time this post was written, the ext option has been added to bundler, which automatically configures a new gem to be a native extension. Instead of following the outdated steps in this article, simply create the new gem using the ext option.

bundle gem my_gem --ext

What native extensions for Ruby are

When programming in Ruby, our code is compiled into instructions and then executed by the Ruby virtual machine (which is built in C).

Ruby native extensions are libraries written in C using the built-in functions of the RubyVM. Basically, it's C programming with a ton of functions and macros to interact with the virtual machine. Anything that can be achieved by using pure Ruby can also be implemented using the built-in instructions.

Why they are useful

Native extensions have a significant performance advantage when compared to pure Ruby, making them an excellent alternative for heavy load processing. Additionally, they permit tailored memory management thanks to having access to C functions like malloc and free.

A variety of popular gems are native extensions. When running bundle install, any gem that prints out "building native extensions" to the console is one of them. Some examples are: nokogiri, mysql2 and yajl-ruby.

How to create a native extension

Let's walk through the steps for creating a native extension from scratch.

Creating the gem
Gemspec configurations
Adding the compile task
The extconf file
Creating the C extension
Requiring the shared object
Testing the extension

Creating the gem

The first step is generating the gem. The bundle gem command encapsulates that task. In this case, our example gem is called "super".

$ bundle gem super

Gemspec configurations

With the default files created, we need to modify the gemspec configuration to register the extension and also add the rake-compiler gem to be able to compile it in development. The important modifications are:

Adding the "ext" folder to spec.files. The ext folder is where the native extensions files will live
Adding the extconf.rb file path to spec.extensions. We'll go through what this file is later. For now, just remember that it needs to be inside the path "ext/NAME_OF_EXTENSION/"
Adding the rake-compiler as a development dependency

# super.gemspec

lib = File.expand_path("../lib", __FILE__)
$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
require "super/version"

Gem::Specification.new do |spec|
  ...
  spec.files = Dir["{app,config,db,lib,ext}/**/*",
                   "MIT-LICENSE",
                   "Rakefile",
                   "README.md"]

  spec.extensions << "ext/super/extconf.rb"

  spec.add_development_dependency "rake-compiler"
  ...
end

Adding the compile task

After adding the rake-compiler gem, The compile task needs to be made available for the application. This is done by adding the following in our Rakefile.

# Rakefile
...
require "rake/extensiontask"

Rake::ExtensionTask.new("super") do |ext|
  ext.lib_dir = "lib/super"
end
...

The extconf file

The extconf.rb file contains the configurations to generate the makefile used to compile the extension. Customizing this file can be quite tricky, involving manipulating global variables, checking the current platform and including external libraries.

It becomes increasingly complex if the extension is split across many C files instead of a single one, for instance. However, the default configuration for a single file is straight forward.

# ext/super/extconf.rb

require "mkmf"

extension_name = "super"
dir_config(extension_name)
create_makefile(extension_name)

Creating the C extension

This is certainly the most challenging part of building native extensions. Learning how to use all the functions and macros made available by the RubyVM takes time and a few gotchas might have you looking at your code with a confused expression on your face.

An example of that is type conversions. A C float is not the same as a Ruby float and the appropriate macros need to be applied to handle values. If the input value is coming from Ruby into C, it needs to be converted into a C float. It must then be converted back to a Ruby float when returning to the Ruby context. Let's avoid type conversions in our super extension for simplicity.

The two mandatory steps of the C extension are: including the RubyVM and creating an initializer for the extension (which is named Init_NAMEOFEXTENSION). Everything else is the gem's logic.

# ext/super/super.c
#include <ruby.h>

void Init_super(void) {}

Let's dive into an example. We'll create the following class (represented here in pure Ruby) using the C extension.

# lib/super/super.rb

module Super
  class Super
    def initialize
      @var = {}
    end
  end
end

The equivalent native extension would be:

# ext/super/super.c
VALUE SuperModule = Qnil;
VALUE SuperClass = Qnil;

void Init_super();
VALUE super_initialize(VALUE self);

void Init_super() {
    SuperModule = rb_define_module("Super");
    SuperClass = rb_define_class_under(SuperModule, "Super", rb_cObject);
    rb_define_method(SuperClass, "initialize", super_initialize, 0);
}

VALUE super_initialize(VALUE self) {
    rb_iv_set(self, "@var", rb_hash_new());
    return self;
}

The class Super is now defined with the initialize method as presented in pure Ruby. The functions and macros details are listed below.

VALUE a macro for representing generic values
Qnil Ruby's nil definition
rb_define_module defines a module
rb_define_class_under creates a class under a given module. The arguments are the module object, the class name as a string and the class it will inherit from (which is Object in this case)
rb_define_method defines the initialize method. The arguments are the class object where the method will be defined, the method name as a string, the method implementation function and the number of arguments
rb_iv_set sets an instance variable to a given value. Takes the self object, the variable name, and the variable value
rb_hash_new instantiates a new hash. Just like {} in Ruby

Knowing the available RubyVM functions and macros is essential for creating extensions, but they are undoubtedly hard to memorize. Documentation and examples provide valuable assistance during the process.

Requiring the shared object

The native extension has been written. We can now cross our fingers, compile it and require the resulting shared object. Compilation in development is done using the task we previously imported.

$ rake compile

The result is the shared object file super.so under the lib folder. Requiring it in the gem's module will make all our definitions available.

# lib/super.rb

require "super/version"
require_relative "super.so"

module Super
end

Testing the extension

Our extension is complete and tests can be written to verify it. By requiring the shared object file, everything defined in the C is now available as Ruby. Therefore, extensions are tested likewise regular Ruby code.

Here is a possible test for the initialize method using rspec.

# spec/super/super_spec.rb

require "spec_helper"

describe Super::Super, type: :lib do
  describe ".initialize" do
    subject { described_class.new }

    it "sets var as an empty hash" do
      var = subject.instance_variable_get(:@var)
      expect(var).to eq({})
    end
  end
end

Conclusion

Using pure Ruby or C native extensions is a tradeoff. Despite the significant performance advantage, C extensions increase the complexity of reading and writing code when compared to Ruby.

Committing to using native extensions must be a conscious decision and the responsible team has to agree that the extra maintenance efforts will not surpass the performance benefits.

Nonetheless, knowing your way around native extensions is yet another useful skill for the Rubyist toolbelt.

Customizing Rails rake tasks

Vinicius Stock — Thu, 29 Nov 2018 21:43:03 +0000

Motivation

Rails rake tasks are commands that automate specific actions to be used either by the developers or by other mechanisms (e.g.: a deploy that will invoke rake tasks). Many tasks come configured with Rails out of the box to provide important functionality. In this post, I will explain how to override tasks and change their steps to customize them for your own application.

Here are a few examples of out of the box tasks:

$ rake -T      # Lists all rake tasks for the application
$ rake         # Default rake task. On a fresh application, does the same as rake test
$ rake test    # Task to run your tests (replaced by "rake spec" if using rspec instead of minitest)
$ rake db:seed # Populates the database using the seeds.rb file

However, tasks can quite easily be overridden to execute different actions. This is useful for defining steps for a build process that might include more than running the test suite or simply for changing the behavior of an existing task.

Customizing rake tasks to fit your needs can improve your productivity and help to guarantee that everyone in the project is using a standardized process (or at least that they have the tools to easily do so).

How to do it?

Overriding rake tasks is pretty straight forward. It involves two things: clearing the original task and re-defining it. Any code can go inside the new definition, however I recommend to neatly organize each step with their own rake task for simplicity.

How to create a new rake task

User defined rake tasks live inside the lib/tasks folder. Any file ending in ".rake" will be automatically picked up and loaded by Rails.

# lib/tasks/my_task.rake

namespace :custom do
  desc "This take does something useful!"

  task :do_it do
    puts "Do something useful!"
  end
end

Done! You can now invoke your new rake task using the command below. In the next section, we will go through on how to invoke it from other tasks.

$ rake custom:do_it

How to override an existing task

To override a task, clear the current behavior and re-define it in Rakefile. The example below will override the default rake to invoke our custom task.

# Rakefile
# frozen_string_literal: true

require_relative "config/application"

Rails.application.load_tasks
Rake::Task["default"].clear

task :default do
  Rake::Task["custom:do_it"].invoke
end

And there you have it! The default rake task can be configured to do whatever your application needs.

In the next section, I will go through my usual set up for Rails applications.

My preferred configuration

The configuration I like to use overrides both the default and the test rake tasks, integrating them with a few tools. The steps for each are described below (check individual tool set up and configuration in their respective repos).

If any of these steps break, build process is stopped and fails.

Default

Steps run in the following order

Brakeman - Code analysis for security
Parallel tests - Runs tests in parallel
Rubocop - Code quality analysis
Rails best practices - Best practices for Rails analysis
Reek - Code smells analysis

Test

This one simply replaces running tests to use parallel

Parallel tests - Runs tests in parallel

Now that we went through the high level description, let's get to business. Here is the Rakefile with the overridden tasks and the individual task definitions themselves.

# Rakefile
# frozen_string_literal: true

require_relative "config/application"
require "rubocop/rake_task"

Rails.application.load_tasks
Rake::Task["default"].clear
Rake::Task["test"].clear

task :default do
  Rake::Task["brakeman:check"].invoke
  Rake::Task["parallel:test"].invoke

  RuboCop::RakeTask.new(:rubocop)
  Rake::Task["rubocop"].invoke
  Rake::Task["rails_best_practices:run"].invoke
  Rake::Task["reek:run"].invoke
end

task :test do
  Rake::Task["parallel:test"].invoke
end

The brakeman rake task

# lib/tasks/brakeman.rake
# frozen_string_literal: true

namespace :brakeman do
  desc "Check your code with Brakeman"

  task :check do
    require "brakeman"
    result = Brakeman.run app_path: ".", print_report: true, pager: nil
    exit Brakeman::Warnings_Found_Exit_Code unless result.filtered_warnings.empty?
  end
end

The rails best practices rake task

# lib/tasks/rails_best_practices.rake
# frozen_string_literal: true

namespace :rails_best_practices do
  desc "Run rails best practices"

  task :run do
    puts "Running rails best practices!"
    puts `rails_best_practices`
  end
end

The reek rake task

# lib/tasks/reek.rake
# frozen_string_literal: true

namespace :reek do
  desc "Run reek"

  task :run do
    puts "Running reek!"
    bundle exec "reek ."
  end
end

The Gemfile

# Gemfile
group :development, :test do
  gem "brakeman", require: false
  gem "parallel_tests"
  gem "rails_best_practices", require: false
  gem "reek", require: false
  gem "rubocop", require: false
end

Conclusion

Overridden rake tasks can boost productivity and help enforce good practices among members of a team. Take advantage of them!

What other tools would you integrate with rake tasks?

What other uses can this capability have?