merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
|
|
@ -1,33 +1,50 @@
|
|||
#+TITLE: term/vterm
|
||||
#+DATE: January 16, 2019
|
||||
#+SINCE: 2.1
|
||||
#+STARTUP: inlineimages
|
||||
# -*- mode: doom-docs-org -*-
|
||||
#+title: :term vterm
|
||||
#+subtitle: As good as terminal emulation gets in Emacs
|
||||
#+created: January 16, 2019
|
||||
#+since: 21.12.0 (#1144)
|
||||
|
||||
* 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
|
||||
* Description :unfold:
|
||||
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:
|
||||
#+begin_quote
|
||||
💡 [[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:
|
||||
|
||||
+ ~+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
|
||||
- Emacs must be built with dynamic modules support,
|
||||
- and =vterm-module.so= must be compiled, which depends on =libvterm=,
|
||||
=cmake=, and =libtool-bin=.
|
||||
|
||||
** Module Flags
|
||||
This module provides no flags.
|
||||
[[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?).
|
||||
#+end_quote
|
||||
|
||||
** Plugins
|
||||
+ [[https://github.com/akermu/emacs-libvterm][vterm]]
|
||||
** Maintainers
|
||||
- [[doom-user:][@hlissner]]
|
||||
|
||||
[[doom-contrib-maintainer:][Become a maintainer?]]
|
||||
|
||||
** Module flags
|
||||
/This module has no flags./
|
||||
|
||||
** Packages
|
||||
- [[doom-package:][vterm]]
|
||||
|
||||
** Hacks
|
||||
/No hacks documented for this module./
|
||||
|
||||
** TODO Changelog
|
||||
# This section will be machine generated. Don't edit it by hand.
|
||||
/This module does not have a changelog yet./
|
||||
|
||||
* Installation
|
||||
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
||||
|
||||
* Prerequisites
|
||||
+ Emacs must be built with dynamic module support, i.e. compiled with the
|
||||
=--with-modules= option.
|
||||
+ You need =libvterm= installed on your system.
|
||||
|
|
@ -35,12 +52,12 @@ This module provides no flags.
|
|||
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.
|
||||
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=).
|
||||
You can also check for ~--with-modules~ in the ~system-configuration-options~
|
||||
variable ([[kbd:][SPC h v system-configuration-options]]).
|
||||
|
||||
- Archlinux or Manjaro users who installed Emacs through pacman will have
|
||||
support baked in.
|
||||
|
|
@ -48,76 +65,103 @@ variable (=SPC h v system-configuration-options=).
|
|||
- 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~
|
||||
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:
|
||||
- Ubuntu or Debian users: ~$ apt-get install libvterm-dev~
|
||||
- ArchLinux or Manjaro: ~$ pacman -S libvterm~
|
||||
- MacOS: ~$ brew install libvterm~
|
||||
- NixOS:
|
||||
|
||||
#+BEGIN_SRC nix
|
||||
#+begin_src nix
|
||||
systemPackages = with pkgs; [
|
||||
# emacs # no need for this, the next line includes emacs
|
||||
((emacsPackagesNgGen emacs).emacsWithPackages (epkgs: [
|
||||
((emacsPackagesFor emacs).emacsWithPackages (epkgs: [
|
||||
epkgs.vterm
|
||||
]))
|
||||
];
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
Or for home-manager users:
|
||||
|
||||
#+BEGIN_SRC nix
|
||||
#+begin_src nix
|
||||
programs.emacs = {
|
||||
enable = true;
|
||||
extraPackages = epkgs: [ epkgs.vterm ];
|
||||
};
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
This already contains a version of =vterm-module.so=, so NixOS users need
|
||||
not compile the module themselves as described below.
|
||||
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.
|
||||
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)
|
||||
- =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
|
||||
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
|
||||
e.g. To use a local build of libvterm instead of the included one:
|
||||
#+begin_src emacs-lisp
|
||||
(setq vterm-module-cmake-args "-DUSE_SYSTEM_LIBVTERM=yes")
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
*WARNING*: Emacs will hang during the compilation. It may take a while.
|
||||
#+begin_quote
|
||||
🚧 Emacs will hang during the compilation. It may take a while.
|
||||
#+end_quote
|
||||
|
||||
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
|
||||
directory (usually =$HOME/.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
|
||||
#+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=
|
||||
=$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.
|
||||
|
||||
* TODO Usage
|
||||
#+begin_quote
|
||||
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
The following commands are available to open it:
|
||||
|
||||
- ~+vterm/toggle~ ([[kbd:][<leader> o t]]) -- Toggle vterm pop up window in the current
|
||||
project.
|
||||
- ~+vterm/here~ ([[kbd:][<leader> o T]]) -- Opens vterm in the current window.
|
||||
|
||||
* TODO Configuration
|
||||
#+begin_quote
|
||||
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
|
||||
#+end_quote
|
||||
|
||||
* Troubleshooting
|
||||
/There are no known problems with this module./ [[doom-report:][Report one?]]
|
||||
|
||||
* Frequently asked questions
|
||||
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
||||
|
||||
* TODO Appendix
|
||||
#+begin_quote
|
||||
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
||||
#+end_quote
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue