- <p><tt>llvmc</tt> always looks for files of a specific name. It uses the
- first file with the name its looking for by searching directories in the
- following order:<br/>
- <ol>
- <li>Any directory specified by the <tt>-config-dir</tt> option will be
- checked first.</li>
- <li>If the environment variable LLVM_CONFIG_DIR is set, and it contains
- the name of a valid directory, that directory will be searched next.</li>
- <li>If the user's home directory (typically <tt>/home/user</tt> contains
- a sub-directory named <tt>.llvm</tt> and that directory contains a
- sub-directory named <tt>etc</tt> then that directory will be tried
- next.</li>
- <li>If the LLVM installation directory (typically <tt>/usr/local/llvm</tt>
- contains a sub-directory named <tt>etc</tt> then that directory will be
- tried last.</li>
- <li>A standard "system" directory will be searched next. This is typically
- <tt>/etc/llvm</tt> on UNIX™ and <tt>C:\WINNT</tt> on Microsoft
- Windows™.</li>
- <li>If the configuration file sought still can't be found, <tt>llvmc</tt>
- will print an error message and exit.</li>
- </ol>
- <p>The first file found in this search will be used. Other files with the
- same name will be ignored even if they exist in one of the subsequent search
- locations.</p>
+<div class="doc_section"><a class="toc-backref" href="#id6" id="writing-a-tool-description" name="writing-a-tool-description">Writing a tool description</a></div>
+<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">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 lack explicit descriptions.</p>
+<p>The complete list of the 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.</li>
+<li><tt class="docutils literal"><span class="pre">out_language</span></tt> - output language name.</li>
+<li><tt class="docutils literal"><span class="pre">output_suffix</span></tt> - output file suffix.</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 (more on this below).</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>
+</ul>
+</li>
+</ul>
+<p>The next tool definition is slightly more complex:</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),
+ (prefix_list_option "L", (forward),
+ (help "add a directory to link path")),
+ (prefix_list_option "l", (forward),
+ (help "search a library when linking")),
+ (prefix_list_option "Wl", (unpack_values),
+ (help "pass options to linker"))
+ ]>;
+</pre>
+<p>This tool has a "join" property, which means that it behaves like a
+linker. This tool also defines several command-line options: <tt class="docutils literal"><span class="pre">-l</span></tt>,
+<tt class="docutils literal"><span class="pre">-L</span></tt> and <tt class="docutils literal"><span class="pre">-Wl</span></tt> which have their usual meaning. An option has two
+attributes: a name and a (possibly empty) list of properties. All
+currently implemented option types and properties are described below:</p>
+<ul>
+<li><p class="first">Possible option types:</p>
+<blockquote>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">switch_option</span></tt> - a simple boolean switch, for example <tt class="docutils literal"><span class="pre">-time</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">parameter_option</span></tt> - option that takes an argument, for example
+<tt class="docutils literal"><span class="pre">-std=c99</span></tt>;</li>
+<li><tt class="docutils literal"><span class="pre">parameter_list_option</span></tt> - same as the above, but more than one
+occurence of the option is allowed.</li>
+<li><tt class="docutils literal"><span class="pre">prefix_option</span></tt> - same as the parameter_option, but the option name
+and parameter value are not separated.</li>
+<li><tt class="docutils literal"><span class="pre">prefix_list_option</span></tt> - same as the above, but more than one
+occurence of the option is allowed; example: <tt class="docutils literal"><span class="pre">-lm</span> <span class="pre">-lpthread</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">alias_option</span></tt> - a special option type for creating
+aliases. Unlike other option types, aliases are not allowed to
+have any properties besides the aliased option name. Usage
+example: <tt class="docutils literal"><span class="pre">(alias_option</span> <span class="pre">"preprocess",</span> <span class="pre">"E")</span></tt></li>
+</ul>
+</blockquote>
+</li>
+<li><p class="first">Possible option properties:</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.</li>
+<li><tt class="docutils literal"><span class="pre">forward</span></tt> - forward this option unchanged.</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">(switch</span> <span class="pre">"E",</span> <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 phase.</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.</li>
+<li><tt class="docutils literal"><span class="pre">help</span></tt> - help string associated with this option. Used for
+<tt class="docutils literal"><span class="pre">--help</span></tt> output.</li>
+<li><tt class="docutils literal"><span class="pre">required</span></tt> - this option is obligatory.</li>
+</ul>
+</blockquote>
+</li>
+</ul>