#+TITLE:   term/vterm
#+DATE:    April 4, 2022
#+SINCE:   3.0
#+STARTUP: inlineimages

* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
  - [[#module-flags][Module Flags]]
  - [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
  - [[#dynamic-module-support][Dynamic Module support]]
  - [[#libvterm][libvterm]]
  - [[#compilation-tools-for-vterm-moduleso][Compilation tools for vterm-module.so]]

* Description
This module provides a terminal emulator powered by libvterm.

The following commands are available to open it:

+ ~+vterm/other-window~ (=C-c o t=): Opens vterm in other window
+ ~+vterm/project/other-window~ (=C-c o p=): Opens vterm in the current project
  in other window
+ ~+vterm/here~ (=C-c o T=): Opens vterm in the current window
+ ~+vterm/project/here~ (=C-c o P=): Opens vterm in the current project in the
  current window

These commands will first try to find an existing suitable vterm buffer and open
it. If one does not exist, they will create a new one. If the current buffer is
such a vterm buffer, a new vterm session will be created.

** Module Flags
This module provides no flags.

** Plugins
+ [[https://github.com/akermu/emacs-libvterm][vterm]]

* 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 (=C-c h v system-configuration-options=).

** libvterm
+ Ubuntu or Debian users: ~apt-get install libvterm-dev~

** 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)