aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Eklöf <daniel@ekloef.se>2020-05-30 08:46:22 +0000
committerDaniel Eklöf <daniel@ekloef.se>2020-05-30 08:46:22 +0000
commit1ba8de9ceead9baafcacdf87439407fcd6eeb315 (patch)
tree710a0b598e6ebafa59b08a1094e1e442e7667b75
parentrender: resize: don't try to signal TIOCSWINSZ on a closed ptmx FD (diff)
readme: describe how to do a PGO build
-rw-r--r--README.md95
1 files changed, 85 insertions, 10 deletions
diff --git a/README.md b/README.md
index 0035bd6d..0b80d72e 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,11 @@ The fast, lightweight and minimalistic Wayland terminal emulator.
1. [Installing](#installing)
1. [Arch Linux](#arch-linux)
1. [Other](#other)
+ 1. [Setup](#setup)
+ 1. [Release build](#release-build)
+ 1. [Profile Guided Optimization](#profile-guided-optimization)
+ 1. [Debug build](#debug-build)
+ 1. [Running the new build](#running-the-new-build)
1. [Bugs](#bugs)
@@ -378,6 +383,9 @@ I also recommend taking a look at the bundled Arch
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](https://codeberg.org/dnkl/tllist)
and [fcft](https://codeberg.org/dnkl/fcft) as system libraries, clone
them into the `subprojects` directory:
@@ -395,28 +403,95 @@ To build, first, create a build directory, and switch to it:
mkdir -p bld/release && cd bld/release
```
-Second, configure[^2] the build (suggested flags):
+#### Release build
+
```sh
-meson --buildtype=release --prefix=/usr \
- -Db_lto=true -Dc_args="-march=native -fno-plt" ../..
+export CFLAGS+="-O3 -march=native -fno-plt"
+meson --buildtype=release --prefix=/usr -Db_lto=true
```
-[^2]: for advanced users: a profile guided build will have
- significantly better performance; take a look at
- [PKDBUILD](PKGBUILD) to see how this can be done.
+For performance reasons, I strongly recommend doing a
+[PGO](#profile-guided-optimization) (Profile Guided Optimization)
+build. This requires a running Wayland session since we will be
+executing an intermediate build of foot.
-To instead do a debug build (for example, to be able to provide a
-meaningful backtrace when reporting a bug):
+If you do not want this, just build:
```sh
-meson --buildtype=debug ../..
+ninja
+```
+
+and then skip to [Running the new build](#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)[#profile-guided-optimization)
+build.
+
+
+##### Profile Guided Optimization
+
+First, make sure you have configured a [release](#release-build) build
+directory. If using Clang, make sure to add
+`-Wno-ignored-optimization-argument -Wno-profile-instr-out-of-date` to
+`CFLAGS`.
+
+Then, tell meson we want to _generate_ profile data:
+
+```sh
+meson configure -Db_pgo=generate
```
-Three, build it:
+Build an intermediate version of foot:
+
```sh
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`:
+
+```sh
+foot_tmp_file=$(mktemp)
+./foot --config=/dev/null --term=xterm sh -c "<path-to-generate-alt-ranodm-writes.py> --scroll --scroll-region --colors-regular --colors-bright --colors-rgb ${foot_tmp_file} && cat ${foot_tmp_file}"
+```
+
+If using Clang (if using GCC, just skip to the next step), 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
+```
+
+
+#### Debug build
+
+```sh
+meson --buildtype=debug ../..
+ninja
+```
+
+#### Running the new build
+
You can now run it directly from the build directory:
```sh
./foot