forked from OSchip/llvm-project
314 lines
11 KiB
ReStructuredText
314 lines
11 KiB
ReStructuredText
=====================
|
|
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. 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:
|
|
|
|
1. Explicitly, by referring to the transform options directly, see
|
|
:ref:`transform-specific-command-line-options`.
|
|
2. Implicitly, based on the compilers to support, see
|
|
:ref:`-for-compilers=\<string\> <for-compilers-option>`.
|
|
|
|
If both ways of specifying transforms are used only explicitly specified
|
|
transformations that are supported by the given compilers will be applied.
|
|
|
|
General Command Line Options
|
|
============================
|
|
|
|
.. option:: -help
|
|
|
|
Displays tool usage instructions and command line options.
|
|
|
|
.. option:: -version
|
|
|
|
Displays the version information of this tool.
|
|
|
|
.. _-p:
|
|
|
|
.. option:: -p=<build-path>
|
|
|
|
``<build-path>`` is the directory containing a *compilation databasefile*, a
|
|
file named ``compile_commands.json``, which provides compiler arguments for
|
|
building each source file. CMake can generate this file by specifying
|
|
``-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`` when running CMake. Ninja_, since v1.2
|
|
can also generate this file with ``ninja -t compdb``. If the compilation
|
|
database cannot be used for any reason, an error is reported.
|
|
|
|
This option is ignored if ``--`` is present.
|
|
|
|
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
|
|
command line following ``--``. Arguments provided this way are used for
|
|
*every* source file.
|
|
|
|
If neither ``--`` nor ``-p`` are specified a compilation database is
|
|
searched for starting with the path of the first-provided source file and
|
|
proceeding through parent directories. If no compilation database is found or
|
|
one is found and cannot be used for any reason then ``-std=c++11`` is used as
|
|
the only compiler argument.
|
|
|
|
.. option:: -risk=<risk-level>
|
|
|
|
Some transformations may cause a change in semantics. In such cases the
|
|
maximum acceptable risk level specified through the ``-risk`` command
|
|
line option decides whether or not a transformation is applied.
|
|
|
|
Three different risk level options are available:
|
|
|
|
``-risk=safe``
|
|
Perform only safe transformations.
|
|
``-risk=reasonable`` (default)
|
|
Enable transformations that may change semantics.
|
|
``-risk=risky``
|
|
Enable transformations that are likely to change semantics.
|
|
|
|
The meaning of risk is handled differently for each transform. See
|
|
:ref:`transform documentation <transforms>` for details.
|
|
|
|
.. option:: -final-syntax-check
|
|
|
|
After applying the final transform to a file, parse the file to ensure the
|
|
last transform did not introduce syntax errors. Syntax errors introduced by
|
|
earlier transforms are already caught when subsequent transforms parse the
|
|
file.
|
|
|
|
.. option:: -summary
|
|
|
|
Displays a summary of the number of changes each transform made or could have
|
|
made to each source file immediately after each transform is applied.
|
|
**Accepted** changes are those actually made. **Rejected** changes are those
|
|
that could have been made if the acceptable risk level were higher.
|
|
**Deferred** changes are those that might be possible but they might conflict
|
|
with other accepted changes. Re-applying the transform will resolve deferred
|
|
changes.
|
|
|
|
.. _for-compilers-option:
|
|
|
|
.. option:: -for-compilers=<string>
|
|
|
|
Select transforms targeting the intersection of language features supported by
|
|
the given compilers.
|
|
|
|
Four compilers are supported. The transforms are enabled according to this
|
|
table:
|
|
|
|
=============== ===== === ==== ====
|
|
Transforms clang gcc icc mscv
|
|
=============== ===== === ==== ====
|
|
AddOverride (1) 3.0 4.7 14 8
|
|
LoopConvert 3.0 4.6 13 11
|
|
PassByValue 3.0 4.6 13 11
|
|
ReplaceAutoPtr 3.0 4.6 13 11
|
|
UseAuto 2.9 4.4 12 10
|
|
UseNullptr 3.0 4.6 12.1 10
|
|
=============== ===== === ==== ====
|
|
|
|
(1): if *-override-macros* is provided it's assumed that the macros are C++11
|
|
aware and the transform is enabled without regard to the supported compilers.
|
|
|
|
The structure of the argument to the `-for-compilers` option is
|
|
**<compiler>-<major ver>[.<minor ver>]** where **<compiler>** is one of the
|
|
compilers from the above table.
|
|
|
|
Some examples:
|
|
|
|
1. To support `Clang >= 3.0`, `gcc >= 4.6` and `MSVC >= 11`:
|
|
|
|
``clang-modernize -for-compilers=clang-3.0,gcc-4.6,msvc-11 <args..>``
|
|
|
|
Enables LoopConvert, ReplaceAutoPtr, UseAuto, UseNullptr.
|
|
|
|
2. To support `icc >= 12` while using a C++11-aware macro for the `override`
|
|
virtual specifier:
|
|
|
|
``clang-modernize -for-compilers=icc-12 -override-macros <args..>``
|
|
|
|
Enables AddOverride and UseAuto.
|
|
|
|
.. warning::
|
|
|
|
If your version of Clang depends on the GCC headers (e.g: when `libc++` is
|
|
not used), then you probably want to add the GCC version to the targeted
|
|
platforms as well.
|
|
|
|
.. option:: -perf[=<directory>]
|
|
|
|
Turns on performance measurement and output functionality. The time it takes to
|
|
apply each transform is recorded by the migrator and written in JSON format
|
|
to a uniquely named file in the given ``<directory>``. All sources processed
|
|
by a single Modernizer process are written to the same output file. If
|
|
``<directory>`` is not provided the default is ``./migrate_perf/``.
|
|
|
|
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
|
|
=======================================
|
|
|
|
.. option:: -loop-convert
|
|
|
|
Makes use of C++11 range-based for loops where possible. See
|
|
:doc:`LoopConvertTransform`.
|
|
|
|
.. option:: -use-nullptr
|
|
|
|
Makes use of the new C++11 keyword ``nullptr`` where possible.
|
|
See :doc:`UseNullptrTransform`.
|
|
|
|
.. option:: -user-null-macros=<string>
|
|
|
|
``<string>`` is a comma-separated list of user-defined macros that behave like
|
|
the ``NULL`` macro. The :option:`-use-nullptr` transform will replace these
|
|
macros along with ``NULL``. See :doc:`UseNullptrTransform`.
|
|
|
|
.. option:: -use-auto
|
|
|
|
Replace the type specifier of variable declarations with the ``auto`` type
|
|
specifier. See :doc:`UseAutoTransform`.
|
|
|
|
.. option:: -add-override
|
|
|
|
Adds the override specifier to member functions where it is appropriate. That
|
|
is, the override specifier is added to member functions that override a
|
|
virtual function in a base class and that don't already have the specifier.
|
|
See :doc:`AddOverrideTransform`.
|
|
|
|
.. option:: -override-macros
|
|
|
|
Tells the Add Override Transform to locate a macro that expands to
|
|
``override`` and use that macro instead of the ``override`` keyword directly.
|
|
If no such macro is found, ``override`` is still used. This option enables
|
|
projects that use such macros to maintain build compatibility with non-C++11
|
|
code.
|
|
|
|
.. option:: -pass-by-value
|
|
|
|
Replace const-reference parameters by values in situations where it can be
|
|
beneficial.
|
|
See :doc:`PassByValueTransform`.
|
|
|
|
.. option:: -replace-auto_ptr
|
|
|
|
Replace ``std::auto_ptr`` (deprecated in C++11) by ``std::unique_ptr`` and
|
|
wrap calls to the copy constructor and assignment operator with
|
|
``std::move()``.
|
|
See :doc:`ReplaceAutoPtrTransform`.
|