Hi tareqsiraj, arielbernal, Sarcasm,
Docs updated to reflect new behaviour and new options.
http://llvm-reviews.chandlerc.com/D1841
Files:
docs/ModernizerUsage.rst
docs/clang-modernize.rst
Index: docs/ModernizerUsage.rst
===================================================================
--- docs/ModernizerUsage.rst
+++ docs/ModernizerUsage.rst
@@ -5,7 +5,9 @@
``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 @@
Displays the version information of this tool.
+.. _-p:
+
.. option:: -p=<build-path>
``<build-path>`` is the directory containing a *compilation databasefile*, a
@@ -40,16 +44,18 @@
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:
``clang-modernize -p=<build-path> -include=<project_root>``
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 @@
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 @@
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 @@
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
Index: docs/clang-modernize.rst
===================================================================
--- docs/clang-modernize.rst
+++ docs/clang-modernize.rst
@@ -60,12 +60,19 @@
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
_______________________________________________
cfe-commits mailing list
[email protected]
http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
