1.. index:: cpp11-migrate
2
3============================
4C++11 Migrator User's Manual
5============================
6
7.. toctree::
8   :hidden:
9
10   UseAutoTransform
11   UseNullptrTransform
12   LoopConvertTransform
13   AddOverrideTransform
14   MigratorUsage
15
16:program:`cpp11-migrate` is a standalone tool used to automatically convert
17C++98 and C++03 code to use features of the new C++11 standard where
18appropriate.
19
20Getting Started
21===============
22
23To build from source:
24
251. Read `Getting Started with the LLVM System`_ and `Clang Tools
26   Documentation`_ for information on getting sources for LLVM, Clang, and
27   Clang Extra Tools.
28
292. `Getting Started with the LLVM System`_ and `Building LLVM with CMake`_ give
30   directions for how to build. With sources all checked out into the
31   right place the LLVM build will build Clang Extra Tools and their
32   dependencies automatically.
33
34   * If using CMake, you can also use the ``cpp11-migrate`` target to build
35     just the Migrator and its dependencies.
36
37Before continuing, take a look at :doc:`MigratorUsage` to see how to invoke the
38Migrator.
39
40Before running the Migrator on code you'll need the arguments you'd normally
41pass to the compiler. If you're migrating a single file with few compiler
42arguments, it might be easier to pass the compiler args on the command line
43after ``--``. If you're working with multiple files or even a single file
44with many compiler args, it's probably best to use a *compilation database*.
45
46A `compilation database`_ contains the command-line arguments for multiple
47files. If the code you want to transform can be built with CMake, you can
48generate this database easily by running CMake with the
49``-DCMAKE_EXPORT_COMPILE_COMMANDS`` option. The Ninja_ build system, since
50v1.2, can create this file too using the *compdb* tool: ``ninja -t compdb``. If
51you're not already using either of these tools or cannot easily make use of
52them you might consider looking into Bear_.
53
54In addition to the compiler arguments you usually build your code with, you must
55provide the option for enabling C++11 features. For clang and versions of gcc
56≥ v4.8 this is ``-std=c++11``.
57
58Now with compiler arguments, the Migrator can be applied to source. Sources are
59transformed in place and changes are only written to disk if compilation errors
60aren't caused by the transforms. Each transform will re-parse the output from
61the previous transform. The output from the last transform is not checked
62unless ``-final-syntax-check`` is enabled.
63
64
65.. _Ninja: http://martine.github.io/ninja/
66.. _Bear: https://github.com/rizsotto/Bear
67.. _compilation database: http://clang.llvm.org/docs/JSONCompilationDatabase.html
68.. _Getting Started with the LLVM System: http://llvm.org/docs/GettingStarted.html
69.. _Building LLVM with CMake: http://llvm.org/docs/CMake.html
70.. _Clang Tools Documentation: http://clang.llvm.org/docs/ClangTools.html
71
72Getting Involved
73================
74
75If you find a bug
76
77.. raw:: html
78
79  <input type="button" id="logbug" value="Log a Bug!" />
80  <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>
81  <script type="text/javascript">window.ATL_JQ_PAGE_PROPS =  {
82    "triggerFunction": function(showCollectorDialog) {
83      //Requries that jQuery is available!
84      jQuery("#logbug").click(function(e) {
85        e.preventDefault();
86        showCollectorDialog();
87      });
88    }};
89  </script>
90
91Bugs and feature development of the Migrator are tracked at
92http://cpp11-migrate.atlassian.net. If you want to get involved the front page
93shows a list of outstanding issues or you can browse around the project to get
94familiar. To take on issues or contribute feature requests and/or bug reports
95you need to sign up for an account from the `log in page`_. An account also
96lets you sign up for notifications on issues or vote for unassigned issues to
97be completed.
98
99.. _log in page: https://cpp11-migrate.atlassian.net/login
100
101.. _transforms:
102
103Transformations
104===============
105
106The Migrator is a collection of independent transforms which can be
107independently enabled. The transforms currently implemented are:
108
109* :doc:`LoopConvertTransform`
110
111* :doc:`UseNullptrTransform`
112
113* :doc:`UseAutoTransform`
114
115* :doc:`AddOverrideTransform`
116