From 6dbd87016fc9f86c1681c3c438dbaeb7065b370b Mon Sep 17 00:00:00 2001 From: Daniel Eklöf Date: Thu, 27 Aug 2020 19:48:13 +0200 Subject: config: prefer loading configuration from $XDG_CONFIG_HOME/foot/foot.ini --- config.c | 260 ++++++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 217 insertions(+), 43 deletions(-) diff --git a/config.c b/config.c index 8a7a3476..c1f59b6c 100644 --- a/config.c +++ b/config.c @@ -6,11 +6,13 @@ #include #include #include -#include -#include -#include #include #include +#include +#include + +#include +#include #include #include @@ -161,50 +163,210 @@ get_shell(void) return xstrdup(shell); } -static char * -get_config_path_user_config(void) +struct config_file { + char *path; /* Full, absolute, path */ + int fd; /* FD of file, O_RDONLY */ +}; + +struct path_component { + const char *component; + int fd; +}; +typedef tll(struct path_component) path_components_t; + +static void +path_component_add(path_components_t *components, const char *comp, int fd) { - struct passwd *passwd = getpwuid(getuid()); - if (passwd == NULL) { - LOG_ERRNO("failed to lookup user"); - return NULL; + assert(comp != NULL); + assert(fd >= 0); + + struct path_component pc = {.component = comp, .fd = fd}; + tll_push_back(*components, pc); +} + +static void +path_component_destroy(struct path_component *component) +{ + assert(component->fd >= 0); + close(component->fd); +} + +static void +path_components_destroy(path_components_t *components) +{ + tll_foreach(*components, it) { + path_component_destroy(&it->item); + tll_remove(*components, it); + } +} + +static struct config_file +path_components_to_config_file(const path_components_t *components) +{ + if (tll_length(*components) == 0) + goto err; + + size_t len = 0; + tll_foreach(*components, it) + len += strlen(it->item.component) + 1; + + char *path = malloc(len); + if (path == NULL) + goto err; + + size_t idx = 0; + tll_foreach(*components, it) { + strcpy(&path[idx], it->item.component); + idx += strlen(it->item.component); + path[idx++] = '/'; } + path[idx - 1] = '\0'; /* Strip last ’/’ */ - const char *home_dir = passwd->pw_dir; - LOG_DBG("user's home directory: %s", home_dir); + int fd_copy = dup(tll_back(*components).fd); + if (fd_copy < 0) { + free(path); + goto err; + } - char *path = xasprintf("%s/.config/footrc", home_dir); - return path; + return (struct config_file){.path = path, .fd = fd_copy}; + +err: + return (struct config_file){.path = NULL, .fd = -1}; } -static char * -get_config_path_xdg(void) +static const char * +get_user_home_dir(void) { - const char *xdg_config_home = getenv("XDG_CONFIG_HOME"); - if (xdg_config_home == NULL) + const struct passwd *passwd = getpwuid(getuid()); + if (passwd == NULL) return NULL; - - char *path = xasprintf("%s/footrc", xdg_config_home); - return path; + return passwd->pw_dir; } -static char * -get_config_path(void) +static bool +try_open_file(path_components_t *components, const char *name) { + int parent_fd = tll_back(*components).fd; + struct stat st; + if (fstatat(parent_fd, name, &st, 0) == 0 && S_ISREG(st.st_mode)) { + int fd = openat(parent_fd, name, O_RDONLY); + if (fd >= 0) { + path_component_add(components, name, fd); + return true; + } + } + + return false; +} + +static struct config_file +open_config(struct config *conf) +{ + struct config_file ret = {.path = NULL, .fd = -1}; + bool log_deprecation = false; + + path_components_t components = tll_init(); + + const char *xdg_config_home = getenv("XDG_CONFIG_HOME"); + const char *user_home_dir = get_user_home_dir(); + char *xdg_config_dirs_copy = NULL; + + /* Use XDG_CONFIG_HOME, or ~/.config */ + if (xdg_config_home != NULL) { + int fd = open(xdg_config_home, O_RDONLY); + if (fd >= 0) + path_component_add(&components, xdg_config_home, fd); + } else if (user_home_dir != NULL) { + int home_fd = open(user_home_dir, O_RDONLY); + if (home_fd >= 0) { + int config_fd = openat(home_fd, ".config", O_RDONLY); + if (config_fd >= 0) { + path_component_add(&components, user_home_dir, home_fd); + path_component_add(&components, ".config", config_fd); + } else + close(home_fd); + } + } + + /* First look for foot/foot.ini */ + if (tll_length(components) > 0) { + int foot_fd = openat(tll_back(components).fd, "foot", O_RDONLY); + if (foot_fd >= 0) { + path_component_add(&components, "foot", foot_fd); + + if (try_open_file(&components, "foot.ini")) + goto done; + + struct path_component pc = tll_pop_back(components); + path_component_destroy(&pc); + } + } + + /* Next try footrc */ + if (tll_length(components) > 0 && try_open_file(&components, "footrc")) { + log_deprecation = true; + goto done; + } + + /* Finally, try foot/foot.ini in all XDG_CONFIG_DIRS */ + const char *xdg_config_dirs = getenv("XDG_CONFIG_DIRS"); + xdg_config_dirs_copy = xdg_config_dirs != NULL + ? strdup(xdg_config_dirs) : NULL; + + if (xdg_config_dirs_copy != NULL) { + for (char *save = NULL, + *xdg_dir = strtok_r(xdg_config_dirs_copy, ":", &save); + xdg_dir != NULL; + xdg_dir = strtok_r(NULL, ":", &save)) + { + path_components_destroy(&components); + + int xdg_fd = open(xdg_dir, O_RDONLY); + if (xdg_fd < 0) + continue; - char *config = get_config_path_xdg(); - if (config != NULL && stat(config, &st) == 0 && S_ISREG(st.st_mode)) - return config; - free(config); + int foot_fd = openat(xdg_fd, "foot", O_RDONLY); + if (foot_fd < 0) { + close(xdg_fd); + continue; + } + + assert(tll_length(components) == 0); + path_component_add(&components, xdg_dir, xdg_fd); + path_component_add(&components, "foot", foot_fd); + + if (try_open_file(&components, "foot.ini")) + goto done; + } + } + +out: + path_components_destroy(&components); + free(xdg_config_dirs_copy); + return ret; + +done: + assert(tll_length(components) > 0); + ret = path_components_to_config_file(&components); + + if (log_deprecation && ret.path != NULL) { + LOG_WARN("deprecated: configuration in $XDG_CONFIG_HOME/footrc, " + "use $XDG_CONFIG_HOME/foot/foot.ini instead"); - /* 'Default' XDG_CONFIG_HOME */ - config = get_config_path_user_config(); - if (config != NULL && stat(config, &st) == 0 && S_ISREG(st.st_mode)) - return config; - free(config); + char *text = xstrdup( + "configuration in \033[31m$XDG_CONFIG_HOME/footrc\033[39m or " + "\033[31m~/.config/footrc\033[39m, " + "use \033[32m$XDG_CONFIG_HOME/foot/foot.ini\033[39m or " + "\033[32m~/.config/foot/foot.ini\033[39m instead"); - return NULL; + struct user_notification deprecation = { + .kind = USER_NOTIFICATION_DEPRECATED, + .text = text, + }; + tll_push_back(conf->notifications, deprecation); + } + goto out; } static bool @@ -1644,24 +1806,33 @@ config_load(struct config *conf, const char *conf_path, bool errors_are_fatal) add_default_search_bindings(conf); add_default_mouse_bindings(conf); - char *default_path = NULL; - if (conf_path == NULL) { - if ((default_path = get_config_path()) == NULL) { - /* Default conf */ - LOG_AND_NOTIFY_WARN("no configuration found, using defaults"); + struct config_file conf_file = {.path = NULL, .fd = -1}; + if (conf_path != NULL) { + int fd = open(conf_path, O_RDONLY); + if (fd < 0) { + LOG_AND_NOTIFY_ERRNO("%s: failed to open", conf_path); ret = !errors_are_fatal; goto out; } - conf_path = default_path; + conf_file.path = xstrdup(conf_path); + conf_file.fd = fd; + } else { + conf_file = open_config(conf); + if (conf_file.fd < 0) { + LOG_AND_NOTIFY_ERR("no configuration found, using defaults"); + ret = !errors_are_fatal; + goto out; + } } - assert(conf_path != NULL); - LOG_INFO("loading configuration from %s", conf_path); + assert(conf_file.path != NULL); + assert(conf_file.fd >= 0); + LOG_INFO("loading configuration from %s", conf_file.path); - FILE *f = fopen(conf_path, "r"); + FILE *f = fdopen(conf_file.fd, "r"); if (f == NULL) { - LOG_AND_NOTIFY_ERR("%s: failed to open", conf_path); + LOG_AND_NOTIFY_ERRNO("%s: failed to open", conf_file.path); ret = !errors_are_fatal; goto out; } @@ -1677,7 +1848,10 @@ out: if (ret && tll_length(conf->fonts) == 0) tll_push_back(conf->fonts, config_font_parse("monospace")); - free(default_path); + free(conf_file.path); + if (conf_file.fd < 0) + close(conf_file.fd); + return ret; } -- cgit v1.3 From 865127d836e6bea2459ab4eaa18d25f082ebed9a Mon Sep 17 00:00:00 2001 From: Daniel Eklöf Date: Thu, 27 Aug 2020 19:48:48 +0200 Subject: footrc: move to foot.ini --- foot.ini | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ footrc | 101 --------------------------------------------------------------- 2 files changed, 101 insertions(+), 101 deletions(-) create mode 100644 foot.ini delete mode 100644 footrc diff --git a/foot.ini b/foot.ini new file mode 100644 index 00000000..207ee657 --- /dev/null +++ b/foot.ini @@ -0,0 +1,101 @@ +# -*- conf -*- + +# font=monospace +# geometry=700x500 +# pad=2x2 +# initial-window-mode=windowed +# shell=$SHELL (if set, otherwise user's default shell from /etc/passwd) +# term=foot +# login-shell=no +# workers= + +[scrollback] +# lines=1000 +# multiplier=1.0 +# indicator-position=relative +# indicator-format= + +[cursor] +# style=block +# color=111111 dcdccc +# blink=no + +[mouse] +# hide-when-typing=no + +[colors] +# alpha=1.0 +# foreground=dcdccc +# background=111111 +# regular0=222222 # black +# regular1=cc9393 # red +# regular2=7f9f7f # green +# regular3=d0bf8f # yellow +# regular4=6ca0a3 # blue +# regular5=dc8cc3 # magenta +# regular6=93e0e3 # cyan +# regular7=dcdccc # white +# bright0=666666 # bright black +# bright1=dca3a3 # bright red +# bright2=bfebbf # bright green +# bright3=f0dfaf # bright yellow +# bright4=8cd0d3 # bright blue +# bright5=fcace3 # bright magenta +# bright6=b3ffff # bright cyan +# bright7=ffffff # bright white +# selection-foreground= +# selection-background= + +[csd] +# preferred=server +# size=26 +# color= +# button-width=26 +# button-minimize-color=ff0000ff +# button-maximize-color=ff00ff00 +# button-close-color=ffff0000 + +[key-bindings] +# scrollback-up=Shift+Page_Up +# scrollback-down=Shift+Page_Down +# clipboard-copy=Control+Shift+C +# clipboard-paste=Control+Shift+V +# search-start=Control+Shift+R +# font-increase=Control+plus Control+equal Control+KP_Add +# font-decrease=Control+minus Control+KP_Subtract +# font-reset=Control+0 Control+KP_0 +# spawn-terminal=Control+Shift+N +# minimize=none +# maximize=none +# fullscreen=none +# pipe-visible=[sh -c "xurls | bemenu | xargs -r firefox"] none +# pipe-scrollback=[sh -c "xurls | bemenu | xargs -r firefox"] none +# pipe-selected=[xargs -r firefox] none + + +[search-bindings] +# cancel=Control+g Escape +# commit=Return +# find-prev=Control+r +# find-next=Control+s +# cursor-left=Left Control+b +# cursor-left-word=Control+Left Mod1+b +# cursor-right=Right Control+f +# cursor-right-word=Control+Right Mod1+f +# cursor-home=Home Control+a +# cursor-end=End Control+e +# delete-prev=BackSpace +# delete-prev-word=Mod1+BackSpace Control+BackSpace +# delete-next=Delete +# delete-next-word=Mod1+d Control+Delete +# extend-to-word-boundary=Control+w +# extend-to-next-whitespace=Control+Shift+W + +[mouse-bindings] +# primary-paste=BTN_MIDDLE +# select-begin=BTN_LEFT +# select-begin-block=Control+BTN_LEFT +# select-extend=BTN_RIGHT +# select-word=BTN_LEFT-2 +# select-word-whitespace=Control+BTN_LEFT-2 +# select-row=BTN_LEFT-3 diff --git a/footrc b/footrc deleted file mode 100644 index 207ee657..00000000 --- a/footrc +++ /dev/null @@ -1,101 +0,0 @@ -# -*- conf -*- - -# font=monospace -# geometry=700x500 -# pad=2x2 -# initial-window-mode=windowed -# shell=$SHELL (if set, otherwise user's default shell from /etc/passwd) -# term=foot -# login-shell=no -# workers= - -[scrollback] -# lines=1000 -# multiplier=1.0 -# indicator-position=relative -# indicator-format= - -[cursor] -# style=block -# color=111111 dcdccc -# blink=no - -[mouse] -# hide-when-typing=no - -[colors] -# alpha=1.0 -# foreground=dcdccc -# background=111111 -# regular0=222222 # black -# regular1=cc9393 # red -# regular2=7f9f7f # green -# regular3=d0bf8f # yellow -# regular4=6ca0a3 # blue -# regular5=dc8cc3 # magenta -# regular6=93e0e3 # cyan -# regular7=dcdccc # white -# bright0=666666 # bright black -# bright1=dca3a3 # bright red -# bright2=bfebbf # bright green -# bright3=f0dfaf # bright yellow -# bright4=8cd0d3 # bright blue -# bright5=fcace3 # bright magenta -# bright6=b3ffff # bright cyan -# bright7=ffffff # bright white -# selection-foreground= -# selection-background= - -[csd] -# preferred=server -# size=26 -# color= -# button-width=26 -# button-minimize-color=ff0000ff -# button-maximize-color=ff00ff00 -# button-close-color=ffff0000 - -[key-bindings] -# scrollback-up=Shift+Page_Up -# scrollback-down=Shift+Page_Down -# clipboard-copy=Control+Shift+C -# clipboard-paste=Control+Shift+V -# search-start=Control+Shift+R -# font-increase=Control+plus Control+equal Control+KP_Add -# font-decrease=Control+minus Control+KP_Subtract -# font-reset=Control+0 Control+KP_0 -# spawn-terminal=Control+Shift+N -# minimize=none -# maximize=none -# fullscreen=none -# pipe-visible=[sh -c "xurls | bemenu | xargs -r firefox"] none -# pipe-scrollback=[sh -c "xurls | bemenu | xargs -r firefox"] none -# pipe-selected=[xargs -r firefox] none - - -[search-bindings] -# cancel=Control+g Escape -# commit=Return -# find-prev=Control+r -# find-next=Control+s -# cursor-left=Left Control+b -# cursor-left-word=Control+Left Mod1+b -# cursor-right=Right Control+f -# cursor-right-word=Control+Right Mod1+f -# cursor-home=Home Control+a -# cursor-end=End Control+e -# delete-prev=BackSpace -# delete-prev-word=Mod1+BackSpace Control+BackSpace -# delete-next=Delete -# delete-next-word=Mod1+d Control+Delete -# extend-to-word-boundary=Control+w -# extend-to-next-whitespace=Control+Shift+W - -[mouse-bindings] -# primary-paste=BTN_MIDDLE -# select-begin=BTN_LEFT -# select-begin-block=Control+BTN_LEFT -# select-extend=BTN_RIGHT -# select-word=BTN_LEFT-2 -# select-word-whitespace=Control+BTN_LEFT-2 -# select-row=BTN_LEFT-3 -- cgit v1.3 From f7c29408804bc276ae01914947a84fd85e92e5ce Mon Sep 17 00:00:00 2001 From: Daniel Eklöf Date: Thu, 27 Aug 2020 19:50:07 +0200 Subject: readme: update references to the configuration file --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 41c6854a..6dcd8fe6 100644 --- a/README.md +++ b/README.md @@ -54,11 +54,12 @@ See [INSTALL.md](INSTALL.md). ## Configuration **foot** can be configured by creating a file -`$XDG_CONFIG_HOME/footrc` (defaulting to `~/.config/footrc`). A -template for that can usually be found in `/usr/share/foot/footrc` or -[here](https://codeberg.org/dnkl/foot/src/branch/master/footrc). +`$XDG_CONFIG_HOME/foot/foot.ini` (defaulting to +`~/.config/foot/foot.ini`). A template for that can usually be found +in `/usr/share/foot/foot.ini;9~` or +[here](https://codeberg.org/dnkl/foot/src/branch/master/foot.ini). -Further information can be found in foot's man page `footrc(5)`. +Further information can be found in foot's man page `foot.ini(5)`. ## Troubleshooting @@ -104,8 +105,8 @@ fonts, _then_ fontconfig's list is used. ## Shortcuts -These are the default shortcuts. See `man 5 foot` and the example -`footrc` to see how these can be changed. +These are the default shortcuts. See `man foot.ini` and the example +`foot.ini` to see how these can be changed. ### Keyboard -- cgit v1.3 From 5c4af880fc62ee509015c28eb0b4c395b956081d Mon Sep 17 00:00:00 2001 From: Daniel Eklöf Date: Thu, 27 Aug 2020 20:02:30 +0200 Subject: doc: rename footrc.5 to foot.ini.5, and update references --- doc/foot.1.scd | 9 +- doc/foot.ini.5.scd | 557 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/footrc.5.scd | 554 ---------------------------------------------------- doc/meson.build | 11 +- meson.build | 2 +- 5 files changed, 569 insertions(+), 564 deletions(-) create mode 100644 doc/foot.ini.5.scd delete mode 100644 doc/footrc.5.scd diff --git a/doc/foot.1.scd b/doc/foot.1.scd index eb2213d6..19e1b0ee 100644 --- a/doc/foot.1.scd +++ b/doc/foot.1.scd @@ -23,7 +23,8 @@ the foot command line # OPTIONS *-c*,*--config*=_PATH_ - Path to configuration file. Default: *$XDG_CONFIG_HOME/footrc*. + Path to configuration file. Default: + *$XDG_CONFIG_HOME/foot/foot.ini*. *--check-config* Verify configuration and then exit with 0 if ok, otherwise exit @@ -131,7 +132,7 @@ The following keyboard shortcuts are available. ## NORMAL MODE Note that these are just the defaults; they can be changed in -*footrc*, see *footrc*(5). +*foot.ini*, see *foot.ini*(5). *shift*+*page up*/*page down* Scroll up/down in history @@ -253,7 +254,7 @@ Finally, pressing *alt* will prefix the transmitted byte with ESC. # CONFIGURATION -See *footrc*(5) +See *foot.ini*(5) # BUGS @@ -270,4 +271,4 @@ The report should contain the following: # SEE ALSO -*footrc*(5), *footclient*(1) +*foot.ini*(5), *footclient*(1) diff --git a/doc/foot.ini.5.scd b/doc/foot.ini.5.scd new file mode 100644 index 00000000..cede6e26 --- /dev/null +++ b/doc/foot.ini.5.scd @@ -0,0 +1,557 @@ +foot.ini(5) + +# NAME +foot.ini - configuration file + +# DESCRIPTION + +*foot* uses the standard _unix configuration format_, with section based +key/value pairs. The default section is unnamed (i.e. not prefixed +with a _[section]_). + +foot will search for a configuration file in the following locations, +in this order: + +- _XDG_CONFIG_HOME/foot/foot.ini_ +- _~/.config/foot/foot.ini_ +- _XDG_CONFIG_HOME/footrc_ +- _~/.config/footrc_ +- _XDG_CONFIG_DIRS/foot/foot.init_ + +# SECTION: default + +*font* + Comma separated list of fonts to use, in fontconfig format (see + *FONT FORMAT*). + + The first font is the primary font. The remaining fonts are + fallback fonts that will be used whenever a glyph cannot be found + in the primary font. + + The fallback fonts are searched in the order they appear. If a + glyph cannot be found in any of the fallback fonts, the dynamic + fallback list from fontconfig (for the primary font) is + searched. + + Default: _monospace_. + +*geometry* + Initial window width and height in pixels (subject to output + scaling), on the form _WIDTHxHEIGHT_. Default: _700x500_. + +*pad* + Padding between border and glyphs, in pixels (subject to output + scaling), on the form _XxY_. Default: _2x2_. + +*initial-window-mode* + Initial window mode for each newly spawned window: *windowed*, + *maximized* or *fullscreen*. Default: _windowed_. + +*shell* + Executable to launch. Typically a shell. Default: _$SHELL_ if set, + otherwise the user's default shell (as specified in + _/etc/passwd_). You can also pass arguments. For example + "/bin/bash --norc". + +*login-shell* + Boolean. If enabled, the shell will be launched as a login shell, + by prepending a '-' to argv[0]. Default: _no_. + +*term* + Value to set the environment variable *TERM* to. Default: _foot_. + +*title* + Initial window title. Default: _foot_. + +*app-id* + Value to set the *app-id* property on the Wayland window to. The + compositor can use this value to e.g. group multiple windows, or + apply window management rules. Default: _foot_. + +*workers* + Number of threads to use for rendering. Set to 0 to disable + multithreading. Default: the number of available logical CPUs + (including SMT). Note that this is not always the best value. In + some cases, the number of physical _cores_ is better. + + +# SECTION: scrollback + +*lines* + Number of scrollback lines. Default: _1000_. + +*multiplier* + Amount to multiply mouse scrolling with. It is a decimal number, + i.e. fractions are allowed. Default: _1.0_. + +*indicator-position* + Configures the style of the scrollback position indicator. One of + *none*, *fixed* or *relative*. *none* disables the indicator + completely. *fixed* always renders the indicator near the top at + the window, and *relative* renders the indicator at the position + corresponding to the current scrollback position. Default: + _relative_. + +*indicator-format* + Which format to use when displaying the scrollback position + indicator. Either _percentage_, _line_, or a custom fixed + string. This option is ignored if + *indicator-position=none*. Default: _empty string_. + + +# SECTION: cursor + +This section controls the cursor style and color. Note that +applications can change these at runtime. + +*style* + Configures the default cursor style, and is one of: _block_, _bar_ + or _underline_. Note that this can be overridden by + applications. Default: _block_. + +*blink* + Boolean. Enables blinking cursor. Note that this can be overridden + by applications. Default: _no_. + +*color* + Two RRGGBB values specifying the foreground (text) and background + (cursor) colors for the cursor. Default: inversed foreground and + background colors. Note that this value only applies to the block + cursor. The other cursor styles are always rendered with the + foreground color. + + +# SECTION: mouse + +*hide-when-typing* + Boolean. When enabled, the mouse cursor is hidden while typing. + + +# SECTION: colors + +This section controls the 16 ANSI colors and the default foreground +and background colors. Note that applications can change these at +runtime. + +The colors are in RRGGBB format. That is, they do *not* have an alpha +component. You can configure the background transparency with the +_alpha_ option. + +*foreground* + Default RRGGBB foreground color. This is the color used when no + ANSI color is being used. Default: _dcdccc_. + +*background* + Default RRGGBB background color. This is the color used when no + ANSI color is being used. Default: _111111_. + +*regular0*, *regular1* *..* *regular7* + The eight basic ANSI colors. Default: _222222_, _cc9393_, + _7f9f7f_, _d0bf8f_, _6ca0a3_, _dc8cc3_, _93e0e3_ and _dcdccc_ (a + variant of the _zenburn_ theme). + +*bright0*, *bright1* *..* *bright7* + The eight bright ANSI colors. Default: _666666_, _dca3a3_, + _bfebbf_, _f0dfaf_, _8cd0d3_, _fcace3_, _b3ffff_ and _ffffff_ (a + variant of the _zenburn_ theme). + +*alpha* + Background translucency. A value in the range 0.0-1.0, where 0.0 + means completely transparent, and 1.0 is opaque. Default: _1.0_. + +*selection-foreground*, *selection-background* + Foreground (text) and background color to use in selected + text. Note that *both* options must be set, or the default will be + used. Default: _inverse foreground/background_. + + +# SECTION: csd + +This section controls the look of the _CSDs_ (Client Side +Decorations). Note that the default is to *not* use CSDs, but instead +to use _SSDs_ (Server Side Decorations) when the compositor supports +it. + +Note that unlike the colors defined in the _colors_ section, the color +values here are in AARRGGBB format. I.e. they contain an alpha +component. + +*preferred* + Which type of window decorations to prefer: *client* (CSD) or + *server* (SSD). Note that this is only a hint to the + compositor. Depending on the compositor's configuration and + capabilities, it may not have any effect. Default: _server_. + +*size* + Height, in pixels (subject to output scaling), of the + titlebar. Default: _26_. + +*color* + Titlebar AARRGGBB color. Default: use the default _foreground_ + color. + +*button-width* + Width, in pixels (subject to output scaling), of the + minimize/maximize/close buttons. Default: _26_. + +*button-minimize-color* + Minimize button's AARRGGBB color. Default: use the default + _regular4_ color (blue). + +*button-maximize-color* + Maximize button's AARRGGBB color. Default: use the default + _regular2_ color (green). + +*button-close-color* + Close button's AARRGGBB color. Default: use the default _regular1_ + color (red). + + +# SECTION: key-bindings + +This section lets you override the default key bindings. + +The general format is _action=combo1...comboN_. That is, each action +may have one or more key combinations, space separated. Each +combination is on the form _mod1+mod2+key_. The names of the modifiers +and the key *must* be valid XKB key names. + +Note that if *Shift* is one of the modifiers, the _key_ *must* be in +upper case. For example, *Control+Shift+v* will never trigger - +*Control+Shift+V* is the correct way to write it. + +Note that *Alt* is usually called *Mod1*. + +A key combination can only be mapped to *one* action. Lets say you +want to bind *Control+Shift+R* to *fullscreen*. Since this is the +default shortcut for *search-start*, you first need to unmap the +default binding. This can be done by setting _action=none_; +e.g. *search-start=none*. + +*scrollback-up* + Scrolls up/back in history. Default: _Shift+Page\_Up_. + +*scrollback-down* + Scroll down/forward in history. Default: _Shift+Page\_Down_. + +*clipboard-copy* + Copies the current selection into the _clipboard_. Default: _Control+Shift+C_. + +*clipboard-paste* + Pastes from the _clipboard_. Default: _Control+Shift+V_. + +*primary-paste* + Pastes from the _primary selection_. Default: not bound (to a + _key_, see *mouse-bindings*). + +*search-start* + Starts a scrollback/history search. Default: _Control+Shift+R_. + +*font-increase* + Increases the font size by 0.5pt. Default: _Control+plus + Control+equal Control+KP\_Add_. + +*font-decrease* + Decreases the font size by 0.5pt. Default: _Control+minus + Control+KP\_Subtract_. + +*font-reset* + Resets the font size to the default. Default: _Control+0 Control+KP\_0_. + +*spawn-terminal* + Spawns a new terminal. If the shell has been configured to emit + the OSC 7 escape sequence, the new terminal will start in the + current working directory. Default: _Control+Shift+N_. + +*minimize* + Minimizes the window. Default: _not bound_. + +*maximize* + Toggle the maximized state. Default: _not bound_. + +*fullscreen* + Toggles the fullscreen state. Default: _not bound_. + +*pipe-visible*, *pipe-scrollback*, *pipe-selected* + Pipes the currently visible text, the entire scrollback, or the + currently selected text to an external tool. The syntax for this + option is a bit special; the first part of the value is the + command to execute enclosed in "[]", followed by the binding(s). + + You can configure multiple pipes as long as the command strings + are different and the key bindings are unique. + + Note that the command is *not* automatically run inside a shell; + use *sh -c "command line"* if you need that. + + Example: + *pipe-visible=[sh -c "xurls | uniq | tac | bemenu | xargs -r + firefox"] Control+Print* + + Default: _not bound_ + + +# SECTION: search-bindings + +This section lets you override the default key bindings used in +scrollback search mode. The syntax is exactly the same as the regular +**key-bindings**. + +*cancel* + Aborts the search. The viewport is restored and the _primary + selection_ is **not** updated. Default: _Control+g Escape_. + +*commit* + Exit search mode and copy current selection into the _primary + selection_. Viewport is **not** restored. To copy the selection to + the regular _clipboard_, use *Control+Shift+C*. Default: _Return_. + +*find-prev* + Search **backwards** in the scrollback history for the next + match. Default: _Control+r_. + +*find-next* + Searches **forwards** in the scrollback history for the next + match. Default: _Control+s_. + +*cursor-left* + Moves the cursor in the search box one **character** to the + left. Default: _Left Control+b_. + +*cursor-left-word* + Moves the cursor in the search box one **word** to the + left. Default: _Control+Left Mod1+b_. + +*cursor-right* + Moves the cursor in the search box one **character** to the + right. Default: _Right Control+f_. + +*cursor-right-word* + Moves the cursor in the search box one **word** to the + right. Default: _Control+Left Mod1+b_. + +*cursor-home* + Moves the cursor in the search box to the beginning of the + input. Default: _Home Control+a_. + +*cursor-end* + Moves the cursor in the search box to the end of the + input. Default: _End Control+e_. + +*delete-prev* + Deletes the **character before** the cursor. Default: _BackSpace_. + +*delete-prev-word* + Deletes the **word before** the cursor. Default: _Mod1+BackSpace + Control+BackSpace_. + +*delete-next* + Deletes the **character after** the cursor. Default: _Delete_. + +*delete-next-word* + Deletes the **word after** the cursor. Default: _Mod1+b + Control+Delete_. + +*extend-to-word-boundary* + Extend current selection to the next word boundary. Default: + _Control+w_. + +*extend-to-next-whitespace* + Extend the current selection to the next whitespace. Default: + _Control+Shift+W_. + + +# SECTION: mouse-bindings + +This section lets you override the default mouse bindings. + +The general format is _action=combo1...comboN_. That is, each action +may have one or more key combinations, space separated. Each +combination is on the form _mod1+mod2+BTN\_[-COUNT]_. The names +of the modifiers *must* be valid XKB key names, and the button name +*must* be a valid libinput name. You can find the button names using +*libinput debug-events*. + +Note that *Shift* cannot be used as a modifier in mouse bindings since +it is used to enable selection when the client application is grabbing +the mouse. + +The trailing *COUNT* is optional and specifies the click count +required to trigger the binding. The default if *COUNT* is omitted is +_1_. + +A modifier+button combination can only be mapped to *one* action. Lets +say you want to bind *BTN\_MIDDLE* to *fullscreen*. Since +*BTN\_MIDDLE* is the default binding for *primary-paste*, you first +need to unmap the default binding. This can be done by setting +_action=none_; e.g. *primary-paste=none*. + +All actions listed under *key-bindings* can be user here as well. + +*select-begin* + Begin an interactive selection. The selection is finalized, and + copied to the _primary selection_, when the button is + released. Default: _BTN\_LEFT_. + +*select-begin-block* + Begin an interactive block selection. The selection is finalized, + and copied to the _primary selection_, when the button is + released. Default: _Control+BTN\_LEFT_. + +*select-extend* + Interactively extend an existing selection. The selection is + finalized, and copied to the _primary selection_, when the button + is released. Default: _BTN\_RIGHT_. + +*select-word* + Select the _word_ (separated by spaces, period, comma, parenthesis + etc) under the pointer. Default: _BTN\_LEFT-2_. + +*select-word-whitespace* + Select the _word_ (separated by spaces _only_) under the + pointer. Default: Control+_BTN\_LEFT-2_. + +*select-row* + Select the whole row under the pointer. Default: _BTN\_LEFT-3_. + +*primary-paste* + Pastes from the _primary selection_. Default: _BTN\_MIDDLE_. + + +# FONT FORMAT + +The font is specified in FontConfig syntax. That is, a colon-separated +list of font name and font options. + +_Examples_: +- Dina:weight=bold:slant=italic +- Courier New:size=12 + +# TWEAKS + +This section is for advanced users and describes configuration options +that can be used to tweak foot's low-level behavior. + +These options are *not* included in the example configuration. You +should not change these unless you understand what they do and note +that changing the default values *will* print a warning when launching +foot. + +When reporting bugs, please mention if, and to what, you have changed +any of these options. + +*render-timer* + Enables a frame rendering timer, that prints the time it takes to + render each frame, in microseconds, either on-screen, to stderr, + or both. Valid values are *none*, *osd*, *log* and + *both*. Default: _none_. + +*delayed-render-lower*, *delayed-render-upper* + These two values control the timeouts (in nanoseconds) that are + used to mitigate screen flicker caused by clients writing large, + non-atomic screen updates. + + If a client splits up a screen update over multiple *write*(3) + calls, we may end up rendering an intermediate frame, quickly + followed by another frame with the final screen content. For + example, the client may erase part of the screen (or scroll) in + one write, and then write new content in one or more subsequent + writes. Rendering the frame when the screen has been erased, but + not yet filled with new content will be perceived as screen + flicker. + + The *real* solution to this is _Application Synchronized Updates_ + (https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/2). + + The problem with this is twofold - first, it has not yet been + standardized, and thus there are not many terminal emulators that + implement it (foot *does* implement it), and second, applications + must be patched to use it. + + Until this has happened, foot offers an interim workaround; an + attempt to mitigate the screen flicker *without* affecting neither + performance nor latency. + + It is based on the fact that the screen is updated at a fixed + interval (typically 60Hz). For us, this means it does not matter + if we render a new frame at the *beginning* of a frame interval, + or at the *end*. Thus, the goal is to introduce a delay between + receiving client data and rendering the resulting state, but + without causing a frame skip. + + While it should be possible to estimate the amount of time left + until the next frame, foot's algorithm is currently not that + advanced, but is based on statistics I guess you could say - the + delay we introduce is so small that the risk of pushing the frame + over to the next frame interval is also very small. + + Now, that was a lot of text. But what is it foot actually does? + + When receiving client data, it schedules a timer, the + *delayed-render-lower*. If we do not receive any more client data + before the timer has run out, we render the frame. If however, we + do receive more data, the timer is re-scheduled. That is, each + time we receive client data, frame rendering is delayed another + *delayed-render-lower* nanoseconds. + + Now, while this works very well with most clients, it would be + possible to construct a malicious client that keeps writing data + at a slow pace. To the user, this would look like foot has frozen + as we never get to render a new frame. To prevent this, an upper + limit is set - *delayed-render-upper*. If this timer runs out, we + render the frame regardless of what the client is doing. + + If changing these values, note that the lower timeout *must* be + set lower than the upper timeout, but that this is not verified by + foot. Furthermore, both values must be less than 16ms (that is, + 16000000 nanoseconds). + + You can disable the feature altogether by setting either value to + 0. In this case, frames are rendered "as soon as possible". + + Default: lower=_500000_ (0.5ms), upper=_8333333_ (8.3ms - half a + frame interval). + +*max-shm-pool-size-mb* + + This option controls the amount of *virtual* memory used by the + pixmap memory to which the terminal screen content is rendered. + + It does *not* change how much physical memory foot uses. + + Foot uses a memory mapping trick to implement fast rendering of + interactive scrolling (typically, but applies to "slow" scrolling + in general). Example: holding down the 'up' or 'down' arrow key to + scroll in a text editor. + + For this to work, it needs a large amount of virtual address + space. Again, note that this is *not* physical memory. + + On a normal x64 based computer, each process has 128TB of virtual + address space, and newer ones have 64PB. This is an insane amount + and most applications do not use anywhere near that amount. + + Each foot terminal window can allocate up to 2GB of virtual + address space. With 128TB of address space, that means a maximum + of 65536 windows in server/daemon mode (for 2GB). That should be + enough, yes? + + However, the Wayland compositor *also* needs to allocate the same + amount of virtual address space. Thus, it has a slightly higher + chance of running out of address space since it needs to host + *all* running Wayland clients in the same way, at the same time. + + In the off chance that this becomes a problem for you, you can + reduce the amount used with this option. + + Or, for optimal performance, you can increase it to the maximum + allowed value, 2GB (but note that you most likely will not notice + any difference compared to the default value). + + Note: this feature is always disabled in 32-bit. + + Default: _512_. Maximum allowed: _2048_ (2GB). + +# SEE ALSO + +*foot*(1), *footclient*(1) diff --git a/doc/footrc.5.scd b/doc/footrc.5.scd deleted file mode 100644 index 1c974d41..00000000 --- a/doc/footrc.5.scd +++ /dev/null @@ -1,554 +0,0 @@ -footrc(5) - -# NAME -footrc - configuration file - -# DESCRIPTION - -*foot* uses the standard _unix configuration format_, with section based -key/value pairs. The default section is unnamed (i.e. not prefixed -with a _[section]_). - -foot will search for a configuration file in the following locations, -in this order: - -- _XDG_CONFIG_HOME/footrc_ -- _~/.config/footrc_ - -# SECTION: default - -*font* - Comma separated list of fonts to use, in fontconfig format (see - *FONT FORMAT*). - - The first font is the primary font. The remaining fonts are - fallback fonts that will be used whenever a glyph cannot be found - in the primary font. - - The fallback fonts are searched in the order they appear. If a - glyph cannot be found in any of the fallback fonts, the dynamic - fallback list from fontconfig (for the primary font) is - searched. - - Default: _monospace_. - -*geometry* - Initial window width and height in pixels (subject to output - scaling), on the form _WIDTHxHEIGHT_. Default: _700x500_. - -*pad* - Padding between border and glyphs, in pixels (subject to output - scaling), on the form _XxY_. Default: _2x2_. - -*initial-window-mode* - Initial window mode for each newly spawned window: *windowed*, - *maximized* or *fullscreen*. Default: _windowed_. - -*shell* - Executable to launch. Typically a shell. Default: _$SHELL_ if set, - otherwise the user's default shell (as specified in - _/etc/passwd_). You can also pass arguments. For example - "/bin/bash --norc". - -*login-shell* - Boolean. If enabled, the shell will be launched as a login shell, - by prepending a '-' to argv[0]. Default: _no_. - -*term* - Value to set the environment variable *TERM* to. Default: _foot_. - -*title* - Initial window title. Default: _foot_. - -*app-id* - Value to set the *app-id* property on the Wayland window to. The - compositor can use this value to e.g. group multiple windows, or - apply window management rules. Default: _foot_. - -*workers* - Number of threads to use for rendering. Set to 0 to disable - multithreading. Default: the number of available logical CPUs - (including SMT). Note that this is not always the best value. In - some cases, the number of physical _cores_ is better. - - -# SECTION: scrollback - -*lines* - Number of scrollback lines. Default: _1000_. - -*multiplier* - Amount to multiply mouse scrolling with. It is a decimal number, - i.e. fractions are allowed. Default: _1.0_. - -*indicator-position* - Configures the style of the scrollback position indicator. One of - *none*, *fixed* or *relative*. *none* disables the indicator - completely. *fixed* always renders the indicator near the top at - the window, and *relative* renders the indicator at the position - corresponding to the current scrollback position. Default: - _relative_. - -*indicator-format* - Which format to use when displaying the scrollback position - indicator. Either _percentage_, _line_, or a custom fixed - string. This option is ignored if - *indicator-position=none*. Default: _empty string_. - - -# SECTION: cursor - -This section controls the cursor style and color. Note that -applications can change these at runtime. - -*style* - Configures the default cursor style, and is one of: _block_, _bar_ - or _underline_. Note that this can be overridden by - applications. Default: _block_. - -*blink* - Boolean. Enables blinking cursor. Note that this can be overridden - by applications. Default: _no_. - -*color* - Two RRGGBB values specifying the foreground (text) and background - (cursor) colors for the cursor. Default: inversed foreground and - background colors. Note that this value only applies to the block - cursor. The other cursor styles are always rendered with the - foreground color. - - -# SECTION: mouse - -*hide-when-typing* - Boolean. When enabled, the mouse cursor is hidden while typing. - - -# SECTION: colors - -This section controls the 16 ANSI colors and the default foreground -and background colors. Note that applications can change these at -runtime. - -The colors are in RRGGBB format. That is, they do *not* have an alpha -component. You can configure the background transparency with the -_alpha_ option. - -*foreground* - Default RRGGBB foreground color. This is the color used when no - ANSI color is being used. Default: _dcdccc_. - -*background* - Default RRGGBB background color. This is the color used when no - ANSI color is being used. Default: _111111_. - -*regular0*, *regular1* *..* *regular7* - The eight basic ANSI colors. Default: _222222_, _cc9393_, - _7f9f7f_, _d0bf8f_, _6ca0a3_, _dc8cc3_, _93e0e3_ and _dcdccc_ (a - variant of the _zenburn_ theme). - -*bright0*, *bright1* *..* *bright7* - The eight bright ANSI colors. Default: _666666_, _dca3a3_, - _bfebbf_, _f0dfaf_, _8cd0d3_, _fcace3_, _b3ffff_ and _ffffff_ (a - variant of the _zenburn_ theme). - -*alpha* - Background translucency. A value in the range 0.0-1.0, where 0.0 - means completely transparent, and 1.0 is opaque. Default: _1.0_. - -*selection-foreground*, *selection-background* - Foreground (text) and background color to use in selected - text. Note that *both* options must be set, or the default will be - used. Default: _inverse foreground/background_. - - -# SECTION: csd - -This section controls the look of the _CSDs_ (Client Side -Decorations). Note that the default is to *not* use CSDs, but instead -to use _SSDs_ (Server Side Decorations) when the compositor supports -it. - -Note that unlike the colors defined in the _colors_ section, the color -values here are in AARRGGBB format. I.e. they contain an alpha -component. - -*preferred* - Which type of window decorations to prefer: *client* (CSD) or - *server* (SSD). Note that this is only a hint to the - compositor. Depending on the compositor's configuration and - capabilities, it may not have any effect. Default: _server_. - -*size* - Height, in pixels (subject to output scaling), of the - titlebar. Default: _26_. - -*color* - Titlebar AARRGGBB color. Default: use the default _foreground_ - color. - -*button-width* - Width, in pixels (subject to output scaling), of the - minimize/maximize/close buttons. Default: _26_. - -*button-minimize-color* - Minimize button's AARRGGBB color. Default: use the default - _regular4_ color (blue). - -*button-maximize-color* - Maximize button's AARRGGBB color. Default: use the default - _regular2_ color (green). - -*button-close-color* - Close button's AARRGGBB color. Default: use the default _regular1_ - color (red). - - -# SECTION: key-bindings - -This section lets you override the default key bindings. - -The general format is _action=combo1...comboN_. That is, each action -may have one or more key combinations, space separated. Each -combination is on the form _mod1+mod2+key_. The names of the modifiers -and the key *must* be valid XKB key names. - -Note that if *Shift* is one of the modifiers, the _key_ *must* be in -upper case. For example, *Control+Shift+v* will never trigger - -*Control+Shift+V* is the correct way to write it. - -Note that *Alt* is usually called *Mod1*. - -A key combination can only be mapped to *one* action. Lets say you -want to bind *Control+Shift+R* to *fullscreen*. Since this is the -default shortcut for *search-start*, you first need to unmap the -default binding. This can be done by setting _action=none_; -e.g. *search-start=none*. - -*scrollback-up* - Scrolls up/back in history. Default: _Shift+Page\_Up_. - -*scrollback-down* - Scroll down/forward in history. Default: _Shift+Page\_Down_. - -*clipboard-copy* - Copies the current selection into the _clipboard_. Default: _Control+Shift+C_. - -*clipboard-paste* - Pastes from the _clipboard_. Default: _Control+Shift+V_. - -*primary-paste* - Pastes from the _primary selection_. Default: not bound (to a - _key_, see *mouse-bindings*). - -*search-start* - Starts a scrollback/history search. Default: _Control+Shift+R_. - -*font-increase* - Increases the font size by 0.5pt. Default: _Control+plus - Control+equal Control+KP\_Add_. - -*font-decrease* - Decreases the font size by 0.5pt. Default: _Control+minus - Control+KP\_Subtract_. - -*font-reset* - Resets the font size to the default. Default: _Control+0 Control+KP\_0_. - -*spawn-terminal* - Spawns a new terminal. If the shell has been configured to emit - the OSC 7 escape sequence, the new terminal will start in the - current working directory. Default: _Control+Shift+N_. - -*minimize* - Minimizes the window. Default: _not bound_. - -*maximize* - Toggle the maximized state. Default: _not bound_. - -*fullscreen* - Toggles the fullscreen state. Default: _not bound_. - -*pipe-visible*, *pipe-scrollback*, *pipe-selected* - Pipes the currently visible text, the entire scrollback, or the - currently selected text to an external tool. The syntax for this - option is a bit special; the first part of the value is the - command to execute enclosed in "[]", followed by the binding(s). - - You can configure multiple pipes as long as the command strings - are different and the key bindings are unique. - - Note that the command is *not* automatically run inside a shell; - use *sh -c "command line"* if you need that. - - Example: - *pipe-visible=[sh -c "xurls | uniq | tac | bemenu | xargs -r - firefox"] Control+Print* - - Default: _not bound_ - - -# SECTION: search-bindings - -This section lets you override the default key bindings used in -scrollback search mode. The syntax is exactly the same as the regular -**key-bindings**. - -*cancel* - Aborts the search. The viewport is restored and the _primary - selection_ is **not** updated. Default: _Control+g Escape_. - -*commit* - Exit search mode and copy current selection into the _primary - selection_. Viewport is **not** restored. To copy the selection to - the regular _clipboard_, use *Control+Shift+C*. Default: _Return_. - -*find-prev* - Search **backwards** in the scrollback history for the next - match. Default: _Control+r_. - -*find-next* - Searches **forwards** in the scrollback history for the next - match. Default: _Control+s_. - -*cursor-left* - Moves the cursor in the search box one **character** to the - left. Default: _Left Control+b_. - -*cursor-left-word* - Moves the cursor in the search box one **word** to the - left. Default: _Control+Left Mod1+b_. - -*cursor-right* - Moves the cursor in the search box one **character** to the - right. Default: _Right Control+f_. - -*cursor-right-word* - Moves the cursor in the search box one **word** to the - right. Default: _Control+Left Mod1+b_. - -*cursor-home* - Moves the cursor in the search box to the beginning of the - input. Default: _Home Control+a_. - -*cursor-end* - Moves the cursor in the search box to the end of the - input. Default: _End Control+e_. - -*delete-prev* - Deletes the **character before** the cursor. Default: _BackSpace_. - -*delete-prev-word* - Deletes the **word before** the cursor. Default: _Mod1+BackSpace - Control+BackSpace_. - -*delete-next* - Deletes the **character after** the cursor. Default: _Delete_. - -*delete-next-word* - Deletes the **word after** the cursor. Default: _Mod1+b - Control+Delete_. - -*extend-to-word-boundary* - Extend current selection to the next word boundary. Default: - _Control+w_. - -*extend-to-next-whitespace* - Extend the current selection to the next whitespace. Default: - _Control+Shift+W_. - - -# SECTION: mouse-bindings - -This section lets you override the default mouse bindings. - -The general format is _action=combo1...comboN_. That is, each action -may have one or more key combinations, space separated. Each -combination is on the form _mod1+mod2+BTN\_[-COUNT]_. The names -of the modifiers *must* be valid XKB key names, and the button name -*must* be a valid libinput name. You can find the button names using -*libinput debug-events*. - -Note that *Shift* cannot be used as a modifier in mouse bindings since -it is used to enable selection when the client application is grabbing -the mouse. - -The trailing *COUNT* is optional and specifies the click count -required to trigger the binding. The default if *COUNT* is omitted is -_1_. - -A modifier+button combination can only be mapped to *one* action. Lets -say you want to bind *BTN\_MIDDLE* to *fullscreen*. Since -*BTN\_MIDDLE* is the default binding for *primary-paste*, you first -need to unmap the default binding. This can be done by setting -_action=none_; e.g. *primary-paste=none*. - -All actions listed under *key-bindings* can be user here as well. - -*select-begin* - Begin an interactive selection. The selection is finalized, and - copied to the _primary selection_, when the button is - released. Default: _BTN\_LEFT_. - -*select-begin-block* - Begin an interactive block selection. The selection is finalized, - and copied to the _primary selection_, when the button is - released. Default: _Control+BTN\_LEFT_. - -*select-extend* - Interactively extend an existing selection. The selection is - finalized, and copied to the _primary selection_, when the button - is released. Default: _BTN\_RIGHT_. - -*select-word* - Select the _word_ (separated by spaces, period, comma, parenthesis - etc) under the pointer. Default: _BTN\_LEFT-2_. - -*select-word-whitespace* - Select the _word_ (separated by spaces _only_) under the - pointer. Default: Control+_BTN\_LEFT-2_. - -*select-row* - Select the whole row under the pointer. Default: _BTN\_LEFT-3_. - -*primary-paste* - Pastes from the _primary selection_. Default: _BTN\_MIDDLE_. - - -# FONT FORMAT - -The font is specified in FontConfig syntax. That is, a colon-separated -list of font name and font options. - -_Examples_: -- Dina:weight=bold:slant=italic -- Courier New:size=12 - -# TWEAKS - -This section is for advanced users and describes configuration options -that can be used to tweak foot's low-level behavior. - -These options are *not* included in the example configuration. You -should not change these unless you understand what they do and note -that changing the default values *will* print a warning when launching -foot. - -When reporting bugs, please mention if, and to what, you have changed -any of these options. - -*render-timer* - Enables a frame rendering timer, that prints the time it takes to - render each frame, in microseconds, either on-screen, to stderr, - or both. Valid values are *none*, *osd*, *log* and - *both*. Default: _none_. - -*delayed-render-lower*, *delayed-render-upper* - These two values control the timeouts (in nanoseconds) that are - used to mitigate screen flicker caused by clients writing large, - non-atomic screen updates. - - If a client splits up a screen update over multiple *write*(3) - calls, we may end up rendering an intermediate frame, quickly - followed by another frame with the final screen content. For - example, the client may erase part of the screen (or scroll) in - one write, and then write new content in one or more subsequent - writes. Rendering the frame when the screen has been erased, but - not yet filled with new content will be perceived as screen - flicker. - - The *real* solution to this is _Application Synchronized Updates_ - (https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/2). - - The problem with this is twofold - first, it has not yet been - standardized, and thus there are not many terminal emulators that - implement it (foot *does* implement it), and second, applications - must be patched to use it. - - Until this has happened, foot offers an interim workaround; an - attempt to mitigate the screen flicker *without* affecting neither - performance nor latency. - - It is based on the fact that the screen is updated at a fixed - interval (typically 60Hz). For us, this means it does not matter - if we render a new frame at the *beginning* of a frame interval, - or at the *end*. Thus, the goal is to introduce a delay between - receiving client data and rendering the resulting state, but - without causing a frame skip. - - While it should be possible to estimate the amount of time left - until the next frame, foot's algorithm is currently not that - advanced, but is based on statistics I guess you could say - the - delay we introduce is so small that the risk of pushing the frame - over to the next frame interval is also very small. - - Now, that was a lot of text. But what is it foot actually does? - - When receiving client data, it schedules a timer, the - *delayed-render-lower*. If we do not receive any more client data - before the timer has run out, we render the frame. If however, we - do receive more data, the timer is re-scheduled. That is, each - time we receive client data, frame rendering is delayed another - *delayed-render-lower* nanoseconds. - - Now, while this works very well with most clients, it would be - possible to construct a malicious client that keeps writing data - at a slow pace. To the user, this would look like foot has frozen - as we never get to render a new frame. To prevent this, an upper - limit is set - *delayed-render-upper*. If this timer runs out, we - render the frame regardless of what the client is doing. - - If changing these values, note that the lower timeout *must* be - set lower than the upper timeout, but that this is not verified by - foot. Furthermore, both values must be less than 16ms (that is, - 16000000 nanoseconds). - - You can disable the feature altogether by setting either value to - 0. In this case, frames are rendered "as soon as possible". - - Default: lower=_500000_ (0.5ms), upper=_8333333_ (8.3ms - half a - frame interval). - -*max-shm-pool-size-mb* - - This option controls the amount of *virtual* memory used by the - pixmap memory to which the terminal screen content is rendered. - - It does *not* change how much physical memory foot uses. - - Foot uses a memory mapping trick to implement fast rendering of - interactive scrolling (typically, but applies to "slow" scrolling - in general). Example: holding down the 'up' or 'down' arrow key to - scroll in a text editor. - - For this to work, it needs a large amount of virtual address - space. Again, note that this is *not* physical memory. - - On a normal x64 based computer, each process has 128TB of virtual - address space, and newer ones have 64PB. This is an insane amount - and most applications do not use anywhere near that amount. - - Each foot terminal window can allocate up to 2GB of virtual - address space. With 128TB of address space, that means a maximum - of 65536 windows in server/daemon mode (for 2GB). That should be - enough, yes? - - However, the Wayland compositor *also* needs to allocate the same - amount of virtual address space. Thus, it has a slightly higher - chance of running out of address space since it needs to host - *all* running Wayland clients in the same way, at the same time. - - In the off chance that this becomes a problem for you, you can - reduce the amount used with this option. - - Or, for optimal performance, you can increase it to the maximum - allowed value, 2GB (but note that you most likely will not notice - any difference compared to the default value). - - Note: this feature is always disabled in 32-bit. - - Default: _512_. Maximum allowed: _2048_ (2GB). - -# SEE ALSO - -*foot*(1), *footclient*(1) diff --git a/doc/meson.build b/doc/meson.build index 39697496..18cff552 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -3,16 +3,17 @@ sh = find_program('sh', native: true) scdoc = dependency('scdoc', native: true) scdoc_prog = find_program(scdoc.get_pkgconfig_variable('scdoc'), native: true) -foreach man_src : ['foot.1.scd', 'footrc.5.scd', 'footclient.1.scd'] - parts = man_src.split('.') - name = parts[-3] - section = parts[-2] +foreach man_src : [{'name': 'foot', 'section' : 1}, + {'name': 'foot.ini', 'section': 5}, + {'name': 'footclient', 'section': 1}] + name = man_src['name'] + section = man_src['section'] out = '@0@.@1@'.format(name, section) custom_target( out, output: out, - input: man_src, + input: '@0@.@01@.scd'.format(name, section), command: [sh, '-c', '@0@ < @INPUT@'.format(scdoc_prog.path())], capture: true, install: true, diff --git a/meson.build b/meson.build index d5b306a6..468626d8 100644 --- a/meson.build +++ b/meson.build @@ -163,7 +163,7 @@ install_data( install_data( 'foot.desktop', 'foot-server.desktop', install_dir: join_paths(get_option('datadir'), 'applications')) -install_data('footrc', install_dir: join_paths(get_option('datadir'), 'foot')) +install_data('foot.ini', install_dir: join_paths(get_option('datadir'), 'foot')) subdir('completions') subdir('doc') -- cgit v1.3 From 3309d8d779dd22d19970e11a9f648f8ddb9358ef Mon Sep 17 00:00:00 2001 From: Daniel Eklöf Date: Thu, 27 Aug 2020 20:02:43 +0200 Subject: changelog: new configuration file location --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ba356441..537e7d88 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,6 +50,8 @@ ### Deprecated * **scrollback** option in `footrc`. Use **scrollback.lines** instead. +* `$XDG_CONFIG_HOME/footrc`/`~/.config/footrc`. Use + `$XDG_CONFIG_HOME/foot/foot.ini`/`~/.config/foot/foot.ini` instead. ### Removed @@ -64,6 +66,13 @@ * Trailing empty cells are no longer highlighted in mouse selections. * Scrollback position indicator is now based on the number of _used_ scrollback lines, instead of the _total_ number of scrollback lines. +* Foot now searches for its configuration in + `$XDG_CONFIG_HOME/foot/foot.ini` (typically + `~/.config/foot/foot.ini`), before looking for + `$XDG_CONFIG_HOME/footrc`. +* Foot now searches for its configuration in + `$XDG_DATA_DIRS/foot/foot.ini`, if no configuration is found in + `$XDG_CONFIG_HOME/foot/foot.ini` or in `$XDG_CONFIG_HOME/footrc`. ### Fixed -- cgit v1.3 From df35b09142d280db703fd62ad5e96fa6e86a3f0e Mon Sep 17 00:00:00 2001 From: Daniel Eklöf Date: Thu, 27 Aug 2020 20:03:30 +0200 Subject: main: usage: footrc -> foot.ini --- main.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/main.c b/main.c index 3f5372bb..b53aaf17 100644 --- a/main.c +++ b/main.c @@ -46,7 +46,7 @@ print_usage(const char *prog_name) "Usage: %s [OPTIONS...] command [ARGS...]\n" "\n" "Options:\n" - " -c,--config=PATH load configuration from PATH ($XDG_CONFIG_HOME/footrc)\n" + " -c,--config=PATH load configuration from PATH ($XDG_CONFIG_HOME/foot/foot.ini)\n" " --check-config verify configuration, exit with 0 if ok, otherwise exit with 1\n" " -f,--font=FONT comma separated list of fonts in fontconfig format (monospace)\n" " -t,--term=TERM value to set the environment variable TERM to (foot)\n" -- cgit v1.3 From fdb1f64cae72250cbf53c3cfe75bdffa3cde4b04 Mon Sep 17 00:00:00 2001 From: Daniel Eklöf Date: Thu, 27 Aug 2020 21:08:24 +0200 Subject: readme: remove stray ’;9~’ sequence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6dcd8fe6..773d6a7f 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ See [INSTALL.md](INSTALL.md). **foot** can be configured by creating a file `$XDG_CONFIG_HOME/foot/foot.ini` (defaulting to `~/.config/foot/foot.ini`). A template for that can usually be found -in `/usr/share/foot/foot.ini;9~` or +in `/usr/share/foot/foot.ini` or [here](https://codeberg.org/dnkl/foot/src/branch/master/foot.ini). Further information can be found in foot's man page `foot.ini(5)`. -- cgit v1.3 From a24109a5e35e6d6cbeec64ec954328af91ebb889 Mon Sep 17 00:00:00 2001 From: Daniel Eklöf Date: Thu, 27 Aug 2020 21:09:54 +0200 Subject: doc: foot.ini: highlight configuration file paths with bold, not italic/underline --- doc/foot.ini.5.scd | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/foot.ini.5.scd b/doc/foot.ini.5.scd index cede6e26..9f8c6cbb 100644 --- a/doc/foot.ini.5.scd +++ b/doc/foot.ini.5.scd @@ -12,11 +12,11 @@ with a _[section]_). foot will search for a configuration file in the following locations, in this order: -- _XDG_CONFIG_HOME/foot/foot.ini_ -- _~/.config/foot/foot.ini_ -- _XDG_CONFIG_HOME/footrc_ -- _~/.config/footrc_ -- _XDG_CONFIG_DIRS/foot/foot.init_ +- *XDG_CONFIG_HOME/foot/foot.ini* +- *~/.config/foot/foot.ini* +- *XDG_CONFIG_HOME/footrc* +- *~/.config/footrc* +- *XDG_CONFIG_DIRS/foot/foot.init* # SECTION: default -- cgit v1.3 From 6f114f639adea4bfba801d08f5e2ee206d10d0e6 Mon Sep 17 00:00:00 2001 From: Daniel Eklöf Date: Thu, 27 Aug 2020 21:11:03 +0200 Subject: config: close FD if it is *valid*, not when it is *invalid* --- config.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config.c b/config.c index c1f59b6c..83a0ef4d 100644 --- a/config.c +++ b/config.c @@ -1849,7 +1849,7 @@ out: tll_push_back(conf->fonts, config_font_parse("monospace")); free(conf_file.path); - if (conf_file.fd < 0) + if (conf_file.fd >= 0) close(conf_file.fd); return ret; -- cgit v1.3 From b957f2faa7a8c0624f25dcd6190b6e2bea8ca7f9 Mon Sep 17 00:00:00 2001 From: Daniel Eklöf Date: Thu, 27 Aug 2020 21:22:27 +0200 Subject: doc: meson: @01@ -> @1@ --- doc/meson.build | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/meson.build b/doc/meson.build index 18cff552..1f017db4 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -13,7 +13,7 @@ foreach man_src : [{'name': 'foot', 'section' : 1}, custom_target( out, output: out, - input: '@0@.@01@.scd'.format(name, section), + input: '@0@.@1@.scd'.format(name, section), command: [sh, '-c', '@0@ < @INPUT@'.format(scdoc_prog.path())], capture: true, install: true, -- cgit v1.3