Magic-Mirror/llvm-capstone
1
0
Fork 0
mirror of https://github.com/capstone-engine/llvm-capstone.git synced 2025-01-08 09:03:18 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Update clang-modernizer docs

Browse Source 
Summary: Docs updated to reflect new behaviour and new options.

Differential Revision: http://llvm-reviews.chandlerc.com/D1841

llvm-svn: 192105
This commit is contained in:
Edwin Vane 2013-10-07 15:56:25 +00:00
parent 6339988787
commit c76c0dd952
2 changed files with 116 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

172
clang-tools-extra/docs/ModernizerUsage.rst
View File

@ -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

17
clang-tools-extra/docs/clang-modernize.rst
View File

@ -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