You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by dl...@apache.org on 2015/04/27 19:56:09 UTC
svn commit: r1676349 [3/3] - in /mesos/site: publish/
publish/documentation/clang-format/
publish/documentation/latest/clang-format/
publish/documentation/latest/mesos-c++-style-guide/
publish/documentation/latest/powered-by-mesos/ publish/documentatio...
Modified: mesos/site/source/documentation/latest/clang-format.md
URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/clang-format.md?rev=1676349&r1=1676348&r2=1676349&view=diff
==============================================================================
--- mesos/site/source/documentation/latest/clang-format.md (original)
+++ mesos/site/source/documentation/latest/clang-format.md Mon Apr 27 17:56:09 2015
@@ -4,17 +4,13 @@ layout: documentation
# ClangFormat
-[ClangFormat](http://llvm.org/releases/3.5.0/tools/clang/docs/ClangFormat.html) is an automatic source code formatting tool which help us focus on the code rather than the formatting.
+[ClangFormat](http://llvm.org/releases/3.5.1/tools/clang/docs/ClangFormat.html) is an automatic source code formatting tool which helps us focus on the code rather than the formatting.
-> The provided configurations try to honor the [Mesos C++ Style Guide](http://mesos.apache.org/documentation/latest/mesos-c++-style-guide/) as much as possible, but there are some limitations. Even with these limitations however, ClangFormat will likely be extremely useful for your workflow!
-
-## Quick Start
-
-If you already have an installation of `clang-format` version >= 3.5, follow your editor's [integration instructions](#integrate-with-your-editor) then start formatting!
+> The provided configurations try to honor the [Mesos C++ Style Guide](http://mesos.apache.org/documentation/latest/mesos-c++-style-guide/) as much as possible, but there are some limitations which require manual attention. Even with these limitations however, ClangFormat will be extremely useful for your workflow!
## Setup
-### Install clang 3.5
+### Install `clang-format-3.5`
#### Ubuntu 14.04
@@ -29,32 +25,26 @@ sudo apt-get install clang-format-3.5
#### OS X Yosemite
```bash
-# Download and extract the clang-3.5 source.
-$ wget http://llvm.org/releases/3.5.0/cfe-3.5.0.src.tar.xz
-$ tar -xzf cfe-3.5.0.src.tar.xz
-
-# Download and extract the clang-3.5 pre-built binaries.
-$ wget http://llvm.org/releases/3.5.0/clang+llvm-3.5.0-macosx-apple-darwin.tar.xz
-$ tar -xzf clang+llvm-3.5.0-macosx-apple-darwin.tar.xz
+# Install clang-3.5. The binaries are suffixed with '-3.5', e.g. 'clang++-3.5'.
+$ brew install llvm35 --with-clang
-# Create a directory for clang.
-$ mkdir `brew --cellar`/clang
-
-# Install the pre-built binaries.
-$ mv clang+llvm-3.5.0-macosx-apple-darwin `brew --cellar`/clang/3.5
+# Download and install the clang-format scripts.
+$ wget http://llvm.org/releases/3.5.1/cfe-3.5.1.src.tar.xz
+$ tar -xzf cfe-3.5.1.src.tar.xz
+$ cp cfe-3.5.1.src/tools/clang-format/clang-format* `brew --cellar`/llvm35/3.5.1/share/clang-3.5
+```
-# Install the clang-format tools.
-$ mkdir `brew --cellar`/clang/3.5/share/clang
-$ cp cfe-3.5.0.src/tools/clang-format/clang-format* `brew --cellar`/clang/3.5/share/clang
+### Formatting Configuration
-# Link!
-$ brew link clang
-Linking /usr/local/Cellar/clang/3.5... 491 symlinks created
+By default, ClangFormat uses the configuration defined in a `.clang-format` or
+`_clang-format` file located in the nearest parent directory of the input file.
+The `bootstrap` script creates a `.clang-format` symlink at the top-level
+directory which points to `support/clang-format` for ClangFormat to find.
-# You can delete cleanly by running `brew uninstall clang`
-```
+> NOTE: If you're using `clang-format-3.6`, you'll need to add a new option
+`BinPackArguments: false` to the `.clang-format` file!
-### Integrate with your editor
+### Editor Integration
#### Vim
@@ -70,8 +60,8 @@ imap <C-K> <c-o>:pyf /usr/share/vim/addo
OS X:
```
-map <C-K> :pyf /usr/local/share/clang/clang-format.py<cr>
-imap <C-K> <c-o>:pyf /usr/local/share/clang/clang-format.py<cr>
+map <C-K> :pyf /usr/local/share/clang-3.5/clang-format.py<cr>
+imap <C-K> <c-o>:pyf /usr/local/share/clang-3.5/clang-format.py<cr>
```
The first line enables clang-format for `NORMAL` and `VISUAL` mode, the second line adds support for `INSERT` mode. Change `C-K` to another binding if you need clang-format on a different key (`C-K` stands for `Ctrl+k`).
@@ -80,7 +70,7 @@ With this integration you can press the
It operates on the current, potentially unsaved buffer and does not create or save any files. To revert a formatting, just undo.
-> Source: http://llvm.org/releases/3.5.0/tools/clang/docs/ClangFormat.html
+> Source: http://llvm.org/releases/3.5.1/tools/clang/docs/ClangFormat.html
#### Emacs
@@ -96,13 +86,13 @@ Ubuntu:
OS X:
```
-(load "/usr/local/share/clang/clang-format.el")
+(load "/usr/local/share/clang-3.5/clang-format.el")
(global-set-key [C-M-tab] 'clang-format-region)
```
This binds the function `clang-format-region` to `C-M-tab`, which then formats the current line or selected region.
-> Source: http://llvm.org/releases/3.5.0/tools/clang/docs/ClangFormat.html
+> Source: http://llvm.org/releases/3.5.1/tools/clang/docs/ClangFormat.html
## Known Limitations
Modified: mesos/site/source/documentation/latest/mesos-c++-style-guide.md
URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/mesos-c%2B%2B-style-guide.md?rev=1676349&r1=1676348&r2=1676349&view=diff
==============================================================================
--- mesos/site/source/documentation/latest/mesos-c++-style-guide.md (original)
+++ mesos/site/source/documentation/latest/mesos-c++-style-guide.md Mon Apr 27 17:56:09 2015
@@ -10,6 +10,28 @@ The Mesos codebase follows the [Google C
### Variable Names
* We use [lowerCamelCase](http://en.wikipedia.org/wiki/CamelCase#Variations_and_synonyms) for variable names (Google uses snake_case, and their class member variables have trailing underscores).
+* We prepend constructor and function arguments with a leading underscore to avoid ambiguity and / or shadowing:
+
+```
+Try(State _state, T* _t = NULL, const std::string& _message = "")
+ : state(_state), t(_t), message(_message) {}
+```
+
+* Prefer trailing underscores for use as member fields (but not required). Some trailing underscores are used to distinguish between similar variables in the same scope (think prime symbols), *but this should be avoided as much as possible, including removing existing instances in the code base.*
+
+* If you find yourself creating a copy of an argument passed by const reference, consider passing it by value instead (if you don't want to use a leading underscore and copy in the body of the function):
+
+```
+// You can pass-by-value in ProtobufProcess::install() handlers.
+void Slave::statusUpdate(StatusUpdate update, const UPID& pid)
+{
+ ...
+ update.mutable_status()->set_source(
+ pid == UPID() ? TaskStatus::SOURCE_SLAVE : TaskStatus::SOURCE_EXECUTOR);
+ ...
+}
+```
+
### Constant Names
* We use [SCREAMING_SNAKE_CASE](http://en.wikipedia.org/wiki/Letter_case#Special_case_styles) for constant names (Google uses a `k` followed by mixed case, e.g. `kDaysInAWeek`).
@@ -25,7 +47,7 @@ The Mesos codebase follows the [Google C
* Strings used in log and error messages should end without a period.
## Comments
-* End each sentence with a period.
+* End each sentence within a comment with a punctuation mark (please note that we generally prefer periods); this applies to incomplete sentences as well.
* At most 70 characters per line in comments.
* For trailing comments, leave one space.
@@ -42,13 +64,13 @@ The Mesos codebase follows the [Google C
* Newline when calling or defining a function: indent with 4 spaces.
* We do not follow Google's style of wrapping on the open parenthesis, the general goal is to reduce visual "jaggedness" in the code. Prefer (1), (4), (5), sometimes (3), never (2):
-<pre>
+```
// 1: OK.
allocator->resourcesRecovered(frameworkId, slaveId, resources, filters);
// 2: Don't use.
allocator->resourcesRecovered(frameworkId, slaveId,
- resources, filters);
+ resources, filters);
// 3: Don't use in this case due to "jaggedness".
allocator->resourcesRecovered(frameworkId,
@@ -71,15 +93,15 @@ allocator->resourcesRecovered(
// 5: OK.
allocator->resourcesRecovered(
frameworkId, slaveId, resources, filters);
-</pre>
+```
### Continuation
* Newline for an assignment statement: indent with 2 spaces.
-<pre>
+```
Try<Duration> failoverTimeout =
Duration::create(FrameworkInfo().failover_timeout());
-</pre>
+```
## Empty Lines
* 1 blank line at the end of the file.
@@ -92,10 +114,9 @@ We still support older compilers. The wh
* Static assertions.
* Multiple right angle brackets.
-* Type inference (`auto` and `decltype`). The main goal is to increase code readability. This is safely the case if the exact same type omitted on the left is already fully stated on the right.
-* Here are several examples:
+* Type inference (`auto` and `decltype`). The main goal is to increase code readability. This is safely the case if the exact same type omitted on the left is already fully stated on the right. Here are several examples:
-<pre>
+```
// 1: OK.
const auto& i = values.find(keys.front());
// Compare with
@@ -110,14 +131,14 @@ shared_ptr<list<string>> names = shared_
auto authorizer = LocalAuthorizer::create(acls);
// Compare with
Try<Owned<LocalAuthorizer>> authorizer = LocalAuthorizer::create();
-</pre>
+```
* Rvalue references.
* Variadic templates.
* Mutexes.
- * std::mutex.
- * std::lock_guard<std::mutex>.
- * std::unique_lock<std::mutex>.
+ * `std::mutex`
+ * `std::lock_guard<std::mutex>`
+ * `std::unique_lock<std::mutex>`
* Shared from this.
- * class T : public std::enable_shared_from_this<T>.
- * shared_from_this().
+ * `class T : public std::enable_shared_from_this<T>`
+ * `shared_from_this()`
Modified: mesos/site/source/documentation/latest/powered-by-mesos.md
URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/powered-by-mesos.md?rev=1676349&r1=1676348&r2=1676349&view=diff
==============================================================================
--- mesos/site/source/documentation/latest/powered-by-mesos.md (original)
+++ mesos/site/source/documentation/latest/powered-by-mesos.md Mon Apr 27 17:56:09 2015
@@ -7,6 +7,7 @@ layout: documentation
## Organizations using Mesos
* [Airbnb](http://www.airbnb.com)
+* [Apple](http://www.apple.com)
* [Artirix](http://www.artirix.com)
* [Atigeo](http://www.atigeo.com)
* [Atlassian](http://www.atlassian.com)
Modified: mesos/site/source/documentation/latest/release-guide.md
URL: http://svn.apache.org/viewvc/mesos/site/source/documentation/latest/release-guide.md?rev=1676349&r1=1676348&r2=1676349&view=diff
==============================================================================
--- mesos/site/source/documentation/latest/release-guide.md (original)
+++ mesos/site/source/documentation/latest/release-guide.md Mon Apr 27 17:56:09 2015
@@ -23,7 +23,10 @@ This guide describes the process of doin
4. Add your GPG fingerprint to your [Apache account](https://id.apache.org/).
5. Create a Maven settings file (`~/.m2/settings.xml`) for the Apache
- servers. Encrypt your Apache password using `mvn --encrypt-password`.
+ servers where you must copy your encrypted Apache password which
+ you can get from running `mvn --encrypt-password` (NOTE: you may
+ need to first generate a [master
+ password](http://maven.apache.org/guides/mini/guide-encryption.html).
```
<settings>
<servers>