1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
===================
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
PassByValue 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:: -pass-by-value
Replace const-reference parameters by values in situations where it can be
beneficial.
See :doc:`PassByValueTransform`.
.. 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`.
|
