foot/INSTALL.md

Installing

1. Overview
2. Requirements
   1. Running
   2. Building
3. Arch Linux
4. Other
   1. Setup
   2. Release build
      1. Profile Guided Optimization
   3. Debug build
   4. Running the new build

Overview

foot makes use of a couple of libraries I have developed: tllist and fcft. As such, they will most likely not have been installed already. You can either install them as system libraries, or you can build them as subprojects in foot.

When building foot, they will first be searched for as system libraries. If found, foot will link dynamically against them.

If not found, they will be searched for as subprojects. In this case you need to create the subprojects directory and clone https://codeberg.org/dnkl/fcft.git and https://codeberg.org/dnkl/tllist.git (see Other below).

Requirements

Running

• fontconfig
• freetype
• pixman
• wayland (client and cursor libraries)
• xkbcommon
• fcft ¹

Building

In addition to the dev variant of the packages above, you need:

• meson
• ninja
• wayland protocols
• ncurses (needed to generate terminfo)
• scdoc (for man page generation)
• tllist ¹

A note on compilers; in general, foot runs much faster when compiled with gcc instead of clang. A profile-guided gcc build can be more than twice as fast as a clang build.

Note GCC 10.1 has a performance regression that severely affects foot when doing PGO builds and building with -O2; it is about 30-40% slower compared to GCC 9.3.

The work around is simple: make sure you build with -O3. This is the default with meson --buildtype=release, but e.g. makepkg can override it (makepkg uses -O2 by default).

Arch Linux

Install from AUR:

• foot + foot-terminfo
• foot-git + foot-terminfo-git

Or use makepkg to build the bundled PKGBUILD (run makepkg in the source root directory).

Unlike the AUR packages, the bundled PKGBUILD requires tllist and fcft to be installed as system libraries. If you do not want this, please edit the PKGBUILD file, or install manually (see Other below).

Note that it will do a profiling-guided build, and that this requires a running wayland session since it needs to run an intermediate build of foot.

Other

Foot uses meson. If you are unfamiliar with it, the official tutorial might be a good starting point.

I also recommend taking a look at the bundled Arch PKGBUILD file, to see how it builds foot. Especially so if you intend to install a release build of foot, in which case you might be interested in the compiler flags used there.

Setup

If you have not installed tllist and fcft as system libraries, clone them into the subprojects directory:

mkdir -p subprojects
pushd subprojects
git clone https://codeberg.org/dnkl/tllist.git
git clone https://codeberg.org/dnkl/fcft.git
popd

To build, first, create a build directory, and switch to it:

mkdir -p bld/release && cd bld/release

Release build

CFLAGS+="-O3 -march=native -fno-plt"
export CFLAGS
meson --buildtype=release --prefix=/usr -Db_lto=true ../..

For performance reasons, I strongly recommend doing a PGO (Profile Guided Optimization) build. This requires a running Wayland session since we will be executing an intermediate build of foot.

If you do not want this, just build:

ninja

and then skip to Running the new build.

For packagers: normally, you would configure compiler flags using -Dc_args. This however "overwrites" CFLAGS. makepkg from Arch, for example, uses CFLAGS to specify the default set of flags.

Thus, we do export CFLAGS+="..." to at least not throw away those flags.

When packaging, you may want to use the default CFLAGS only, but note this: foot is a performance critical application that relies on compiler optimizations to perform well.

In particular, with GCC 10.1, it is very important -O3 is used (and not e.g. -O2) when doing a PGO build.

Profile Guided Optimization

First, make sure you have configured a release build directory, but:

If using Clang, make sure to add -Wno-ignored-optimization-argument -Wno-profile-instr-out-of-date to CFLAGS.

If using GCC, make sure to add -Wno-missing-profile to CFLAGS.

Then, tell meson we want to generate profile data, and build:

meson configure -Db_pgo=generate
ninja

Next, we need to execute the intermediate build of foot, and run a payload inside it that will exercise the performance critical code paths. To do this, we will use the script scripts/generate-alt-random-writes.py:

foot_tmp_file=$(mktemp)
./foot --config=/dev/null --term=xterm sh -c "<path-to-generate-alt-random-writes.py> --scroll --scroll-region --colors-regular --colors-bright --colors-rgb ${foot_tmp_file} && cat ${foot_tmp_file}"
rm ${foot_tmp_file}

You should see a foot window open up, with random colored text. The window should close after ~1-2s.

If using Clang, now do (this requires llvm to have been installed):

llvm-profdata merge default_*profraw --output=default.profdata

Next, tell meson to use the profile data we just generated, and rebuild:

meson configure -Db_pgo=use
ninja

Continue reading in Running the new build

Debug build

meson --buildtype=debug ../..
ninja

Running the new build

You can now run it directly from the build directory:

./foot

But note that it will default to TERM=foot, and that this terminfo has not been installed yet. However, most things should work with the xterm-256color terminfo:

./foot --term xterm-256color

But, I recommend you install the foot and foot-direct terminfo files. You can either copy them manually (typically to /usr/share/terminfo/f - but this depends on the distro), or just install everything:

ninja install

---

1. can also be built as subprojects, in which case they are statically linked. ↩︎