Zutty user guide

On a current (stable or testing) Debian, or a Debian-derivative such as Ubuntu, the following command will make sure everything you need to build Zutty is in place. It also gives you an idea of what you need to install Zutty on other flavours of Linux.

sudo apt-get install \
   build-essential pkg-config python3 \
   libegl-dev libfreetype-dev libgles-dev libxmu-dev

Hint: You might need to substitute libfreetype6-dev for libfreetype-dev and libgles2-mesa-dev for libgles-dev. When in doubt, use your distribution's package manager along with your favourite Internet search engine.

Clone the source from git:

git clone https://git.hq.sig7.se/zutty.git
cd zutty

You are supposed to be inside the repository directory structure, i.e., the zutty directory created above should be your working directory. Issue this command:

./waf configure

You should see some output with a confirmation of the Zutty version you are going to build, and whether you are creating a Debug build (it should say "no" at this point; read the Developer guide if you are interested in debugging Zutty).

By default, g++ (the gcc compiler for C++) will be used to compile Zutty. To use clang instead, pass --check-cxx-compiler=clang++ to the above script.

In the configure output, you will see checks for the presence of the build dependencies. If anything is missing, the configure script will terminate with an error. Otherwise, the configure output will finish with a line like this:

'configure' finished successfully (0.373s)

In case you will want to install the zutty executable to somewhere other than /usr/local/bin, use the --prefix option to specify the installation prefix (the default is /usr/local). For example, I often install stuff for my user account only, in which case I would issue ./waf configure --prefix=/home/tom/root so that later on, zutty would end up installed as /home/tom/root/bin/zutty.

If you would like to learn more, ./waf --help lists a reference of every option you can use.

Just type:

./waf

Alternatively, if you want to specify the number of jobs to run in parallel, issue ./waf -j 4 (substitute your number of CPU cores in place of 4).

The compilation messages should be self-explanatory (assuming you do not run into C++ error messages – decoding those is an art form in its own right). A successful compile ends with a line like this:

'build' finished successfully (23.524s)

At this point, the zutty executable is complete and ready to be run at build/src/zutty and you might want to launch it just to see if it works. You can run it without arguments to start it up with defaults, or add -h (or -help) to learn about available options.

For regular use, it is best to copy the zutty executable to a system-wide directory for binaries where it will be found as part of the default executable search path. This makes it easier to launch and also decouples it from any local changes. You can manually copy the executable built in the previous step, but it might be easier to use the built-in install step in the waf script. Running it with sudo will ensure that it is able to write to protected system-wide locations:

sudo ./waf install

Note that your ability to run the above command (with sudo) is contingent on the presence of sudo, the setup of your user account with respect to sudo, etc. If it does not work, please search the web or ask your friendly local guru. Also, if you have specified an install location that is actually yours (like the one I showed above) then of course there is no point in using sudo.

At the end, you should see something like this:

'install' finished successfully (0.135s)

Congratulations, you are now ready to start using Zutty as your terminal!

The following list summarizes user-triggered actions. Note that these are hooks handled by the terminal itself, and will not reach the program running in the terminal. For the specification of how the terminal encodes keypresses to the program running inside it, see the Key mapping sequences reference.

Trigger	Action
Shift+PageUp, Shift+PageDown	Page screen upwards (into earlier scrollback history) or downwards by half the page height. If on the alternate screen with -altScroll enabled, emit synthetic arrow key events to move up/down half the screen height.
Scroll wheel up/down	Page screen up/down by 5 lines; if on the alternate screen with -altScroll enabled, emit a single synthetic up/down arrow key event.
Left mouse button press (and hold)	Start a new selection. Adjust by moving the mouse with the button held down.
Right mouse button press (and hold)	Adjust current selection (will grab the edge closest to the pointer); adjust by moving the mouse with the button held down.
Quickly release and re-engage left/right mouse button	While a selection is in progress, this will cycle between snap-to-char, snap-to-word and snap-to-line. (In rectangular selection mode, only snap-to-char exists.)
Space key while left/right mouse button is held	Toggle between regular and rectangular selection mode.
Middle mouse button, Shift+Insert	Paste the current content of the primary selection into the terminal.
Control+Shift+C	Copy the current content of the primary selection into the clipboard selection. (With -autoCopy enabled, this happens automatically whenever the primary selection is set.)
Control+Shift+V	Paste the current content of the clipboard selection into the terminal.

Zutty sets or alters the below environment variables in the process spawned to run the shell. All other environment variables accessible to Zutty will be passed unaltered to the shell program.

Environment variable	Treatment
DISPLAY	Set to the current X display.
SHELL	Set to the full (resolved) pathname of the shell being run; unset if the program is not a valid shell as per /etc/shells.
TERM	Set to xterm-256color.
COLORTERM	Set to truecolor.
WINDOWID	Set to the current X window id of the Zutty window.
ZUTTY_VERSION	Set to the build version of Zutty.

-altScroll    Alternate scroll mode [boolean]

If enabled, mouse scroll up and down events while on the alternate screen buffer are translated into synthetic up- and down-arrow key events. This might prove to be a convenient way of moving up/down one-by-one in programs usually navigated with the keyboard arrows.

Another, similar effect (also on the alternate screen) is that the keys normally used to page through the screen buffer (Shift+PageUp, Shift+PageDown) will generate the same synthetic up- and down-arrow key events as above, but in multiples, to scroll half the amount of scrollable lines. This might be convenient in the same situations, only for larger jumps.

-autoCopy     Sync primary to clipboard [boolean]

By enabling this option, Zutty will automatically propagate the primary selection to the clipboard each time a selection is completed, acting as if you pressed Control+Shift+C immediately after each selection. This might be convenient if you do not wish to use the dual selection capability (primary plus clipboard), and expect to be able to paste into other programs that source the data from the clipboard.

-display      Display to connect to

The X display to connect to. By default, the value of the environment variable DISPLAY is used. This option is exceptional in that (for obvious reasons) it cannot be configured via the X resource database, only the command line.

-glinfo       Print OpenGL information

If enabled, Zutty will query and log some GL variables on program startup. These include EGL_VERSION, EGL_VENDOR, EGL_EXTENSIONS, as well as GL_RENDERER, GL_VERSION, GL_VENDOR, GL_EXTENSIONS, and numeric limits on the Compute Shader implementation. This is mostly a debugging aid. The output is not affected by any verbosity changes made via -v or -q.

-help         Print usage listing and quit

Print the help message containing the list of options documented here, and quit.

-listres      Print resource listing and quit

Print a listing of configurable Extra resources and quit.

-name         Instance name for Xrdb and WM_CLASS

This option specifies the application instance name, which will be used to look up resources in the X resource database, and reported to the window manager as part of the WM_CLASS property (the other part being the application class name, hardcoded as Zutty). The specified name should not contain "." (dot) or "*" (asterisk), as those characters have special meanings within Xrdb entries.

If this option is not present, but the environment variable RESOURCE_NAME is set, that will be used instead. If none of these are available, the hard default value of Zutty will be used.

This option is exceptional in that (for obvious reasons) it cannot be configured via the X resource database, only the command line.

-saveLines    Lines of scrollback history (default: 500)

Set the number of lines to keep in off-screen page history, viewable via paging the terminal up/down by Shift+PageUp and Shift+PageDown (jumping half a page-height at once), or the mouse scrollwheel (moving in units of 5 lines). The set amount of saved lines is in addition to the lines visible in the terminal window.

The default value is 500 lines, which should be enough for everyday use (the occasional peek at the output of a command that rolled off the screen). The minimum setting is 0 (no scrollback), the maximum allowed value is 50,000. Note that while the performance of scrolling itself (and Zutty in general) will not degrade with a larger setting, the screen buffer will consume proportional amounts of memory. With very large settings, this will dominate the total memory usage of Zutty! For example, 1024 buffered lines (24 lines on-screen and 1000 lines of scrollback) with 80 columns will consume 960 KiB; this will balloon to 10 MiB with 10,000 lines of scrollback. Adjusting the column width will have a similar (proportional) effect; 50,000 lines at a width of 120 columns will consume a whopping 70 MiB!

Note that the alternate screen buffer does not have scrollback; this is by design and in conformance with the relevant specs (but see -altScroll for enabling synthetic up- and down-arrow key events).

-quiet        Silence logging output [boolean]
-verbose      Output info messages [boolean]

These options control the verbosity of log output emitted by Zutty. You will only observe the effects of these if you run Zutty itself from another terminal (as opposed to some launcher that discards the program's output). In that case, you will notice output that looks like this:

I [font.cc: 54] Loading /usr/share/fonts/X11/misc/9x18.pcf.gz as primary
I [font.cc:198] Glyph size 9x18
...
I [main.cc:118] Window ID: 48234498 / 0x2e00002
I [charvdev.cc:377] Resize to 935 x 771 pixels, 103 x 42 chars

The first letter is an indication of the log level or "severity"; E means Error, W stands for Warning, I is Info and T is Trace. Trace will only be output if you compile Zutty into a debug build; see the Developer guide for details. Next, the origin of the log message is shown in square brackets, indicating the source code location (filename and line number) where the message was printed. Then comes the actual message.

By default (if neither -quiet nor -verbose is given), Zutty will print errors and warnings, but not info messages. If -verbose is given, info messages are also printed. On the other hand, if -quiet is given, nothing is printed. If both options are given, -quiet wins.

-geometry     Terminal size in chars (default: 80x24)

This option defines the desired initial size of the terminal as measured in characters. (The pixel size of the window will be a function of this plus the font geometry, and cannot be specified directly.)

This is just a request to the window manager; Zutty will accept and work with whatever final window size it gets. Setting this will in no way interfere with your ability to resize Zutty once it is up and running.

-bg           Background color (default: #000)
-fg           Foreground color (default: #fff)
-cr           Cursor color

These options accept a hexadecimal RGB or RRGGBB color specification, similar to how you can define a color in many other places, e.g., CSS. The leading # is optional (supported mainly to provide compatibility with established conventions); take care to protect it from the shell when passing it on the command line. Both lower- and uppercase hexadecimal digits (a-f, A-F) are accepted, but note that names (e.g., red instead of #f00) are not supported.

If not explicitly set, the cursor color defaults to the foreground color. In case the cursor is placed on a cell with a background color set to the cursor color, the cursor color is automatically inverted to ensure it stays visible.

-rv           Reverse video [boolean]

Using this option will swap the effective foreground and background color, regardless of whether their values originate from -fg and -bg, or the corresponding resources, or the defaults. It will not swap the meaning of color codes and such; if a program explicitly specifies the color green, it will be rendered green with and without -rv.

-boldColors   Enable bright for bold [boolean]

This option enables combining the bold attribute with a brightening of base colors. That is, when printing bold text, colors 0 through 7 will be mapped to colors 8 through 15 by adding 8 to the color number. These normally correspond to the brighter variants of the same colors. This is enabled by default; supply +boldColors on the command line to turn it off.

-border       Border width in pixels (default: 2)

Specify the border width; specifically, the border that is part of the client area of the Zutty window and not part of any window decoration outside of the program's direct control. (This is equivalent to what Xterm calls internal border width.)

-showWraps    Show wrap marks at right margin [boolean]

Specify whether to draw a vertical mark on the right edge of cells having the wrap bit set. This bit is set in case an auto-wrap occurs just after the given position, so it only gets set on the right margin. However, following an increase of the window size, cells with a set wrap bit might reside inside the right margin.

When selecting text, line breaks are suppressed depending on the wrap bit (wrapped text is copied without the breaks introduced by the wraps), so a visual indicator of this status bit might be useful to better understand (or predict) behaviour. It might also be useful to see this when debugging Zutty or an application writing text at the right margin.

-title        Window title (default: Zutty)

Set the title of the Zutty window. A title configured in the X resource database will be overridden by usage of the -e option, which sets the title to the basename of the program to be run. Passing the title on the command line takes precedence over the title implied by -e. In any case, the title can be overridden at runtime by escape sequences output by the shell (or any program executed by it).

-login        Start shell as a login shell [boolean]

When this option is enabled, the shell started by Zutty will be a login shell. This will be signalled to the shell process by setting its argv [0] to begin with a dash (-). Shells evaluate different sets of startup files depending on this (e.g., bash sources /etc/profile and ~/.bash_profile if started as a login shell, but sources ~/.bashrc otherwise). Please consult the documentation of your shell for accurate details.

When using the -e option, this option will be ignored, because -e is supposed to be used to launch non-shell text-mode programs in a terminal window, and manipulating the argv [0] of such programs might interfere with their operation.

-shell        Shell program to run

Specify the shell program to run in the terminal. As a bit of special syntax, this option can be passed both as a regular option (-shell bash anywhere among a list of other options), or just the shell itself (bash) as the last item on the command line. Either way, this option is mutually exclusive with using the -e option. If both forms are present, the last item on the command line will take precedence over the value supplied after -shell.

The algorithm to resolve the executable to spawn resembles the behaviour of xterm, and follows these steps:

1. Start with the value of shell (the last argument given after all valid options, if present, or the value supplied after -shell). In case no shell argument is given, the Zutty.shell resource is consulted; if that is not set, the value of the SHELL environment variable is used; if that is not set, the built-in default of bash is assumed.
2. If not already an absolute path, resolve this to an absolute path taking PATH into account, trying elements of the list of PATH entries until the given shell resolves to an existing file at that path.
3. Fall back on the SHELL environment variable, then the user's /etc/passwd shell entry, if the above did not result in any candidate.
4. Use /bin/sh as a last resort.
5. Validate the outcome of the above steps against the permitted shell entries found in /etc/shells. Proceed, but clear SHELL from the environment if the program is not listed as a valid shell. Else, set SHELL to the resolved full program path.

-e            Command line to run

This option specifies the command line (program and arguments) to be run in the Zutty terminal window. It also sets the window title to the basename of the program to be executed, unless the title is explicitly set by passing -title on the command line.

Note that this must be the last option on the command line, as everything after it will be passed verbatim to the spawned child process.

Using this option is mutually exclusive with the -shell option, and will silently override it, as well as discarding the -login option, if any of those are also present.

Zutty employs a simple but powerful model of font selection. Font files are located under a search path and loaded by Zutty itself (bypassing any infrastructure such as a font server, etc). In principle, any font that is supported by the Freetype font library can be used; in practice, only monospace fonts make sense. Both fixed size (bitmap) fonts and scaled (vectorized) fonts are supported.

You specify the font to use by its name, which will be part of the actual filename(s) that store the font. Multiple variants of the font will be sought after: Zutty will try to find a Regular, a Bold, an Italic and a Bold Italic variant of the font you specify. It is not an error if these do not exist, as long as the primary variant (Regular) is found.

-font        Font to use (default: 9x18)

This option specifies the font name to use. The name supplied will form the basis of a case-insensitive search under the font search path. The search will try to locate a set of files under the same subdirectory, starting with the supplied name and ending with the same extension that is one of the recognized font file extensions. If such a set of files is found, the full filenames (the parts after the specified font name) will be used to assign the files to each variant sought after.

For example, the default font is 9x18. This is one of the "misc fixed" fonts. After seeing that the font name is 9x18, Zutty will search under the font path /usr/share/fonts for files starting with 9x18. It will find 9x18.pcf.gz and 9x18B.pcf.gz, both under /usr/share/fonts/X11/misc. Based on the filenames, Zutty will recognize the first file as the regular variant, and the second file as the bold variant. Other variants are absent; use of text attributes that depend on them will result in sensible fallbacks.

As a second example, we will load a scaled font called Liberation Mono by supplying -font LiberationMono (or -font liberationmono) to Zutty. This will result in several files found, all under /usr/share/fonts/truetype/liberation: LiberationMono-Regular.ttf, LiberationMono-Bold.ttf, LiberationMono-Italic.ttf and LiberationMono-BoldItalic.ttf. These files will be loaded as the respective variants of the chosen font.

-dwfont      Double-width font to use (default: 18x18ja)

This option specifies the font name to use for rendering double-width characters (CJK ideographs). Everything written above for -font applies here as well. The double-width font is located in a separate search, so it may reside in a different location (the set of search paths is the same; see -fontpath). It may also be of a different type (e.g., it is possible to use a scaled font for CJK characters even if the main font is of a fixed type). No variants (bold, italic) are considered.

The default setting is a fixed width bitmap font chosen to work well with the default main font (see -font). See Recommended fonts below for tips on using a scalable CJK font.

The font size to use will be defined by the main font (governed by the -fontsize option). For the double-width font to load, its geometry must match this predetermined cell size (times two horizontally). It is not an error if no suitable font is found. A warning will be logged on startup, and the program will draw empty boxes in place of any double-width characters. In such case, as only the ability to render these characters is missing, it is still possible to select them in Zutty and paste into a different program that is able to display them.

-fontsize    Font size (default: 16)

For scaled fonts, such as Liberation Mono above, this setting controls the height, measured in integer pixels, to rasterize the glyphs to. The actual character grid size will almost always be more, due to the fact that typefaces have some spacing around the glyphs themselves.

The specified size, if within one pixel of the size of a bitmap strike, will result in picking that strike (pre-rasterized version) from a scaled font with strikes. If there are no strikes, or the specified size is too far from any pre-rasterized sizes, Zutty falls back to rendering the outline at the requested size.

In case of a fixed size font with multiple bitmap sizes, the size closest to the configured size will be selected.

-fontpath    Font search path (default: /usr/share/fonts)

This option specifies the root of the directory structure where font files will be searched. It is seldom necessary to change this, but might be useful to try some new font you downloaded from the Internet (and have not yet installed to a system-wide location).

Hint: you can specify more than one root, separated by colons. These will be searched in order (left to right) until the specified font is found.

Zutty can be configured via some extra resources not available as command line options. To get a printout of all these extra resources available for configuration, pass the -listres option to Zutty. The result will look like this:

Resources:
  altSendsEscape    Encode Alt key as ESC prefix (default: true)
  bellIsAudible     Invoke audible bell (XBell) on ^G (default: true)
  bellIsUrgent      Signal bell to WM as Urgency Hint (default: false)
  modifyOtherKeys   Key modifier encoding level; 0..2 (default: 1)
  color0            Palette color 0 (default: #000000)
  color1            Palette color 1 (default: #cd0000)
  ...
  color15           Palette color 15 (default: #ffffff)

To customize <resource>, put an entry into ~/.Xresources under the key Zutty.<resource>. For example:

Zutty.altSendsEscape:          false
Zutty.modifyOtherKeys:         0

After merging into Xrdb, the above output will reflect the configured values, similar to the output of zutty -h for options as shown above.

printf "\a"

sleep 5 && printf "\a"

Zutty.color0:                  #1c1b19
Zutty.color1:                  #ef2f27
Zutty.color2:                  #519f50
Zutty.color3:                  #fbb829
Zutty.color4:                  #2c78bf
Zutty.color5:                  #e02c6d
Zutty.color6:                  #0aaeb3
Zutty.color7:                  #d0bfa1
Zutty.color8:                  #918175
Zutty.color9:                  #f75341
Zutty.color10:                 #98bc37
Zutty.color11:                 #fed06e
Zutty.color12:                 #68a8e4
Zutty.color13:                 #ff5c8f
Zutty.color14:                 #53fde9
Zutty.color15:                 #fce8c3

Removing a piece of configuration is a bit tricky. If you remove a setting from ~/.Xresources and merge that into Xrdb, it will have no immediate effect, since the existing setting will still persist in-memory until you restart your X session.

To get around this, you might issue xrdb -remove to drop all your customizations (and then reload them from file). Another solution is to use xrdb ~/.Xresources (without the -merge) to load exactly what is in that file (as opposed to merging). Useful if you have no other sources of configuration!

Now that you have a tailored baseline of how you expect Zutty to start up without any explicit options, remember that you can still override all options on the command line! For example, if you have Zutty.altScroll: true in your config, you might start Zutty with the +altScroll option to turn it off only in that instance.