aboutsummaryrefslogtreecommitdiff
path: root/INSTALL.md
diff options
context:
space:
mode:
authorDaniel Eklöf <daniel@ekloef.se>2021-08-17 19:24:11 +0000
committerDaniel Eklöf <daniel@ekloef.se>2021-08-17 19:24:11 +0000
commitf4da46350e47d1094136b264d76fcf9caeb77a55 (patch)
treef0c8d8cd62ae26cb477fff7f89896aecf1a01d85 /INSTALL.md
parentterm: check visual-focus, not kbd-focus when enabling/disabling cursor blink (diff)
parentterminfo: install to $datadir/foot/terminfo by default, append to TERMINFO_DIRS (diff)
Merge branch 'terminfo-dirs'
Closes #671
Diffstat (limited to 'INSTALL.md')
-rw-r--r--INSTALL.md142
1 files changed, 109 insertions, 33 deletions
diff --git a/INSTALL.md b/INSTALL.md
index 1d0366c1..92cda14d 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -17,6 +17,7 @@
1. [Use the generated PGO data](#use-the-generated-pgo-data)
1. [Profile Guided Optimization](#profile-guided-optimization)
1. [Debug build](#debug-build)
+ 1. [Terminfo](#terminfo)
1. [Running the new build](#running-the-new-build)
@@ -116,6 +117,35 @@ 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.
+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.
+
+As of ncurses 2021-07-31, ncurses ships a version of foot’s
+terminfo. I still recommend building and installing the version
+shipped with foot, since:
+
+* It will be more up to date (and more importantly, guaranteed to
+ match the installed version of foot).
+* The ncurses version is missing several of the non-standard capabilities.
+
+Foot’s terminfo will by default be built, and installed along with
+foot itself. This can be disabled (for example, to simplify packaging
+when the terminfo definitions are packaged in a separate
+package). Instructions on how to do so is in [terminfo](#terminfo).
+
+I recommend packaging foot’s terminfo files in a separate package, to
+allow them to be installed on remote systems without having to install
+foot itself.
+
### Setup
@@ -128,38 +158,64 @@ mkdir -p bld/release && cd bld/release
Available compile-time options:
-| Option | Type | Default | Description | Extra dependencies |
-|-------------------------------|---------|-----------------------|---------------------------------------|--------------------|
-| `-Ddocs` | feature | `auto` | Builds and install documentation | scdoc |
-| `-Dime` | bool | `true` | Enables IME support | None |
-| `-Dgrapheme-clustering` | feature | `auto` | Enables grapheme clustering | libutf8proc |
-| `-Dterminfo` | feature | `auto` | Build terminfo files | `tic` (ncurses) |
-| `-Dterminfo-install-location` | string | `${datadir}/terminfo` | Where to install the terminfo files | None |
+| Option | Type | Default | Description | Extra dependencies |
+|--------------------------------------|---------|----------------------------|---------------------------------------|--------------------|
+| `-Ddocs` | feature | `auto` | Builds and install documentation | scdoc |
+| `-Dime` | bool | `true` | Enables IME support | None |
+| `-Dgrapheme-clustering` | feature | `auto` | Enables grapheme clustering | libutf8proc |
+| `-Dterminfo` | feature | `enabled` | Build and install terminfo files | tic (ncurses) |
+| `-Ddefault-terminfo` | string | `foot` | Default value of `TERM` | none |
+| `-Dcustom-terminfo-install-location` | string | `${datadir}/foot/terminfo` | Value to append to `TERMINFO_DIRS` | None |
Documentation includes the man pages, the example `foot.ini`, readme,
changelog and license files.
-The two `terminfo` options are related, but control different aspects
-of how the terminfo files are built, installed and used.
+`-Ddefault-terminfo`: I strongly recommend leaving the default
+value. This option is meant to be used as a last resort on platforms
+where individual terminfo files cannot easily be installed.
+
+`-Dcustom-terminfo-install-location` enables foot’s terminfo to
+co-exist with ncurses’ version. 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 append this path to the
+`TERMINFO_DIRS` environment variable in the client application’s
+process. The value is **relative to ${prefix}**.
-`-Dterminfo` controls if the terminfo files should be generated _at
-all_. If disabled, foot’s hardcoded default terminfo is
-`xterm-256color` instead of `foot`.
+Conforming applications _should_ look in `TERMINFO_DIRS` first, and
+fallback to the builtin default (e.g. `/usr/share/terminfo`) if not
+found. Thus, it will prefer foot’s version, if it exists (which it
+typically will on localhost), and fallback to ncurses’ version if not
+(e.g. on remote systems, where foot’s terminfo package has not been
+installed).
-`-Dterminfo-install-location` controls _where_ the terminfo files are
-installed, relative to the installation prefix. The default is
-`${datadir}/terminfo`.
+If set to `no`, foot will **not** set or modify `TERMINFO_DIRS` at
+all. Use this if you do not intend to use/support foot’s terminfo
+definitions at all.
-It also recognizes the special value `disabled`, that prevents the
-terminfo files from being _installed_. They are still _built_, and
-foot’s hardcoded default terminfo is still `foot`. It is intended to
-be used when the terminfo files are packaged in a separate package
-(something I **highly** recommend distros do).
+`-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_DIRS`.
-To build the terminfo files manually, run
+Example:
```sh
-tic -x -o <output-directory> -e foot,foot-direct foot.info
+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 append to the
+`TERMINFO_DIRS` environment variable.
+
+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:
+
+```sh
+tic -o <output-directory> -x -e foot,foot-direct foot.info
```
@@ -347,6 +403,35 @@ 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
+tic -o <output-directory> -x -e foot,foot-direct foot.info
+```
+
+Where _”output-directory”_ **must** match the value passed to
+`-Dcustom-terminfo-install-location` in the foot build.
+
+To compile and install directly (assuming the default
+`-Dcustom-terminfo-install-location`):
+
+```sh
+sudo tic -o /usr/share/foot/terminfo ...
+```
+
+Or, if packaging:
+
+```sh
+tic -o ${DESTDIR}/usr/share/foot/terminfo ...
+```
+
### Running the new build
@@ -355,17 +440,8 @@ 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:
-```sh
-./foot --term xterm-256color
-```
+Or, if you did not install the terminfo definitions:
-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:
```sh
-ninja install
+./foot --term xterm-256color
```