+<div class="section" id="writing-a-tool-description">
+<h1><a class="toc-backref" href="#id13">Writing a tool description</a></h1>
+<p>As was said earlier, nodes in the compilation graph represent tools,
+which are described separately. A tool definition looks like this
+(taken from the <tt class="docutils literal"><span class="pre">include/llvm/CompilerDriver/Tools.td</span></tt> file):</p>
+<pre class="literal-block">
+def llvm_gcc_cpp : Tool<[
+ (in_language "c++"),
+ (out_language "llvm-assembler"),
+ (output_suffix "bc"),
+ (cmd_line "llvm-g++ -c $INFILE -o $OUTFILE -emit-llvm"),
+ (sink)
+ ]>;
+</pre>
+<p>This defines a new tool called <tt class="docutils literal"><span class="pre">llvm_gcc_cpp</span></tt>, which is an alias for
+<tt class="docutils literal"><span class="pre">llvm-g++</span></tt>. As you can see, a tool definition is just a list of
+properties; most of them should be self-explanatory. The <tt class="docutils literal"><span class="pre">sink</span></tt>
+property means that this tool should be passed all command-line
+options that aren't mentioned in the option list.</p>
+<p>The complete list of all currently implemented tool properties follows.</p>
+<ul class="simple">
+<li>Possible tool properties:<ul>
+<li><tt class="docutils literal"><span class="pre">in_language</span></tt> - input language name. Can be either a string or a
+list, in case the tool supports multiple input languages.</li>
+<li><tt class="docutils literal"><span class="pre">out_language</span></tt> - output language name. Tools are not allowed to
+have multiple output languages.</li>
+<li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - output file suffix. Can also be changed
+dynamically, see documentation on actions.</li>
+<li><tt class="docutils literal"><span class="pre">cmd_line</span></tt> - the actual command used to run the tool. You can
+use <tt class="docutils literal"><span class="pre">$INFILE</span></tt> and <tt class="docutils literal"><span class="pre">$OUTFILE</span></tt> variables, output redirection
+with <tt class="docutils literal"><span class="pre">></span></tt>, hook invocations (<tt class="docutils literal"><span class="pre">$CALL</span></tt>), environment variables
+(via <tt class="docutils literal"><span class="pre">$ENV</span></tt>) and the <tt class="docutils literal"><span class="pre">case</span></tt> construct.</li>
+<li><tt class="docutils literal"><span class="pre">join</span></tt> - this tool is a "join node" in the graph, i.e. it gets a
+list of input files and joins them together. Used for linkers.</li>
+<li><tt class="docutils literal"><span class="pre">sink</span></tt> - all command-line options that are not handled by other
+tools are passed to this tool.</li>
+<li><tt class="docutils literal"><span class="pre">actions</span></tt> - A single big <tt class="docutils literal"><span class="pre">case</span></tt> expression that specifies how
+this tool reacts on command-line options (described in more detail
+below).</li>
+</ul>
+</li>
+</ul>
+<div class="section" id="actions">
+<h2><a class="toc-backref" href="#id14">Actions</a></h2>
+<p>A tool often needs to react to command-line options, and this is
+precisely what the <tt class="docutils literal"><span class="pre">actions</span></tt> property is for. The next example
+illustrates this feature:</p>
+<pre class="literal-block">
+def llvm_gcc_linker : Tool<[
+ (in_language "object-code"),
+ (out_language "executable"),
+ (output_suffix "out"),
+ (cmd_line "llvm-gcc $INFILE -o $OUTFILE"),
+ (join),
+ (actions (case (not_empty "L"), (forward "L"),
+ (not_empty "l"), (forward "l"),
+ (not_empty "dummy"),
+ [(append_cmd "-dummy1"), (append_cmd "-dummy2")])
+ ]>;
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">actions</span></tt> tool property is implemented on top of the omnipresent
+<tt class="docutils literal"><span class="pre">case</span></tt> expression. It associates one or more different <em>actions</em>
+with given conditions - in the example, the actions are <tt class="docutils literal"><span class="pre">forward</span></tt>,
+which forwards a given option unchanged, and <tt class="docutils literal"><span class="pre">append_cmd</span></tt>, which
+appends a given string to the tool execution command. Multiple actions
+can be associated with a single condition by using a list of actions
+(used in the example to append some dummy options). The same <tt class="docutils literal"><span class="pre">case</span></tt>
+construct can also be used in the <tt class="docutils literal"><span class="pre">cmd_line</span></tt> property to modify the
+tool command line.</p>
+<p>The "join" property used in the example means that this tool behaves
+like a linker.</p>
+<p>The list of all possible actions follows.</p>
+<ul>
+<li><p class="first">Possible actions:</p>
+<blockquote>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">append_cmd</span></tt> - append a string to the tool invocation
+command.
+Example: <tt class="docutils literal"><span class="pre">(case</span> <span class="pre">(switch_on</span> <span class="pre">"pthread"),</span> <span class="pre">(append_cmd</span>
+<span class="pre">"-lpthread"))</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">error`</span> <span class="pre">-</span> <span class="pre">exit</span> <span class="pre">with</span> <span class="pre">error.</span>
+<span class="pre">Example:</span> <span class="pre">``(error</span> <span class="pre">"Mixing</span> <span class="pre">-c</span> <span class="pre">and</span> <span class="pre">-S</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">allowed!")</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">forward</span></tt> - forward an option unchanged.
+Example: <tt class="docutils literal"><span class="pre">(forward</span> <span class="pre">"Wall")</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">forward_as</span></tt> - Change the name of an option, but forward the
+argument unchanged.
+Example: <tt class="docutils literal"><span class="pre">(forward_as</span> <span class="pre">"O0",</span> <span class="pre">"--disable-optimization")</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - modify the output suffix of this
+tool.
+Example: <tt class="docutils literal"><span class="pre">(output_suffix</span> <span class="pre">"i")</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">stop_compilation</span></tt> - stop compilation after this tool processes
+its input. Used without arguments.</li>
+<li><tt class="docutils literal"><span class="pre">unpack_values</span></tt> - used for for splitting and forwarding
+comma-separated lists of options, e.g. <tt class="docutils literal"><span class="pre">-Wa,-foo=bar,-baz</span></tt> is
+converted to <tt class="docutils literal"><span class="pre">-foo=bar</span> <span class="pre">-baz</span></tt> and appended to the tool invocation
+command.
+Example: <tt class="docutils literal"><span class="pre">(unpack_values</span> <span class="pre">"Wa,")</span></tt>.</li>
+</ul>
+</blockquote>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="language-map">
+<h1><a class="toc-backref" href="#id15">Language map</a></h1>
+<p>If you are adding support for a new language to LLVMC, you'll need to
+modify the language map, which defines mappings from file extensions
+to language names. It is used to choose the proper toolchain(s) for a
+given input file set. Language map definition looks like this:</p>