Magic-Mirror/llvm-capstone
1
0
Fork 0
mirror of https://github.com/capstone-engine/llvm-capstone.git synced 2024-10-09 12:24:08 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Update build instructions / coding conventions.

Browse Source 
This improves the instructions for checking out LLDB, adds
more links to LLVM instructions, and more explicitly calls out
when we differ from the style guide.

Also updates the clang-format configuration file to correctly
reflect a 120 column limit.

Reviewed by: Jim Ingham
Differential Revision: http://reviews.llvm.org/D8222

llvm-svn: 231884
This commit is contained in:
Zachary Turner 2015-03-10 23:22:25 +00:00
parent 49338e9fa6
commit c99b5ce13a
3 changed files with 78 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
lldb/.clang-format
View File

@ -1,6 +1,6 @@
BasedOnStyle: LLVM
IndentWidth: 4
ColumnLimit: 140
ColumnLimit: 120
BreakBeforeBraces: Allman
AlwaysBreakAfterDefinitionReturnType: true
AllowShortFunctionsOnASingleLine: Inline

32
lldb/www/lldb-coding-conventions.html
View File

@ -20,14 +20,22 @@
<div class="postcontent">
<p>The lldb coding conventions for the most part follow those used in llvm. For instance the
importance of comments, particularly for defining classes and methods, the restrictions on
features of C++ to use, and the generally excellent advice about using C++ features
properly should all be followed when writing code for lldb. However, lldb does differ
from the llvm coding conventions in several ways. This document outlines the most important ones.
<h3>Source code width:</h3>
<p>The LLDB coding conventions differ in a few important respects from LLVM.</p>
<p>
Note that <a href="http://clang.llvm.org/docs/ClangFormat.html">clang-format</a> will deal with
most of this for you, as such is suggested to run on patches before uploading. Note however that
clang-format is not smart enough to detect instances of humans intentionally trying to line variables
up on a particular column boundary, and it will reformat them to remove this "extraneous" whitespace.
While this is usually the correct behavior, LLDB does have many uses of manually aligned types and
fields, so please be aware of this behavior of clang-format when editing this type of code.
</p>
<p>
<b>Important</b>: Where not explicitly outlined below, assume that the
<a href="http://llvm.org/docs/CodingStandards.html">LLVM Coding Conventions</a> are to be followed.
</p>
<h3>Source code width:</h3>
<p>lldb does not follow the 80 character line restriction llvm imposes. In our
experience, trying to fit C++ code into an 80 character line results in code that
is awkward to read, and the time spent trying to find good indentation points to
@ -37,14 +45,16 @@
to make them better fit in 80 characters. In our opinion choosing good descriptive
names is much more important than fitting in 80 characters.
<p>In lldb, we don't have a hard character limit, though we try to keep code statements under
120 characters because it gets awkward to scan longer lines even on a fairly big monitor,
and we've found at that length you seldom have to make code look ugly to get it to wrap.
<p>In lldb the limit for code lines is 120 characters because it gets awkward to scan
longer lines even on a fairly big monitor, and we've found at that length you seldom
have to make code look ugly to get it to wrap.
<p>However you will see some instances of longer lines. The most common occurrence is in
the options tables for the CommandInterpreter, which contain the help strings as well as
a bunch of important but hard to remember fields. These tables are much easier to read if
all the fields line up vertically, and don't have help text interleaved in between the lines.
This is another thing to keep in mind when running clang-format, as it will always wrap at
120, so you will need to tweak its output when running against intentionally too-long lines.
<h3>Indentation:</h3>
<p>lldb uses 4 character indentation. We find this makes the code structure much easier to

76
lldb/www/source.html
View File

@ -18,30 +18,66 @@
<div id="middle">
<div class="post">
<h1 class ="postheader">Downloading LLDB sources</h1>
<div class="postcontent">
<p>Obtaining read only access to the LLDB sources is easy:</p>
<ul>
<li>svn co http://llvm.org/svn/llvm-project/lldb/trunk lldb</li>
</ul>
<p>If you prefer using Git, you can check out LLDB from the <a href="http://llvm.org/docs/GettingStarted.html#git-mirror">LLVM git mirror</a> instead:</p>
<ul>
<li>git clone http://llvm.org/git/lldb.git</li>
</ul>
</div>
<div class="postfooter"></div>
<h1 class ="postheader">Checking out LLDB sources</h1>
<div class="postcontent">
<p>Refer to the <a href="http://llvm.org/docs/GettingStarted.html#getting-started-with-llvm">LLVM Getting Started Guide</a>
for general instructions on how to check out source. Note that LLDB depends on having a working checkout of LLVM
and Clang, so the first step is to download LLVM and Clang sources as described at the above URL. Then you can
additionally download the LLDB sources from the following repository URLs.</p>
<p><b>SVN Repository</b>: http://llvm.org/svn/llvm-project/lldb/trunk </p>
<p><b>Git Clone</b>: http://llvm.org/git/lldb.git </p>
<p>
For non-Mac platforms, and for MacOSX building with CMake (not Xcode), you should check out your sources to adhere to
the following directory structure:
<pre><tt>
llvm
|
`-- tools
|
+-- clang
|
`-- lldb
</tt></pre>
</p>
<p>
For MacOSX building from Xcode, simply checkout LLDB and then build from Xcode. The Xcode project will
automatically detect that it is a fresh checkout, and checkout LLVM and clang automatically. Unlike other
platforms / build systems, it will use the following directory structure.
<pre><tt>
lldb
|
`-- llvm
|
+-- tools
|
`-- clang
</tt>
</pre>
So updating your checkout will consist of updating lldb, llvm, and clang in these locations.
</p>
<p>
Refer to the <a href="build.html">Build Instructions</a> for more detailed instructions on how to build for a particular
platform / build system combination.
</p>
</div>
</div>
<div class="post">
<h1 class ="postheader">Contributing to LLDB</h1>
<div class="postcontent">
<p>If you wish to contribute to LLDB, you must first get commit access by
<a href="http://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access">requesting commit access</a></p>
<p>Once you have commit access, you will have a <b>USERNAME</b> and you can checkout the sources:
<a href="http://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access">requesting commit access</a></p>
<ul>
<li>svn co https://USERNAME@llvm.org/svn/llvm-project/lldb/trunk lldb</li>
</ul>
</div>
<p>
Please refer to the <a href="http://llvm.org/docs/DeveloperPolicy.html">LLVM Developer Policy</a>
for information about authoring and uploading a patch. LLDB differs from the LLVM Developer Policy in
the following respects.
<ul>
<li>Coding conventions. Refer to <a href="lldb-coding-conventions.html">LLDB Coding Conventions</a>.</li>
<li>
Test infrastructure. It is still important to submit tests with your patches, but LLDB uses a different
system for tests. Refer to the lldb/test folder on disk for examples of how to write tests.
</li>
</ul>
For anything not explicitly listed here, assume that LLDB follows the LLVM policy.
</p>
</div>
<div class="postfooter"></div>
</div>
</div>