2018-01-11 23:14:24 +01:00
|
|
|
* ob-tmux
|
|
|
|
Ob-tmux is an Emacs library that allows org mode to evaluate code
|
|
|
|
blocks in a tmux session.
|
2018-01-11 23:33:13 +01:00
|
|
|
|
|
|
|
Ob-tmux is useful for keeping notes on how to perform tasks in the
|
|
|
|
terminal, especially when some interactivity is required. The
|
|
|
|
functionality can be used to document software installation, build
|
|
|
|
instructions, and administrative tasks. The documentation can be
|
|
|
|
tested and adjusted while it is written.
|
2018-01-11 23:14:24 +01:00
|
|
|
* Installation
|
|
|
|
Unfortunately, ob-tmux has not yet been added to melpa. You will need
|
|
|
|
to copy the ~ob-tmux.el~ file to a directory in your ~load-path~.
|
|
|
|
** Configuration
|
|
|
|
In your ~.emacs~ or ~.emacs.d/init.el~ file, add the following:
|
|
|
|
#+BEGIN_SRC elisp
|
|
|
|
(require 'ob-tmux)
|
|
|
|
(setq org-babel-default-header-args:tmux
|
|
|
|
'((:results . "silent") ;
|
|
|
|
(:session . "default") ; The default tmux session to send code to
|
|
|
|
;; You can use xterm or gnome terminal
|
|
|
|
(:terminal . "gnome-terminal")))
|
|
|
|
|
|
|
|
;; The tmux sessions are prefixed with the following string.
|
|
|
|
;; You can customize this if you like.
|
|
|
|
(setq org-babel-tmux-session-prefix "org-babel-session-")
|
|
|
|
|
2018-01-11 23:33:13 +01:00
|
|
|
;; Syntax highlighting can be added with the following line:
|
|
|
|
(add-to-list 'org-src-lang-modes (cons "tmux" 'sh))
|
|
|
|
|
|
|
|
;; Finally, if your tmux is not in your $PATH for whatever reason, you
|
2018-01-11 23:14:24 +01:00
|
|
|
;; may set the path to the tmux binary as follows:
|
|
|
|
(setq org-babel-tmux-location "/usr/bin/tmux")
|
2018-01-11 23:33:13 +01:00
|
|
|
|
|
|
|
|
2018-01-11 23:14:24 +01:00
|
|
|
#+END_SRC
|
|
|
|
* Usage
|
|
|
|
You can start a new terminal window with a tmux session as follows:
|
|
|
|
: #+BEGIN_SRC tmux :session hello
|
|
|
|
: echo hello
|
|
|
|
: #+END_SRC
|
2018-01-11 23:33:13 +01:00
|
|
|
If you press =C-c C-c= with your point in the code block, a terminal
|
|
|
|
window will pop up with a new tmux session named
|
2018-01-11 23:14:24 +01:00
|
|
|
=org-babel-session-hello=.
|
|
|
|
|
|
|
|
You can continue work in this session with another code block.
|
|
|
|
: #+BEGIN_SRC tmux :session hello
|
|
|
|
: echo world
|
|
|
|
: #+END_SRC
|
|
|
|
If you press =C-c C-c= now, no new terminal window will open, but the
|
|
|
|
code will be sent to the existing tmux session.
|
|
|
|
|
2018-01-11 23:33:13 +01:00
|
|
|
You can also specify to which tmux window the source block should be
|
|
|
|
sent. If the tmux window does not yet exist, ob-tmux will create it.
|
|
|
|
To specify the window, you may use the tmux target syntax. In the
|
|
|
|
following example, the ~:session~ argument has been changed to
|
|
|
|
=hello:new-world=:
|
2018-01-11 23:14:24 +01:00
|
|
|
: #+BEGIN_SRC tmux :session hello:new-window
|
|
|
|
: echo hello world in new-window
|
|
|
|
: #+END_SRC
|
|
|
|
Executing this code block will add a window, ~new-window~, to your
|
|
|
|
session.
|
|
|
|
|
|
|
|
You can exit your tmux session by detaching. The terminal window will
|
|
|
|
close automatically. Ob-tmux will not detect that you have
|
2018-01-11 23:33:13 +01:00
|
|
|
detached. Any commands you send will be sent to the tmux session in
|
|
|
|
the background. You can reattach to your tmux session at any time and
|
|
|
|
check that the commands have indeed been executed.
|
2018-01-11 23:14:24 +01:00
|
|
|
|
2018-01-11 23:33:13 +01:00
|
|
|
*Tip*. Ob-tmux is also very useful for restarting your tmux sessions
|
|
|
|
after a reboot. Take a Look at the following snippet.
|
2018-01-11 23:14:24 +01:00
|
|
|
: ** Startup tmux
|
|
|
|
: Use ~C-c C-v s~ to execute subtree.
|
|
|
|
: *** Jupyter
|
|
|
|
: #+BEGIN_SRC tmux :session daemons:jupyter
|
|
|
|
: cd ~/projects/notebooks/
|
|
|
|
: jupyter notebook
|
|
|
|
: #+END_SRC
|
|
|
|
: *** htop
|
|
|
|
: #+BEGIN_SRC tmux session daemons:htop
|
|
|
|
: htop
|
|
|
|
: #+END_SRC
|
|
|
|
: *** dmesg
|
|
|
|
: #+BEGIN_SRC tmux :session daemons:dmesg
|
|
|
|
: dmesg
|
|
|
|
: #+END_SRC
|
|
|
|
If your point is on the =Startup tmux= header, you can execute all
|
2018-01-11 23:33:13 +01:00
|
|
|
code blocks in the subtree with ~C-c C-v s~ to restart your favorite
|
|
|
|
tmux sessions.
|
2018-01-11 23:14:24 +01:00
|
|
|
|
|
|
|
* Known bugs and or possible issues
|
|
|
|
My tmux indexes start at 1. By default, tmux window indexes start at
|
|
|
|
zero. This might lead to problems. I have not yet checked.
|
|
|
|
|
|
|
|
Terminals other than xterm and gnome-terminal have not been
|
2018-01-11 23:33:13 +01:00
|
|
|
tested. If you have positive or negative experiences with any other
|
2018-01-11 23:14:24 +01:00
|
|
|
terminal, let me know.
|
|
|
|
|
|
|
|
I will try to respond within a week to any issues raised. I cannot
|
|
|
|
promise I will fix them.
|
|
|
|
* Contributions
|
|
|
|
Contributions are always welcome. Please be in touch before you make
|
|
|
|
sweeping changes or add large features. This may prevent
|
|
|
|
disappointment and will help me help you.
|