[clang-tools-extra] r183417 - cpp11-migrate: Docs refresh
Edwin Vane
edwin.vane at intel.com
Thu Jun 6 07:30:14 PDT 2013
Author: revane
Date: Thu Jun 6 09:30:14 2013
New Revision: 183417
URL: http://llvm.org/viewvc/llvm-project?rev=183417&view=rev
Log:
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.
Added:
clang-tools-extra/trunk/docs/MigratorUsage.rst
Modified:
clang-tools-extra/trunk/docs/AddOverrideTransform.rst
clang-tools-extra/trunk/docs/cpp11-migrate.rst
Modified: clang-tools-extra/trunk/docs/AddOverrideTransform.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/AddOverrideTransform.rst?rev=183417&r1=183416&r2=183417&view=diff
==============================================================================
--- clang-tools-extra/trunk/docs/AddOverrideTransform.rst (original)
+++ clang-tools-extra/trunk/docs/AddOverrideTransform.rst Thu Jun 6 09:30:14 2013
@@ -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
-----------------
Added: clang-tools-extra/trunk/docs/MigratorUsage.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/MigratorUsage.rst?rev=183417&view=auto
==============================================================================
--- clang-tools-extra/trunk/docs/MigratorUsage.rst (added)
+++ clang-tools-extra/trunk/docs/MigratorUsage.rst Thu Jun 6 09:30:14 2013
@@ -0,0 +1,128 @@
+===================
+cpp11-migrate Usage
+===================
+
+``cpp11-migrate [options] <source0> [... <sourceN>] [-- [args]]``
+
+``<source#>`` 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[=<build-path>]
+
+ ``<build-path>`` 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 ``<build-path>`` 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=<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:: -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[=<directory>]
+
+ 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 ``<directory>``. All sources processed
+ by a single Migrator process are written to the same output file. If ``<directory>`` 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=<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:: -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.
+
Modified: clang-tools-extra/trunk/docs/cpp11-migrate.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/cpp11-migrate.rst?rev=183417&r1=183416&r2=183417&view=diff
==============================================================================
--- clang-tools-extra/trunk/docs/cpp11-migrate.rst (original)
+++ clang-tools-extra/trunk/docs/cpp11-migrate.rst Thu Jun 6 09:30:14 2013
@@ -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] <source0> [... <sourceN>]``
+To build from source:
-``<source0>...`` 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.
+
+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.
-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.
+.. _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`
More information about the cfe-commits
mailing list