| .. 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` |