cpp11-migrate: Docs refresh
* Documented new command-line options. * Moved usage to a new page. * Usage now split into general options and transform-related options. * Main Migrator page now contains getting started and getting involved information. * Also included a JIRA issue collector button for logging bugs. llvm-svn: 183417
This commit is contained in:
Edwin Vane
parent
3b03728227
commit
573ec4f1aa
|
|
@ -25,6 +25,16 @@ For example:
|
|||
void h() const override;
|
||||
};
|
||||
|
||||
Using Expands-to-Override Macros
|
||||
--------------------------------
|
||||
|
||||
Like LLVM's ``LLVM_OVERRIDE``, several projects have macros that conditionally
|
||||
expand to the ``override`` keyword when compiling with C++11 features enabled.
|
||||
To maintain compatibility with non-C++11 builds, the Add-Override Transform
|
||||
supports detection and use of these macros instead of using the ``override``
|
||||
keyword directly. Specify ``-override-macros`` on the command line to the
|
||||
Migrator to enable this behavior.
|
||||
|
||||
|
||||
Known Limitations
|
||||
-----------------
|
||||
|
|
|
|||
|
|
@ -0,0 +1,128 @@
|
|||
===================
|
||||
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.
|
||||
|
||||
At least one transform must be enabled.
|
||||
|
||||
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 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 ``<build-path>`` 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=<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:: -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.
|
||||
|
||||
.. 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
|
||||
---------------------------------------
|
||||
|
||||
.. 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.
|
||||
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
.. index:: cpp11-migrate
|
||||
|
||||
===========================
|
||||
cpp11-migrate User's Manual
|
||||
===========================
|
||||
============================
|
||||
C++11 Migrator User's Manual
|
||||
============================
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
|
@ -11,107 +11,105 @@ cpp11-migrate User's Manual
|
|||
UseNullptrTransform
|
||||
LoopConvertTransform
|
||||
AddOverrideTransform
|
||||
MigratorUsage
|
||||
|
||||
: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
|
||||
===========
|
||||
Getting Started
|
||||
---------------
|
||||
|
||||
``cpp11-migrate [options] <source0> [... <sourceN>]``
|
||||
To build from source:
|
||||
|
||||
``<source0>...`` specify the paths of files in the CMake source tree,
|
||||
with the same requirements as other tools built on LibTooling.
|
||||
1. Read `Getting Started with the LLVM System`_ and `Clang Tools
|
||||
Documentation`_ for information on getting sources for LLVM, Clang, and
|
||||
Clang Extra Tools.
|
||||
|
||||
Command Line Options
|
||||
--------------------
|
||||
2. `Getting Started with the LLVM System`_ and `Building LLVM with CMake`_ give
|
||||
directions for how to build. With sources all checked out into the
|
||||
right place the LLVM build will build Clang Extra Tools and their
|
||||
dependencies automatically.
|
||||
|
||||
.. option:: -help
|
||||
* If using CMake, you can also use the ``cpp11-migrate`` target to build
|
||||
just the Migrator and its dependencies.
|
||||
|
||||
Displays tool usage instructions and command line options.
|
||||
Before continuing, take a look at :doc:`MigratorUsage` to see how to invoke the
|
||||
Migrator.
|
||||
|
||||
.. option:: -loop-convert
|
||||
Before running the Migrator on code you'll need the arguments you'd normally
|
||||
pass to the compiler. If you're migrating a single file with few compiler
|
||||
arguments, it might be easier to pass the compiler args on the command line
|
||||
after ``--``. If you're working with multiple files or even a single file
|
||||
with many compiler args, it's probably best to use a *compilation database*.
|
||||
|
||||
Makes use of C++11 range-based for loops where possible. See
|
||||
:doc:`LoopConvertTransform`.
|
||||
A `compilation database`_ contains the command-line arguments for multiple
|
||||
files. If the code you want to transform can be built with CMake, you can
|
||||
generate this database easily by running CMake with the
|
||||
``-DCMAKE_EXPORT_COMPILE_COMMANDS`` option. The Ninja_ build system, since
|
||||
v1.2, can create this file too using the *compdb* tool: ``ninja -t compdb``. If
|
||||
you're not already using either of these tools or cannot easily make use of
|
||||
them you might consider looking into Bear_.
|
||||
|
||||
.. option:: -use-nullptr
|
||||
In addition to the compiler arguments you usually build your code with, you must
|
||||
provide the option for enabling C++11 features. For clang and versions of gcc
|
||||
≥ v4.8 this is ``-std=c++11``.
|
||||
|
||||
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.
|
||||
Now with compiler arguments, the Migrator can be applied to source. Sources are
|
||||
transformed in place and changes are only written to disk if compilation errors
|
||||
aren't caused by the transforms. Each transform will re-parse the output from
|
||||
the previous transform. The output from the last transform is not checked
|
||||
unless ``-final-syntax-check`` is enabled.
|
||||
|
||||
|
||||
.. option:: -version
|
||||
.. _Ninja: http://martine.github.io/ninja/
|
||||
.. _Bear: https://github.com/rizsotto/Bear
|
||||
.. _compilation database: http://clang.llvm.org/docs/JSONCompilationDatabase.html
|
||||
.. _Getting Started with the LLVM System: http://llvm.org/docs/GettingStarted.html
|
||||
.. _Building LLVM with CMake: http://llvm.org/docs/CMake.html
|
||||
.. _Clang Tools Documentation: http://clang.llvm.org/docs/ClangTools.html
|
||||
|
||||
Displays the version information of this tool.
|
||||
Getting Involved
|
||||
----------------
|
||||
|
||||
If you find a bug
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<input type="button" id="logbug" value="Log a Bug!" />
|
||||
<script type="text/javascript" src="https://cpp11-migrate.atlassian.net/s/en_USpfg3b3-1988229788/6095/34/1.4.0-m2/_/download/batch/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector/com.atlassian.jira.collector.plugin.jira-issue-collector-plugin:issuecollector.js?collectorId=50813874"></script>
|
||||
<script type="text/javascript">window.ATL_JQ_PAGE_PROPS = {
|
||||
"triggerFunction": function(showCollectorDialog) {
|
||||
//Requries that jQuery is available!
|
||||
jQuery("#logbug").click(function(e) {
|
||||
e.preventDefault();
|
||||
showCollectorDialog();
|
||||
});
|
||||
}};
|
||||
</script>
|
||||
|
||||
Bugs and feature development of the Migrator are tracked at
|
||||
http://cpp11-migrate.atlassian.net. If you want to get involved the front page
|
||||
shows a list of outstanding issues or you can browse around the project to get
|
||||
familiar. To take on issues or contribute feature requests and/or bug reports
|
||||
you need to sign up for an account from the `log in page`_. An account also
|
||||
lets you sign up for notifications on issues or vote for unassigned issues to
|
||||
be completed.
|
||||
|
||||
.. _log in page: https://cpp11-migrate.atlassian.net/login
|
||||
|
||||
.. _transforms:
|
||||
|
||||
Transformations
|
||||
===============
|
||||
---------------
|
||||
|
||||
The Migrator is a collection of independent transforms which can be
|
||||
independently enabled. The transforms currently implemented are:
|
||||
|
||||
* :doc:`LoopConvertTransform`
|
||||
|
||||
* :doc:`UseNullptrTransform`
|
||||
|
||||
* :doc:`UseAutoTransform`
|
||||
|
||||
* :doc:`AddOverrideTransform`
|
||||
|
|
|
|||
Loading…
Reference in New Issue