Executing code in Org files with Babel

Abstract: a very short introduction into the word of Org Babel.

No other package seems to have had such huge impact on Emacs community as the introduction of Org Babel¹. It made folks not only love their Org Mode, but live in it.

In short: Babel allows for literate programming form within an Org document.

Source code basics

Babel comes baked into any modern version of Emacs, so you’ve already got everything you need. Open any org document, add the code to the document within source code blocks:

regular text

#+BEGIN_SRC emacs-lisp
(+ 1 1)
#+END_SRC

and more regular text

Now, move the pointer to with the blocks, tap C-c C-c and the code is evaluated. The result will be appended just below the source code, in a RESULT block.

You now know how to do literate programming in Emacs. Create an Org document, add your narrative, add your source code and execute. Simple, isn’t it?

By default, Babel allows only for execution of emacs-lisp mode, but it supports many more. You can enable all supported via:

(org-babel-do-load-languages 'org-babel-load-languages
                             '((shell      . t)
                               (js         . t)
                               (emacs-lisp . t)
                               (clojure    . t)
                               (python     . t)
                               (ruby       . t)
                               (dot        . t)
                               (css        . t)
                               (plantuml   . t)))

There are even more provided as dedicated packages.

Being faster

Typing #+BEGIN_SRC can become tedious pretty quick. We can use the org-tempo package to make it much faster.

(require 'org-tempo)
(setq org-structure-template-alist
      '(("s" . "src")))

Now, we can create new block simply by taping <s and pressing tab.

Org tempo supports many more blocks, you can refer to the official manual.

Joining the blocks together

In strict Literate Programming sense, your web/ should not be where you execute code. Instead, you should extract programmatic parts and run it separately - the process is called tangling.

Babel bypasses this limitation with noweb mode, in which code blocks can reference each other. First, you need to name your code blocks:

#+NAME: two
#+BEGIN_SRC emacs-lisp
(+ 1 1)
#+END_SRC

Then we can use it the result other code blocks

#+NAME: three
#+BEGIN_SRC emacs-lisp :noweb yes
(+ <<two>> 1)
#+END_SRC

Here, the <<two>> will be replaced with the result of block named two. This makes the block three return the number 3.

This mode gives quite a lot more option. You can read about them inside manual.

Running on remote machines

To make it even cooler, Babel integrates with Tramp mode which allows for execution over ssh! You can add a tramp-style header argument as :dir and the code will be executed over the established connection.

#+BEGIN_SRC shell :dir /user@host:~/
rm -rf /
#+END_SRC

And boom - we’ve got a bomb.

Babel as source for Emacs configuration

The most popular use case of Babel however is Emacs configuration. You can have as many org files as you want, have the configuration inside emacs-lisp code blocks and use that as config.

Loading files directly

If your config isn’t very complicated, you can force Emacs to parse the files on boot. To achieve that, add

(org-babel-load-file "~/.emacs.d/config.org")

To your init.el.

What happens is, that Emacs will create a corresponding config.el (tangle) file and load it as a elisp file. Just remember not to name your config as init.org as there will be naming conflict with init.el.

Pre-tangling

If you don’t want tangling on boot time, but rather want to have it ready you can manually org-babel-tangle. To achieve it, add a tangle header argument to all you code blocks:

#+BEGIN_SRC emacs-lisp :tangle ~/.emacs.d/init.el
(+ 1 1)
#+END_SRC

And then, after any changes of the file run org-babel-tangle and your init.el will be up-to-date. This is the approach Prot uses, but his config consists of over 17_000 [sic!] lines of org file, so your mileage may vary.