| Chandler Carruth | e56f3a6 | 2012-08-14 07:19:09 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> |
| 4 | <head> |
| 5 | <title>Clang Tools</title> |
| 6 | <link type="text/css" rel="stylesheet" href="../menu.css"> |
| 7 | <link type="text/css" rel="stylesheet" href="../content.css"> |
| 8 | </head> |
| 9 | <body> |
| 10 | |
| 11 | <!--#include virtual="../menu.html.incl"--> |
| 12 | |
| 13 | <div id="content"> |
| 14 | |
| 15 | <h1>Clang Tools</h1> |
| Chandler Carruth | ec2d7b7 | 2012-08-14 07:21:00 +0000 | [diff] [blame] | 16 | <p>Clang Tools are standalone command line (and potentially GUI) tools design |
| 17 | for use by C++ developers who are already using and enjoying Clang as their |
| Chandler Carruth | e56f3a6 | 2012-08-14 07:19:09 +0000 | [diff] [blame] | 18 | compiler. These tools provide developer-oriented functionality such as fast |
| 19 | syntax checking, automatic formatting, refactoring, etc.</p> |
| 20 | |
| 21 | <p>Only a couple of the most basic and fundamental tools are kept in the primary |
| 22 | Clang Subversion project. The rest of the tools are kept in a side-project so |
| 23 | that developers who don't want or need to build them don't. If you want to get |
| 24 | access to the extra Clang Tools repository, simply check it out into the tools |
| 25 | tree of your Clang checkout and follow the usual process for building and |
| 26 | working with a combined LLVM/Clang checkout:</p> |
| 27 | <ul> |
| 28 | <li>With Subversion: |
| 29 | <ul> |
| 30 | <li><tt>cd llvm/tools/clang/tools</tt></li> |
| 31 | <li><tt>svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk |
| 32 | extra</tt></li> |
| 33 | </ul> |
| 34 | </li> |
| 35 | <li>Or with Git: |
| 36 | <ul> |
| 37 | <li><tt>cd llvm/tools/clang/tools</tt></li> |
| 38 | <li><tt>git clone http://llvm.org/git/clang-tools-extra.git extra</tt></li> |
| 39 | </ul> |
| 40 | </li> |
| 41 | </ul> |
| 42 | |
| 43 | <p>This document describes a high-level overview of the organization of Clang |
| 44 | Tools within the project as well as giving an introduction to some of the more |
| 45 | important tools. However, it should be noted that this document is currently |
| 46 | focused on Clang and Clang Tool developers, not on end users of these tools.</p> |
| 47 | |
| 48 | <!-- ======================================================================= --> |
| 49 | <h2 id="org">Clang Tools Organization</h2> |
| 50 | <!-- ======================================================================= --> |
| 51 | |
| 52 | <p>Clang Tools are CLI or GUI programs that are intended to be directly used by |
| 53 | C++ developers. That is they are <em>not</em> primarily for use by Clang |
| 54 | developers, although they are hopefully useful to C++ developers who happen to |
| 55 | work on Clang, and we try to actively dogfood their functionality. They are |
| 56 | developed in three components: the underlying infrastructure for building |
| 57 | a standalone tool based on Clang, core shared logic used by many different tools |
| 58 | in the form of refactoring and rewriting libraries, and the tools |
| 59 | themselves.</p> |
| 60 | |
| Chandler Carruth | ec2d7b7 | 2012-08-14 07:21:00 +0000 | [diff] [blame] | 61 | <p>The underlying infrastructure for Clang Tools is the |
| Chandler Carruth | e56f3a6 | 2012-08-14 07:19:09 +0000 | [diff] [blame] | 62 | <a href="LibTooling.html">LibTooling</a> platform. See its documentation for |
| Chandler Carruth | ec2d7b7 | 2012-08-14 07:21:00 +0000 | [diff] [blame] | 63 | much more detailed information about how this infrastructure works. The common |
| Chandler Carruth | e56f3a6 | 2012-08-14 07:19:09 +0000 | [diff] [blame] | 64 | refactoring and rewriting toolkit-style library is also part of LibTooling |
| 65 | organizationally.</p> |
| 66 | |
| 67 | <p>A few Clang Tools are developed along side the core Clang libraries as |
| 68 | examples and test cases of fundamental functionality. However, most of the tools |
| 69 | are developed in a side repository to provide easy separation from the core |
| 70 | libraries. We intentionally do not support public libraries in the side |
| 71 | repository, as we want to carefully review and find good APIs for libraries as |
| 72 | they are lifted out of a few tools and into the core Clang library set.</p> |
| 73 | |
| Chandler Carruth | ec2d7b7 | 2012-08-14 07:21:00 +0000 | [diff] [blame] | 74 | <p>Regardless of which repository Clang Tools' code resides in, the development |
| Chandler Carruth | e56f3a6 | 2012-08-14 07:19:09 +0000 | [diff] [blame] | 75 | process and practices for all Clang Tools are exactly those of Clang itself. |
| 76 | They are entirely within the Clang <em>project</em>, regardless of the version |
| 77 | control scheme.</p> |
| 78 | |
| 79 | |
| 80 | <!-- ======================================================================= --> |
| 81 | <h2 id="coretools">Core Clang Tools</h2> |
| 82 | <!-- ======================================================================= --> |
| 83 | |
| 84 | <p>The core set of Clang tools that are within the main repository are tools |
| 85 | that very specifically compliment, and allow use and testing of <em>Clang</em> |
| 86 | specific functionality.</p> |
| 87 | |
| 88 | <h3 id="clang-check"><tt>clang-check</tt></h3> |
| 89 | <p>This tool combines the LibTooling framework for running a Clang tool with the |
| Chandler Carruth | ec2d7b7 | 2012-08-14 07:21:00 +0000 | [diff] [blame] | 90 | basic Clang diagnostics by syntax checking specific files in a fast, command line |
| Chandler Carruth | e56f3a6 | 2012-08-14 07:19:09 +0000 | [diff] [blame] | 91 | interface. It can also accept flags to re-display the diagnostics in different |
| 92 | formats with different flags, suitable for use driving an IDE or editor.</p> |
| 93 | |
| 94 | <p>FIXME: Link to user-oriented clang-check documentation.</p> |
| 95 | |
| Chandler Carruth | 2372ffc | 2012-08-14 07:36:05 +0000 | [diff] [blame] | 96 | <h3 id="clang-fixit"><tt>clang-fixit</tt> (Not yet implemented!)</h3> |
| Chandler Carruth | ec2d7b7 | 2012-08-14 07:21:00 +0000 | [diff] [blame] | 97 | <p>A tool which specifically applies the Clang fix-it hint diagnostic technology |
| Chandler Carruth | e56f3a6 | 2012-08-14 07:19:09 +0000 | [diff] [blame] | 98 | on top of a dedicated tool. It is designed to explore alternative interfaces for |
| 99 | applying fix-it hints, including automatic application, prompting users with |
| 100 | options for different fixes, etc.</p> |
| 101 | |
| Chandler Carruth | 2372ffc | 2012-08-14 07:36:05 +0000 | [diff] [blame] | 102 | <p><b>NB:</b> The clang-fixit tool is planned, but not yet implemented.</p> |
| Chandler Carruth | e56f3a6 | 2012-08-14 07:19:09 +0000 | [diff] [blame] | 103 | |
| 104 | <p>FIXME: Link to user-oriented clang-fixit documentation.</p> |
| 105 | |
| 106 | <!-- ======================================================================= --> |
| 107 | <h2 id="registerplugin">Extra Clang Tools</h2> |
| 108 | <!-- ======================================================================= --> |
| 109 | |
| 110 | <p>As various categories of Clang Tools are added to the extra repository, |
| 111 | they'll be tracked here. The focus of this documentation is on the scope and |
| 112 | features of the tools for other tool developers; each tool should provide its |
| 113 | own user-focused documentation.</p> |
| 114 | |
| 115 | </div> |
| 116 | </body> |
| 117 | </html> |
| 118 | |