Creating the YaST journalctl module

Welcome to the tutorial

The goal

The goal of this tutorial is to present a very simple example of a YaST module developed from scratch. The document is focused in the tools and the overall architecture used for such a simple development. Many other interesting YaST subjects, like modifying the installer or accessing complex configurations in the underlying system, are intentionally left out.

You, as a reader, are expected to be familiar with the Ruby programming language at least to a certain degree. No general Ruby subjects will be explained, but you can always check the introduction documents recommended by the excellent ruby-doc.org Ruby documentation project.

Setting up the environment

This tutorial is better followed using a recent version of openSUSE (tested in openSUSE 13.2). Of course, using openSUSE Tumbleweed would be even better, since it's the recommended development environment for YaST.

Everything needed in order to set up the YaST development environment is detailed in the "contributing" section of the YaST development home page. In a recent openSUSE, it's as simple as installing Git, the YaST development tools and the YaST-Rake gem. The first two are easily installed running:

zypper install git-core yast2-devtools

In order to install Ruby gems for YaST development you should always install the package that corresponds to the version of Ruby that is used by default in your system. For example, in systems based in Ruby 2.1, the package name would be "ruby2.1-rubygem-yast-rake". The following set of commands will always install the right package by first guessing your Ruby version and storing it in a variable (make sure there are no spaces before and after "=").

ruby_version=$(ruby -e "puts RbConfig::CONFIG['ruby_version']")
zypper install -C "rubygem(ruby:$ruby_version:yast-rake)"

The method

This document is a step by step tutorial to develop a module called yast-journalctl which resembles a lot the already existing yast-journal. In fact, this tutorial reflects closely the author's own learning experience while developing yast-journal as his first YaST module. From that point of view, this is a tutorial for newbies written by a newbie.

All the example code and files used in the tutorial are available at this GitHub repository and organized following the learning time-line. The tutorial is divided into small steps and every step correspond with a tag in the repository's history, so instead of reading some chunks of code embedded in the tutorial's text, you can actually go back and forward in time and freely explore the whole tree with your favorite source code editor.

If you are proficient with git, feel free to play with the repository. Otherwise it's better to do not change anything in your local copy of the repository and just use the provided commands to browse the history while writing your own code in a different clean directory.

A look into the future

As a first step, simply clone the repository to have your own local copy.

git clone https://github.com/yast/yast-journalctl-tutorial

Right after cloning, you can already see how the final result will look like once you have finished the tutorial.

cd yast-journalctl-tutorial
rake run

If it shows too few journal entries for your taste (or even none), try to run it again with the root user, who has full access to the systemd journal.

Let's start

If you were able to execute the module, you are ready to proceed to the next step by clicking on Step 1/7.