eddc7db22c
I hit a problem with `epkgs.vterm` from `nixos-20.09` being too old and thus missing `vterm-goto-char` which is present in newer versions of `epkgs.vterm`. I added a note to clear this up for future users, and added two other changes/clarifications as well: * Changed `epkgs.emacs-libvterm` -> `epkgs.vterm`, as the old name is deprecated. * Added note that `epkgs.vterm` already contains a `vterm-module.so` * Added note that the version of `emacs` needs to be recent enough and that otherwise bugs might occur.
123 lines
4.2 KiB
Org Mode
123 lines
4.2 KiB
Org Mode
#+TITLE: term/vterm
|
|
#+DATE: January 16, 2019
|
|
#+SINCE: 2.1
|
|
#+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. 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
|
|
+ [[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 (=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 [[https://emacsformacosx.com/][Emacs For Mac OS X]], this option is enabled.
|
|
- If you use [[https://github.com/d12frosted/homebrew-emacs-plus][emacs-plus]], this option is enabled by default.
|
|
- If you use [[https://github.com/railwaycat/homebrew-emacsmacport][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:
|
|
|
|
#+BEGIN_SRC nix
|
|
systemPackages = with pkgs; [
|
|
# emacs # no need for this, the next line includes emacs
|
|
((emacsPackagesNgGen emacs).emacsWithPackages (epkgs: [
|
|
epkgs.vterm
|
|
]))
|
|
];
|
|
#+END_SRC
|
|
|
|
Or for home-manager users:
|
|
|
|
#+BEGIN_SRC nix
|
|
programs.emacs = {
|
|
enable = true;
|
|
extraPackages = epkgs: [ epkgs.vterm ];
|
|
};
|
|
#+END_SRC
|
|
|
|
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.
|
|
|
|
#+BEGIN_SRC elisp
|
|
(setq vterm-module-cmake-args "-DUSE_SYSTEM_LIBVTERM=yes")
|
|
#+END_SRC
|
|
|
|
*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:
|
|
|
|
#+BEGIN_SRC sh
|
|
mkdir -p build
|
|
cd build
|
|
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
|
|
make
|
|
#+END_SRC
|
|
|
|
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.
|