diff options
Diffstat (limited to 'clang-tools-extra/docs/cpp11-migrate.rst')
| -rw-r--r-- | clang-tools-extra/docs/cpp11-migrate.rst | 182 |
1 files changed, 90 insertions, 92 deletions
diff --git a/clang-tools-extra/docs/cpp11-migrate.rst b/clang-tools-extra/docs/cpp11-migrate.rst index 70e833683dc..bba4df11fe6 100644 --- a/clang-tools-extra/docs/cpp11-migrate.rst +++ b/clang-tools-extra/docs/cpp11-migrate.rst @@ -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 -=========== - -``cpp11-migrate [options] <source0> [... <sourceN>]`` - -``<source0>...`` specify the paths of files in the CMake source tree, -with the same requirements as other tools built on LibTooling. - -Command Line Options --------------------- - -.. option:: -help - - Displays tool usage instructions and 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:: -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. - - -.. option:: -version - - Displays the version information of this tool. +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 ``cpp11-migrate`` target to build + just the Migrator and its dependencies. + +Before continuing, take a look at :doc:`MigratorUsage` to see how to invoke the +Migrator. + +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*. + +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``. + +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. + + +.. _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 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` |
