diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Block-ABI-Apple.rst | 8 | ||||
| -rw-r--r-- | docs/ClangFormat.rst | 12 | ||||
| -rw-r--r-- | docs/ClangFormatStyleOptions.rst | 300 | ||||
| -rw-r--r-- | docs/LibFormat.rst | 4 | ||||
| -rw-r--r-- | docs/MemorySanitizer.rst | 2 | ||||
| -rw-r--r-- | docs/SourceBasedCodeCoverage.rst | 5 | ||||
| -rw-r--r-- | docs/ThinLTO.rst | 44 | ||||
| -rw-r--r-- | docs/tools/dump_format_style.py | 11 |
8 files changed, 271 insertions, 115 deletions
diff --git a/docs/Block-ABI-Apple.rst b/docs/Block-ABI-Apple.rst index 628e6f3d90ba5..7f49bbd40d71c 100644 --- a/docs/Block-ABI-Apple.rst +++ b/docs/Block-ABI-Apple.rst @@ -856,15 +856,15 @@ mentioned above, call: .. code-block:: c - _Block_object_assign(&dst->target, src->target, BLOCK_FIELD_<appropo>); + _Block_object_assign(&dst->target, src->target, BLOCK_FIELD_<apropos>); in the copy helper and: .. code-block:: c - _Block_object_dispose(->target, BLOCK_FIELD_<appropo>); + _Block_object_dispose(->target, BLOCK_FIELD_<apropos>); -in the dispose helper where ``<appropo>`` is: +in the dispose helper where ``<apropos>`` is: .. code-block:: c @@ -888,7 +888,7 @@ and functions are generated in the same manner. Under ObjC we allow ``__weak`` as an attribute on ``__block`` variables, and this causes the addition of ``BLOCK_FIELD_IS_WEAK`` orred onto the ``BLOCK_FIELD_IS_BYREF`` flag when copying the ``block_byref`` structure in the -``Block`` copy helper, and onto the ``BLOCK_FIELD_<appropo>`` field within the +``Block`` copy helper, and onto the ``BLOCK_FIELD_<apropos>`` field within the ``block_byref`` copy/dispose helper calls. The prototypes, and summary, of the helper functions are: diff --git a/docs/ClangFormat.rst b/docs/ClangFormat.rst index ed0e58e452d30..902afcd08ed5f 100644 --- a/docs/ClangFormat.rst +++ b/docs/ClangFormat.rst @@ -120,6 +120,18 @@ entity. It operates on the current, potentially unsaved buffer and does not create or save any files. To revert a formatting, just undo. +An alternative option is to format changes when saving a file and thus to +have a zero-effort integration into the coding workflow. To do this, add this to +your `.vimrc`: + +.. code-block:: vim + + function! Formatonsave() + let l:formatdiff = 1 + pyf ~/llvm/tools/clang/tools/clang-format/clang-format.py + endfunction + autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave() + Emacs Integration ================= diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst index fb014241809cc..6133ca9900c97 100644 --- a/docs/ClangFormatStyleOptions.rst +++ b/docs/ClangFormatStyleOptions.rst @@ -309,12 +309,28 @@ the configuration (without a prefix: ``Auto``). * ``SFS_None`` (in configuration: ``None``) Never merge functions into a single line. + * ``SFS_InlineOnly`` (in configuration: ``InlineOnly``) + Only merge functions defined inside a class. Same as "inline", + except it does not implies "empty": i.e. top level empty functions + are not merged either. + + .. code-block:: c++ + + class Foo { + void f() { foo(); } + }; + void f() { + foo(); + } + void f() { + } + * ``SFS_Empty`` (in configuration: ``Empty``) Only merge empty functions. .. code-block:: c++ - void f() { bar(); } + void f() {} void f2() { bar2(); } @@ -327,6 +343,10 @@ the configuration (without a prefix: ``Auto``). class Foo { void f() { foo(); } }; + void f() { + foo(); + } + void f() {} * ``SFS_All`` (in configuration: ``All``) Merge all functions fitting on a single line. @@ -518,147 +538,159 @@ the configuration (without a prefix: ``Auto``). * ``bool AfterClass`` Wrap class definitions. - .. code-block:: c++ + .. code-block:: c++ - true: - class foo - {}; + true: + class foo {}; - false: - class foo {}; + false: + class foo + {}; * ``bool AfterControlStatement`` Wrap control statements (``if``/``for``/``while``/``switch``/..). - .. code-block:: c++ + .. code-block:: c++ - true: - if (foo()) - { - } else - {} - for (int i = 0; i < 10; ++i) - {} + true: + if (foo()) + { + } else + {} + for (int i = 0; i < 10; ++i) + {} - false: - if (foo()) { - } else { - } - for (int i = 0; i < 10; ++i) { - } + false: + if (foo()) { + } else { + } + for (int i = 0; i < 10; ++i) { + } * ``bool AfterEnum`` Wrap enum definitions. - .. code-block:: c++ + .. code-block:: c++ - true: - enum X : int - { - B - }; + true: + enum X : int + { + B + }; - false: - enum X : int { B }; + false: + enum X : int { B }; * ``bool AfterFunction`` Wrap function definitions. - .. code-block:: c++ + .. code-block:: c++ - true: - void foo() - { - bar(); - bar2(); - } + true: + void foo() + { + bar(); + bar2(); + } - false: - void foo() { - bar(); - bar2(); - } + false: + void foo() { + bar(); + bar2(); + } * ``bool AfterNamespace`` Wrap namespace definitions. - .. code-block:: c++ + .. code-block:: c++ - true: - namespace - { - int foo(); - int bar(); - } + true: + namespace + { + int foo(); + int bar(); + } - false: - namespace { - int foo(); - int bar(); - } + false: + namespace { + int foo(); + int bar(); + } * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (``@autoreleasepool``, interfaces, ..). * ``bool AfterStruct`` Wrap struct definitions. - .. code-block:: c++ + .. code-block:: c++ - true: - struct foo - { - int x; - }; + true: + struct foo + { + int x; + }; - false: - struct foo { - int x; - }; + false: + struct foo { + int x; + }; * ``bool AfterUnion`` Wrap union definitions. - .. code-block:: c++ + .. code-block:: c++ - true: - union foo - { - int x; - } + true: + union foo + { + int x; + } - false: - union foo { - int x; - } + false: + union foo { + int x; + } * ``bool BeforeCatch`` Wrap before ``catch``. - .. code-block:: c++ + .. code-block:: c++ - true: - try { - foo(); - } - catch () { - } + true: + try { + foo(); + } + catch () { + } - false: - try { - foo(); - } catch () { - } + false: + try { + foo(); + } catch () { + } * ``bool BeforeElse`` Wrap before ``else``. - .. code-block:: c++ + .. code-block:: c++ - true: - if (foo()) { - } - else { - } + true: + if (foo()) { + } + else { + } - false: - if (foo()) { - } else { - } + false: + if (foo()) { + } else { + } * ``bool IndentBraces`` Indent the wrapped braces themselves. + * ``bool SplitEmptyFunctionBody`` If ``false``, empty function body can be put on a single line. + This option is used only if the opening brace of the function has + already been wrapped, i.e. the `AfterFunction` brace wrapping mode is + set, and the function could/should not be put on a single line (as per + `AllowShortFunctionsOnASingleLine` and constructor formatting options). + + .. code-block:: c++ + + int f() vs. inf f() + {} { + } + **BreakAfterJavaFieldAnnotations** (``bool``) Break after each annotation on a field in Java files. @@ -899,17 +931,40 @@ the configuration (without a prefix: ``Auto``). firstValue : SecondValueVeryVeryVeryVeryLong; -**BreakConstructorInitializersBeforeComma** (``bool``) - Always break constructor initializers before commas and align - the commas with the colon. +**BreakConstructorInitializers** (``BreakConstructorInitializersStyle``) + The constructor initializers style to use. + + Possible values: + + * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``) + Break constructor initializers before the colon and after the commas. + + .. code-block:: c++ + + Constructor() + : initializer1(), + initializer2() + + * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``) + Break constructor initializers before the colon and commas, and align + the commas with the colon. + + .. code-block:: c++ + + Constructor() + : initializer1() + , initializer2() + + * ``BCIS_AfterColon`` (in configuration: ``AfterColon``) + Break constructor initializers after the colon and commas. + + .. code-block:: c++ + + Constructor() : + initializer1(), + initializer2() - .. code-block:: c++ - true: false: - SomeClass::Constructor() vs. SomeClass::Constructor() : a(a), - : a(a) b(b), - , b(b) c(c) {} - , c(c) {} **BreakStringLiterals** (``bool``) Allow breaking string literals when formatting. @@ -931,6 +986,31 @@ the configuration (without a prefix: ``Auto``). // Will leave the following line unaffected #include <vector> // FOOBAR pragma: keep +**CompactNamespaces** (``bool``) + If ``true``, consecutive namespace declarations will be on the same + line. If ``false``, each namespace is declared on a new line. + + .. code-block:: c++ + + true: + namespace Foo { namespace Bar { + }} + + false: + namespace Foo { + namespace Bar { + } + } + + If it does not fit on a single line, the overflowing namespaces get + wrapped: + + .. code-block:: c++ + + namespace Foo { namespace Bar { + namespace Extra { + }}} + **ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``) If the constructor initializers don't fit on a line, put each initializer on its own line. @@ -1321,6 +1401,9 @@ the configuration (without a prefix: ``Auto``). Add a space in front of an Objective-C protocol list, i.e. use ``Foo <Protocol>`` instead of ``Foo<Protocol>``. +**PenaltyBreakAssignment** (``unsigned``) + The penalty for breaking around an assignment operator. + **PenaltyBreakBeforeFirstCallParameter** (``unsigned``) The penalty for breaking a function call after ``call(``. @@ -1392,6 +1475,15 @@ the configuration (without a prefix: ``Auto``). #include "b.h" vs. #include "a.h" #include "a.h" #include "b.h" +**SortUsingDeclarations** (``bool``) + If ``true``, clang-format will sort using declarations. + + .. code-block:: c++ + + false: true: + using std::cout; vs. using std::cin; + using std::cin; using std::cout; + **SpaceAfterCStyleCast** (``bool``) If ``true``, a space is inserted after C style casts. diff --git a/docs/LibFormat.rst b/docs/LibFormat.rst index eacdc16145671..086a52827d8ce 100644 --- a/docs/LibFormat.rst +++ b/docs/LibFormat.rst @@ -28,7 +28,9 @@ The core routine of LibFormat is ``reformat()``: This reads a token stream out of the lexer ``Lex`` and reformats all the code ranges in ``Ranges``. The ``FormatStyle`` controls basic decisions made during -formatting. A list of options can be found under :ref:`style-options`. +formatting. A list of options can be found under :ref:`style-options`. + +The style options are described in :doc:`ClangFormatStyleOptions`. .. _style-options: diff --git a/docs/MemorySanitizer.rst b/docs/MemorySanitizer.rst index 8088ecdf561fd..5bb19ed8a5091 100644 --- a/docs/MemorySanitizer.rst +++ b/docs/MemorySanitizer.rst @@ -27,7 +27,7 @@ executable, so make sure to use ``clang`` (not ``ld``) for the final link step. When linking shared libraries, the MemorySanitizer run-time is not linked, so ``-Wl,-z,defs`` may cause link errors (don't use it with MemorySanitizer). To get a reasonable performance add ``-O1`` or -higher. To get meaninful stack traces in error messages add +higher. To get meaningful stack traces in error messages add ``-fno-omit-frame-pointer``. To get perfect stack traces you may need to disable inlining (just use ``-O1``) and tail call elimination (``-fno-optimize-sibling-calls``). diff --git a/docs/SourceBasedCodeCoverage.rst b/docs/SourceBasedCodeCoverage.rst index 474af30ae30f7..805c98794804a 100644 --- a/docs/SourceBasedCodeCoverage.rst +++ b/docs/SourceBasedCodeCoverage.rst @@ -274,6 +274,11 @@ To specify an alternate directory for raw profiles, use Drawbacks and limitations ========================= +* Prior to version 2.26, the GNU binutils BFD linker is not able link programs + compiled with ``-fcoverage-mapping`` in its ``--gc-sections`` mode. Possible + workarounds include disabling ``--gc-sections``, upgrading to a newer version + of BFD, or using the Gold linker. + * Code coverage does not handle unpredictable changes in control flow or stack unwinding in the presence of exceptions precisely. Consider the following function: diff --git a/docs/ThinLTO.rst b/docs/ThinLTO.rst index d417febda502c..31fff51a61e9a 100644 --- a/docs/ThinLTO.rst +++ b/docs/ThinLTO.rst @@ -126,6 +126,50 @@ which currently must be enabled through a linker option. - lld (as of LLVM r296702): ``-Wl,--thinlto-cache-dir=/path/to/cache`` +Cache Pruning +------------- + +To help keep the size of the cache under control, ThinLTO supports cache +pruning. Cache pruning is supported with ld64 and ELF lld, but currently only +ELF lld allows you to control the policy with a policy string. The cache +policy must be specified with a linker option. + +- ELF lld (as of LLVM r298036): + ``-Wl,--thinlto-cache-policy,POLICY`` + +A policy string is a series of key-value pairs separated by ``:`` characters. +Possible key-value pairs are: + +- ``cache_size=X%``: The maximum size for the cache directory is ``X`` percent + of the available space on the the disk. Set to 100 to indicate no limit, + 50 to indicate that the cache size will not be left over half the available + disk space. A value over 100 is invalid. A value of 0 disables the percentage + size-based pruning. The default is 75%. + +- ``cache_size_bytes=X``, ``cache_size_bytes=Xk``, ``cache_size_bytes=Xm``, + ``cache_size_bytes=Xg``: + Sets the maximum size for the cache directory to ``X`` bytes (or KB, MB, + GB respectively). A value over the amount of available space on the disk + will be reduced to the amount of available space. A value of 0 disables + the byte size-based pruning. The default is no byte size-based pruning. + + Note that ThinLTO will apply both size-based pruning policies simultaneously, + and changing one does not affect the other. For example, a policy of + ``cache_size_bytes=1g`` on its own will cause both the 1GB and default 75% + policies to be applied unless the default ``cache_size`` is overridden. + +- ``prune_after=Xs``, ``prune_after=Xm``, ``prune_after=Xh``: Sets the + expiration time for cache files to ``X`` seconds (or minutes, hours + respectively). When a file hasn't been accessed for ``prune_after`` seconds, + it is removed from the cache. A value of 0 disables the expiration-based + pruning. The default is 1 week. + +- ``prune_interval=Xs``, ``prune_interval=Xm``, ``prune_interval=Xh``: + Sets the pruning interval to ``X`` seconds (or minutes, hours + respectively). This is intended to be used to avoid scanning the directory + too often. It does not impact the decision of which files to prune. A + value of 0 forces the scan to occur. The default is every 20 minutes. + Clang Bootstrap --------------- diff --git a/docs/tools/dump_format_style.py b/docs/tools/dump_format_style.py index 81a5af6ef42bf..e2571f46448d2 100644 --- a/docs/tools/dump_format_style.py +++ b/docs/tools/dump_format_style.py @@ -24,10 +24,10 @@ def doxygen2rst(text): text = re.sub(r'\\\w+ ', '', text) return text -def indent(text, columns): +def indent(text, columns, indent_first_line=True): indent = ' ' * columns s = re.sub(r'\n([^\n])', '\n' + indent + '\\1', text, flags=re.S) - if s.startswith('\n'): + if not indent_first_line or s.startswith('\n'): return s return indent + s @@ -64,7 +64,9 @@ class NestedField: self.comment = comment.strip() def __str__(self): - return '\n* ``%s`` %s' % (self.name, doxygen2rst(self.comment)) + return '\n* ``%s`` %s' % ( + self.name, + doxygen2rst(indent(self.comment, 2, indent_first_line=False))) class Enum: def __init__(self, name, comment): @@ -179,7 +181,7 @@ def read_options(header): if enums.has_key(option.type): option.enum = enums[option.type] elif nested_structs.has_key(option.type): - option.nested_struct = nested_structs[option.type]; + option.nested_struct = nested_structs[option.type] else: raise Exception('Unknown type: %s' % option.type) return options @@ -195,4 +197,3 @@ contents = substitute(contents, 'FORMAT_STYLE_OPTIONS', options_text) with open(DOC_FILE, 'wb') as output: output.write(contents) - |