st Source Build^

The Simple Terminal, or st, is a terminal emulator for X. It is very lightweight, easy to modify, and a good tool to use if you want to learn C programming and hacking on Linux.

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 st from source, you need a local repository with the st 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 st 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 st repository hosted by Suckless.org.

Clone 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-st ~/.local/opt/st/main

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

Note

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

Configure 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/st/main
$ git remote add upstream https://git.suckless.org/st

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 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 st repository uses the master branch to track on-going work on the tool. If you plan to run st 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
...
8.5
9
9.1
9.2
9.3

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 0.9.3

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 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 st 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 ^

St is written to the C99 standard of the C programming language. Make calls the c99 command, which on my system invokes GCC with the -std=c99 option.

$ make
c99 -I/usr/X11R6/include  `pkg-config --cflags fontconfig`
`pkg-config --cflags freetype2` -DVERSION=\"0.9.3\"
-D_XOPEN_SOURCE=600  -O1 -c st.c
c99 -I/usr/X11R6/include  `pkg-config --cflags fontconfig`
`pkg-config --cflags freetype2` -DVERSION=\"0.9.3\"
-D_XOPEN_SOURCE=600  -O1 -c x.c
c99 -o st st.o x.o -L/usr/X11R6/lib -lm -lrt -lX11 -lutil
-lXft  `pkg-config --libs fontconfig`  `pkg-config
--libs freetype2`

As you can see, it runs the compiler three times to build out the st binary 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 st 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:
mkdir -p /usr/local/bin
cp -f st /usr/local/bin
chmod 755 /usr/local/bin/st
mkdir -p /usr/local/share/man/man1
sed "s/VERSION/0.9.3/g" < st.1 > /usr/local/share/man/man1/st.1
chmod 644 /usr/local/share/man/man1/st.1
tic -sx st.info
7 entries written to /usr/share/terminfo
Please see the README file regarding the terminfo entry of st.

This command installs st command and the documentation.

There are people who recommend you run all the Make commands with sudo, that way you can run Make with install and clean as a single step, but I find this breaks down the paradigm. You should test a build and then install it as separate steps. You should also not include sudo in Makefiles to ensure that the user is always clear when they’re using elevated privileges and when they are not.

Clean Repository ^

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

$ make clean
rm -f st st.o x.o st-0.9.3.tar.gz

This isn’t strictly necessary, given that the extra disk space claimed by these binary .o and .tar.gz files is negligible in these inferior years of plenty—but, it’s best practice. It also ensure that when you run fzf or attempt tab completion later, you won’t have those binaries getting in the way.

Verify Install ^

Verification of an installation is not a step you need to undertake every time you rebuild st. You can usually just call st from dmenu 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 st is available in your PATH. This can be done with the whereis command:

$ whereis st
st: /usr/local/bin/st /usr/share/man/man4/st.4.gz

Here, whereis shows me that st is available in my PATH and that it has a man page for me to use in the event that I want to research its options and usage.

If you want to read the documentation, use the man command:

$ man st

Check Version ^

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

$ st -v
st 0.9.3

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.

st: The Simple Terminal

Bibliography