diff --git a/clang-tools-extra/docs/ModernizerUsage.rst b/clang-tools-extra/docs/ModernizerUsage.rst index bc09eec0af76..d5ef9ae9ef6d 100644 --- a/clang-tools-extra/docs/ModernizerUsage.rst +++ b/clang-tools-extra/docs/ModernizerUsage.rst @@ -5,7 +5,9 @@ clang-modernize Usage ``clang-modernize [options] [...] [-- [args]]`` ```` 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= ```` 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=,,..., - - 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=,,..., - - 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= - - Like ``-include`` but read paths from the given file. Paths should be one per - line. - -.. option:: -exclude-from= - - Like ``-exclude`` but read paths from the given file. Paths are listed one - per line. - .. option:: -risk= 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= - - 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::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= + + Choose a directory to serialize replacements to. The directory must exist. + +.. _include/exclude options: + +Path Inclusion/Exclusion Options +================================ + +.. option:: -include=,,..., + + 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=,,..., + + 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= + + Like ``-include`` but read paths from the given file. Paths should be one per + line. + +.. option:: -exclude-from= + + 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= + + 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= + + 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::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 diff --git a/clang-tools-extra/docs/clang-modernize.rst b/clang-tools-extra/docs/clang-modernize.rst index bbcba93211cd..cec6a8baa545 100644 --- a/clang-tools-extra/docs/clang-modernize.rst +++ b/clang-tools-extra/docs/clang-modernize.rst @@ -60,12 +60,19 @@ In addition to the compiler arguments you usually build your code with, you must 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