This is an archive of the discontinued LLVM Phabricator instance.

Update the LLDB website with more information
ClosedPublic

Authored by zturner on Mar 10 2015, 12:08 PM.

Download Raw Diff

Details

Reviewers

Commits

rGc99b5ce13ac1: Update build instructions / coding conventions.
rLLDB231884: Update build instructions / coding conventions.
rL231884: Update build instructions / coding conventions.

Summary

This patch adds better instructions for checking out source, more links to the LLVM website, more explicit wording about falling back to the LLVM policies where not explicitly outlined, and a reduction in the .clang-format indentation from 140 to 120 based on existing wording in the style guide.

Diff Detail

Repository: rL LLVM

Event Timeline

zturner updated this revision to Diff 21615.Mar 10 2015, 12:08 PM

zturner retitled this revision from to Update the LLDB website with more information.

zturner updated this object.

zturner edited the test plan for this revision. (Show Details)

zturner added a reviewer: jingham.

zturner added a subscriber: Unknown Object (MLST).

Couple of comments.

First off, if you are building with Xcode, you don't need to check out llvm & clang, the build will do that for you if they don't already exist. So for people who want to work on lldb & don't have an extant llvm/clang checkout, it is easier to just check out lldb & build.

By saying "The line limit IS 120 characters"... "However you will see places" you make it sound like the exceptions are of questionable status, which is not at all the intent. Particularly for these tables, letting them run longer is IMO preferable (there are a few of the tables where the help text wraps & I find those harder to read.) You could say something like:

The line limit for code statements is...

Then it would be clearer that this statement does not contradict the immediately following paragraph.

I wasn't aware that the Xcode build did that. I'll update in a bit. I think
it's useful to say something about the directory structure though because
it lets people know how to update their code. Also will fix the suggestions
about line length

zturner updated this revision to Diff 21618.Mar 10 2015, 12:53 PM

zturner edited edge metadata.

That looks good.

Closed by commit rL231884: Update build instructions / coding conventions. (authored by zturner). · Explain WhyMar 10 2015, 4:24 PM

This revision was automatically updated to reflect the committed changes.

Revision Contents

Path

Size

lldb/

trunk/

.clang-format

2 lines

www/

lldb-coding-conventions.html

32 lines

source.html

76 lines

Diff 21657

lldb/trunk/.clang-format

	BasedOnStyle: LLVM			BasedOnStyle: LLVM
	IndentWidth: 4			IndentWidth: 4
	ColumnLimit: 140			ColumnLimit: 120
	BreakBeforeBraces: Allman			BreakBeforeBraces: Allman
	AlwaysBreakAfterDefinitionReturnType: true			AlwaysBreakAfterDefinitionReturnType: true
	AllowShortFunctionsOnASingleLine: Inline			AllowShortFunctionsOnASingleLine: Inline
	BreakConstructorInitializersBeforeComma: true			BreakConstructorInitializersBeforeComma: true
	IndentCaseLabels: true			IndentCaseLabels: true

lldb/trunk/www/lldb-coding-conventions.html

Show All 14 Lines	<div id="container">
<div id="content">		<div id="content">
<!--#include virtual="sidebar.incl"-->		<!--#include virtual="sidebar.incl"-->
<div id="middle">		<div id="middle">
<div class="post">		<div class="post">
<h1 class ="postheader">LLDB Coding Conventions</h1>		<h1 class ="postheader">LLDB Coding Conventions</h1>
<div class="postcontent">		<div class="postcontent">


<p>The lldb coding conventions for the most part follow those used in llvm. For instance the		<p>The LLDB coding conventions differ in a few important respects from LLVM.</p>
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.

		<p>
<h3>Source code width:</h3>		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		<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		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		is awkward to read, and the time spent trying to find good indentation points to
avoid this would be much better spent on thinking about your code.		avoid this would be much better spent on thinking about your code.

<p>More importantly, the restriction induces coders to choose overly abbreviated names		<p>More importantly, the restriction induces coders to choose overly abbreviated names
to make them better fit in 80 characters. In our opinion choosing good descriptive		to make them better fit in 80 characters. In our opinion choosing good descriptive
names is much more important than fitting in 80 characters.		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		<p>In lldb the limit for code lines is 120 characters because it gets awkward to scan
120 characters because it gets awkward to scan longer lines even on a fairly big monitor,		longer lines even on a fairly big monitor, and we've found at that length you seldom
and we've found at that length you seldom have to make code look ugly to get it to wrap.		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		<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		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		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.		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>		<h3>Indentation:</h3>
<p>lldb uses 4 character indentation. We find this makes the code structure much easier to		<p>lldb uses 4 character indentation. We find this makes the code structure much easier to
see when scanning code, and since we aren't trying to fit code into 80 characters, the		see when scanning code, and since we aren't trying to fit code into 80 characters, the
benefit of not wasting 2 out of the 80 precious spaces per indentation level is moot.		benefit of not wasting 2 out of the 80 precious spaces per indentation level is moot.

<p>We also use the Allman brace style rather than putting the initial brace at the end		<p>We also use the Allman brace style rather than putting the initial brace at the end
of the braced line. This makes the block structure of the code much easier to see on		of the braced line. This makes the block structure of the code much easier to see on
▲ Show 20 Lines • Show All 74 Lines • Show Last 20 Lines

lldb/trunk/www/source.html

	Show All 12 Lines

	<div id="container">			<div id="container">
	<div id="content">			<div id="content">

	<!--#include virtual="sidebar.incl"-->			<!--#include virtual="sidebar.incl"-->

	<div id="middle">			<div id="middle">
	<div class="post">			<div class="post">
	<h1 class ="postheader">Downloading LLDB sources</h1>			<h1 class ="postheader">Checking out LLDB sources</h1>
	<div class="postcontent">			<div class="postcontent">
	<p>Obtaining read only access to the LLDB sources is easy:</p>			<p>Refer to the <a href="http://llvm.org/docs/GettingStarted.html#getting-started-with-llvm">LLVM Getting Started Guide</a>
	<ul>			for general instructions on how to check out source. Note that LLDB depends on having a working checkout of LLVM
	<li>svn co http://llvm.org/svn/llvm-project/lldb/trunk lldb</li>			and Clang, so the first step is to download LLVM and Clang sources as described at the above URL. Then you can
	</ul>			additionally download the LLDB sources from the following repository URLs.</p>
	<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>			<p><b>SVN Repository</b>: http://llvm.org/svn/llvm-project/lldb/trunk </p>
	<ul>			<p><b>Git Clone</b>: http://llvm.org/git/lldb.git </p>
	<li>git clone http://llvm.org/git/lldb.git</li>			<p>
	</ul>			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="postfooter"></div>
	</div>			</div>
	<div class="post">			<div class="post">
	<h1 class ="postheader">Contributing to LLDB</h1>			<h1 class ="postheader">Contributing to LLDB</h1>
	<div class="postcontent">			<div class="postcontent">
	<p>If you wish to contribute to LLDB, you must first get commit access by			<p>
	<a href="http://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access">requesting commit access</a></p>			Please refer to the <a href="http://llvm.org/docs/DeveloperPolicy.html">LLVM Developer Policy</a>
	<p>Once you have commit access, you will have a <b>USERNAME</b> and you can checkout the sources:			for information about authoring and uploading a patch. LLDB differs from the LLVM Developer Policy in
	<a href="http://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access">requesting commit access</a></p>			the following respects.
	<ul>			<ul>
	<li>svn co https://USERNAME@llvm.org/svn/llvm-project/lldb/trunk lldb</li>			<li>Coding conventions. Refer to <a href="lldb-coding-conventions.html">LLDB Coding Conventions</a>.</li>
	</ul>			<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>
	<div class="postfooter"></div>			<div class="postfooter"></div>
	</div>			</div>
	</div>			</div>
	</div>			</div>
	</div>			</div>
	</body>			</body>
	</html>			</html>