| Edwin Vane | e4e7c24 | 2013-03-09 03:33:50 +0000 | [diff] [blame] | 1 | .. index:: cpp11-migrate |
| 2 | |
| Edwin Vane | 30f7004 | 2013-02-25 20:37:03 +0000 | [diff] [blame] | 3 | =========================== |
| 4 | cpp11-migrate User's Manual |
| 5 | =========================== |
| 6 | |
| Edwin Vane | 3b9f08d | 2013-03-08 23:26:00 +0000 | [diff] [blame] | 7 | .. toctree:: |
| 8 | :hidden: |
| 9 | |
| 10 | UseAutoTransform |
| Edwin Vane | e4e7c24 | 2013-03-09 03:33:50 +0000 | [diff] [blame] | 11 | UseNullptrTransform |
| 12 | LoopConvertTransform |
| Edwin Vane | 3b9f08d | 2013-03-08 23:26:00 +0000 | [diff] [blame] | 13 | |
| Edwin Vane | 30f7004 | 2013-02-25 20:37:03 +0000 | [diff] [blame] | 14 | :program:`cpp11-migrate` is a standalone tool used to automatically convert |
| 15 | C++98 and C++03 code to use features of the new C++11 standard where |
| 16 | appropriate. |
| 17 | |
| 18 | Basic Usage |
| 19 | =========== |
| 20 | |
| 21 | ``cpp11-migrate [options] <source0> [... <sourceN>]`` |
| 22 | |
| 23 | ``<source0>...`` specify the paths of files in the CMake source tree, |
| 24 | with the same requirements as other tools built on LibTooling. |
| 25 | |
| 26 | Command Line Options |
| 27 | -------------------- |
| 28 | |
| Edwin Vane | 30f7004 | 2013-02-25 20:37:03 +0000 | [diff] [blame] | 29 | .. option:: -help |
| 30 | |
| 31 | Displays tool usage instructions and command line options. |
| 32 | |
| 33 | .. option:: -loop-convert |
| 34 | |
| Edwin Vane | e4e7c24 | 2013-03-09 03:33:50 +0000 | [diff] [blame] | 35 | Makes use of C++11 range-based for loops where possible. See |
| 36 | :doc:`LoopConvertTransform`. |
| 37 | |
| 38 | .. option:: -use-nullptr |
| 39 | |
| 40 | Makes use of the new C++11 keyword ``nullptr`` where possible. |
| 41 | See :doc:`UseNullptrTransform`. |
| Edwin Vane | 30f7004 | 2013-02-25 20:37:03 +0000 | [diff] [blame] | 42 | |
| Tareq A. Siraj | c2aa348d | 2013-03-28 16:06:59 +0000 | [diff] [blame^] | 43 | .. option:: -user-null-macros=<string> |
| 44 | |
| 45 | ``<string>`` is a comma-separated list of user-defined macros that behave like |
| 46 | the ``NULL`` macro. The :option:`-use-nullptr` transform will replace these |
| 47 | macros along with ``NULL``. See :doc:`UseNullptrTransform`. |
| 48 | |
| Edwin Vane | 3b9f08d | 2013-03-08 23:26:00 +0000 | [diff] [blame] | 49 | .. option:: -use-auto |
| 50 | |
| 51 | Replace the type specifier of variable declarations with the ``auto`` type |
| 52 | specifier. See :doc:`UseAutoTransform`. |
| 53 | |
| Edwin Vane | 30f7004 | 2013-02-25 20:37:03 +0000 | [diff] [blame] | 54 | .. option:: -p=<build-path> |
| 55 | |
| 56 | ``<build-path>`` is a CMake build directory containing a file named |
| 57 | ``compile_commands.json`` which provides compiler options for building |
| 58 | each source file and can be generated by specifying |
| 59 | ``-DCMAKE_EXPORT_COMPILE_COMMANDS`` when running CMake. If ``<build-path>`` |
| 60 | is not provided the ``compile_commands.json`` file is searched for through |
| 61 | all parent directories. |
| 62 | |
| 63 | Alternatively, one can provide compile options to be applied to every |
| 64 | source file after the optional ``--``. |
| 65 | |
| 66 | .. option:: -risk=<risk-level> |
| 67 | |
| 68 | Some transformations may cause a change in semantics. In such cases the |
| 69 | maximum acceptable risk level specified through the ``-risk`` command |
| 70 | line option decides whether or not a transformation is applied. |
| 71 | |
| 72 | Three different risk level options are available: |
| 73 | |
| 74 | ``-risk=safe`` |
| 75 | Perform only safe transformations. |
| 76 | ``-risk=reasonable`` (default) |
| 77 | Enable transformations that may change semantics. |
| 78 | ``-risk=risky`` |
| 79 | Enable transformations that are likely to change semantics. |
| 80 | |
| Edwin Vane | e4e7c24 | 2013-03-09 03:33:50 +0000 | [diff] [blame] | 81 | The meaning of risk is handled differently for each transform. See |
| 82 | :ref:`transform documentation <transforms>` for details. |
| Edwin Vane | 30f7004 | 2013-02-25 20:37:03 +0000 | [diff] [blame] | 83 | |
| Edwin Vane | bdcd135 | 2013-03-09 03:38:20 +0000 | [diff] [blame] | 84 | .. option:: -final-syntax-check |
| Tareq A. Siraj | c2aa348d | 2013-03-28 16:06:59 +0000 | [diff] [blame^] | 85 | |
| Edwin Vane | bdcd135 | 2013-03-09 03:38:20 +0000 | [diff] [blame] | 86 | After applying the final transform to a file, parse the file to ensure the |
| 87 | last transform did not introduce syntax errors. Syntax errors introduced by |
| 88 | earlier transforms are already caught when subsequent transforms parse the |
| 89 | file. |
| 90 | |
| 91 | .. option:: -fatal-assembler-warnings |
| 92 | |
| 93 | Treat all compiler warnings as errors. |
| 94 | |
| Edwin Vane | 30f7004 | 2013-02-25 20:37:03 +0000 | [diff] [blame] | 95 | |
| 96 | .. option:: -version |
| 97 | |
| 98 | Displays the version information of this tool. |
| 99 | |
| Edwin Vane | e4e7c24 | 2013-03-09 03:33:50 +0000 | [diff] [blame] | 100 | .. _transforms: |
| Edwin Vane | 30f7004 | 2013-02-25 20:37:03 +0000 | [diff] [blame] | 101 | |
| 102 | Transformations |
| 103 | =============== |
| 104 | |
| Edwin Vane | e4e7c24 | 2013-03-09 03:33:50 +0000 | [diff] [blame] | 105 | * :doc:`LoopConvertTransform` |
| Edwin Vane | 30f7004 | 2013-02-25 20:37:03 +0000 | [diff] [blame] | 106 | |
| Edwin Vane | e4e7c24 | 2013-03-09 03:33:50 +0000 | [diff] [blame] | 107 | * :doc:`UseNullptrTransform` |
| Edwin Vane | 30f7004 | 2013-02-25 20:37:03 +0000 | [diff] [blame] | 108 | |
| Edwin Vane | e4e7c24 | 2013-03-09 03:33:50 +0000 | [diff] [blame] | 109 | * :doc:`UseAutoTransform` |