:term vterm

As good as terminal emulation gets in Emacs

1. Description

This module provides a terminal emulator powered by libvterm. It is still in alpha and requires a component be compiled (vterm-module.so).

vterm is as good as terminal emulation gets in Emacs (at the time of writing) and the most performant, as it is implemented in C. However, it requires extra steps to set up:

  • Emacs must be built with dynamic modules support
  • You must compile vterm-module.so, which has external dependencies (libvterm, cmake and libtool-bin).

vterm will try to automatically build vterm-module.so when you first open it, but this will fail on Windows, NixOS and Guix out of the box. Install instructions for nix/guix can be found in the :term vterm module’s documentation. There is no way to install vterm on Windows that I’m aware of (but perhaps with WSL?).

1.1. Maintainers

This module has no dedicated maintainers. Become a maintainer?

1.2. Module flags

This module has no flags.

1.4. Hacks

No hacks documented for this module.

2. Prerequisites

  • Emacs must be built with dynamic module support, i.e. compiled with the --with-modules option.
  • You need libvterm installed on your system.
  • You need make, cmake and a C compiler such as gcc so that vterm can build vterm-module.so.

2.1. Dynamic Module support

To check if your build of Emacs was built with dynamic module support, check $ doom info for MODULES in the “features” row. If it’s there, you’re good to go.

You can also check for --with-modules in the system-configuration-options variable (<help> v system-configuration-options).

  • Archlinux or Manjaro users who installed Emacs through pacman will have support baked in.
  • MacOS users:
    • If you use Emacs For Mac OS X, this option is enabled.
    • If you use emacs-plus, this option is enabled by default.
    • If you use emacs-mac, this options is not enabled by default. You may have to reinstall emacs with: $ brew install emacs-mac --with-modules

2.2. libvterm

  • Ubuntu or Debian users: $ apt-get install libvterm-dev
  • ArchLinux or Manjaro: $ pacman -S libvterm
  • MacOS: $ brew install libvterm

  • NixOS:

    # ⎘
    systemPackages = with pkgs; [
  # emacs    # no need for this, the next line includes emacs
  ((emacsPackagesNgGen emacs).emacsWithPackages (epkgs: [
    epkgs.vterm
  ]))
];

    Or for home-manager users:

    # ⎘
    programs.emacs = {
  enable = true;
  extraPackages = epkgs: [ epkgs.vterm ];
};

    This already contains a version of vterm-module.so, so NixOS users need not compile the module themselves as described below.

    Note: The nixpkgs-version that is used needs to be compatible with the rest of the plugins installed in doom. Therefore it might be necessary to pull in emacs and/or emacsPackagesNgGen from unstable or another channel. Otherwise arbitrary functionality of vterm might not work.

2.3. Compilation tools for vterm-module.so

When you first load vterm, it will compile vterm-module.so for you. For this to succeed, you need the following:

  • make
  • cmake
  • A C compiler like gcc
  • An internet connection (cmake will download needed libraries)

There are several ways to manually install the module:

  1. You can use M-x vterm-module-compile to let emacs automatically compile and install the module.

    Modify vterm-module-cmake-args to pass arguments to the cmake build script. e.g. To use a local build of libvterm instead of the included one.

    # ⎘
    (setq vterm-module-cmake-args "-DUSE_SYSTEM_LIBVTERM=yes")

WARNING: Emacs will hang during the compilation. It may take a while.

  1. You can compile and install the module yourself. Go to the vterm installation directory (usually ~/.emacs.d/.local/packages/elpa/vterm-<version>) and run the following:

    # ⎘
    $ mkdir -p build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
$ make
  2. You can also compile vterm-module.so elsewhere, but the module must be moved/symlinked to ~/.emacs.d/.local/packages/elpa/vterm-<version>/vterm-module.so vterm-module.so. Keep in mind that this folder will be deleted whenever the vterm package is updated.

3. TODO Usage

The following commands are available to open it:

  • +vterm/toggle (<leader> t): Toggle vterm pop up window in the current project
  • +vterm/here (<leader> T): Opens vterm in the current window

4. TODO Configuration

This module has no configuration documentation yet. Write some?

5. Troubleshooting

There are no known problems with this module. Report one?

6. TODO Appendix

This module has no appendix yet. Write one?