Skip to content

Commit

Permalink
Add initial documentation about the new tools repository and the
Browse files Browse the repository at this point in the history 
structure of how we're building concrete tools as well as tooling
infrastructure as part of the Clang project.

This documentation is definitely still rough. If anyone can improve it,
flesh it out, or help structure it in a more natural way, please, help!
=] This is not my forte, and patches here are more than welcome!

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@161855 91177308-0d34-0410-b5e6-96231b3b80d8
  • Loading branch information
@chandlerc
chandlerc committed Aug 14, 2012
1 parent f345ffb commit e56f3a6
Show file tree
Hide file tree
Showing 3 changed files with 143 additions and 0 deletions.
118 changes: 118 additions & 0 deletions docs/ClangTools.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Clang Tools</title>
<link type="text/css" rel="stylesheet" href="../menu.css">
<link type="text/css" rel="stylesheet" href="../content.css">
</head>
<body>

<!--#include virtual="../menu.html.incl"-->

<div id="content">

<h1>Clang Tools</h1>
<p>Clang Tools are standalone commandline (and potentially GUI) tools design for
use by C++ developers who are already using and enjoying Clang as their
compiler. These tools provide developer-oriented functionality such as fast
syntax checking, automatic formatting, refactoring, etc.</p>

<p>Only a couple of the most basic and fundamental tools are kept in the primary
Clang Subversion project. The rest of the tools are kept in a side-project so
that developers who don't want or need to build them don't. If you want to get
access to the extra Clang Tools repository, simply check it out into the tools
tree of your Clang checkout and follow the usual process for building and
working with a combined LLVM/Clang checkout:</p>
<ul>
<li>With Subversion:
<ul>
<li><tt>cd llvm/tools/clang/tools</tt></li>
<li><tt>svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk
extra</tt></li>
</ul>
</li>
<li>Or with Git:
<ul>
<li><tt>cd llvm/tools/clang/tools</tt></li>
<li><tt>git clone http://llvm.org/git/clang-tools-extra.git extra</tt></li>
</ul>
</li>
</ul>

<p>This document describes a high-level overview of the organization of Clang
Tools within the project as well as giving an introduction to some of the more
important tools. However, it should be noted that this document is currently
focused on Clang and Clang Tool developers, not on end users of these tools.</p>

<!-- ======================================================================= -->
<h2 id="org">Clang Tools Organization</h2>
<!-- ======================================================================= -->

<p>Clang Tools are CLI or GUI programs that are intended to be directly used by
C++ developers. That is they are <em>not</em> primarily for use by Clang
developers, although they are hopefully useful to C++ developers who happen to
work on Clang, and we try to actively dogfood their functionality. They are
developed in three components: the underlying infrastructure for building
a standalone tool based on Clang, core shared logic used by many different tools
in the form of refactoring and rewriting libraries, and the tools
themselves.</p>

<p>The underyling infrastructure for Clang Tools is the
<a href="LibTooling.html">LibTooling</a> platform. See its documentation for
much more detailed information about how this infrastructuro works. The common
refactoring and rewriting toolkit-style library is also part of LibTooling
organizationally.</p>

<p>A few Clang Tools are developed along side the core Clang libraries as
examples and test cases of fundamental functionality. However, most of the tools
are developed in a side repository to provide easy separation from the core
libraries. We intentionally do not support public libraries in the side
repository, as we want to carefully review and find good APIs for libraries as
they are lifted out of a few tools and into the core Clang library set.</p>

<p>Regardless of which repositiory Clang Tools' code resides in, the development
process and practices for all Clang Tools are exactly those of Clang itself.
They are entirely within the Clang <em>project</em>, regardless of the version
control scheme.</p>


<!-- ======================================================================= -->
<h2 id="coretools">Core Clang Tools</h2>
<!-- ======================================================================= -->

<p>The core set of Clang tools that are within the main repository are tools
that very specifically compliment, and allow use and testing of <em>Clang</em>
specific functionality.</p>

<h3 id="clang-check"><tt>clang-check</tt></h3>
<p>This tool combines the LibTooling framework for running a Clang tool with the
basic Clang diagnostics by syntax checking specific files in a fast, commandline
interface. It can also accept flags to re-display the diagnostics in different
formats with different flags, suitable for use driving an IDE or editor.</p>

<p>FIXME: Link to user-oriented clang-check documentation.</p>

<h3 id="clang-fixit"><tt>clang-fixit</tt></h3>
<p>A tool which specifically applies the Clang fix-it hint diagnostic technogoy
on top of a dedicated tool. It is designed to explore alternative interfaces for
applying fix-it hints, including automatic application, prompting users with
options for different fixes, etc.</p>

<p>Note that the clang-fixit tool is planned, but not yet implemented.</p>

<p>FIXME: Link to user-oriented clang-fixit documentation.</p>

<!-- ======================================================================= -->
<h2 id="registerplugin">Extra Clang Tools</h2>
<!-- ======================================================================= -->

<p>As various categories of Clang Tools are added to the extra repository,
they'll be tracked here. The focus of this documentation is on the scope and
features of the tools for other tool developers; each tool should provide its
own user-focused documentation.</p>

</div>
</body>
</html>

17 changes: 17 additions & 0 deletions docs/Tooling.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,23 @@ <h2 id="libtooling"><a href="LibTooling.html">LibTooling</a></h2>
<li>do not want to write your tools in C++</li>
</ul>

<!-- ======================================================================= -->
<h2 id="clang-tools"><a href="ClangTools.html">Clang Tools</a></h2>
<!-- ======================================================================= -->

<p>These are a collection of specific developer tools built on top of the
LibTooling infrastructure as part of the Clang project. They are targeted at
automating and improving core development activities of C/C++ developers.</p>
<p>Examples of tools we are building or planning as part of the Clang
project:</p>
<ul>
<li>Syntax checking (clang-check)</li>
<li>Automatic fixing of compile errors (clangc-fixit)</li>
<li>Automatic code formatting</li>
<li>Migration tools for new features in new language standards</li>
<li>Core refactoring tools</li>
</ul>

</div>
</body>
</html>
Expand Down
8 changes: 8 additions & 0 deletions www/get_started.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,14 @@ <h3 id="buildNix">On Unix-like Systems</h3>
<li><tt>cd ../..</tt></li>
</ul>
</li>
<li>Checkout extra Clang Tools: (optional)
<ul>
<li><tt>cd llvm/tools/clang/tools</tt></li>
<li><tt>svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk
extra</tt></li>
<li><tt>cd ../../../..</tt></li>
</ul>
</li>
<li>Checkout Compiler-RT:
<ul>
<li><tt>cd llvm/projects</tt></li>
Expand Down

0 comments on commit e56f3a6

Please sign in to comment.