Termonad

Termonad is a terminal emulator configurable in Haskell. It is extremely customizable and provides hooks to modify the default behavior. It can be thought of as the "XMonad" of terminal emulators.

Termonad was featured on an episodeof DistroTube. This video gives a short overview of Termonad.

Table of Contents

• Termonad
  • Installation
    • Arch Linux
    • Ubuntu / Debian
    • Nix
    • Mac OS X
      • Installing with juststack
      • Installing with justnix
      • Installing withstackusingnix
    • Windows
  • How to use Termonad
    • Default Key Bindings
    • Configuring Termonad
    • Compiling Local Settings
      • Running withstack
      • Running withnix
  • Goals
  • Where to get help
  • Contributions
  • Maintainers

Installation

Termonad can be installed on any system as long as the necessary GTK libraries are available. The following are instructions for installing Termonad on a few different distributions and systems. If the given steps don't work for you, or you want to add instructions for an additional system, please send a pull request.

The following steps use the stackbuild tool to build Termonad, butcabalcan be used as well. Steps for installingstackcan be found on this page.

Arch Linux

First, you must install the required Gnome/GTK system libraries:

$ pacman -S vte3 gobject-introspection

In order to install Termonad, clone this repository and runstack install. This will install thetermonadbinary to~/.local/bin/:

$ git clone https://github /cdepillabout/termonad
$cdtermonad/
$ stack install

Note that Termonad depends on thehaskell-gifamily of Haskell libraries.haskell-gicontains Haskell wrappers for for Gnome/GTK system libraries. It uses theGObject Introspectionfunctionality from the Gnome libraries.

One problem that Arch users often run into is that their system Gnome/GTK libraries are newer than what thehaskell-gidependencies from Stackage support. If you run into this problem, there are a couple things you can try:

• Manually switch to a newer Stackage resolver (probably Stackage Nightly). Newer Stackage resolvers often have newer versions of thehaskell-gilibraries. Newer versions of thehaskell-gilibraries are more likely to support your newer system Gnome/GTK libraries. If you get something working like this, please open a PR.
• Usecabalfor building Termonad instead ofstack.Make surecabal's constraint solver picks the latest versions of thehaskell-gilibraries on Hackage.
• Use Nix for installing Termonad.

My suggestion is to use Nix, since it is highly likely to "just work" (because with Nix,alllibraries are pinned to known working versions, even system libraries).

Ubuntu / Debian

Termonad can be installed throughapton Debian and Ubuntu:

$sudo apt install termonad libghc-termonad-dev

Note that thelibghc-termonad-devpackage is necessary if you want to be able to compile the Haskell-based settings file,termonad.hs.

Compiling from source on Ubuntu / Debian

First, you must install the required Gnome/GTK system libraries:

$ apt-get install gobject-introspection libgirepository1.0-dev libgtk-3-dev libvte-2.91-dev libpcre2-dev

In order to install Termonad, clone this repository and runstack install. This will install thetermonadbinary to~/.local/bin/:

$ git clone https://github /cdepillabout/termonad
$cdtermonad/
$ stack install

Nix

If you havenixinstalled, you should be able to use it to obtain Termonad. This means that it will work on NixOS, or withnixon another distro. There are three different ways to usenixto get Termonad:

1. Get Termonad from Nixpkgs. Termonad is provided as a top-leveltermonad attribute in Nixpkgs.

   For instance, run anix-shellwith Termonad:

   $nix-shell -p termonad
   $termonad#run termonad within the nix-shell

   You can also installtermonadwith tools likenix-envor home-manager. If you're using NixOS, you can addtermonadto your environment.systemPackageslist.

   Keep in mind that if you're using an old release of NixOS, you'll likely get an older version of Termonad.

2. Build Termonad using the code in this repository. The following commands clone this repo and build thetermonadbinary at./result/bin/:

   $ git clone https://github /cdepillabout/termonad
   $cdtermonad/
   $ nix-build

3. Build Termonad usingstackwith Nix-integration. The following commands installstackfor your user, clone this repository, and install the termonadbinary to~/.local/bin/:

   $ nix-env -i stack
   $ git clone https://github /cdepillabout/termonad
   $cdtermonad/
   $ stack --nix install

   (edit:Building withstackusing Nix-integration does not currently work. See#99.)

Mac OS X

Building and installing Termonad on Mac OS X should be possible with any of the following three methods:

• Install the required system libraries (like GTK and VTE) by hand, then use stackto build Termonad.

  This is probably the easiest method. You don't have to understand anything aboutnix.However, it is slightly annoying to have to install GTK and VTE by hand.

• Usenixto install both the required system libraries and Termonad itself.

  If you are a nix user and want an easy way to install Termonad, this is the recommended method.

• Usenixto install install the required system libraries, andstackto build Termonad.

  If you are a nix user, but want to usestackto actually do development on Termonad, usingstackmay be easier than usingcabal.

The following sections describe each method.

Installing with juststack

(currently no instructions available. please send a PR adding instructions if you get termonad to build using this method.)

Installing with justnix

nixcan be used to install Termonad with the following steps, assuming you havenixinstalled.These commands clone this repository and build thetermonadbinary at./result/bin/:

$ git clone https://github /cdepillabout/termonad
$cdtermonad/
$ nix-build

Installing withstackusingnix

stackcan be used in conjunction withnixto install Termonad.nixwill handle installing system dependencies (like GTK and VTE), whilestackwill handle compiling and installing Haskell packages.

You must havenixinstalled.

You will also needstackinstalled. You can do that with the following command:

$ nix-env -i stack

Afterstackis installed, you will need to clone Termonad and build it:

$ git clone https://github /cdepillabout/termonad
$ cd termonad/
$ stack --nix install

This will install thetermonadbinary to~/.local/bin/.

Windows

To run Termonad on Windows, you'll need:

• any X server app, for exampleVcxsrv
• any WSL, for exampleUbuntu

I'm using both Vcxsrv and Ubuntu WSL.

Configure both Vcxsrv and WSL. For Vcxsrv go with default settings everywhere, it will be fine. Configure your WSL as you want (choose your name etc.). After you set up the user, you'll have to update your OS, run:

$sudo apt-get update
$sudo apt-get upgrade -y
$sudo apt-get dist-upgrade -y
$sudo apt-get autoremove -y

Configure theDISPLAYenvironment variable for the X server, and load the changes in bash:

For WSL1:

$echo"export DISPLAY=localhost:0.0">>~/.bashrc
$source~/.bashrc

For WSL2:

$echoexportDISPLAY=$(awk'/nameserver / {print $2; exit}'/etc/resolv.conf2>/dev/null):0>>~/.bashrc
$echoexportLIBGL_ALWAYS_INDIRECT=1>>~/.bashrc
$source~/.bashrc

If you're using WSL2, you have to create a separateinbound rulefor TCP port 6000, to allow WSL access to the X server. If you're using mentioned earlierVcxsrvyou can enable public access for your X server by disabling Access Control on the Extra Settings. You can also use-acflag in the Additional parameters for VcXsrv section.

Your X server should now be configured.

Execute following command to install the necessary GTK system libraries:

$apt-get install gobject-introspection libgirepository1.0-dev libgtk-3-dev libvte-2.91-dev libpcre2-dev

The required GTK system libraries should now be installed.

Clone the Termonad repo:

$ git clone https://github /cdepillabout/termonad
$cdtermonad/
$ stack build
$ stack run

Afterstack run,you should see a new window with your Termonad running.

How to use Termonad

Termonad is similar to XMonad. The above steps will install atermonadbinary somewhere on your system. If you have installed Termonad usingstack,the termonadbinary will be in~/.local/bin/.If you have installed Termonad using your Linux distro, thetermonadbinary will likely be in/usr/bin/.This binary is a version of Termonad configured with default settings. You can try running it to get an idea of what Termonad is like:

$ /usr/bin/termonad

If you would like to configure Termonad with your own settings, first you will need to create a Haskell file called~/.config/termonad/termonad.hs.A following section gives an example configuration file.

If this configuration file exists, when the/usr/bin/termonadbinary launches, it will try to use GHC to compile the configuration file. If GHC is able to successfully compile the configuration file, a separate binary will be created called something like~/.cache/termonad/termonad-linux-x86_64. This binary file can be thought of as your own personal Termonad, configured with all your own settings.

When you run/usr/bin/termonad,it will re-exec ~/.cache/termonad/termonad-linux-x86_64if it exists.

However, there is one difficulty with this setup. In order for the /usr/bin/termonadbinary to be able to compile your ~/.config/termonad/termonad.hsconfiguration file, Termonad needs to know where GHC is, as well as where all your Haskell packages live. This presents some difficulties that will be discussed in one of the following sections.

Default Key Bindings

Termonad provides the following default key bindings.

Key binding	Action
CtrlShiftt	Open new tab.
CtrlShiftw	Close tab.
CtrlShiftf	Open Find dialog for searching for a regex.
CtrlShiftp	Find the regexabovethe current position.
CtrlShifti	Find the regexbelowthe current position.
Ctrl+	Increase font size.
Ctrl-	Decrease font size.
CtrlPgUp	Switch to previous tab.
CtrlPgDown	Switch to next tab.
Alt(number key)	Switch to tabnumber.For example,Alt2switches to tab 2.

Configuring Termonad

Termonad has three different ways to be configured.

1. Pass arguments on the command line. For instance, run termonad --no-show-menuto never show theFilemenubar.

   Arguments passed on the command line will normally override other configuration methods.

2. Use the built-in Preferences editor. You can find this in thePreferencesmenu underEditin the menubar.

   When opening Termonad for the first time, it will create a preferences file at~/.config/termonad/termonad.yaml.When you change a setting in the Preferences editor, Termonad will update the setting in the preferences file.

   When running Termonad, it will load settings from the preferences file. Do not edit the preferences file by hand, because it will be overwritten when updating settings in the Preferences editor.

   This method is perfect for users who only want to make small changes to the Termonad settings, like the default font size.

3. Use a Haskell-based settings file, called~/.config/termonad/termonad.hsby default. This method allows you to make large, sweeping changes to Termonad. This method is recommended for power users.

   The rest of this section explains the~/.config/termonad/termonad.hsfile.

WARNING: If you have a~/.config/termonad/termonad.hsfile, then all settings from~/.config/termonad/termonad.yamlwill be ignored. If you want to setANYsettings in~/.config/termonad/termonad.hs,then you must setALLsettings in~/.config/termonad/termonad.hs.However, as stated above, CLI arguments will override settings in~/.config/termonad/termonad.hsby default.

The following is an example Termonad configuration file. You should save this to ~/.config/termonad/termonad.hs.You can find more information on the available configuration options within the Termonad.Config module.

{-#LANGUAGEOverloadedStrings #-}

moduleMainwhere

importTermonad
(FontConfig,FontSize(FontSizePoints),Option(Set)
,ShowScrollbar(ShowScrollbarAlways),defaultConfigOptions,defaultFontConfig
,defaultMain,defaultTMConfig,fontConfig,fontFamily,fontSize,options
,showScrollbar
)
importTermonad.Config.Colour
(AlphaColour,ColourConfig,addColourExtension,createColour
,createColourExtension,cursorBgColour,defaultColourConfig
)

--|This sets the color of the cursor in the terminal.
--
--This uses the "Data.Colour" module to define a dark-red color.
--There are many default colors defined in "Data.Colour.Names".
cursBgColour::AlphaColourDouble
cursBgColour=createColour20400

--|This sets the colors used for the terminal. We only specify the background
--color of the cursor.
colConf::ColourConfig(AlphaColourDouble)
colConf=
defaultColourConfig
{ cursorBgColour=SetcursBgColour
}

--|This defines the font for the terminal.
fontConf::FontConfig
fontConf=
defaultFontConfig
{ fontFamily="DejaVu Sans Mono"
,fontSize=FontSizePoints13
}

main::IO()
main=do
colExt<-createColourExtension colConf
lettermonadConf=
defaultTMConfig
{ options=
defaultConfigOptions
{ fontConfig=fontConf
--Make sure the scrollbar is always visible.
,showScrollbar=ShowScrollbarAlways
}
}
`addColourExtension`colExt
defaultMain termonadConf

There are other example configuration files in the example-config/directory.

If you want to test what all the colors look like, you may find it convenient to use the print-console-colors package, which provides an executable calledprint-console-colorsthat prints all of the colors for your terminal.

Compiling Local Settings

If you launch Termonad by calling/usr/bin/termonad,it will try to compile the~/.config/termonad/termonad.hsfile if it exists. The problem is that/usr/bin/termonadneeds to be able to see GHC and the required Haskell libraries to be able to compile~/.config/termonad/termonad.hs.

There are a couple solutions to this problem, listed in the sections below.

(These steps are definitely confusing. I would love to figure out a better way to do this. Please submit an issue or PR if you have a good idea about how to fix this.)

Running withstack

If you originally compiled Termonad withstackand installed it to ~/.local/bin/termonad,you can usestackto execute Termonad. First, you must change to the directory with the Termonad source code. From there, you can runstack exec:

$cdtermonad/#change to the termonad source code directory
$ stackexec-- termonad

stackwill pick up the correct GHC version and libraries from the stack.yamlandtermonad.cabalfile.termonadwill be run in an environment with GHC available.termonadwill use this GHC and libraries to compile your~/.config/termonad/termonad.hsfile. It if succeeds, it should create a~/.cache/termonad/termonad-linux-x86_64binary.

If you need extra Haskell libraries available when compiling your ~/.config/termonad/termonad.hsfile, you can specify them tostack exec:

$ stackexec--package lens --package conduit -- termonad

The problem with this is thatstack execchanges quite a few of your environment variables. It is not recommended to actually run Termonad from withinstack exec.After you runstack exec -- termonadand let it recompile your~/.config/termonad/termonad.hsfile, exit Termonad. Re-run Termonad by calling it directly. Termonad will notice that ~/.config/termonad/termonad.hshasn't changed since ~/.cache/termonad/termonad-linux-x86_64has been recompiled, so it will directly execute~/.cache/termonad/termonad-linux-x86_64.

Running withnix

Building Termonad withnix(by runningnix-buildin the top directory) sets it up so that Termonad can see GHC. Termonad should be able to compile the~/.config/termonad/termonad.hsfile by default.

If you're interested in how this works, or want to change which Haskell packages are available from your~/.config/termonad/termonad.hsfile, please see the documentation in the .nix-helpers/termonad-with-packages.nix file.

Additional Info

This section contains some additional info that may be helpful for using Termonad.

Opening URLs by right-clicking

It is possible to open a URL in a browser by right-clicking on it, and selectingOpen URL in browser.In order for this you work, you may have to setup your XDG defaults. You can set the default browser to Firefox with a command like the following:

$xdg-mime default firefox.desktop x-scheme-handler/http
$xdg-mime default firefox.desktop x-scheme-handler/https

Thisxdg-mimeexecutable comes from a package calledxdg-utilsin both Nixpkgs and Ubutun/Debian.

Goals

Termonad has the following goals:

• fully configurable in Haskell

  There are already many good terminal emulators.However, there are no terminal emulators fully configurable in Haskell. Termonad fills this niche.

• flexible

  Most people only need a terminal emulator that lets you change the font-size, cursor color, etc. They don't need tons of configuration options. Termonad should be for people that like lots of configuration options. Termonad should provide many hooks to allow the user full control over its behavior.

• stable

  Termonad should be able to be used everyday as your main terminal emulator. It should not crash for any reason. If you experience a crash, please file an issue or a pull request!

• good documentation

  Thedocumentationfor Termonad on Hackage should be good. You shouldn't have to guess at what certain data types or functions do. If you have a hard time understanding anything in the documentation, please submit an issue or PR.

Where to get help

If you find a bug in Termonad, please either send a PRfi xing it or create anissueexplaining it.

If you just need help with configuring Termonad, you can either join the Gitter roomor #termonad on irc.freenode.net.

Contributions

Contributions are highly appreciated. Termonad is currently missing many helpful configuration options and behavior hooks. If there is something you would like to add, please submit an issue or PR.

Maintainers

• cdepillabout