Next:Languages, Previous:Exporting Code Blocks, Up:Working with Source Code [Contents][Index]
Extracting source code from code blocks is a basic task in literateprogramming. Org has features to make this easy. In literateprogramming parlance, documents on creation arewoven with code anddocumentation, and on export, the code is tangled for execution bya computer. Org facilitates weaving and tangling for producing,maintaining, sharing, and exporting literate programming documents.Org provides extensive customization options for extracting sourcecode.
When Org tangles code blocks, it expands, merges, and transforms them.Then Org recomposes them into one or more separate files, asconfigured through the options. During this tangling process, Orgexpands variables in the source code, and resolves any noweb stylereferences (seeNoweb Reference Syntax).
The ‘tangle’ header argument specifies if the code block is exportedto source file(s).
Export the code block to source file. The file name for the sourcefile is derived from the name of the Org file, and the fileextension is derived from the source code language identifier.Example: ‘:tangle yes’.
The default. Do not extract the code in a source code file.Example: ‘:tangle no’.
Export the code block to source file whose file name is derived fromany string passed to the ‘tangle’ header argument. Org derives thefile name as being relative to the directory of the Org file’slocation. Example: ‘:tangle FILENAME’.
The ‘mkdirp’ header argument creates parent directories for tangledfiles if the directory does not exist. A ‘yes’ value enablesdirectory creation whereas ‘no’ inhibits it.
The ‘comments’ header argument controls inserting comments intotangled files. These are above and beyond whatever comments mayalready exist in the code block.
The default. Do not insert any extra comments during tangling.
Wrap the code block in comments. Include links pointing back to theplace in the Org file from where the code was tangled.
Kept for backward compatibility; same as ‘link’.
Nearest headline text from Org file is inserted as comment. Theexact text that is inserted is picked from the leading context ofthe source block.
Includes both ‘link’ and ‘org’ options.
Includes ‘link’ option, expands noweb references (seeNoweb Reference Syntax), and wraps them in link comments inside the bodyof the code block.
The ‘padline’ header argument controls insertion of newlines to padsource code in the tangled file.
Default. Insert a newline before and after each code block in thetangled file.
Do not insert newlines to pad the tangled code blocks.
The ‘shebang’ header argument can turn results into executable scriptfiles. By setting it to a string value—for example, ‘:shebang"#!/bin/bash"’—Org inserts that string as the first line of thetangled file that the code block is extracted to. Org then turns onthe tangled file’s executable permission.
The ‘tangle-mode’ header argument specifies what permissions to setfor tangled files byset-file-modes. Permissions are given by anoctal value, which can be provided calling theidentity function onan elisp octal value. For instance, to create a read-only file one mayuse ‘:tangle-mode (identity #o444)’. To reduce the verbosity required,a octal shorthand is defined, ‘oXXX’ (‘o’ for octal). Using this, ourread-only example is ‘:tangle-mode o444’. Omitting the ‘o’ prefix willcause the argument to be interpreted as an integer, which can lead tounexpected results (‘444’ is the same as ‘o674’).Two other shorthands are recognized, ls-style strings like‘rw-r--r--’, and chmod-style permissions like ‘g+w’.Note that chmod-style permissions are based onorg-babel-tangle-default-file-mode, which is ‘#o644’ by default.
When ‘:tangle-mode’ and ‘:shebang’ are both specified, the give‘:tangle-mode’ will override the permissions from ‘:shebang’. Whenmultiple source code blocks tangle to a single file with conflicting‘:tangle-mode’ header arguments, Org’s behavior is undefined.
By default Org expands code blocks during tangling. The ‘no-expand’header argument turns off such expansions. Note that one side-effectof expansion byorg-babel-expand-src-block also assigns values (seeEnvironment of a Code Block) to variables. Expansions also replacenoweb references with their targets (seeNoweb Reference Syntax).Some of these expansions may cause premature assignment, hence thisoption. This option makes a difference only for tangling. It has noeffect when exporting since code blocks for execution have to beexpanded anyway.
org-babel-tangle ¶Tangle the current file. Bound toC-c C-v t.
With prefix argument only tangle the current code block.
org-babel-tangle-file ¶Choose a file to tangle. Bound toC-c C-v f.
org-babel-pre-tangle-hook ¶This hook is run before the tangle process begins. The activebuffer is buffer to be tangled.
org-babel-tangle-body-hook ¶This hook is run from a temporary buffer containing expanded code ofevery tangled code block. The hook can modify the expanded code asneeded. The contents of the current buffer will be used as actualcode block expansion.
org-babel-post-tangle-hook ¶This hook is run from within code files tangled byorg-babel-tangle, making it suitable for post-processing,compilation, and evaluation of code in the tangled files.
org-babel-tangle-finished-hook ¶This hook is run after post-tangle hooks, in the original buffer.
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 tothe tangled source file. To make this extra jump, Org usesorg-babel-tangle-jump-to-org function with two additional sourcecode block header arguments:
Next:Languages, Previous:Exporting Code Blocks, Up:Working with Source Code [Contents][Index]