[clang-tools-extra] r192105 - Update clang-modernizer docs
Edwin Vane
edwin.vane at intel.com
Mon Oct 7 08:56:25 PDT 2013
Author: revane
Date: Mon Oct 7 10:56:25 2013
New Revision: 192105
URL: http://llvm.org/viewvc/llvm-project?rev=192105&view=rev
Log:
Update clang-modernizer docs
Summary: Docs updated to reflect new behaviour and new options.
Differential Revision: http://llvm-reviews.chandlerc.com/D1841
Modified:
clang-tools-extra/trunk/docs/ModernizerUsage.rst
clang-tools-extra/trunk/docs/clang-modernize.rst
Modified: clang-tools-extra/trunk/docs/ModernizerUsage.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/ModernizerUsage.rst?rev=192105&r1=192104&r2=192105&view=diff
==============================================================================
--- clang-tools-extra/trunk/docs/ModernizerUsage.rst (original)
+++ clang-tools-extra/trunk/docs/ModernizerUsage.rst Mon Oct 7 10:56:25 2013
@@ -5,7 +5,9 @@ clang-modernize Usage
``clang-modernize [options] [<sources>...] [-- [args]]``
``<source#>`` specifies the path to the source to migrate. This path may be
-relative to the current directory.
+relative to the current directory. If no sources are provided, a compilation
+database provided with `-p`_ can be used to provide sources together with the
+`include/exclude options`_.
By default all transformations are applied. There are two ways to enable a
subset of the transformations:
@@ -29,6 +31,8 @@ General Command Line Options
Displays the version information of this tool.
+.. _-p:
+
.. option:: -p=<build-path>
``<build-path>`` is the directory containing a *compilation databasefile*, a
@@ -40,8 +44,8 @@ General Command Line Options
This option is ignored if ``--`` is present.
- Files in the compilation database that can be transformed if no sources are
- provided and file paths are explicitly included using ``-include`` or
+ Files in the compilation database will be transformed if no sources are
+ provided and paths to files are explicitly included using ``-include`` or
``-include-from``.
In order to transform all files in a compilation database the following
command line can be used:
@@ -50,6 +54,8 @@ General Command Line Options
Use ``-exclude`` or ``-exclude-from`` to limit the scope of ``-include``.
+.. _Ninja: http://martine.github.io/ninja/
+
.. option:: -- [args]
Another way to provide compiler arguments is to specify all arguments on the
@@ -62,34 +68,6 @@ General Command Line Options
one is found and cannot be used for any reason then ``-std=c++11`` is used as
the only compiler argument.
-.. _Ninja: http://martine.github.io/ninja/
-
-.. option:: -include=<path1>,<path2>,...,<pathN>
-
- Use this option to indicate which directories contain files that can be
- changed by the modernizer. Inidividual files may be specified if desired.
- Multiple paths can be specified as a comma-separated list. Sources mentioned
- explicitly on the command line are always included so this option controls
- which other files (e.g. headers) may be changed while transforming
- translation units.
-
-.. option:: -exclude=<path1>,<path2>,...,<pathN>
-
- Used with ``-include`` to provide finer control over which files and
- directories can be transformed. Individual files and files within directories
- specified by this option **will not** be transformed. Multiple paths can be
- specified as a comma-separated list.
-
-.. option:: -include-from=<filename>
-
- Like ``-include`` but read paths from the given file. Paths should be one per
- line.
-
-.. option:: -exclude-from=<filename>
-
- Like ``-exclude`` but read paths from the given file. Paths are listed one
- per line.
-
.. option:: -risk=<risk-level>
Some transformations may cause a change in semantics. In such cases the
@@ -115,43 +93,6 @@ General Command Line Options
earlier transforms are already caught when subsequent transforms parse the
file.
-.. option:: -format-style=<string>
-
- After all transformations have been applied, reformat the changes using the
- style ``string`` given as argument to the option. The style can be a builtin
- style, one of LLVM, Google, Chromium, Mozilla; or a YAML configuration file.
-
- If you want a place to start for using your own custom configuration file,
- ClangFormat_ can generate a file with ``clang-format -dump-config``.
-
- Example:
-
- .. code-block:: c++
- :emphasize-lines: 10-12,18
-
- // file.cpp
- for (std::vector<int>::const_iterator I = my_container.begin(),
- E = my_container.end();
- I != E; ++I) {
- std::cout << *I << std::endl;
- }
-
- // No reformatting:
- // clang-modernize -use-auto file.cpp --
- for (auto I = my_container.begin(),
- E = my_container.end();
- I != E; ++I) {
- std::cout << *I << std::endl;
- }
-
- // With reformatting enabled:
- // clang-modernize -format-style=LLVM -use-auto file.cpp --
- for (auto I = my_container.begin(), E = my_container.end(); I != E; ++I) {
- std::cout << *I << std::endl;
- }
-
-.. _ClangFormat: http://clang.llvm.org/docs/ClangFormat.html
-
.. option:: -summary
Displays a summary of the number of changes each transform made or could have
@@ -222,6 +163,101 @@ General Command Line Options
The time recorded for a transform includes parsing and creating source code
replacements.
+.. option:: -serialize-replacements
+
+ Causes the modernizer to generate replacements and serialize them to disk but
+ not apply them. This can be useful for debugging or for manually running
+ ``clang-apply-replacements``. Replacements are serialized in YAML_ format.
+ By default serialzied replacements are written to a temporary directory whose
+ name is written to stderr when serialization is complete.
+
+.. _YAML: http://www.yaml.org/
+
+.. option:: -serialize-dir=<string>
+
+ Choose a directory to serialize replacements to. The directory must exist.
+
+.. _include/exclude options:
+
+Path Inclusion/Exclusion Options
+================================
+
+.. option:: -include=<path1>,<path2>,...,<pathN>
+
+ Use this option to indicate which directories contain files that can be
+ changed by the modernizer. Inidividual files may be specified if desired.
+ Multiple paths can be specified as a comma-separated list. Sources mentioned
+ explicitly on the command line are always included so this option controls
+ which other files (e.g. headers) may be changed while transforming
+ translation units.
+
+.. option:: -exclude=<path1>,<path2>,...,<pathN>
+
+ Used with ``-include`` to provide finer control over which files and
+ directories can be transformed. Individual files and files within directories
+ specified by this option **will not** be transformed. Multiple paths can be
+ specified as a comma-separated list.
+
+.. option:: -include-from=<filename>
+
+ Like ``-include`` but read paths from the given file. Paths should be one per
+ line.
+
+.. option:: -exclude-from=<filename>
+
+ Like ``-exclude`` but read paths from the given file. Paths are listed one
+ per line.
+
+Formatting Command Line Options
+===============================
+
+.. option:: -format
+
+ Enable reformatting of code changed by transforms. Formatting is done after
+ every transform.
+
+.. option:: -style=<string>
+
+ Specifies how formatting should be done. The behaviour of this option is
+ identical to the same option provided by clang-format_. Refer to
+ `clang-format's style options`_ for more details.
+
+.. option:: -style-config=<dir>
+
+ When using ``-style=file``, the default behaviour is to look for
+ ``.clang-format`` starting in the current directory and then in ancestors. To
+ specify a directory to find the style configuration file, use this option.
+
+Example:
+
+.. code-block:: c++
+ :emphasize-lines: 10-12,18
+
+ // file.cpp
+ for (std::vector<int>::const_iterator I = my_container.begin(),
+ E = my_container.end();
+ I != E; ++I) {
+ std::cout << *I << std::endl;
+ }
+
+ // No reformatting:
+ // clang-modernize -use-auto file.cpp
+ for (auto I = my_container.begin(),
+ E = my_container.end();
+ I != E; ++I) {
+ std::cout << *I << std::endl;
+ }
+
+ // With reformatting enabled:
+ // clang-modernize -format -use-auto file.cpp
+ for (auto I = my_container.begin(), E = my_container.end(); I != E; ++I) {
+ std::cout << *I << std::endl;
+ }
+
+.. _clang-format: http://clang.llvm.org/docs/ClangFormat.html
+.. _clang-format's style options: http://clang.llvm.org/docs/ClangFormatStyleOptions.html
+
+
.. _transform-specific-command-line-options:
Transform-Specific Command Line Options
Modified: clang-tools-extra/trunk/docs/clang-modernize.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/clang-modernize.rst?rev=192105&r1=192104&r2=192105&view=diff
==============================================================================
--- clang-tools-extra/trunk/docs/clang-modernize.rst (original)
+++ clang-tools-extra/trunk/docs/clang-modernize.rst Mon Oct 7 10:56:25 2013
@@ -60,12 +60,19 @@ In addition to the compiler arguments yo
provide the option for enabling C++11 features. For clang and versions of gcc
⥠v4.8 this is ``-std=c++11``.
-Now with compiler arguments, the Modernizer can be applied to source. Sources
-are transformed in place and changes are only written to disk if compilation
-errors aren't caused by the transforms. Each transform will re-parse the output
-from the previous transform. The output from the last transform is not checked
-unless ``-final-syntax-check`` is enabled.
+With compiler arguments in hand, the modernizer can be applied to sources. Each
+transform is applied to all sources before the next transform. All the changes
+generated by each transform pass are serialized to disk and applied using
+``clang-apply-replacements``. This executable must be located on the ``PATH``
+or be present in the same directory as the ``clang-modernizer`` executable. If
+any changes fail to apply, the modernizer will **not** proceed to the next
+transform and will halt.
+There's a small chance that changes made by a transform will produce code that
+doesn't compile, also causing the modernizer to halt. This can happen with
+bugs in the transforms or use of the pre-processor to make the same code behave
+differently between translation units. Before logging a bug, be sure which
+situation you are dealing with.
.. _Ninja: http://martine.github.io/ninja/
.. _Bear: https://github.com/rizsotto/Bear
More information about the cfe-commits
mailing list