OrangeShark

Setting up a GNU Guile project with Autotools

2017-10-29T12:00:00-0400

Lisp, specifically Scheme, has captivated me for about three years now. My Scheme implementation of choice is GNU Guile because it is the official extension language of the GNU project. One issue I faced early with when trying to develop for Guile was how to set up and organize my project. There doesn't seem to be a single recommended way to set up a Guile project but several projects do follow a similar project structure I will describe below. You can find a git repository with the example project here.

Simple Project Structure

The project template I created for new projects is based on several GNU Guile projects I have examined. These projects follow the traditional GNU Build System using the familiar commands ./configure && make && sudo make install for building and installing software. To help generate these files, we will use the collection of software known as autotools which include the software Autoconf and Automake. Unfortunately, autotools can be quite complex for developers with its esoteric languages like m4 being used to magically create and configure all the necessary build files for your project. Good news for us, not much magic is needed for us to conjure the build files for a simple Guile project.

.
├── bootstrap
├── configure.ac
├── COPYING
├── COPYING.LESSER
├── guile.am
├── m4
│   └── guile.m4
├── Makefile.am
├── skeleton
│   └── hello.scm
├── pre-inst-env.in
├── README
└── skeleton.scm

Above is the directory structure of the project. bootstrap is a simple shell script which a developer can regenerate all the GNU Build System files. configure.ac is a template file which Autoconf uses to generate the familiar configure script. m4/guile.m4 is a recent copy of Guile's m4 macros, may not be needed if you prefer to use the macro from your Guile distribution, but it is recommended to keep your own copy. COPYING and COPYING.LESSER are just the GPL and LGPL licenses. Makefile.am and guile.am are Automake files used to generate the Makefile.in which configure will configure. skeleton.scm and skeleton/hello.scm are some initial source code files, where skeleton.scm represents the Guile module (skeleton) and skeleton/hello.scm is the (skeleton hello) module, change these file and directory names to what you want to name your modules as. pre-inst-env.in is a shell script which set up environment variables to be able to use your code before installing it.

Bootstrapping the Project

#! /bin/sh

autoreconf --verbose --install --force

This is the bootstrap script, it just calls autoreconf, which uses Autoconf and Automake, to generate the configure script from configure.ac and Makefile.in file from Makefile.am. The bootstrap script is sometimes also named autogen.sh in projects but seems to no longer be preferred to avoid confusion with the GNU AutoGen project. The command will also generate a bunch of other files needed by the build process. This script is only used when building from a checkout of the project's repository, because a user will only need configure and Makefile.in. Whenever you might be having an issue with the configure script or made a change to it, doing ./bootstrap will regenerate the files for you.

Generating the Configure Script

AC_INIT([guile-skeleton], [0.1])
AC_CONFIG_SRCDIR([skeleton.scm])
AC_CONFIG_AUX_DIR([build-aux])
AC_CONFIG_MACRO_DIR([m4])
AM_INIT_AUTOMAKE([-Wall -Werror foreign])

GUILE_PKG([2.2 2.0])
GUILE_PROGS
if test "x$GUILD" = "x"; then
   AC_MSG_ERROR(['guild' binary not found; please check your guile-2.x installation.])
fi

AC_CONFIG_FILES([Makefile])
AC_CONFIG_FILES([pre-inst-env], [chmod +x pre-inst-env])

AC_OUTPUT

Above is the configure.ac file used by GNU Autoconf to generate the configure script. The first line is the AC_INIT macro, the first argument is the package name and the second argument is the version. There is a couple of other optional arguments which you can learn more about here. The AC_CONFIG_SRCDIR macro adds a check to configure for the existence of a unique file in the source directory, useful as a safety check to make sure a user is configuring the correct project. AC_CONFIG_AUX_DIR macro is where auxiliary builds tools are found, build-aux is the the most commonly used directory, we use this so we don't litter the source directory with build tools. The next macro, AC_CONFIG_MACRO_DIR is where additional macros can be found, we add this to include the m4/guile.m4 file. GNU Automake options are part of the next macro, AM_INIT_AUTOMAKE, where -Wall turns all warnings, -Werror turns those warnings into errors, and finally foreign will turn the strictness to a standard less than the GNU standard. More automake options can be found here.

The GUILE_PKG and GUILE_PROGS macro is part of the m4/guile.m4 file. This macro will substitute various variables that will be used in the Makefile. The GUILE_PKG macro will use the pkg-config program to find the development files for Guile and substitute the GUILE_EFFECTIVE_VERSION variable in the Makefile. The GUILE_PROGS macro finds the various Guile programs we will need to compile our program. This macro substitutes the variables GUILE and GUILD with the path to the guile and guild programs. By default, these Guile macros will check for the latest version of Guile first, which is currently 2.2. If you have multiple versions of Guile installed, a user of the configure script may override the above Guile variables. For example if you have Guile 2.2 and 2.0 installed and you want to install the package for 2.0, you can run ./configure GUILE=/path/to/guile2.0. There is also a check to ensure the GUILD variable was set by GUILE_PROGS and displayed an error if it could not be found.

The next portion of this file involves the files that will actually be configured when a user runs the configure script. The AC_CONFIG_FILES macro's first argument is files that will be created by substituting the variables found in the file of the same name with .in appended to the end. In the first macro, it creates a Makefile by substituting the variables in Makefile.in. The second argument of this macro will be commands to run after the file is created, in the second macro, it uses chmod to make the pre-inst-env script executable. The last macro in this script is AC_OUTPUT and must be the final macro in configure.ac. This macro generates config.status and then uses it to do all the configuration.

Generating the Project Makefile

For this project we use GNU Automake to help us generate the Makefile. When Automake is ran, it will produce a Makefile.in file which will then be configured by the configure script. We divide the Makefile into two files, Makefile.am and guile.am. The first file is where we will put code specific for this project, that includes source code and any other files to be distributed to users. guile.am file is where we have all the code that can be shared between any other Guile project.

include guile.am

SOURCES =               \
  skeleton/hello.scm    \
  skeleton.scm

EXTRA_DIST =            \
  README                \
  bootstrap             \
  pre-inst-env.in

This Makefile.am file is pretty small for now. The Automake script first includes the Guile specific automake script guile.am. The next part is the variable SOURCES which is a list of the project's source code that will be compiled and installed. The next variable, EXTRA_DIST is a list of other files that should be included in the tarball used to distribute this project.

moddir=$(datadir)/guile/site/$(GUILE_EFFECTIVE_VERSION)
godir=$(libdir)/guile/$(GUILE_EFFECTIVE_VERSION)/site-ccache

GOBJECTS = $(SOURCES:%.scm=%.go)

nobase_dist_mod_DATA = $(SOURCES) $(NOCOMP_SOURCES)
nobase_go_DATA = $(GOBJECTS)

# Make sure source files are installed first, so that the mtime of
# installed compiled files is greater than that of installed source
# files.  See
# <http://lists.gnu.org/archive/html/guile-devel/2010-07/msg00125.html>
# for details.
guile_install_go_files = install-nobase_goDATA
$(guile_install_go_files): install-nobase_dist_modDATA

CLEANFILES = $(GOBJECTS)
GUILE_WARNINGS = -Wunbound-variable -Warity-mismatch -Wformat
SUFFIXES = .scm .go
.scm.go:
    $(AM_V_GEN)$(top_builddir)/pre-inst-env $(GUILD) compile $(GUILE_WARNINGS) -o "$@" "$<"

Now for guile.am, this file has all of the Guile specific code used in our Automake scripts. The first two variables, moddir and godir, are the paths where we will install our Guile modules and compiled modules. The next variable is the GOBJECTS variable which has some code that creates a list of Guile object files from our SOURCE variable. The next two variables declared are special DATA variables using some of Automake's features to indicate which files should be installed and where. The first portion of the variable, the nobase_ prefix is used to tell Automake to not strip the path of these files when installing them. dist_ tells Automake that these files must be distributed in the tarball. The next part, mod_ or go_, tell which directory these files should be installed, they refer to the above moddir and godir variables. The files in SOURCES and NOCOMP_SOURCES are installed in the moddir, where SOURCES are the scheme files that we want to be compiled and the NOCOMP_SOURCES are scheme files which should not be compiled. The compiled Guile source code, GOBJECTS are installed in the godir. The next two lines of code are some special magic to ensure the files are installed in the right order by Automake.

The CLEANFILES variable is an Automake variable with files which should be deleted when a user runs make clean. The compiled Guile modules are just the files we need to delete, so we assign GOBJECTS. GUILE_WARNINGS are warnings we want to pass to Guile when it compiles or executes the code. SUFFIXES allows us to add Guile's .scm and .go file extensions to be handled by Automake and we define a suffix rule on how to compile the source code using GUILD.

GNU Guile Project Source Files

We now get to the actual Guile code for this project. A Guile project may be divided into several modules and organized in various ways. In this skeleton project, the main module is the skeleton module and is found in skeleton.scm file. Sub-modules of skeleton are found in the skeleton/ directory, where we currently have the skeleton hello module found in the skeleton/hello.scm file.

(define-module (skeleton)
  #:use-module (skeleton hello))

(hello-world)

This is the skeleton module, it defines the module with the define-module form. We also import the skeleton hello module using the #:use-module option of define-module. All this file does is call hello-world procedure defined in the skeleton hello module.

(define-module (skeleton hello)
  #:export (hello-world))

(define (hello-world)
  (display "Hello, World!"))

The final module is the skeleton hello module. This module defines the hello-world procedure used in the previous module and then exports it using the #:exports option in the define-module form.

Putting It All Together

Now how does this all come together for development? With all these files in place in the project, executing the command ./bootstrap will use Autoconf and Automake to generate the configure, Makefile.in, and some other files. Then executing ./configure will configure Makefile.in, pre-inst-env.in. Running the program make should now compile your source code.

#!/bin/sh

abs_top_srcdir="`cd "@abs_top_srcdir@" > /dev/null; pwd`"
abs_top_builddir="`cd "@abs_top_builddir@" > /dev/null; pwd`"

GUILE_LOAD_COMPILED_PATH="$abs_top_builddir${GUILE_LOAD_COMPILED_PATH:+:}$GUILE_LOAD_COMPILED_PATH"
GUILE_LOAD_PATH="$abs_top_builddir:$abs_top_srcdir${GUILE_LOAD_PATH:+:}:$GUILE_LOAD_PATH"
export GUILE_LOAD_COMPILED_PATH GUILE_LOAD_PATH

PATH="$abs_top_builddir:$PATH"
export PATH

exec "$@"

Above is the pre-inst-env.in file which is configured by the configure script. The variables between '@' characters are variables that will be replaced by the configure script. abs_top_srcdir and abs_top_builddir are Autoconf variables which gives the absolute source directory and build directory. Then we add these directories to Guile's GUILE_LOAD_COMPILED_PATH and GUILE_LOAD_PATH. GUILE_LOAD_COMPILED_PATH is an environment variable that has the search path for compiled Guile code which have the .go extension. GUILE_LOAD_PATH is the search path for Guile source code files. When the configure script configures this file, it then allows you to run Guile and use the modules of the project before installing them. This can be done with this command ./pre-inst-env guile. The script also does the same for the PATH variable, to allow you to execute any scripts in the project's directory. Finally, the script executes the rest of the command passed into this script.

Distributing the Project

So the project is now complete and you want to distribute it to other people so they can build and install it. One of the great features of autotools is it generates everything you need to distribute your project. From the Makefile that is generated by GNU Automake, you run make dist and it will generate a tar.gz file of your project. This will be the file you will then give to your users and they will just extract the contents and run ./configure && make && sudo make install to build and install your project. The files that are included in the distribution are figured out by Automake and can be added to in your Makefile.am script file using the EXTRA_DIST variable. One other helpful feature that GNU Automake will generate is the command make distcheck. This command will check to ensure the distribution actually works, it will first create a distribution and then proceed to open the distribution, build the project, run tests, install the project, and uninstall the project all in a temporary directory. You can learn more about GNU Automake distribution in the manual.

One more note about installing your GNU Guile project. By default, the GNU Build System installs your project in the /usr/local directory. GNU Guile installations generally do not have this directory on their load path. There are several options on how to resolve this issue. You can add /usr/local/share/guile/site/$(GUILE_EFFECTIVE_VERSION) to the GUILE_LOAD_PATH variable as well as /usr/local/lib/guile/$(GUILE_EFFECTIVE_VERSION)/site-ccache to the GUILE_COMPILED_LOAD_PATH variable, where $(GUILE_EFFECTIVE_VERSION) is the GNU Guile version you are using, like 2.0 or 2.2. You can add these variables to your .profile or .bash_profile in your home directory like so:

export GUILE_LOAD_PATH="/usr/local/share/guile/site/2.2${GUILE_LOAD_PATH:+:}$GUILE_LOAD_PATH"
export GUILE_LOAD_COMPILED_PATH="/usr/local/lib/guile/2.2/site-ccache${GUILE_LOAD_COMPILED_PATH:+:}$GUILE_COMPILED_LOAD_PATH"

The alternative is to install your project in the current load path of your GNU Guile installation which is often /usr. You can easily do this by changing the prefix variable in the configure script like ./configure --prefix=/usr. Now when you run make install it will install everything in /usr instead of /usr/local. With the GNU Build System, you have full control of where you install your Guile files so you have the possibility of installing it anywhere you want like your home directory, just be sure to add that location to your load paths for Guile. There are several other variables you can modify to change the installation location of various files, you can learn more in the GNU Autoconf manual.

Conclusion

The GNU Build System provides a common interface for configuring, building, and installing software. The autotools project, although a bit complex, helps us achieve this. This should be enough for a basic GNU Guile library that can be compiled and distributed to users using the GNU Build System. You can find the example project on GitLab here. The project can be extended to include tests and documentation that I hope to cover in other blog posts.

Algorithms: Insertion Sort

2015-11-11T12:00:00-0500

I will be writing a series of blog posts about various algorithms. The purpose of these posts will be to help me further my understanding and ability to explain algorithms. Each post will cover an algorithm, provide an implementation in a programming language, explain the algorithm using the implementation, and finally discuss any possible other discoveries I find when researching the algorithm.

What are Algorithms?

Algorithms are a fundamental part of Computer Science, but what exactly are algorithms? Well according to Merriam-Webster, they define it as:

a set of steps that are followed in order to solve a mathematical problem or to complete a computer process

In Introduction to Algorithms, algorithms are described as "a tool for solving a well-specified computational problem" and as a technology. Knuth further describes algorithms as having five important features in his book The Art of Computer Programming. These include:

Finiteness: it must eventually stop (better if it stops in a reasonable amount of time)
Definiteness: each step must be clearly stated
Input: Zero or more inputs to give to an algorithm
Output: One or more outputs the algorithm produces
Effectiveness: operations must be basic and producible

So why are algorithms important to study? Well just as Introduction to Algorithms describes them as tools, they should be an important tool in any programmer's tool set to allow them to go above and beyond to solve problems.

Insertion Sort

Sorting algorithms are typically one of the first algorithms introduced to students studying Computer Science. The problems are usually easy to understand; I have a sequence of objects and I want to arrange them in some ordered sequence. Numbers are often used as the objects in examples of these algorithms because ordering numbers in an increasing or decreasing sequence is simple to understand. Insertion sort is one of those sorting algorithms.

The basic high level idea of the insertion sort algorithm is given an unsorted list, each item of the list is taken out and then inserted into a list in sorted order. Well according to the definition of an algorithm, maybe what I just described is more like the strategy to come up with an algorithm. This basic strategy can thus produce multiple algorithms with different properties. I will cover two variations of insertion sort and discuss their pros and cons.

Insertion Sort on Arrays

Insertion-Sort(v)
    for i <- 1 to length(v) - 1
        j <- i
        while j > 0 and v[j-1] > v[j]
            swap v[j] and v[j-1]
            j <- j - 1

The above is the pseudocode for insertion sort taken from Wikipedia. Please note the <- operator is the assignment operator, more commonly written as = in many languages. The algorithm sorts the list v in place, meaning it will modify, or mutate, the list given to the Insertion-Sort function. One will notice that the operation swap is usually not a basic operation in most languages so here is the simple pseudocode for swap.

temp <- v[j]
v[j] <- v[j-1]
v[j-1] <- temp

With the above pseudocode, translating it to your favorite programming language is trivial. Here it is written in python.

def insertion_sort(v):
    for i in range(1, len(v)):
        j = i
        while j > 0 and v[j-1] > v[j]:
            v[j], v[j-1] = v[j-1], v[j]
            j = j - 1

The python code is almost a literal copy and paste of the pseudocode, which shows off the popular idea on how python is almost like pseudocode. The line v[j], v[j-1] = v[j-1], v[j] is how you perform a swap operation in python.

Now to explain the basic idea behind the above insertion sort algorithm. The algorithm treats the front of the list, that is elements with index less than i, as a list that is already sorted and elements that are greater than i as elements which need to be sorted. This is why the algorithm starts from 1 because sorting a list of length 1 is trivial, it is already sorted. So the first loop goes through the unsorted part of the list, "taking out" the element, and then inserting it into the the sorted part of the list. The insertion part of the algorithm is the inner while loop, which keeps swapping elements from the tail end of the sorted list until it reaches the correct spot.

The behavior of this algorithm is also pretty straight forward. In the best case, the list is already sorted and the algorithm takes linear time or O(n). The algorithm will go through the list and try to insert the element to only find v[j-1] > v[j] to be false and thus no need to swap the element. For the worst case insertion sort takes quadratic time or O(n²), the worst case being the list is in reverse sorted order. It is the worst case because at each element in the list, it must swap that element until it reaches the front of the list. For memory, the algorithm sorts the list in place and thus is constant space or O(1). The insertion sort algorithm I listed here can actually be improved to make it slightly faster, but I leave that as an exercise for the reader (Hint: it is mentioned on Wikipedia).

Insertion Sort on Linked Lists

The second variation is an algorithm that works on linked lists or sometimes known as cons cells in other programming languages. This algorithm is written as a recursive function.

Insertion-Sort(l)
    if l is the empty list
        return the empty list
    else
        return Insert(Insertion-Sort(rest of l), head of l)

The above pseudocode is an example of the algorithm. There is of course one problem with the above pseudocode, Insertion-Sort uses the operation of Insert to insert an element into an already sorted list. Insert isn't a basic operation so we must provide an Insert algorithm for lists.

Insert(l, n)
    if l is the empty list
        return a list with the element n
    else if n <= the head of l
        return a list with the element n as the new head of list l
    else
        return a list with Insert(rest of l, n))

Now we should be able to implement the Insertion Sort algorithm in a programming language. I decided to use the Scheme programming language because of lists being native to the language.

(define (insertion-sort l)
  (if (null? l)
      '()
      (insert (insertion-sort (cdr l)) (car l))))

(define (insert l n)
  (cond ((null? l) (list n))
        ((<= n (car l)) (cons n l))
        (else (cons (car l) 
                    (insert (cdr l) n)))))

For those unfamiliar with the Lisp family of languages, here is a break down of some of the operations performed above. null? is a procedure to check for the empty list, car is a procedure to get the first element of a list, cdr is the procedure to get the list without the first element, cons is the procedure to create pairs which form the linked lists of lisp. So (cons x y) with y being a list (a b) creates a list (x a b). cond is a special form similar to if except with multiple clauses in the form (question answer), where if question evaluates to true, then answer is evaluated and returned as the result.

(insertion-sort '(3 1 2))
(insert (insertion-sort '(1 2)) 3)
(insert (insert (insertion-sort '(2)) 1) 3)
(insert (insert (insert (insertion-sort '()) 2) 1) 3)
(insert (insert (insert '() 2) 1) 3)
(insert (insert '(2) 1) 3)
(insert '(1 2) 3)
(cons 1 (insert '(2) 3))
(cons 1 (cons 2 (insert '() 3)))
(cons 1 (cons 2 '(3)))
(cons 1 '(2 3))
'(1 2 3)

The idea behind this linked list version of insertion sort is to take each element from the list and then insert it into the sorted version of the list. So this recursive algorithm has to have a base case, which is if the list l is the empty list. Well, how do you sort the empty list? Of course, it is just the empty list. Now if the list isn't empty, we need to sort it, so the recursive step is to sort the rest of l. With the result of the recursive call, we have a sorted list without the first element of l, so we then insert the the first element l into the sorted list. The insert algorithm is complex enough to need an explanation as well. The insert algorithm is also recursive with the same base case of the list l being empty, so we just return a new list with the number n. The next base case is when n is less than or equal to the head of list l, so the proper action is to cons n to be the new head of l. The recursive step is when n isn't in the correct position, so we cons the current head of l onto the list with n inserted into it.

The behavior of the list insertion sort is similar to the first insertion sort. The best case is when the list is already sorted which will give you linear time or O(n). What the algorithm does is it tries to insert the head of l onto the already sorted list, the head will just be cons to the front of it. The worst case is also the same, the list is in reverse sorted list and thus has quadratic time or O(n²). Memory is a different story, this version of the algorithm creates a new list instead of sorting in place. The best case, when the list is already sorted, the algorithm copies the elements to the new list and is just linear space or O(n). The worst case is the list is in reverse sorted order, the insert algorithm creates a new list each time n is inserted into l which is quadratic space or O(n²). The above algorithm can also be improved, insertion sort can be made into an iterative process and the insert algorithm can also insert into the list by mutating it.

Tutorial: Hello, world! Cinnamon desklet

2014-12-31T12:00:00-0500

This is the first of hopefully several tutorials on developing desklets for the Cinnamon desktop environment. In this tutorial, I will cover the basics of creating a desklet and do my best to link or refer to additional resources where you might find more information on the topics. Cinnamon is a linux desktop environment forked from Gnome Shell by Linux Mint. A desklet is a small application which appears on the Cinnamon desktop, Cinnamon ships with three desklets and more can be found here. Desklets are written in JavaScript and uses CJS which is based on Gjs. Gjs are JavaScript bindings for GNOME and is based on Mozilla's JavaScript engine Spidermonkey.

My reason for creating this tutorial came about when I was creating a desklet for Cinnamon. There were barely any guides or tutorials on creating a desklet and finding documentation on the libraries available in CJS was difficult. The only advice I saw was to read other people's source code and learn from that, while it is a great way to learn, it does not provide enough information. So I would like to share what I have learned and where I found it.

Our first desklet will be a simple "Hello, World!" program, a simple program which displays the text "Hello, World!" on the desktop using GNOME Shell's Clutter-based toolkit called St (Shell Toolkit). The St library provides an easy way to create simple user interfaces.

Requirements

Cinnamon (I am running Linux Mint 17.1 with version 2.4.5)
Your favorite text editor

Set up

Let's start by setting up the directory for our desklet. Desklets are stored in the user's home directory ~/.local/share/cinnamon/desklets, this is where we will work on our desklet. First, we need to create the directory of our desklet with a unique ID or UUID in the following format "desklet-name@name", where desklet-name is the desklet's name, in this case hello-world, and name is either your name or your domain name. I will use the UUID "hello-world@orangeshark".

mkdir -p ~/.local/share/cinnamon/desklets/hello-world@orangeshark
cd ~/.local/share/cinnamon/desklets/hello-world@orangeshark

Now we need to create the structure for our project. A desklet has the following structure:

hello-world@orangeshark/
├── desklet.js
└── metadata.json

The desklet.js file is where the majority of our JavaScript code will be located. metadata.json contains, of course, the metadata for the desklet, including the UUID and name of the desklet.

touch desklet.js metadata.json

Time to code

Lets first define the metadata for the desklet, open up metadata.json and add the following json.

{
    "uuid": "hello-world@orangeshark",
    "name": "Hello, world! desklet",
    "description": "Displays Hello, World!",
    "prevent-decorations": false
}

The metadata contains basic information about your desklet, including the UUID we discussed earlier. The only special property is "prevent-decorations" which tells Cinnamon whether to apply your desktop's theme or prevent it from inheriting it. For this simple example, we will put the value false so the desklet looks like the rest of your desktop.

Now for the JavaScript. There are several coding style guides to follow for JavaScript by the GNOME project, Cinnamon seems to follow this guide. If you are used to using JavaScript on the web or in node.js, you might notice a couple of differences in the language. Several of these features are from Mozilla's version of JavaScript with some being defined in future versions of ECMAScript. I will provide links where you can find additional information on those features as we encounter them.

const Desklet = imports.ui.desklet;

function HelloDesklet(metadata, desklet_id) {
    this._init(metadata, desklet_id);
}

HelloDesklet.prototype = {
    __proto__: Desklet.Desklet.prototype,

    _init: function(metadata, desklet_id) {
        Desklet.Desklet.prototype._init.call(this, metadata, desklet_id);
    }
}

function main(metadata, desklet_id) {
    return new HelloDesklet(metadata, desklet_id);
}

The above code is all you need to create a minimal desklet. You can use it as the basic template to start your own desklet. Now for an explanation of each part! The first line contains const, one of those new features I mentioned earlier, more info here. The const declaration creates a constant in the current scope, in this case the global scope, with a value that cannot be changed through re-assignment. We use it here to import the desklet module from Cinnamon. The next function is our Desklet object's constructor, following GNOME's style guide for creating "classes". Using GNOME's class pattern, we assign to the prototype of HelloDesklet an object containing the methods and properties for our HelloDesklet class. The first property "__proto__" is a special one, it allows us to modify the prototype chain, allowing us to have a sort of inheritance of classes. So if a property is not found in the current instance, it will walk the prototype chain to the next prototype, in this case Desklet's prototype, and check if the property is there. So our desklet must "inherit" from Cinnamon's Desklet class, Desklet contains a lot of code required by Cinnamon to set up and destroy a desklet. The _init function is the actual constructor for our "class" and our first task is to call the Desklet's constructor, passing the current instance using "this". Finally the main function is the entry point to our desklet and we just return an instance of our desklet.

const Desklet = imports.ui.desklet;
const St = imports.gi.St;

function HelloDesklet(metadata, desklet_id) {
    this._init(metadata, desklet_id);
}

HelloDesklet.prototype = {
    __proto__: Desklet.Desklet.prototype,

    _init: function(metadata, desklet_id) {
        Desklet.Desklet.prototype._init.call(this, metadata, desklet_id);

        this.setupUI();
    },

    setupUI: function() {
        // main container for the desklet
        this.window = new St.Bin();
        this.text = new St.Label();
        this.text.set_text("Hello, world!");
        
        this.window.add_actor(this.text);
        this.setContent(this.window);
    }
}

function main(metadata, desklet_id) {
    return new HelloDesklet(metadata, desklet_id);
}

We now import a new library, this time St or Shell Toolkit library from GNOME. I have found this documentation to be helpful in finding what classes are available in JavaScript over the GNOME's official C API reference. Next, a new method to HelloDesklet has been added which sets up our little window on the desktop and displays the text "Hello, world!". We use a StBin container that can contain a single child, which is a StLabel widget with the text "Hello, world!". Finally we add the label to the window with the add_actor method and then set the desklet content with setContent method inherited from the Desklet base class. That is it! We have finished the basis of a simple desklet for Cinnamon. It should look something like what you see below (the style might be different depending on your Cinnamon theme).

This concludes the tutorial for Cinnamon desklets. I plan on covering more aspects on creating Cinnamon desklets in the future, so stay tuned!