docs/ModernizerUsage.rst

=====================
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`` 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`.