Extra Clang Tools 3.3 documentation

Clang C++ Modernizer User’s Manual

«  Introduction   ::   Contents   ::   Use-Auto Transform  »

Clang C++ Modernizer User’s Manual

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 clang-modernize Usage 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.

Getting Involved

If you find a bug

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.

Transformations

The Modernizer is a collection of independent transforms which can be independently enabled. The transforms currently implemented are:

«  Introduction   ::   Contents   ::   Use-Auto Transform  »