mirror of
https://codeberg.org/dnkl/foot.git
synced 2026-02-05 04:06:08 -05:00
readme: move installation instructions to INSTALL.md
This commit is contained in:
Daniel Eklöf
parent
403b6bd323
commit
f418115bdf
2 changed files with 196 additions and 188 deletions
194
INSTALL.md
Normal file
194
INSTALL.md
Normal file
|
|
@ -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 "<path-to-generate-alt-ranodm-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):
|
||||
|
||||
```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
|
||||
```
|
||||
190
README.md
190
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 "<path-to-generate-alt-ranodm-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):
|
||||
|
||||
```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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue