From 573ec4f1aaa346d0b611c70dcb7b9c45fd0cdf91 Mon Sep 17 00:00:00 2001 From: Edwin Vane Date: Thu, 6 Jun 2013 14:30:14 +0000 Subject: [PATCH] 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 --- .../docs/AddOverrideTransform.rst | 10 ++ clang-tools-extra/docs/MigratorUsage.rst | 128 ++++++++++++++ clang-tools-extra/docs/cpp11-migrate.rst | 158 +++++++++--------- 3 files changed, 216 insertions(+), 80 deletions(-) create mode 100644 clang-tools-extra/docs/MigratorUsage.rst diff --git a/clang-tools-extra/docs/AddOverrideTransform.rst b/clang-tools-extra/docs/AddOverrideTransform.rst index ea537fefc0f0..03f9494e23f9 100644 --- a/clang-tools-extra/docs/AddOverrideTransform.rst +++ b/clang-tools-extra/docs/AddOverrideTransform.rst @@ -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 ----------------- diff --git a/clang-tools-extra/docs/MigratorUsage.rst b/clang-tools-extra/docs/MigratorUsage.rst new file mode 100644 index 000000000000..5c762bd661a4 --- /dev/null +++ b/clang-tools-extra/docs/MigratorUsage.rst @@ -0,0 +1,128 @@ +=================== +cpp11-migrate Usage +=================== + +``cpp11-migrate [options] [... ] [-- [args]]`` + +```` 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[=] + + ```` 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 ```` 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= + + 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 ` 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[=] + + 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 ````. All sources processed + by a single Migrator process are written to the same output file. If ```` 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= + + ```` 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. + diff --git a/clang-tools-extra/docs/cpp11-migrate.rst b/clang-tools-extra/docs/cpp11-migrate.rst index 70e833683dcd..bba4df11fe6d 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 -=========== +Getting Started +--------------- -``cpp11-migrate [options] [... ]`` +To build from source: -``...`` 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= - - ```` 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= - - ```` 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 ```` - 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= - - 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 ` 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 + + + + + +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`