Codebergdnkl

foot

master
ply5 git calls493 ms34 KiB3 cachedprotocol v2
476 lines17 KiBRaw

Installing

  1. Overview
  2. Requirements
    1. Running
    2. Building
  3. Other
    1. Setup
    2. Options
    3. Release build
      1. Size optimized
      2. Performance optimized, non-PGO
      3. Performance optimized, PGO
        1. Partial PGO
        2. Full PGO
        3. Use the generated PGO data
      4. Profile Guided Optimization
    4. Debug build
    5. Terminfo
    6. 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 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, meson will attempt to download and build them as subprojects.

Requirements

Running

  • UTF-8 locale
  • fontconfig
  • freetype
  • pixman
  • wayland (client and cursor libraries)
  • xkbcommon
  • utf8proc (optional, needed for grapheme clustering)
  • libutempter (optional, needed for utmp logging on Linux)
  • ulog (optional, needed for utmp logging on FreeBSD)
  • fcft [^1]

[^1]: can also be built as subprojects, in which case they are statically linked.

If you are packaging foot, you may also want to consider adding the following optional dependencies:

  • libnotify: desktop notifications by default uses notify-send.
  • xdg-utils: URLs are by default launched with xdg-open.
  • bash-completion: If you want completion for positional arguments.

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, not needed if documentation is disabled)
  • llvm (for PGO builds with Clang)
  • tllist [^1]
  • systemd (optional, foot will install systemd unit files if detected)

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).

Other

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

A note on terminfo; the terminfo database exposes terminal capabilities to the applications running inside the terminal. As such, it is important that the terminfo used reflects the actual terminal. Using the xterm-256color terminfo will, in many cases, work, but I still recommend using foot's own terminfo. There are two reasons for this:

  • foot's terminfo contains a couple of non-standard capabilities, used by e.g. tmux.
  • New capabilities added to the xterm-256color terminfo could potentially break foot.
  • There may be future additions or changes to foot's terminfo.

As of ncurses 2021-07-31, ncurses includes a version of foot's terminfo. The recommendation is to use those, and only install the terminfo definitions from this git repo if the system's ncurses predates 2021-07-31.

But, note that the foot terminfo definitions in ncurses' lack the non-standard capabilities. This mostly affects tmux; without them, terminal-overrides must be configured to enable truecolor support. For this reason, it is possible to install "our" terminfo definitions as well, either in a non-default location, or under a different name.

Both have their set of issues. When installing to a non-default location, foot will set the environment variable TERMINFO in the child process. However, there are many situations where this simply does not work. See https://codeberg.org/dnkl/foot/issues/695 for details.

Installing them under a different name generally works well, but will break applications that check if $TERM == foot.

Hence the recommendation to simply use ncurses' terminfo definitions if available.

If packaging "our" terminfo definitions, I recommend doing that as a separate package, to allow them to be installed on remote systems without having to install foot itself.

Setup

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

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

Options

Available compile-time options:

OptionTypeDefaultDescriptionExtra dependencies
-DdocsfeatureautoBuilds and install documentationscdoc
-DtestsbooltrueBuild tests (adds a ninja test build target)None
-DimebooltrueEnables IME supportNone
-Dgrapheme-clusteringfeatureautoEnables grapheme clusteringlibutf8proc
-DterminfofeatureenabledBuild and install terminfo filestic (ncurses)
-Ddefault-terminfostringfootDefault value of TERMNone
-Dterminfo-base-namestring-Ddefault-terminfoBase name of the generated terminfo filesNone
-Dcustom-terminfo-install-locationstring${datadir}/terminfoValue to set TERMINFO toNone
-Dsystemd-units-dirstring${systemduserunitdir}Where to install the systemd service files (absolute)None
-Dutmp-backendcomboautoWhich utmp backend to use (none, libutempter, ulog or auto)libutempter or ulog
-Dutmp-default-helper-pathstringautoDefault path to utmp helper binary. auto selects path based on utmp-backendNone

Documentation includes the man pages, readme, changelog and license files.

-Ddefault-terminfo: I strongly recommend leaving the default value. Use this option if you plan on installing the terminfo files under a different name. Setting this changes the default value of $TERM, and the names of the terminfo files (if -Dterminfo=enabled).

If you want foot to use the terminfo files from ncurses, but still package foot's own terminfo files under a different name, you can use the -Dterminfo-base-name option. Many distributions use the name foot-extra, and thus it might be a good idea to reuse that:

sh
meson ... -Ddefault-terminfo=foot -Dterminfo-base-name=foot-extra

(or just leave out -Ddefault-terminfo, since it defaults to foot anyway).

Finally, -Dcustom-terminfo-install-location enables foot's terminfo to co-exist with ncurses' version, without changing the terminfo names. The idea is that you install foot's terminfo to a non-standard location, for example /usr/share/foot/terminfo. Use -Dcustom-terminfo-install-location to tell foot where the terminfo is. Foot will set the environment variable TERMINFO to this value (with ${prefix} added). The value is relative to ${prefix}.

Note that there are several issues with this approach: https://codeberg.org/dnkl/foot/issues/695.

If left unset, foot will not set or modify TERMINFO.

-Dterminfo can be used to disable building the terminfo definitions in the meson build. It does not change the default value of TERM, and it does not disable TERMINFO, if -Dcustom-terminfo-install-location has been set. Use this if packaging the terminfo definitions in a separate package (and the build script isn't shared with the 'foot' package).

Example:

sh
meson --prefix=/usr -Dcustom-terminfo-install-location=lib/foot/terminfo

The above tells foot its terminfo definitions will be installed to /usr/lib/foot/terminfo. This is the value foot will set the TERMINFO environment variable to.

If -Dterminfo is enabled (the default), then the terminfo files will be built as part of the regular build process, and installed to the specified location.

Packagers may want to set -Dterminfo=disabled, and manually build and install the terminfo files instead.

Release build

Below are instructions for building foot either size optimized, performance optimized, or performance optimized using PGO.

PGO - Profile Guided Optimization - is a way to optimize a program better than -O3 can, and is done by compiling foot twice: first to generate an instrumented version which is used to run a payload that exercises the performance critical parts of foot, and then a second time to rebuild foot using the generated profiling data to guide optimization.

In addition to being faster, PGO builds also tend to be smaller than regular -O3 builds.

Size optimized

To optimize for size (i.e. produce a small binary):

sh
export CFLAGS="$CFLAGS -Os"
meson --buildtype=release --prefix=/usr -Db_lto=true ../..
ninja
ninja test
ninja install
Performance optimized, non-PGO

To do a regular, non-PGO build optimized for performance:

sh
export CFLAGS="$CFLAGS -O3"
meson --buildtype=release --prefix=/usr -Db_lto=true ../..
ninja
ninja test
ninja install

Use -O2 instead of -O3 if you prefer a slightly smaller (and slower!) binary.

Performance optimized, PGO

There are a lot more steps involved in a PGO build, and for this reason there are a number of helper scripts available.

pgo/pgo.sh is a standalone script that pieces together the other scripts in the pgo directory to do a complete PGO build. This script is intended to be used when doing manual builds.

Note that all "full" PGO builds (which auto will prefer, if possible) require LC_CTYPE to be set to an UTF-8 locale. This is not done automatically.

Example:

sh
cd foot
./pgo/pgo.sh auto . /tmp/foot-pgo-build-output

(run ./pgo/pgo.sh to get help on usage)

It supports a couple of different PGO builds; partial (covered in detail below), full (also covered in detail below), and (full) headless builds using Sway or cage.

Packagers may want to use it as inspiration, but may choose to support only a specific build type; e.g. full/headless with Sway.

To do a manual PGO build, instead of using the script(s) mentioned above, detailed instructions follows:

First, configure the build directory:

sh
export CFLAGS="$CFLAGS -O3"
meson --buildtype=release --prefix=/usr -Db_lto=true ../..

It is very important -O3 is being used here, as GCC-10.1.x and later have a regression where PGO with -O2 is much slower.

Clang users must add -Wno-ignored-optimization-argument to CFLAGS.

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

sh
meson configure -Db_pgo=generate
ninja
ninja test

Next, we need to actually generate the profiling data.

There are two ways to do this: a partial PGO build using a PGO helper binary, or a full PGO build by running the real foot binary. The latter has slightly better results (i.e. results in a faster binary), but must be run in a Wayland session.

A full PGO build also tends to be smaller than a partial build.

Partial PGO

This method uses a PGO helper binary that links against the VT parser only. It is similar to a mock test; it instantiates a dummy terminal instance and then directly calls the VT parser with stimuli.

It explicitly does not include the Wayland backend and as such, it does not require a running Wayland session. The downside is that not all code paths in foot is exercised. In particular, the rendering code is not. As a result, the final binary built using this method is slightly slower than when doing a full PGO build.

We will use the pgo binary along with input corpus generated by scripts/generate-alt-random-writes.py:

sh
./utils/xtgettcap
./footclient --version
./foot --version
tmp_file=$(mktemp)
../../scripts/generate-alt-random-writes \
    --rows=67 \
    --cols=135 \
    --scroll \
    --scroll-region \
    --colors-regular \
    --colors-bright \
    --colors-256 \
    --colors-rgb \
    --attr-bold \
    --attr-italic \
    --attr-underline \
    --sixel \
    ${tmp_file}
./pgo ${tmp_file} ${tmp_file} ${tmp_file}
rm ${tmp_file}

The first step, running ./foot --version and ./footclient --version etc, might seem unnecessary, but is needed to ensure we have some profiling data for functions not covered by the PGO helper binary, for all binaries. Without this, the final link phase will fail.

The snippet above then creates an (empty) temporary file. Then, it runs a script that generates random escape sequences (if you cat ${tmp_file} in a terminal, you'll see random colored characters all over the screen). Finally, we feed the randomly generated escape sequences to the PGO helper. This is what generates the profiling data used in the next step.

You are now ready to use the generated PGO data.

Full PGO

This method requires a running Wayland session.

We will use the script scripts/generate-alt-random-writes.py:

sh
./utils/xtgettcap
./footclient --version
foot_tmp_file=$(mktemp)
./foot \
    --config=/dev/null \
    --override tweak.grapheme-shaping=no \
    --term=xterm \
    sh -c "<path-to-generate-alt-random-writes.py> --scroll --scroll-region --colors-regular --colors-bright --colors-256 --colors-rgb --attr-bold --attr-italic --attr-underline --sixel ${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.

The first step, ./utils/xtgettcap && ./footclient --version might seem unnecessary, but is needed to ensure we have some profiling data for all binaries we build. Without this, the final link phase will fail.

Use the generated PGO data

Now that we have generated PGO data, we need to rebuild foot. This time telling meson (and ultimately gcc/clang) to use the PGO data.

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

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

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

sh
meson configure -Db_pgo=use
ninja
ninja test

Continue reading in Running the new build

Debug build

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

Terminfo

By default, building foot also builds the terminfo files. If packaging the terminfo files in a separate package, it might be easier to simply disable the terminfo files in the regular build, and compile the terminfo files manually instead.

To build the terminfo files, run:

sh
sed 's/@default_terminfo@/foot/g' foot.info | \
    tic -o <output-directory> -x -e foot,foot-direct -

Where "output-directory" must match the value passed to -Dcustom-terminfo-install-location in the foot build. If -Dcustom-terminfo-install-location has not been set, -o <output-directory> can simply be omitted.

Or, if packaging:

sh
tic -o ${DESTDIR}/usr/share/terminfo ...

Running the new build

You can now run it directly from the build directory:

sh
./foot

Or, if you did not install the terminfo definitions:

sh
./foot --term xterm-256color
1# Installing
31. [Overview](#overview)
41. [Requirements](#requirements)
5 1. [Running](#running)
6 1. [Building](#building)
71. [Other](#other)
8 1. [Setup](#setup)
9 1. [Options](#options)
10 1. [Release build](#release-build)
11 1. [Size optimized](#size-optimized)
12 1. [Performance optimized, non-PGO](#performance-optimized-non-pgo)
13 1. [Performance optimized, PGO](#performance-optimized-pgo)
14 1. [Partial PGO](#partial-pgo)
15 1. [Full PGO](#full-pgo)
16 1. [Use the generated PGO data](#use-the-generated-pgo-data)
17 1. [Profile Guided Optimization](#profile-guided-optimization)
18 1. [Debug build](#debug-build)
19 1. [Terminfo](#terminfo)
20 1. [Running the new build](#running-the-new-build)
23## Overview
25foot makes use of a couple of libraries I have developed:
26[tllist](https://codeberg.org/dnkl/tllist) and
27[fcft](https://codeberg.org/dnkl/fcft). As such, they will most likely
28not have been installed already. You can either install them as system
29libraries or build them as _subprojects_ in foot.
31When building foot, they will first be searched for as system
32libraries. If **found**, foot will link dynamically against them.
33If **not** found, meson will attempt to download and build them as
34subprojects.
37## Requirements
39### Running
41* UTF-8 locale
42* fontconfig
43* freetype
44* pixman
45* wayland (_client_ and _cursor_ libraries)
46* xkbcommon
47* utf8proc (_optional_, needed for grapheme clustering)
48* libutempter (_optional_, needed for utmp logging on Linux)
49* ulog (_optional_, needed for utmp logging on FreeBSD)
50* [fcft](https://codeberg.org/dnkl/fcft) [^1]
52[^1]: can also be built as subprojects, in which case they are
53 statically linked.
55If you are packaging foot, you may also want to consider adding the
56following **optional** dependencies:
58* libnotify: desktop notifications by default uses `notify-send`.
59* xdg-utils: URLs are by default launched with `xdg-open`.
60* bash-completion: If you want completion for positional arguments.
62### Building
64In addition to the dev variant of the packages above, you need:
66* meson
67* ninja
68* wayland protocols
69* ncurses (needed to generate terminfo)
70* scdoc (for man page generation, not needed if documentation is disabled)
71* llvm (for PGO builds with Clang)
72* [tllist](https://codeberg.org/dnkl/tllist) [^1]
73* systemd (optional, foot will install systemd unit files if detected)
75A note on compilers; in general, foot runs **much** faster when
76compiled with gcc instead of clang. A profile-guided gcc build can be
77more than twice as fast as a clang build.
79**Note** GCC 10.1 has a performance regression that severely affects
80foot when doing PGO builds and building with `-O2`; it is about 30-40%
81slower compared to GCC 9.3.
83The work around is simple: make sure you build with `-O3`. This is the
84default with `meson --buildtype=release`, but e.g. `makepkg` can
85override it (`makepkg` uses `-O2` by default).
87## Other
89Foot uses _meson_. If you are unfamiliar with it, the official
90[tutorial](https://mesonbuild.com/Tutorial.html) might be a good
91starting point.
93A note on terminfo; the terminfo database exposes terminal
94capabilities to the applications running inside the terminal. As such,
95it is important that the terminfo used reflects the actual
96terminal. Using the `xterm-256color` terminfo will, in many cases,
97work, but I still recommend using foot's own terminfo. There are two
98reasons for this:
100* foot's terminfo contains a couple of non-standard capabilities,
101 used by e.g. tmux.
102* New capabilities added to the `xterm-256color` terminfo could
103 potentially break foot.
104* There may be future additions or changes to foot's terminfo.
106As of ncurses 2021-07-31, ncurses includes a version of foot's
107terminfo. **The recommendation is to use those**, and only install the
108terminfo definitions from this git repo if the system's ncurses
109predates 2021-07-31.
111But, note that the foot terminfo definitions in ncurses' lack the
112non-standard capabilities. This mostly affects tmux; without them,
113`terminal-overrides` must be configured to enable truecolor
114support. For this reason, it _is_ possible to install "our" terminfo
115definitions as well, either in a non-default location, or under a
116different name.
118Both have their set of issues. When installing to a non-default
119location, foot will set the environment variable `TERMINFO` in the
120child process. However, there are many situations where this simply
121does not work. See https://codeberg.org/dnkl/foot/issues/695 for
122details.
124Installing them under a different name generally works well, but will
125break applications that check if `$TERM == foot`.
127Hence the recommendation to simply use ncurses' terminfo definitions
128if available.
130If packaging "our" terminfo definitions, I recommend doing that as a
131separate package, to allow them to be installed on remote systems
132without having to install foot itself.
135### Setup
137To build, first, create a build directory, and switch to it:
138```sh
139mkdir -p bld/release && cd bld/release
140```
142### Options
144Available compile-time options:
146| Option | Type | Default | Description | Extra dependencies |
147|--------------------------------------|---------|-------------------------|---------------------------------------------------------------------------------|---------------------|
148| `-Ddocs` | feature | `auto` | Builds and install documentation | scdoc |
149| `-Dtests` | bool | `true` | Build tests (adds a `ninja test` build target) | None |
150| `-Dime` | bool | `true` | Enables IME support | None |
151| `-Dgrapheme-clustering` | feature | `auto` | Enables grapheme clustering | libutf8proc |
152| `-Dterminfo` | feature | `enabled` | Build and install terminfo files | tic (ncurses) |
153| `-Ddefault-terminfo` | string | `foot` | Default value of `TERM` | None |
154| `-Dterminfo-base-name` | string | `-Ddefault-terminfo` | Base name of the generated terminfo files | None |
155| `-Dcustom-terminfo-install-location` | string | `${datadir}/terminfo` | Value to set `TERMINFO` to | None |
156| `-Dsystemd-units-dir` | string | `${systemduserunitdir}` | Where to install the systemd service files (absolute) | None |
157| `-Dutmp-backend` | combo | `auto` | Which utmp backend to use (`none`, `libutempter`, `ulog` or `auto`) | libutempter or ulog |
158| `-Dutmp-default-helper-path` | string | `auto` | Default path to utmp helper binary. `auto` selects path based on `utmp-backend` | None |
160Documentation includes the man pages, readme, changelog and license
161files.
163`-Ddefault-terminfo`: I strongly recommend leaving the default
164value. Use this option if you plan on installing the terminfo files
165under a different name. Setting this changes the default value of
166`$TERM`, and the names of the terminfo files (if
167`-Dterminfo=enabled`).
169If you want foot to use the terminfo files from ncurses, but still
170package foot's own terminfo files under a different name, you can use
171the `-Dterminfo-base-name` option. Many distributions use the name
172`foot-extra`, and thus it might be a good idea to reuse that:
174```sh
175meson ... -Ddefault-terminfo=foot -Dterminfo-base-name=foot-extra
176```
177(or just leave out `-Ddefault-terminfo`, since it defaults to `foot` anyway).
179Finally, `-Dcustom-terminfo-install-location` enables foot's terminfo
180to co-exist with ncurses' version, without changing the terminfo
181names. The idea is that you install foot's terminfo to a non-standard
182location, for example `/usr/share/foot/terminfo`. Use
183`-Dcustom-terminfo-install-location` to tell foot where the terminfo
184is. Foot will set the environment variable `TERMINFO` to this value
185(with `${prefix}` added). The value is **relative to ${prefix}**.
187Note that there are several issues with this approach:
188https://codeberg.org/dnkl/foot/issues/695.
190If left unset, foot will **not** set or modify `TERMINFO`.
192`-Dterminfo` can be used to disable building the terminfo definitions
193in the meson build. It does **not** change the default value of
194`TERM`, and it does **not** disable `TERMINFO`, if
195`-Dcustom-terminfo-install-location` has been set. Use this if
196packaging the terminfo definitions in a separate package (and the
197build script isn't shared with the 'foot' package).
199Example:
201```sh
202meson --prefix=/usr -Dcustom-terminfo-install-location=lib/foot/terminfo
203```
205The above tells foot its terminfo definitions will be installed to
206`/usr/lib/foot/terminfo`. This is the value foot will set the
207`TERMINFO` environment variable to.
209If `-Dterminfo` is enabled (the default), then the terminfo files will
210be built as part of the regular build process, and installed to the
211specified location.
213Packagers may want to set `-Dterminfo=disabled`, and manually build
214and [install the terminfo](#terminfo) files instead.
217### Release build
219Below are instructions for building foot either [size
220optimized](#size-optimized), [performance
221optimized](performance-optimized-non-pgo), or performance
222optimized using [PGO](#performance-optimized-pgo).
224PGO - _Profile Guided Optimization_ - is a way to optimize a program
225better than `-O3` can, and is done by compiling foot twice: first to
226generate an instrumented version which is used to run a payload that
227exercises the performance critical parts of foot, and then a second
228time to rebuild foot using the generated profiling data to guide
229optimization.
231In addition to being faster, PGO builds also tend to be smaller than
232regular `-O3` builds.
235#### Size optimized
237To optimize for size (i.e. produce a small binary):
239```sh
240export CFLAGS="$CFLAGS -Os"
241meson --buildtype=release --prefix=/usr -Db_lto=true ../..
242ninja
243ninja test
244ninja install
245```
247#### Performance optimized, non-PGO
249To do a regular, non-PGO build optimized for performance:
251```sh
252export CFLAGS="$CFLAGS -O3"
253meson --buildtype=release --prefix=/usr -Db_lto=true ../..
254ninja
255ninja test
256ninja install
257```
259Use `-O2` instead of `-O3` if you prefer a slightly smaller (and
260slower!) binary.
263#### Performance optimized, PGO
265There are a lot more steps involved in a PGO build, and for this
266reason there are a number of helper scripts available.
268`pgo/pgo.sh` is a standalone script that pieces together the other
269scripts in the `pgo` directory to do a complete PGO build. This script
270is intended to be used when doing manual builds.
272Note that all "full" PGO builds (which `auto` will prefer, if
273possible) **require** `LC_CTYPE` to be set to an UTF-8 locale. This is
274**not** done automatically.
276Example:
278```sh
279cd foot
280./pgo/pgo.sh auto . /tmp/foot-pgo-build-output
281```
283(run `./pgo/pgo.sh` to get help on usage)
285It supports a couple of different PGO builds; partial (covered in
286detail below), full (also covered in detail below), and (full)
287headless builds using Sway or cage.
289Packagers may want to use it as inspiration, but may choose to support
290only a specific build type; e.g. full/headless with Sway.
292To do a manual PGO build, instead of using the script(s) mentioned
293above, detailed instructions follows:
295First, configure the build directory:
297```sh
298export CFLAGS="$CFLAGS -O3"
299meson --buildtype=release --prefix=/usr -Db_lto=true ../..
300```
302It is **very** important `-O3` is being used here, as GCC-10.1.x and
303later have a regression where PGO with `-O2` is **much** slower.
305Clang users **must** add `-Wno-ignored-optimization-argument` to
306`CFLAGS`.
308Then, tell meson we want to _generate_ profiling data, and build:
310```sh
311meson configure -Db_pgo=generate
312ninja
313ninja test
314```
316Next, we need to actually generate the profiling data.
318There are two ways to do this: a [partial PGO build using a PGO
319helper](#partial-pgo) binary, or a [full PGO build](#full-pgo) by
320running the real foot binary. The latter has slightly better results
321(i.e. results in a faster binary), but must be run in a Wayland
322session.
324A full PGO build also tends to be smaller than a partial build.
327##### Partial PGO
329This method uses a PGO helper binary that links against the VT parser
330only. It is similar to a mock test; it instantiates a dummy terminal
331instance and then directly calls the VT parser with stimuli.
333It explicitly does **not** include the Wayland backend and as such, it
334does not require a running Wayland session. The downside is that not
335all code paths in foot is exercised. In particular, the **rendering**
336code is not. As a result, the final binary built using this method is
337slightly slower than when doing a [full PGO](#full-pgo) build.
339We will use the `pgo` binary along with input corpus generated by
340`scripts/generate-alt-random-writes.py`:
342```sh
343./utils/xtgettcap
344./footclient --version
345./foot --version
346tmp_file=$(mktemp)
347../../scripts/generate-alt-random-writes \
348 --rows=67 \
349 --cols=135 \
350 --scroll \
351 --scroll-region \
352 --colors-regular \
353 --colors-bright \
354 --colors-256 \
355 --colors-rgb \
356 --attr-bold \
357 --attr-italic \
358 --attr-underline \
359 --sixel \
360 ${tmp_file}
361./pgo ${tmp_file} ${tmp_file} ${tmp_file}
362rm ${tmp_file}
363```
365The first step, running `./foot --version` and `./footclient
366--version` etc, might seem unnecessary, but is needed to ensure we
367have _some_ profiling data for functions not covered by the PGO helper
368binary, for **all** binaries. Without this, the final link phase will
369fail.
371The snippet above then creates an (empty) temporary file. Then, it
372runs a script that generates random escape sequences (if you cat
373`${tmp_file}` in a terminal, you'll see random colored characters all
374over the screen). Finally, we feed the randomly generated escape
375sequences to the PGO helper. This is what generates the profiling data
376used in the next step.
378You are now ready to [use the generated PGO
379data](#use-the-generated-pgo-data).
382##### Full PGO
384This method requires a running Wayland session.
386We will use the script `scripts/generate-alt-random-writes.py`:
388```sh
389./utils/xtgettcap
390./footclient --version
391foot_tmp_file=$(mktemp)
392./foot \
393 --config=/dev/null \
394 --override tweak.grapheme-shaping=no \
395 --term=xterm \
396 sh -c "<path-to-generate-alt-random-writes.py> --scroll --scroll-region --colors-regular --colors-bright --colors-256 --colors-rgb --attr-bold --attr-italic --attr-underline --sixel ${foot_tmp_file} && cat ${foot_tmp_file}"
397rm ${foot_tmp_file}
398```
400You should see a foot window open up, with random colored text. The
401window should close after ~1-2s.
403The first step, `./utils/xtgettcap && ./footclient --version`
404might seem unnecessary, but is needed to ensure we have _some_
405profiling data for **all** binaries we build. Without this, the final
406link phase will fail.
409##### Use the generated PGO data
411Now that we have _generated_ PGO data, we need to rebuild foot. This
412time telling meson (and ultimately gcc/clang) to _use_ the PGO data.
414If using Clang, now do (this requires _llvm_ to have been installed):
416```sh
417llvm-profdata merge default_*profraw --output=default.profdata
418```
420Next, tell meson to _use_ the profile data we just generated, and rebuild:
422```sh
423meson configure -Db_pgo=use
424ninja
425ninja test
426```
428Continue reading in [Running the new build](#running-the-new-build)
431### Debug build
433```sh
434meson --buildtype=debug ../..
435ninja
436ninja test
437```
439### Terminfo
441By default, building foot also builds the terminfo files. If packaging
442the terminfo files in a separate package, it might be easier to simply
443disable the terminfo files in the regular build, and compile the
444terminfo files manually instead.
446To build the terminfo files, run:
448```sh
449sed 's/@default_terminfo@/foot/g' foot.info | \
450 tic -o <output-directory> -x -e foot,foot-direct -
451```
453Where _"output-directory"_ **must** match the value passed to
454`-Dcustom-terminfo-install-location` in the foot build. If
455`-Dcustom-terminfo-install-location` has not been set, `-o
456<output-directory>` can simply be omitted.
458Or, if packaging:
460```sh
461tic -o ${DESTDIR}/usr/share/terminfo ...
462```
465### Running the new build
467You can now run it directly from the build directory:
468```sh
469./foot
470```
472Or, if you did not install the terminfo definitions:
474```sh
475./foot --term xterm-256color
476```
Diagnostics5 git calls · 493 ms
CallStatusSizeTime0493 ms
discover200178 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=178
git.server.agent=git/2.56.1-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=178
git.pkt.payload.max=35
ls-refs20010 KiB474 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=421
git.response.bytes=10322
git.response.cache=EXPIRED
git.response.duration_ms=474
git.protocol.version=2
git.pkt.frames=108
git.pkt.data=107
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=10322
git.pkt.payload.max=106
git.ls_refs.count=107
git.ls_refs.head=refs/heads/master
fetchtree:0 · deepen 102009.3 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=9489
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=c0d2c3e95d74cb60526ff28aec9f34ee3df545e0
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=9489
git.pkt.payload.max=9389
git.sideband.band1.bytes=9389
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=10
git.pack.bytes=9389
git.pack.ofs_delta=0
git.pack.ref_delta=0
git.pack.chain.max=0
git.pack.trailer=de930681b6073ba5b599a0f956bfbd114762ad5a
git.pack.full=10
Open pack map
fetchcombine:blob:none+tree:2 · deepen 12008.6 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=8830
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=c0d2c3e95d74cb60526ff28aec9f34ee3df545e0
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=8830
git.pkt.payload.max=8730
git.sideband.band1.bytes=8730
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=14
git.pack.bytes=8730
git.fetch.wide.objects=14
git.fetch.wide.extra_bytes=9909
git.fetch.wide.blobs=0
fetch2005.9 KiB · hit16 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=16
git.response.bytes=6015
git.response.cache=HIT
git.response.duration_ms=16
git.fetch.wants=7df8d0b8375765462f3940862e35095aa104b0bf
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=6015
git.pkt.payload.max=5988
git.sideband.band1.bytes=5988
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://codeberg.org/dnkl/foot
Ref
refs/heads/master
Commit
c0d2c3e95d74cb60526ff28aec9f34ee3df545e0
cf-ray
a5e14d6378b5a140
Request
263e5cd7…
Protocol
v2 · sha1
Agent
git/2.56.1-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format