[CodeGenPrepare] Refine the cost model provided by the promotion helper.

[oota-llvm.git] / docs / CommandLine.rst

diff --git a/docs/CommandLine.rst b/docs/CommandLine.rst
index 8a266e23b269718a430287d5930166cfed4eafce..1d85215f2af30629b21e0c1f75dc59e6540a0616 100644 (file)
--- a/docs/CommandLine.rst
+++ b/docs/CommandLine.rst
@@ -618,6 +618,8 @@ would yield the help output:
     -help             - display available options (-help-hidden for more)
     -o <filename>     - Specify output filename
 
     -help             - display available options (-help-hidden for more)
     -o <filename>     - Specify output filename
 

+.. _grouping options into categories:
+

 Grouping options into categories
 --------------------------------
 
 Grouping options into categories
 --------------------------------
 


@@ -923,12 +925,13 @@ This section describes the basic attributes that you can specify on options.
 
   .. code-block:: c++
 
 
   .. code-block:: c++
 

-    cl::opt<**bool**> Quiet("quiet");
+    cl::opt<bool> Quiet("quiet");

 
 .. _cl::desc(...):
 
 * The **cl::desc** attribute specifies a description for the option to be
 
 .. _cl::desc(...):
 
 * The **cl::desc** attribute specifies a description for the option to be

-  shown in the ``-help`` output for the program.
+  shown in the ``-help`` output for the program. This attribute supports
+  multi-line descriptions with lines separated by '\n'.

 
 .. _cl::value_desc:
 
 
 .. _cl::value_desc:
 


@@ -1267,6 +1270,57 @@ only consists of one function `cl::ParseCommandLineOptions`_) and three main
 classes: `cl::opt`_, `cl::list`_, and `cl::alias`_.  This section describes
 these three classes in detail.
 
 classes: `cl::opt`_, `cl::list`_, and `cl::alias`_.  This section describes
 these three classes in detail.
 

+.. _cl::getRegisteredOptions:
+
+The ``cl::getRegisteredOptions`` function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``cl::getRegisteredOptions`` function is designed to give a programmer
+access to declared non-positional command line options so that how they appear
+in ``-help`` can be modified prior to calling `cl::ParseCommandLineOptions`_.
+Note this method should not be called during any static initialisation because
+it cannot be guaranteed that all options will have been initialised. Hence it
+should be called from ``main``.
+
+This function can be used to gain access to options declared in libraries that
+the tool writter may not have direct access to.
+
+The function retrieves a :ref:`StringMap <dss_stringmap>` that maps the option
+string (e.g. ``-help``) to an ``Option*``.
+
+Here is an example of how the function could be used:
+
+.. code-block:: c++
+
+  using namespace llvm;
+  int main(int argc, char **argv) {
+    cl::OptionCategory AnotherCategory("Some options");
+
+    StringMap<cl::Option*> Map;
+    cl::getRegisteredOptions(Map);
+
+    //Unhide useful option and put it in a different category
+    assert(Map.count("print-all-options") > 0);
+    Map["print-all-options"]->setHiddenFlag(cl::NotHidden);
+    Map["print-all-options"]->setCategory(AnotherCategory);
+
+    //Hide an option we don't want to see
+    assert(Map.count("enable-no-infs-fp-math") > 0);
+    Map["enable-no-infs-fp-math"]->setHiddenFlag(cl::Hidden);
+
+    //Change --version to --show-version
+    assert(Map.count("version") > 0);
+    Map["version"]->setArgStr("show-version");
+
+    //Change --help description
+    assert(Map.count("help") > 0);
+    Map["help"]->setDescription("Shows help");
+
+    cl::ParseCommandLineOptions(argc, argv, "This is a small program to demo the LLVM CommandLine API");
+    ...
+  }
+
+

 .. _cl::ParseCommandLineOptions:
 
 The ``cl::ParseCommandLineOptions`` function
 .. _cl::ParseCommandLineOptions:
 
 The ``cl::ParseCommandLineOptions`` function


@@ -1576,13 +1630,13 @@ To start out, we declare our new ``FileSizeParser`` class:
 
 .. code-block:: c++
 
 
 .. code-block:: c++
 

-  struct FileSizeParser : public cl::basic_parser<unsigned> {
+  struct FileSizeParser : public cl::parser<unsigned> {

     // parse - Return true on error.
     // parse - Return true on error.

-    bool parse(cl::Option &O, const char *ArgName, const std::string &ArgValue,
+    bool parse(cl::Option &O, StringRef ArgName, const std::string &ArgValue,

                unsigned &Val);
   };
 
                unsigned &Val);
   };
 

-Our new class inherits from the ``cl::basic_parser`` template class to fill in
+Our new class inherits from the ``cl::parser`` template class to fill in

 the default, boiler plate code for us.  We give it the data type that we parse
 into, the last argument to the ``parse`` method, so that clients of our custom
 parser know what object type to pass in to the parse method.  (Here we declare
 the default, boiler plate code for us.  We give it the data type that we parse
 into, the last argument to the ``parse`` method, so that clients of our custom
 parser know what object type to pass in to the parse method.  (Here we declare


@@ -1598,7 +1652,7 @@ implement ``parse`` as:
 
 .. code-block:: c++
 
 
 .. code-block:: c++
 

-  bool FileSizeParser::parse(cl::Option &O, const char *ArgName,
+  bool FileSizeParser::parse(cl::Option &O, StringRef ArgName,

                              const std::string &Arg, unsigned &Val) {
     const char *ArgStart = Arg.c_str();
     char *End;
                              const std::string &Arg, unsigned &Val) {
     const char *ArgStart = Arg.c_str();
     char *End;


@@ -1644,7 +1698,7 @@ Which adds this to the output of our program:
   OPTIONS:
     -help                 - display available options (-help-hidden for more)
     ...
   OPTIONS:
     -help                 - display available options (-help-hidden for more)
     ...

-   -max-file-size=<size> - Maximum file size to accept
+    -max-file-size=<size> - Maximum file size to accept

 
 And we can test that our parse works correctly now (the test program just prints
 out the max-file-size argument value):
 
 And we can test that our parse works correctly now (the test program just prints
 out the max-file-size argument value):