Skip to content

Latest commit

 

History

History
166 lines (131 loc) · 5.64 KB

README.org

File metadata and controls

166 lines (131 loc) · 5.64 KB
Raw

:term vterm

Description

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

💡 doom-package: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,
  • and vterm-module.so must be compiled, which depends on libvterm, cmake, and libtool-bin.

doom-package: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 doom-module::term vterm module’s documentation. There is no way to install vterm on Windows that I’m aware of (but perhaps with WSL?).

Maintainers

  • @hlissner

Become a maintainer?

Module flags

This module has no flags.

Packages

  • doom-package:vterm

Hacks

No hacks documented for this module.

Changelog

This module does not have a changelog yet.

Installation

Enable this module in your doom! block.

  • 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 $ 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: $ brew install libvterm
  • NixOS: 
    systemPackages = with pkgs; [
  # emacs    # no need for this, the next line includes emacs
  ((emacsPackagesFor 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 used must be compatible with the packages Doom installs, so it might be necessary to pull in emacs and/or emacsPackagesFor 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")

    🚧 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 $HOME/.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 $HOME/.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.

Usage

🔨 This module’s usage documentation is incomplete. Complete it?

The following commands are available to open it:

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

Configuration

🔨 This module has no configuration documentation yet. Write some?

Troubleshooting

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

Frequently asked questions

This module has no FAQs yet. Ask one?

Appendix

🔨 This module has no appendix yet. Write one?