<li><a href="#hl_dontinclude">#include as Little as Possible</a></li>
<li><a href="#hl_privateheaders">Keep "internal" Headers
Private</a></li>
+ <li><a href="#ll_iostream"><tt>#include <iostream></tt> is
+ <em>forbidden</em></a></li>
</ol></li>
<li><a href="#micro">The Low Level Issues</a>
<ol>
<li><a href="#ll_assert">Assert Liberally</a></li>
<li><a href="#ll_ns_std">Do not use 'using namespace std'</a></li>
- <li><a href="#ll_virtual_anch">Provide a virtual method anchor for clases in headers</a></li>
+ <li><a href="#ll_virtual_anch">Provide a virtual method anchor for
+ classes in headers</a></li>
<li><a href="#ll_preincrement">Prefer Preincrement</a></li>
<li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li>
</ol></li>
</ol>
<div class="doc_author">
- <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
+ <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and
+ <a href="mailto:void@nondot.org">Bill Wendling</a></p>
</div>
<b>File Headers</b>
-<p>Every source file should have a header on it that
-describes the basic purpose of the file. If a file does not have a header, it
-should not be checked into CVS. Most source trees will probably have a standard
+<p>Every source file should have a header on it that describes the basic
+purpose of the file. If a file does not have a header, it should not be
+checked into Subversion. Most source trees will probably have a standard
file header format. The standard format for the LLVM source tree looks like
this:</p>
//
// The LLVM Compiler Infrastructure
//
-// This file was developed by the LLVM research group and is distributed under
+// This file was developed by <whoever started the file> and is distributed under
// the University of Illinois Open Source License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//
</pre>
</div>
-<p>A few things to note about this particular format: The "<tt>-*- C++
+<p>A few things to note about this particular format: The 'developed by' line
+should be the name of the person or organization who initially contributed the
+file. The "<tt>-*- C++
-*-</tt>" string on the first line is there to tell Emacs that the source file
is a C++ file, not a C file (Emacs assumes .h files are C files by default).
Note that this tag is not necessary in .cpp files. The name of the file is also
<tt>#include</tt>'ing speeds up compilation.</p>
<p>It is easy to try to go too overboard on this recommendation, however. You
-<b>must</b> include all of the header files that you are using, either directly
+<b>must</b> include all of the header files that you are using -- you can
+include them either directly
or indirectly (through another header file). To make sure that you don't
accidently forget to include a header file in your module header, make sure to
include your module header <b>first</b> in the implementation file (as mentioned
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="ll_iostream"><tt>#include <iostream></tt> is forbidden</a>
+</div>
+
+<div class="doc_text">
+
+<p>The use of <tt>#include <iostream></tt> in library files is
+hereby <b><em>forbidden</em></b>. The primary reason for doing this is to
+support clients using LLVM libraries as part of larger systems. In particular,
+we statically link LLVM into some dynamic libraries. Even if LLVM isn't used,
+the static c'tors are run whenever an application start up that uses the dynamic
+library. There are two problems with this:</p>
+
+<ol>
+ <li>The time to run the static c'tors impacts startup time of
+ applications—a critical time for gui apps.</li>
+ <li>The static c'tors cause the app to pull many extra pages of memory off the
+ disk: both the code for the static c'tors in each .o file and the small
+ amount of data that gets touched. In addition, touched/dirty pages put
+ more pressure on the VM system on low-memory machines.</li>
+</ol>
+
+<div style="align: center">
+<table>
+ <tbody>
+ <tr>
+ <th>Old Way</th>
+ <th>New Way</th>
+ </tr>
+ <tr>
+ <td align="left"><pre>#include <iostream></pre></td>
+ <td align="left"><pre>#include "llvm/Support/Streams.h"</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>DEBUG(std::cerr << ...);
+DEBUG(dump(std::cerr));</pre></td>
+ <td align="left"><pre>DOUT << ...;
+dump(DOUT);</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::cerr << "Hello world\n";</pre></td>
+ <td align="left"><pre>llvm::cerr << "Hello world\n";</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::cout << "Hello world\n";</pre></td>
+ <td align="left"><pre>llvm::cout << "Hello world\n";</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::cin >> Var;</pre></td>
+ <td align="left"><pre>llvm::cin >> Var;</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::ostream</pre></td>
+ <td align="left"><pre>llvm::OStream</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::istream</pre></td>
+ <td align="left"><pre>llvm::IStream</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>std::stringstream</pre></td>
+ <td align="left"><pre>llvm::StringStream</pre></td>
+ </tr>
+ <tr>
+ <td align="left"><pre>void print(std::ostream &Out);
+// ...
+print(std::cerr);</pre></td>
+ <td align="left"><pre>void print(std::ostream &Out);
+void print(std::ostream *Out) { if (Out) print(*Out) }
+// ...
+print(llvm::cerr);</pre>
+
+<div class="doc_text">
+<i>N.B.</i> The second <tt>print</tt> method is called by the <tt>print</tt>
+expression. It prevents the execution of the first <tt>print</tt> method if the
+stream is <tt>cnull</tt>.</div></td>
+ </tbody>
+</table>
+</div>
+
+</div>
+
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="micro">The Low Level Issues</a>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="ll_ns_std">Do not use 'using namespace std'</a>
+ <a name="ll_ns_std">Do not use '<tt>using namespace std</tt>'</a>
</div>
<div class="doc_text">
<p>In LLVM, we prefer to explicitly prefix all identifiers from the standard
-namespace with an "std::" prefix, rather than rely on "using namespace std;".
-</p>
-
-<p> In header files, adding a 'using namespace XXX' directive pollutes the
-namespace of any source file that includes the header. This is clearly a bad
-thing.</p>
-
-<p>In implementation files (e.g. .cpp files) the rule is more of a stylistic
-rule, but is still important. Basically, using explicit namespace prefixes
-makes
-the code <b>more clear</b> - because it is immediately obvious what facilities
-are being used and where they are coming from - and <b>more portable</b> -
-because namespace clashes cannot occur between LLVM code and other namespaces.
-The portability rule is important because different standard library
-implementations expose different symbols (potentially ones they shouldn't) and
-future revisions to the C++ standard will add more symbols to the std
-namespace. As such, we never 'using namespace std;' in LLVM.</p>
-
-<p>The exception to the general rule (i.e. it's not an exception for the std
-namespace) is for implementation files. For example, all of the code in the
-LLVM project implements code that lives in the 'llvm' namespace. As such, it
-is ok, and actually more clear, for the .cpp files to have a 'using namespace
-llvm' directive at their top, after the #includes. The general form of this
-rule is that any .cpp file that implements code in any namespace may use that
-namespace (and its parents), but should not use any others.</p>
+namespace with an "<tt>std::</tt>" prefix, rather than rely on
+"<tt>using namespace std;</tt>".</p>
+
+<p> In header files, adding a '<tt>using namespace XXX</tt>' directive pollutes
+the namespace of any source file that includes the header. This is clearly a
+bad thing.</p>
+
+<p>In implementation files (e.g. .cpp files), the rule is more of a stylistic
+rule, but is still important. Basically, using explicit namespace prefixes
+makes the code <b>clearer</b>, because it is immediately obvious what facilities
+are being used and where they are coming from, and <b>more portable</b>, because
+namespace clashes cannot occur between LLVM code and other namespaces. The
+portability rule is important because different standard library implementations
+expose different symbols (potentially ones they shouldn't), and future revisions
+to the C++ standard will add more symbols to the <tt>std</tt> namespace. As
+such, we never use '<tt>using namespace std;</tt>' in LLVM.</p>
+
+<p>The exception to the general rule (i.e. it's not an exception for
+the <tt>std</tt> namespace) is for implementation files. For example, all of
+the code in the LLVM project implements code that lives in the 'llvm' namespace.
+As such, it is ok, and actually clearer, for the .cpp files to have a '<tt>using
+namespace llvm</tt>' directive at their top, after the <tt>#include</tt>s. The
+general form of this rule is that any .cpp file that implements code in any
+namespace may use that namespace (and its parents'), but should not use any
+others.</p>
</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="ll_virtual_anch">Provide a virtual method anchor for clases in headers</a>
+ <a name="ll_virtual_anch">Provide a virtual method anchor for classes
+ in headers</a>
</div>
<div class="doc_text">
</div>
+
<!-- *********************************************************************** -->
<div class="doc_section">
<a name="seealso">See Also</a>
projects / oota-llvm.git / blobdiff