Skip to content

Latest commit

 

History

History
123 lines (97 loc) · 4.2 KB

README.org

File metadata and controls

123 lines (97 loc) · 4.2 KB
Raw

term/vterm

Table of Contents

Description

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

The following commands are available to open it:

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

Module Flags

This module provides no flags.

Plugins

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.

Dynamic Module support

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

You can also check for --with-modules in the system-configuration-options variable (SPC h 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 the option: brew install emacs-mac --with-modules

libvterm

  • Ubuntu or Debian users: apt-get install libvterm-dev
  • ArchLinux or Manjaro: pacman -S libvterm
  • MacOS: 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.

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.

  2. 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
  3. 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.