| Cedric Venet | 3d65864 | 2009-02-14 20:20:19 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ --> |
| 4 | <html> |
| 5 | <head> |
| 6 | <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> |
| 7 | <title>Hacking on clang</title> |
| 8 | <link type="text/css" rel="stylesheet" href="menu.css" /> |
| 9 | <link type="text/css" rel="stylesheet" href="content.css" /> |
| 10 | </head> |
| 11 | <body> |
| 12 | <!--#include virtual="menu.html.incl"--> |
| 13 | <div id="content"> |
| 14 | <!--*********************************************************************--> |
| 15 | <h1>Hacking on Clang</h1> |
| 16 | <!--*********************************************************************--> |
| 17 | |
| 18 | <p>This document provides some hints for how to get started hacking |
| 19 | on Clang for developers who are new to the Clang and/or LLVM |
| 20 | codebases.</p> |
| 21 | <ul> |
| 22 | <li><a href="#docs">Developer Documentation</a></li> |
| 23 | <li><a href="#debugging">Debugging</a></li> |
| 24 | <li><a href="#testing">Testing</a></li> |
| 25 | <li><a href="#irgen">LLVM IR Generation</a></li> |
| 26 | </ul> |
| 27 | |
| 28 | <!--=====================================================================--> |
| 29 | <h2 id="docs">Developer Documentation</h2> |
| 30 | <!--=====================================================================--> |
| 31 | |
| 32 | <p>Both Clang and LLVM use doxygen to provide API documentation. Their |
| 33 | respective web pages (generated nightly) are here:</p> |
| 34 | <ul> |
| 35 | <li><a href="http://clang.llvm.org/doxygen">Clang</a></li> |
| 36 | <li><a href="http://llvm.org/doxygen">LLVM</a></li> |
| 37 | </ul> |
| 38 | |
| 39 | <p>For work on the LLVM IR generation, the LLVM assembly language |
| 40 | <a href="http://llvm.org/docs/LangRef.html">reference manual</a> is |
| 41 | also useful.</p> |
| 42 | |
| 43 | <!--=====================================================================--> |
| 44 | <h2 id="debugging">Debugging</h2> |
| 45 | <!--=====================================================================--> |
| 46 | |
| 47 | <p>Inspecting data structures in a debugger:</p> |
| 48 | <ul> |
| 49 | <li>Many LLVM and Clang data structures provide |
| 50 | a <tt>dump()</tt> method which will print a description of the |
| 51 | data structure to <tt>stderr</tt>.</li> |
| 52 | <li>The <a href="docs/InternalsManual.html#QualType"><tt>QualType</tt></a> |
| 53 | structure is used pervasively. This is a simple value class for |
| 54 | wrapping types with qualifiers; you can use |
| 55 | the <tt>isConstQualified()</tt>, for example, to get one of the |
| 56 | qualifiers, and the <tt>getTypePtr()</tt> method to get the |
| 57 | wrapped <tt>Type*</tt> which you can then dump.</li> |
| 58 | </ul> |
| 59 | |
| 60 | <!--=====================================================================--> |
| 61 | <h2 id="testing">Testing</h2> |
| 62 | <!--=====================================================================--> |
| 63 | |
| 64 | <p>Clang includes a basic regression suite in the tree which can be |
| 65 | run with <tt>make test</tt> from the top-level clang directory, or |
| 66 | just <tt>make</tt> in the <em>test</em> sub-directory. <tt>make |
| 67 | report</tt> can be used after running the tests to summarize the |
| 68 | results, and <tt>make VERBOSE=1</tt> can be used to show more detail |
| 69 | about what is being run.</p> |
| 70 | |
| 71 | <p>The regression suite can also be run with Valgrind by running |
| 72 | <tt>make test VG=1</tt> in the top-level clang directory.</p> |
| 73 | |
| 74 | <p>For more intensive changes, running |
| 75 | the <a href="http://llvm.org/docs/TestingGuide.html#testsuiterun">LLVM |
| 76 | Test Suite</a> with clang is recommended. Currently the best way to |
| 77 | override LLVMGCC, as in: <tt>make LLVMGCC="ccc -std=gnu89" |
| 78 | TEST=nightly report</tt> (make sure ccc is in your PATH or use the |
| 79 | full path).</p> |
| 80 | |
| 81 | <!--=====================================================================--> |
| 82 | <h2 id="irgen">LLVM IR Generation</h2> |
| 83 | <!--=====================================================================--> |
| 84 | |
| 85 | <p>The LLVM IR generation part of clang handles conversion of the |
| 86 | AST nodes output by the Sema module to the LLVM Intermediate |
| 87 | Representation (IR). Historically, this was referred to as |
| 88 | "codegen", and the Clang code for this lives |
| 89 | in <tt>lib/CodeGen</tt>.</p> |
| 90 | |
| 91 | <p>The output is most easily inspected using the <tt>-emit-llvm</tt> |
| 92 | option to clang (possibly in conjunction with <tt>-o -</tt>). You |
| 93 | can also use <tt>-emit-llvm-bc</tt> to write an LLVM bitcode file |
| 94 | which can be processed by the suite of LLVM tools |
| 95 | like <tt>llvm-dis</tt>, <tt>llvm-nm</tt>, etc. See the LLVM |
| 96 | <a href="http://llvm.org/docs/CommandGuide/">Command Guide</a> |
| 97 | for more information.</p> |
| 98 | |
| 99 | </div> |
| 100 | </body> |
| 101 | </html> |