slock Source Build^

The Simple Display Locker, or slock, is a simple and straightforward answer the problem of how to blank your screen when you walk away from your computer or otherwise need to shut it off without a complete shutdown. Unlike the alternatives, slock doesn’t require a complicated display manager or login screen.

Unlike most Linux tools but like most everything that Suckless.org ships, the preferred installation path does not involve a call to your distribution’s package manager: instead, they prefer you build from source.

The procedure below is slightly more complex than necessary. It includes in the use of a personal repository, which is helpful but not a strict requirement. It also includes some additional verification steps for cases where you need to confirm that the process was successful.

Configure the Repository ^

Suckless.org uses Git to handle its version control, which is convenient since we also use Git to version control our work.

In order to build slock from source, you need a local repository with the slock code. But, since you may want to save and share any changes you make to this code, it is good to also set up a personal remote repository to keep your code in sync with the upstream slock code.

This guide organizes the following remote repositories:

`origin`	Your personal remote repository, hosted on GitHub, GitLab, or your own remote infrastructure from a bare Git repository.
`upstream`	The slock repository hosted by Suckless.org.

Clone the Origin Repository ^

Start with the origin remote repository. This can be created on GitHub or GitLab as managed solution, or if you need to self-manage everything, you can set up a server in the cloud or on your network to host a bare Git repository.

Once you have the repository ready, clone it onto your local system:

$ git clone git@gitlab.com:kennethpjdyer/dyer-slock ~/.local/opt/slock/main

This command clones the remote Git repository (in this case, my private repository for hosting my fork of slock) from the host to the ~/.local/opt/slock/main directory.

Note

The flat ~/.local/opt/slock directory will be a more familiar path to most users. The reason why I have mine down to slock/main is that I use Git worktrees to separate the branch of live code from feature branches I have in the works.

Configure the Upstream Repository ^

The repository is currently empty. In order to pull down the code from Suckless.org, you need to configure a separate remote to tell Git where to look for the upstream code.

First, add the upstream remote:

$ cd ~/.local/opt/slock/main
$ git remote add upstream https://git.suckless.org/slock

To test that you have the correct URL, use the fetch command to connect to the remote repository and pull down the commit and branch information you need to use the upstream:

$ git fetch upstream

If the fetch pulls down data from upstream, it indicates that the remote repository was correctly configured.

Merge the Upstream Release ^

In order to bring the remote code down from Suckless.org to your local repository, you need to pull a specific branch.

The remote slock repository uses the master branch to track on-going work on the tool. If you plan to run slock as a bleeding edge build, this is the branch to pull down.

However, it is generally advisable that you track a specific release. Suckless.org tags release commits and pushes them to specific branches on the upstream repository.

To list the available tags, use the tag command:

$ git tags
...
9
0
2
3
4
5

This shows the available tags. It’s generally advisable to pull down the latest release, but you can work from any that you feel comfortable using.

To pull down a specific release, use the pull command:

$ git pull --no-rebase upstream 1.5

The --no-rebase option ensures that Git merges the changes from the upstream branch rather than rebases.

Note

As of the writing, I don’t have a strong opinion on whether it’s better to merge or rebase. I expect at some point in this process I’ll do a write up on both so watch for the KB articles on the Git page for more information.

Push the Changes to Origin ^

Once you have the base code from the upstream remote merged into your local repository, you should also push the changes up to your personal remote repository.

$ git push origin HEAD

The HEAD branch is a special designation to push your current branch to a remote branch of the same name.

As best practice, you should make a habit of always pushing your commits up to the origin HEAD branch. This ensures that whatever you are doing exists in at least two places, which is much more secure than trusting your hard drive with all your important work to last forever.

Note

When pushing a rebase up to a remote repository, you sometimes need to use the --force-with-lease option.

Build and Install ^

Now that you have the source code, you need to build slock in your local repository. This can be done using GNU Make, which reads the provided Makefile to perform a series of operations in order to compile the C code to native binaries.

Build Binaries ^

Slock is written to the C99 standard of the C programming language. Make calls the cc command, which on my system invokes GCC.

$ make
slock build options:
CFLAGS   = -std=c99 -pedantic -Wall -Os -I. -I/usr/include
           -I/usr/X11R6/include -DVERSION="1.5" -D_DEFAULT_SOURCE
           -DHAVE_SHADOW_H
LDFLAGS  = -s -L/usr/lib -lc -lcrypt -L/usr/X11R6/lib -lX11
           -lXext -lXrandr
CC       = cc
CC slock.c
CC explicit_bzero.c
CC -o slock

As you can see, it runs the compiler several times to build out the slock binaries that runs the terminal emulator.

A benefit of Suckless.org’s focus on simplicity is that their software tends to compile very fast. So fast that it’s pretty trivial to make a quick change to the C code and then recompile and run the updated binary—which is something you’ll likely be doing a lot as you hack on the code to get it to do what you need.

Note

Most errors you encounter at this stage relate either to a build error you introduced or a missing dependency. In the future I’ll test building slock on a fresh installation to work out distro specific requirements for Arch Linux and Gentoo.

Install Binaries ^

With the binary successfully built, it’s time to install them on your system.

Installation on Linux requires elevated privileges to copy the binary to /usr/local/bin. You can modify the prefix to install the binary somewhere in your user’s /home directory path, such as ~/.local/bin—but, you shouldn’t. It’s best practice to move executable binaries some place where users or rogue processes would have difficulty in making changes. So, use sudo to run the install process.

$ sudo make install
[sudo] password for user:
slock build options:
CFLAGS   = -std=c99 -pedantic -Wall -Os -I. -I/usr/include
           -I/usr/X11R6/include -DVERSION="1.5" -D_DEFAULT_SOURCE
           -DHAVE_SHADOW_H
LDFLAGS  = -s -L/usr/lib -lc -lcrypt -L/usr/X11R6/lib -lX11 -lXext
           -lXrandr
CC       = cc
installing executable file to /usr/local/bin
installing manual page to /usr/local/share/man/man1

This command install slock in the /usr/local/bin directory with the appropriate permissions.

Clean Repository ^

The next step after installing slock is to clean the repository. This can also be done with Make using the clean target to run the appropriate rm operations.

$ make clean
cleaning

Verify Install ^

Verification of an installation is not a step you need to undertake every time you rebuild slock. You can usually just call slock_run to ensure that it’s available to you.

But, it’s good to know how to verify an install in the event that you encounter errors or similarly unexpected behaviors.

Check Location ^

This simplest check is to see if the slock binaries are available in your PATH. This can be done with the whereis command:

$ whereis slock
slock: /usr/local/bin/slock

Check Version ^

An even simpler check to verify the installation of slock is to check its version. Many Linux applications are configured with a version sub-command or a --version option to retrieve this information. Slock uses the simpler -v option.

$ slock -v
slock-1.5

Installation should overwrite any existing binaries installed on your system. If the version number shown here does not match the one for the tag you compiled, something went wrong with the install and you should double-check whereis and other areas to investigate the reason.

slock: The Simple Display Locker

slock Configuration