This is the official manual for the latest Org-mode release.

Table of Contents

Next: , Previous: Publishing, Up: Top


14 Working with source code

Source code here refers to any code typed in Org mode documents. Org can manage source code in any Org file once such code is tagged with begin and end markers. Working with source code begins with tagging source code blocks. Tagged source code blocks are not restricted to the preamble or the end of an Org document; they can go anywhere (with a few exceptions, such as not inside comments and fixed width areas). Here's a sample ‘src’ block in emacs-lisp:

     #+BEGIN_SRC emacs-lisp
       (defun org-xor (a b)
          "Exclusive or."
          (if a (not b) b))
     #+END_SRC

Org can take the code in the block between the ‘#+BEGIN_SRC’ and ‘#+END_SRC’ tags, and format, compile, execute, and show the results. Org can simplify many housekeeping tasks essential to modern code maintenance. That's why these blocks in Org mode literature are sometimes referred to as ‘live code’ blocks (as compared to the static text and documentation around it). Users can control how ‘live’ they want each block by tweaking the headers for compiling, execution, extraction, and so on.

For editing ‘src’ code blocks, Org offers native Emacs major-modes. That leverages all the latest Emacs features for that source code language mode.

For exporting, Org can then extract ‘src’ code blocks into compilable source files (in a conversion process known as tangling in literate programming terminology).

For publishing, Org's back-ends can handle the ‘src’ code blocks and the text for output to a variety of formats with native syntax highlighting.

For executing the source code in the ‘src’ code blocks, Org provides facilities that glue the tasks of compiling, collecting the results of the execution, and inserting them back to the Org file. Besides text output, results may include links to other data types that Emacs can handle: audio, video, and graphics.

An important feature of Org's execution of the ‘src’ code blocks is passing variables, functions, and results between ‘src’ blocks. Such interoperability uses a common syntax even if these ‘src’ blocks are in different source code languages. The integration extends to linking the debugger's error messages to the line in the source code block in the Org file. That should partly explain why this functionality by the original contributors, Eric Schulte and Dan Davison, was called ‘Org Babel’.

In literate programming, the main appeal is code and documentation co-existing in one file. Org mode takes this several steps further. First by enabling execution, and then by inserting results of that execution back into the Org file. Along the way, Org provides extensive formatting features, including handling tables. Org handles multiple source code languages in one file, and provides a common syntax for passing variables, functions, and results between source code blocks.

Org mode fulfills the promise of easy verification and maintenance of publishing reproducible research by keeping text, data, code, configuration settings of the execution environment, the results of the execution, and associated narratives, claims, references, and internal and external links—all in the same file.

Details of Org's facilities for working with source code are shown next.