.. index:: cpp11-migrate

===========================
cpp11-migrate User's Manual
===========================

.. toctree::
   :hidden:

   UseAutoTransform
   UseNullptrTransform
   LoopConvertTransform
   AddOverrideTransform

:program:`cpp11-migrate` is a standalone tool used to automatically convert
C++98 and C++03 code to use features of the new C++11 standard where
appropriate.

Basic Usage
===========

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

``<source0>...`` specify the paths of files in the CMake source tree,
with the same requirements as other tools built on LibTooling.

Command Line Options
--------------------

.. option:: -help

  Displays tool usage instructions and 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:: -p=<build-path>

  ``<build-path>`` is a CMake build directory containing a file named
  ``compile_commands.json`` which provides compiler options for building
  each source file and can be generated by specifying
  ``-DCMAKE_EXPORT_COMPILE_COMMANDS`` when running CMake. If ``<build-path>``
  is not provided the ``compile_commands.json`` file is searched for through
  all parent directories.

  Alternatively, one can provide compile options to be applied to every
  source file after the optional ``--``.

.. 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:: -fatal-assembler-warnings

  Treat all compiler warnings as errors.


.. option:: -version

  Displays the version information of this tool.

.. _transforms:

Transformations
===============

* :doc:`LoopConvertTransform`

* :doc:`UseNullptrTransform`

* :doc:`UseAutoTransform`