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