docs/MigratorUsage.rst - llvm-project/clang-tools-extra - Git at Google

 ===================
 cpp11-migrate Usage
 ===================

 ``cpp11-migrate [options] <source0> [... <sourceN>] [-- [args]]``

 ``<source#>`` specifies the path to the source to migrate. This path may be
 relative to the current directory.

 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.

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

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

 .. _Ninja: http://martine.github.io/ninja/

 .. 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:: -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:
       //     cpp11-migrate -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:
       //     cpp11-migrate -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
   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
   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`:

      ``cpp11-migrate -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:

      ``cpp11-migrate -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 Migrator 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.

 .. _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:: -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`.
	===================
	cpp11-migrate Usage
	===================

	``cpp11-migrate [options] <source0> [... <sourceN>] [-- [args]]``

	``<source#>`` specifies the path to the source to migrate. This path may be
	relative to the current directory.

	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.

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

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

	.. _Ninja: http://martine.github.io/ninja/

	.. 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:: -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:
	// cpp11-migrate -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:
	// cpp11-migrate -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
	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
	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`:

	``cpp11-migrate -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:

	``cpp11-migrate -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 Migrator 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.

	.. _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:: -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`.