=================== cpp11-migrate Usage =================== ``cpp11-migrate [options] [... ] [-- [args]]`` ```` 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=\

`. 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[=] ```` is the directory containing 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 ```` is not provided the ``compile_commands.json`` file is searched for through all parent directories. .. 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 ``-p`` is not specified, ``--`` is necessary, even if no compiler arguments are required. .. _Ninja: http://martine.github.io/ninja/ .. option:: -risk= 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 ` 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= 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::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= 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 **-[.]** where **** 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 `` 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 `` 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[=] 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 ````. All sources processed by a single Migrator process are written to the same output file. If ```` 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= ```` 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`.