14.4 Extracting source code

Extracting source code from code blocks is a basic task in literate programming. Org has features to make this easy. In literate programming parlance, documents on creation are woven with code and documentation, and on export, the code is tangled for execution by a computer. Org facilitates weaving and tangling for producing, maintaining, sharing, and exporting literate programming documents. Org provides extensive customization options for extracting source code.

When Org tangles ‘src’ code blocks, it expands, merges, and transforms them. Then Org recomposes them into one or more separate files, as configured through the options. During this tangling process, Org expands variables in the source code, and resolves any Noweb style references (see Noweb reference syntax).

Header arguments

:tangle no

By default, Org does not tangle the ‘src’ code block on export.

:tangle yes

Org extracts the contents of the code block for the tangled output. By default, the output file name is the same as the Org file but with a file extension derived from the language identifier of the ‘src’ code block.

:tangle filename

Override the default file name with this one for the tangled output.

Functions

org-babel-tangle

Tangle the current file. Bound to C-c C-v t.

With prefix argument only tangle the current ‘src’ code block.

org-babel-tangle-file

Choose a file to tangle. Bound to C-c C-v f.

Hooks

org-babel-post-tangle-hook

This hook runs from within code tangled by org-babel-tangle, making it suitable for post-processing, compilation, and evaluation of code in the tangled files.

Jumping between code and Org

Debuggers normally link errors and messages back to the source code. But for tangled files, we want to link back to the Org file, not to the tangled source file. To make this extra jump, Org uses org-babel-tangle-jump-to-org function with two additional source code block header arguments: One, set padline (see padline) to true (the default setting). Two, set comments (see comments) to link, which makes Org insert links to the Org file.