forked from OSchip/llvm-project
132 lines
5.1 KiB
ReStructuredText
132 lines
5.1 KiB
ReStructuredText
.. index:: clang-modernize
|
|
|
|
==================================
|
|
Clang C++ Modernizer User's Manual
|
|
==================================
|
|
|
|
.. toctree::
|
|
:hidden:
|
|
|
|
UseAutoTransform
|
|
UseNullptrTransform
|
|
LoopConvertTransform
|
|
AddOverrideTransform
|
|
PassByValueTransform
|
|
ReplaceAutoPtrTransform
|
|
ModernizerUsage
|
|
cpp11-migrate
|
|
MigratorUsage
|
|
|
|
:program:`clang-modernize` is a standalone tool used to automatically convert
|
|
C++ code written against old standards to use features of the newest C++
|
|
standard where appropriate.
|
|
|
|
Getting Started
|
|
===============
|
|
|
|
To build from source:
|
|
|
|
1. Read `Getting Started with the LLVM System`_ and `Clang Tools
|
|
Documentation`_ for information on getting sources for LLVM, Clang, and
|
|
Clang Extra Tools.
|
|
|
|
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.
|
|
|
|
* If using CMake, you can also use the ``clang-modernize`` target to build
|
|
just the Modernizer and its dependencies.
|
|
|
|
Before continuing, take a look at :doc:`ModernizerUsage` to see how to invoke
|
|
the Modernizer.
|
|
|
|
Before running the Modernizer 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 don't have any compiler arguments then ``--`` is not needed.
|
|
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*.
|
|
|
|
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_.
|
|
|
|
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``.
|
|
|
|
With compiler arguments in hand, the modernizer can be applied to sources. Each
|
|
transform is applied to all sources before the next transform. All the changes
|
|
generated by each transform pass are serialized to disk and applied using
|
|
``clang-apply-replacements``. This executable must be located on the ``PATH``
|
|
or be present in the same directory as the ``clang-modernizer`` executable. If
|
|
any changes fail to apply, the modernizer will **not** proceed to the next
|
|
transform and will halt.
|
|
|
|
There's a small chance that changes made by a transform will produce code that
|
|
doesn't compile, also causing the modernizer to halt. This can happen with
|
|
bugs in the transforms or use of the pre-processor to make the same code behave
|
|
differently between translation units. Before logging a bug, be sure which
|
|
situation you are dealing with.
|
|
|
|
.. _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
|
|
|
|
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 Modernizer 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 Modernizer is a collection of independent transforms which can be
|
|
independently enabled. The transforms currently implemented are:
|
|
|
|
* :doc:`LoopConvertTransform`
|
|
|
|
* :doc:`UseNullptrTransform`
|
|
|
|
* :doc:`UseAutoTransform`
|
|
|
|
* :doc:`AddOverrideTransform`
|
|
|
|
* :doc:`PassByValueTransform`
|
|
|
|
* :doc:`ReplaceAutoPtrTransform`
|