[PATCH] Enhancements to the LLVM CommandLine library

[Daniel Liew]

Hi,

I have a few patches for the LLVM CommandLine library that should
apply cleanly to the svn trunk (well I do my work against the git
mirror and the rebase went fine).

I've e-mailed this mailing list and not LLVM-dev because your
documentation says I can send one-off patches here (
http://llvm.org/docs/DeveloperPolicy.html#id6 ). If this is incorrect
please let me know.

Here are the patches:

[1] Add the ability to place declared command line options into
categories and added categorised help output (-help-cat and
-help-cat-hidden)

Clients may add categories using a macro (so they don't have to type
boiler plate class code) and then use the cl::cat<>() modifier.

OPT_CAT(CoolCategory, Cool Options, All the cool options live here);

llvm::cl::opt<bool> coolOption("cool", cl::cat<CoolCategory>() );

The patch is attached and can also be found at
https://github.com/delcypher/llvm/commit/b31841b768181c787dac461cac52ace32e01793f.patch

So why would someone want this? Well I work on the KLEE project and we
make heavy use of the LLVM CommandLine library but we have loads of
options which gets a little much to handle (-help is massive!) so we
wanted to categorise our options so they are more readable.

By default all options are stuck in a "Default Category". But in
principle if the LLVM developers think this is useful they could
create their own categories and categorize their options.

[2] Added extra optional arguments to  llvm::PrintHelpMessage() so
that the client can choose what sort of help printer is used
(categorised/uncategorised and normal/all options)

The patch is attached and can also be found at
https://github.com/delcypher/llvm/commit/048e76a99a84f973ca18ac6e20c1413ad446d894.patch

The KLEE developers have no major need for this but given patch [1] is
seemed like a sensible extension

[3] Added llvm::cl::getRegisteredOptions() public method. This allows
clients (such as KLEE) to gain access to registered named options at
runtime and modify them?
Why would we want to do this? Well we would like to modify some LLVM
command line options (that come from libraries that we link with). We
can't change them at the moment
without modifying the LLVM source code. Here is an example of using
the API and the sort of things I imagine doing...

  StringMap<llvm::cl::Option*> h;
  llvm::cl::getRegisteredOptions(h);
  assert(h.count("help") > 0);
  h["help"]->setDescription("Display an alphabetical list of options");
  h["help"]->setArgStr("help-list"); //--help-list now does what --help did

  //Let's make categorised output the default
  assert(h.count("help-cat") > 0);
  h["help-cat"]->setArgStr("help"); //now --help does what --help-cat did

  assert(h.count("print-all-options") >0);
  h["print-all-options"]->setHiddenFlag(llvm::cl::NotHidden); //Unhide
this REALLY useful option
  h["print-all-options"]->setOptionCategory<CoolCategory>(); //Move to
a different category

  //Finished modifying options, we can now parse
  cl::ParseCommandLineOptions(argc, argv, "This is a small program to
demo the LLVM CommandLine API");

In the above example we can modify command line options we don't have
direct access to without modifying the LLVM source code which is good!

The patch is attached and can also be found at
https://github.com/delcypher/llvm/commit/38c4fdaad6858adc4e7ef8a650cbc2588f0fdbc5.patch

What do people think? I realise I've not written any documentation for
any of these additions to the CommandLine library. I'd be quite happy
to update the CommandLine sphinx documentation if these patches are
accepted.

I do have a sample project that builds against LLVM with my patches
that demonstrates some of my changes to the API. It's basically the
sample LLVM project with a few modifications. It can be found at
https://github.com/delcypher/sample-llvm-cmd

Regards,
Dan liew.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 1-categories.patch
Type: application/octet-stream
Size: 11016 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20130326/512d1750/attachment.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 2- enhanced PrintHelpMessage.patch
Type: application/octet-stream
Size: 3443 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20130326/512d1750/attachment-0001.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 3- get registeredOptions.patch
Type: application/octet-stream
Size: 3382 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20130326/512d1750/attachment-0002.obj>