diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..379fbc92 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,194 @@ +# Installing + +1. [Overview](#overview) +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) + + +## Overview + +foot makes use of a couple of libraries I have developed: +[tllist](https://codeberg.org/dnkl/tllist) and +[fcft](https://codeberg.org/dnkl/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](#other) below). + + +## Arch Linux + +Install from AUR: + +* [foot](https://aur.archlinux.org/packages/foot/) + + [foot-terminfo](https://aur.archlinux.org/packages/foot-terminfo/) +* [foot-git](https://aur.archlinux.org/packages/foot-git/) + + [foot-terminfo-git](https://aur.archlinux.org/packages/foot-terminfo-git/) + +Or use [makepkg](https://wiki.archlinux.org/index.php/Makepkg) to +build the bundled [PKGBUILD](PKGBUILD) (run `makepkg` in the source +root directory). + +Unlike the AUR packages, the bundled PKGBUILD **requires** +[tllist](https://codeberg.org/dnkl/tllist) and +[fcft](https://codeberg.org/dnkl/fcft) to be installed as system +libraries. If you do not want this, please edit the PKGBUILD file, or +install manually (see [Other](#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](https://mesonbuild.com/Tutorial.html) might be a good +starting point. + +I also recommend taking a look at the bundled Arch +[PKGBUILD](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](https://codeberg.org/dnkl/tllist) +and [fcft](https://codeberg.org/dnkl/fcft) as system libraries, clone +them into the `subprojects` directory: + +```sh +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: +```sh +mkdir -p bld/release && cd bld/release +``` + +### Release build + +```sh +export CFLAGS+="-O3 -march=native -fno-plt" +meson --buildtype=release --prefix=/usr -Db_lto=true +``` + +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. + +If you do not want this, just build: + +```sh +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, 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: + +```sh +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`: + +```sh +foot_tmp_file=$(mktemp) +./foot --config=/dev/null --term=xterm sh -c " --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): + +```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 +``` + +Continue reading in [Running the new build](#running-the-new-build) + +### Debug build + +```sh +meson --buildtype=debug ../.. +ninja +``` + +### Running the new build + +You can now run it directly from the build directory: +```sh +./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: +```sh +./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 is dependens on the distro), or +just install everything: +```sh +ninja install +``` diff --git a/README.md b/README.md index b131d2f2..4981632e 100644 --- a/README.md +++ b/README.md @@ -24,13 +24,6 @@ The fast, lightweight and minimalistic Wayland terminal emulator. 1. [Running](#running) 1. [Building](#building) 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. [Credits](#Credits) 1. [Bugs](#bugs) 1. [Mastodon](#mastodon) @@ -385,188 +378,9 @@ default with `meson --buildtype=release`, but e.g. `makepkg` can override it (`makepkg` uses `-O2` by default). -## Installing +# Installing -foot makes use of a couple of libraries I have developed: -[tllist](https://codeberg.org/dnkl/tllist) and -[fcft](https://codeberg.org/dnkl/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](#other) below). - - -### Arch Linux - -Install from AUR: - -* [foot](https://aur.archlinux.org/packages/foot/) + - [foot-terminfo](https://aur.archlinux.org/packages/foot-terminfo/) -* [foot-git](https://aur.archlinux.org/packages/foot-git/) + - [foot-terminfo-git](https://aur.archlinux.org/packages/foot-terminfo-git/) - -Or use [makepkg](https://wiki.archlinux.org/index.php/Makepkg) to -build the bundled [PKGBUILD](PKGBUILD) (run `makepkg` in the source -root directory). - -Unlike the AUR packages, the bundled PKGBUILD **requires** -[tllist](https://codeberg.org/dnkl/tllist) and -[fcft](https://codeberg.org/dnkl/fcft) to be installed as system -libraries. If you do not want this, please edit the PKGBUILD file, or -install manually (see [Other](#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](https://mesonbuild.com/Tutorial.html) might be a good -starting point. - -I also recommend taking a look at the bundled Arch -[PKGBUILD](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](https://codeberg.org/dnkl/tllist) -and [fcft](https://codeberg.org/dnkl/fcft) as system libraries, clone -them into the `subprojects` directory: - -```sh -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: -```sh -mkdir -p bld/release && cd bld/release -``` - -#### Release build - -```sh -export CFLAGS+="-O3 -march=native -fno-plt" -meson --buildtype=release --prefix=/usr -Db_lto=true -``` - -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. - -If you do not want this, just build: - -```sh -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, 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: - -```sh -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`: - -```sh -foot_tmp_file=$(mktemp) -./foot --config=/dev/null --term=xterm sh -c " --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): - -```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 -``` - -Continue reading in [Running the new build](#running-the-new-build) - -#### Debug build - -```sh -meson --buildtype=debug ../.. -ninja -``` - -#### Running the new build - -You can now run it directly from the build directory: -```sh -./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: -```sh -./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 is dependens on the distro), or -just install everything: -```sh -ninja install -``` +See [INSTALL.md](INSTALL.md). # Credits