Written by Chris Lattner
+To start out, you need to include the CommandLine header file into your program:
-- #include "Support/CommandLine.h" -+
+ #include "llvm/Support/CommandLine.h" +
Additionally, you need to add this as the first line of your main program:
-+int main(int argc, char **argv) { cl::ParseCommandLineOptions(argc, argv); ... } -+... which actually parses the arguments and fills in the variable declarations.
Now that you are ready to support command line arguments, we need to tell the -system which ones we want, and what type of argument they are. The CommandLine +system which ones we want, and what type of arguments they are. The CommandLine library uses a declarative syntax to model command line arguments with the global variable declarations that capture the parsed values. This means that for every command line option that you would like to support, there should be a global variable declaration to capture the result. For example, in a compiler, -we would like to support the unix standard '-o <filename>' option +we would like to support the Unix-standard '-o <filename>' option to specify where to put the output. With the CommandLine library, this is represented like this:
-- -cl::opt<string> OutputFilename("o", cl::desc("Specify output filename"), cl::value_desc("filename")); -
+ ++cl::opt<string> OutputFilename("o", cl::desc("Specify output filename"), cl::value_desc("filename")); +This declares a global variable "OutputFilename" that is used to capture the result of the "o" argument (first parameter). We specify @@ -231,25 +242,25 @@ that the data type that we are parsing is a string.
to output for the "--help" option. In this case, we get a line that looks like this: -+USAGE: compiler [options] OPTIONS: -help - display available options (--help-hidden for more) -o <filename> - Specify output filename -+Because we specified that the command line option should parse using the string data type, the variable declared is automatically usable as a real string in all contexts that a normal C++ string object may be used. For example:
-+... - ofstream Output(OutputFilename.c_str()); - if (Out.good()) ... + std::ofstream Output(OutputFilename.c_str()); + if (Output.good()) ... ... -+There are many different options that you can use to customize the command line option handling library, but the above example shows the general interface @@ -266,9 +277,9 @@ href="#positional">positional arguments to be specified for the program. These positional arguments are filled with command line parameters that are not in option form. We use this feature like this:
-+cl::opt<string> InputFilename(cl::Positional, cl::desc("<input file>"), cl::init("-")); -+This declaration indicates that the first positional argument should be treated as the input filename. Here we use the cl::Required flag, and we could eliminate the cl::init modifier, like this:
-+cl::opt<string> InputFilename(cl::Positional, cl::desc("<input file>"), cl::Required); -+Again, the CommandLine library does not require the options to be specified in any particular order, so the above declaration is equivalent to:
-+cl::opt<string> InputFilename(cl::Positional, cl::Required, cl::desc("<input file>")); -+By simply adding the cl::Required flag, the CommandLine library will automatically issue an error if the argument is not @@ -300,13 +311,13 @@ can alter the default behaviour of the library, on a per-option basis. By adding one of the declarations above, the --help option synopsis is now extended to:
-+USAGE: compiler [options] <input file> OPTIONS: -help - display available options (--help-hidden for more) -o <filename> - Specify output filename -+... indicating that an input filename is expected.
@@ -320,16 +331,16 @@ OPTIONS:@@ -1037,7 +1178,7 @@ href="#cl::list">cl::list. These modifiers give you the ability to tweak how options are parsed and how --help output is generated to fit your application well. -In addition to input and output filenames, we would like the compiler example -to support three boolean flags: "-f" to force overwriting of the output -file, "--quiet" to enable quiet mode, and "-q" for backwards -compatibility with some of our users. We can support these by declaring options -of boolean type like this:
+to support three boolean flags: "-f" to force writing binary output to +a terminal, "--quiet" to enable quiet mode, and "-q" for +backwards compatibility with some of our users. We can support these by +declaring options of boolean type like this: --cl::opt<bool> Force ("f", cl::desc("Overwrite output files")); ++cl::opt<bool> Force ("f", cl::desc("Enable binary output on terminals")); cl::opt<bool> Quiet ("quiet", cl::desc("Don't print informational messages")); cl::opt<bool> Quiet2("q", cl::desc("Don't print informational messages"), cl::Hidden); -+This does what you would expect: it declares three boolean variables ("Force", "Quiet", and "Quiet2") to recognize these @@ -347,12 +358,12 @@ it assigns the value of true to the variable), or it allows the values "true" or "false" to be specified, allowing any of the following inputs:
-+compiler -f # No value, 'Force' == true compiler -f=true # Value specified, 'Force' == true compiler -f=TRUE # Value specified, 'Force' == true compiler -f=FALSE # Value specified, 'Force' == false -+... you get the idea. The bool parser just turns the string values into boolean values, and rejects things like 'compiler @@ -363,28 +374,28 @@ library calls to parse the string value into the specified data type.
With the declarations above, "compiler --help" emits this:
-+-USAGE: compiler [options] <input file> OPTIONS: - -f - Overwrite output files + -f - Enable binary output on terminals -o - Override output filename -quiet - Don't print informational messages -help - display available options (--help-hidden for more) -+and "opt --help-hidden" prints this:
+and "compiler --help-hidden" prints this:
-+USAGE: compiler [options] <input file> OPTIONS: - -f - Overwrite output files + -f - Enable binary output on terminals -o - Override output filename -q - Don't print informational messages -quiet - Don't print informational messages -help - display available options (--help-hidden for more) -+This brief example has shown you how to use the 'cl::opt' class to parse simple scalar command line @@ -404,25 +415,25 @@ and lists of options.
So far, the example works well, except for the fact that we need to check the quiet condition like this now:
-+... if (!Quiet && !Quiet2) printInformationalMessage(...); ... -+... which is a real pain! Instead of defining two values for the same condition, we can use the "cl::alias" class to make the "-q" option an alias for the "-quiet" option, instead of providing a value itself:
-+cl::opt<bool> Force ("f", cl::desc("Overwrite output files")); cl::opt<bool> Quiet ("quiet", cl::desc("Don't print informational messages")); cl::alias QuietA("q", cl::desc("Alias for -quiet"), cl::aliasopt(Quiet)); -+The third line (which is the only one we modified from above) defines a -"-q alias that updates the "Quiet" variable (as specified by +"-q" alias that updates the "Quiet" variable (as specified by the cl::aliasopt modifier) whenever it is specified. Because aliases do not hold state, the only thing the program has to query is the Quiet variable now. Another nice feature of aliases is @@ -432,11 +443,11 @@ output).
Now the application code can simply use:
-+... if (!Quiet) printInformationalMessage(...); ... -+... which is much nicer! The "cl::alias" can be used to specify an alternative name for any variable type, and has many @@ -452,24 +463,24 @@ uses.
-+ + +So far, we have seen how the CommandLine library handles builtin types like +
So far we have seen how the CommandLine library handles builtin types like std::string, bool and int, but how does it handle things it doesn't know about, like enums or 'int*'s?
-The answer is that it uses a table driven generic parser (unless you specify +
The answer is that it uses a table-driven generic parser (unless you specify your own parser, as described in the Extension -Guide). This parser maps literal strings to whatever type is required, are +Guide). This parser maps literal strings to whatever type is required, and requires you to tell it what this mapping should be.
-Lets say that we would like to add four optimizations levels to our +
Let's say that we would like to add four optimization levels to our optimizer, using the standard flags "-g", "-O0", "-O1", and "-O2". We could easily implement this with boolean options like above, but there are several problems with this strategy:
- A user could specify more than one of the options at a time, for example, -"opt -O3 -O2". The CommandLine library would not be able to catch this -erroneous input for us.
+"compiler -O3 -O2". The CommandLine library would not be able to +catch this erroneous input for us.- We would have to test 4 different variables to see which ones are set.
@@ -482,7 +493,7 @@ see if some level >= "-O1" is enabled. CommandLine library fill it in with the appropriate level directly, which is used like this: -+enum OptLevel { g, O1, O2, O3 }; @@ -493,23 +504,24 @@ enum OptLevel { clEnumVal(O1, "Enable trivial optimizations"), clEnumVal(O2, "Enable default optimizations"), clEnumVal(O3, "Enable expensive optimizations"), - 0)); + clEnumValEnd)); ... if (OptimizationLevel >= O2) doPartialRedundancyElimination(...); ... -+This declaration defines a variable "OptimizationLevel" of the "OptLevel" enum type. This variable can be assigned any of the values that are listed in the declaration (Note that the declaration list must be -terminated with the "0" argument!). The CommandLine library enforces +terminated with the "clEnumValEnd" argument!). The CommandLine +library enforces that the user can only specify one of the options, and it ensure that only valid enum values can be specified. The "clEnumVal" macros ensure that the command line arguments matched the enum values. With this option added, our help output now is:
-+USAGE: compiler [options] <input file> OPTIONS: @@ -518,18 +530,18 @@ OPTIONS: -O1 - Enable trivial optimizations -O2 - Enable default optimizations -O3 - Enable expensive optimizations - -f - Overwrite output files + -f - Enable binary output on terminals -help - display available options (--help-hidden for more) -o <filename> - Specify output filename -quiet - Don't print informational messages -+In this case, it is sort of awkward that flag names correspond directly to enum names, because we probably don't want a enum definition named "g" in our program. Because of this, we can alternatively write this example like this:
-+enum OptLevel { Debug, O1, O2, O3 }; @@ -540,12 +552,12 @@ enum OptLevel { clEnumVal(O1 , "Enable trivial optimizations"), clEnumVal(O2 , "Enable default optimizations"), clEnumVal(O3 , "Enable expensive optimizations"), - 0)); + clEnumValEnd)); ... if (OptimizationLevel == Debug) outputDebugInfo(...); ... -+By using the "clEnumValN" macro instead of "clEnumVal", we can directly specify the name that the flag should get. In general a direct @@ -570,7 +582,7 @@ following options, of which only one can be specified at a time: our optimization level flags, but we also specify an option name. For this case, the code looks like this:
-+enum DebugLev { nodebuginfo, quick, detailed }; @@ -581,15 +593,15 @@ enum DebugLev { clEnumValN(nodebuginfo, "none", "disable debug information"), clEnumVal(quick, "enable quick debug information"), clEnumVal(detailed, "enable detailed debug information"), - 0)); -+ clEnumValEnd)); +This definition defines an enumerated command line variable of type "enum DebugLev", which works exactly the same way as before. The difference here is just the interface exposed to the user of your program and the help output by the "--help" option:
-+USAGE: compiler [options] <input file> OPTIONS: @@ -602,14 +614,14 @@ OPTIONS: =none - disable debug information =quick - enable quick debug information =detailed - enable detailed debug information - -f - Overwrite output files + -f - Enable binary output on terminals -help - display available options (--help-hidden for more) -o <filename> - Specify output filename -quiet - Don't print informational messages -+Again, the only structural difference between the debug level declaration and -the optimiation level declaration is that the debug level declaration includes +the optimization level declaration is that the debug level declaration includes an option name ("debug_level"), which automatically changes how the library processes the argument. The CommandLine library supports both forms so that you can choose the form most appropriate for your application.
@@ -623,7 +635,7 @@ that you can choose the form most appropriate for your application.-+ + + +Now that we have the standard run of the mill argument types out of the way, +
Now that we have the standard run-of-the-mill argument types out of the way, lets get a little wild and crazy. Lets say that we want our optimizer to accept a list of optimizations to perform, allowing duplicates. For example, we might want to run: "compiler -dce -constprop -inline -dce -strip". In @@ -632,34 +644,34 @@ important. This is what the "cl::list" template is for. First, start by defining an enum of the optimizations that you would like to perform:
-+enum Opts { // 'inline' is a C++ keyword, so name it 'inlining' dce, constprop, inlining, strip }; -+Then define your "cl::list" variable:
-+cl::list<Opts> OptimizationList(cl::desc("Available Optimizations:"), cl::values( clEnumVal(dce , "Dead Code Elimination"), clEnumVal(constprop , "Constant Propagation"), clEnumValN(inlining, "inline", "Procedure Integration"), clEnumVal(strip , "Strip Symbols"), - 0)); -+ clEnumValEnd)); +This defines a variable that is conceptually of the type "std::vector<enum Opts>". Thus, you can access it with standard vector methods:
-+for (unsigned i = 0; i != OptimizationList.size(); ++i) switch (OptimizationList[i]) ... -+... to iterate through the list of options specified.
@@ -671,11 +683,11 @@ arguments together if there may be more than one specified. In the case of a linker, for example, the linker takes several '.o' files, and needs to capture them into a list. This is naturally specified as: -+... cl::list<std::string> InputFilenames(cl::Positional, cl::desc("<Input files>"), cl::OneOrMore); ... -+This variable works just like a "vector<string>" object. As such, accessing the list is simple, just like above. In this example, we used @@ -686,6 +698,65 @@ checking we have to do.
+ ++ +Instead of collecting sets of options in a list, it is also possible to +gather information for enum values in a bit vector. The represention used by +the cl::bits class is an unsigned +integer. An enum value is represented by a 0/1 in the enum's ordinal value bit +position. 1 indicating that the enum was specified, 0 otherwise. As each +specified value is parsed, the resulting enum's bit is set in the option's bit +vector:
+ ++ ++ bits |= 1 << (unsigned)enum; +Options that are specified multiple times are redundant. Any instances after +the first are discarded.
+ +Reworking the above list example, we could replace +cl::list with cl::bits:
+ ++ ++cl::bits<Opts> OptimizationBits(cl::desc("Available Optimizations:"), + cl::values( + clEnumVal(dce , "Dead Code Elimination"), + clEnumVal(constprop , "Constant Propagation"), + clEnumValN(inlining, "inline", "Procedure Integration"), + clEnumVal(strip , "Strip Symbols"), + clEnumValEnd)); +To test to see if constprop was specified, we can use the +cl:bits::isSet function:
+ ++ ++ if (OptimizationBits.isSet(constprop)) { + ... + } +It's also possible to get the raw bit vector using the +cl::bits::getBits function:
+ ++ ++ unsigned bits = OptimizationBits.getBits(); +Finally, if external storage is used, then the location specified must be of +type unsigned. In all other ways a cl::bits option is equivalent to a cl::list option.
+ +Adding freeform text to help output @@ -704,17 +775,17 @@ call in main. This additional argument is then printed as the overview information for your program, allowing you to include any additional information that you want. For example: -@@ -759,27 +830,27 @@ tool takes a regular expression argument, and an optional filename to search through (which defaults to standard input if a filename is not specified). Using the CommandLine library, this would be specified as: -+-int main(int argc, char **argv) { cl::ParseCommandLineOptions(argc, argv, " CommandLine compiler example\n\n" " This program blah blah blah...\n"); ... } -+Would yield the help output:
+would yield the help output:
-+OVERVIEW: CommandLine compiler example This program blah blah blah... @@ -725,7 +796,7 @@ OPTIONS: ... -help - display available options (--help-hidden for more) -o <filename> - Specify output filename -++cl::opt<string> Regex (cl::Positional, cl::desc("<regular expression>"), cl::Required); cl::opt<string> Filename(cl::Positional, cl::desc("<input file>"), cl::init("-")); -+Given these two option declarations, the --help output for our grep replacement would look like this:
-+USAGE: spiffygrep [options] <regular expression> <input file> OPTIONS: -help - display available options (--help-hidden for more) -+... and the resultant program could be used just like the standard grep tool.
Positional arguments are sorted by their order of construction. This means that command line options will be ordered according to how they are listed in a -.cpp file, but will not have an ordering defined if they positional arguments +.cpp file, but will not have an ordering defined if the positional arguments are defined in multiple .cpp files. The fix for this problem is simply to define all of your positional arguments in one .cpp file.
@@ -799,7 +870,7 @@ first, you will have trouble doing this, because it will try to find an argument named '-foo', and will fail (and single quotes will not save you). Note that the system grep has the same problem: -+$ spiffygrep '-foo' test.txt Unknown command line argument '-foo'. Try: spiffygrep --help' @@ -808,7 +879,7 @@ Note that the system grep has the same problem: grep: illegal option -- o grep: illegal option -- o Usage: grep -hblcnsviw pattern file . . . -+The solution for this problem is the same for both your tool and the system version: use the '--' marker. When the user specifies '--' on @@ -816,13 +887,72 @@ the command line, it is telling the program that all options after the '--' should be treated as positional arguments, not options. Thus, we can use it like this:
-+$ spiffygrep -- -foo test.txt ...output... -+++Sometimes an option can affect or modify the meaning of another option. For + example, consider gcc's -x LANG option. This tells + gcc to ignore the suffix of subsequent positional arguments and force + the file to be interpreted as if it contained source code in language + LANG. In order to handle this properly, you need to know the + absolute position of each argument, especially those in lists, so their + interaction(s) can be applied correctly. This is also useful for options like + -llibname which is actually a positional argument that starts with + a dash.
+So, generally, the problem is that you have two cl::list variables + that interact in some way. To ensure the correct interaction, you can use the + cl::list::getPosition(optnum) method. This method returns the + absolute position (as found on the command line) of the optnum + item in the cl::list.
+The idiom for usage is like this:
+ ++ ++ static cl::list<std::string> Files(cl::Positional, cl::OneOrMore); + static cl::list<std::string> Libraries("l", cl::ZeroOrMore); + + int main(int argc, char**argv) { + // ... + std::vector<std::string>::iterator fileIt = Files.begin(); + std::vector<std::string>::iterator libIt = Libraries.begin(); + unsigned libPos = 0, filePos = 0; + while ( 1 ) { + if ( libIt != Libraries.end() ) + libPos = Libraries.getPosition( libIt - Libraries.begin() ); + else + libPos = 0; + if ( fileIt != Files.end() ) + filePos = Files.getPosition( fileIt - Files.begin() ); + else + filePos = 0; + + if ( filePos != 0 && (libPos == 0 || filePos < libPos) ) { + // Source File Is next + ++fileIt; + } + else if ( libPos != 0 && (filePos == 0 || libPos < filePos) ) { + // Library is next + ++libIt; + } + else + break; // we're done with the list + } + }Note that, for compatibility reasons, the cl::opt also supports an + unsigned getPosition() option that will provide the absolute position + of that option. You can apply the same approach as above with a + cl::opt and a cl::list option as you can with two lists.
+The cl::ConsumeAfter modifier @@ -840,27 +970,27 @@ interpreted by the command line argument. standard Unix Bourne shell (/bin/sh). To run /bin/sh, first you specify options to the shell itself (like -x which turns on trace output), then you specify the name of the script to run, then you specify -arguments to the script. These arguments to the script are parsed by the bourne +arguments to the script. These arguments to the script are parsed by the Bourne shell command line option processor, but are not interpreted as options to the shell itself. Using the CommandLine library, we would specify this as: --+cl::opt<string> Script(cl::Positional, cl::desc("<input script>"), cl::init("-")); cl::list<string> Argv(cl::ConsumeAfter, cl::desc("<program arguments>...")); cl::opt<bool> Trace("x", cl::desc("Enable trace output")); -+which automatically provides the help output:
-+-USAGE: spiffysh [options] <input script> <program arguments>... OPTIONS: -help - display available options (--help-hidden for more) -x - Enable trace output -+At runtime, if we run our new shell replacement as 'spiffysh -x test.sh +
At runtime, if we run our new shell replacement as `spiffysh -x test.sh -a -x -y bar', the Trace variable will be set to true, the Script variable will be set to "test.sh", and the Argv list will contain ["-a", "-x", "-y", "bar"], because they @@ -870,13 +1000,14 @@ name).
There are several limitations to when cl::ConsumeAfter options can be specified. For example, only one cl::ConsumeAfter can be specified per program, there must be at least one positional -argument specified, and the cl::ConsumeAfter option should be a specified, there must not be any cl::list +positional arguments, and the cl::ConsumeAfter option should be a cl::list option.
+ @@ -891,13 +1022,14 @@ files that use them. This is called the internal storage model. code from the storage of the value parsed. For example, lets say that we have a '-debug' option that we would like to use to enable debug information across the entire body of our program. In this case, the boolean value -controlling the debug code should be globally accessable (in a header file, for +controlling the debug code should be globally accessible (in a header file, for example) yet the command line option processing code should not be exposed to all of these clients (requiring lots of .cpp files to #include CommandLine.h).@@ -977,7 +1107,7 @@ a command line option. Look here for an example.To do this, set up your .h file with your option, like this for example:
+// DebugFlag.h - Get access to the '-debug' command line option // @@ -911,37 +1043,35 @@ extern bool DebugFlag; // DEBUG macro - This macro should be used by code to emit debug information. // In the '-debug' option is specified on the command line, and if this is a // debug build, then the code specified as the option to the macro will be -// executed. Otherwise it will not be. Example: -// -// DEBUG(cerr << "Bitset contains: " << Bitset << "\n"); -// -#ifdef NDEBUG +// executed. Otherwise it will not be. +#ifdef NDEBUG #define DEBUG(X) #else -#define DEBUG(X) \ - do { if (DebugFlag) { X; } } while (0) -#endif +#define DEBUG(X) do { if (DebugFlag) { X; } } while (0) +#endif+This allows clients to blissfully use the DEBUG() macro, or the DebugFlag explicitly if they want to. Now we just need to be able to set the DebugFlag boolean when the option is set. To do this, we pass -an additial argument to our command line argument processor, and we specify +an additional argument to our command line argument processor, and we specify where to fill in with the cl::location attribute:
+-bool DebugFlag; // the actual value +bool DebugFlag; // the actual value static cl::opt<bool, true> // The parser -Debug("debug", cl::desc("Enable debug output"), cl::Hidden, - cl::location(DebugFlag)); +Debug("debug", cl::desc("Enable debug output"), cl::Hidden, cl::location(DebugFlag));+In the above example, we specify "true" as the second argument to -the cl::opt template, indicating that the template should -not maintain a copy of the value itself. In addition to this, we specify the cl::location attribute, so that DebugFlag is -automatically set.
+the cl::opt template, indicating that the +template should not maintain a copy of the value itself. In addition to this, +we specify the cl::location attribute, so +that DebugFlag is automatically set.The cl::init attribute specifies an -inital value for a scalar option. If this attribute is +initial value for a scalar option. If this attribute is not specified then the command line option value defaults to the value created by the default constructor for the type. Warning: If you specify both cl::init and cl::location for an option, @@ -986,18 +1116,19 @@ command-line parser sees cl::init, it knows where to put the initial value. (You will get an error at runtime if you don't put them in the right order.) -The cl::location attribute where to -store the value for a parsed command line option if using external storage. See -the section on Internal vs External Storage for more + The cl::location attribute where +to store the value for a parsed command line option if using external storage. +See the section on Internal vs External Storage for more information. The cl::aliasopt attribute -specifies which option a cl::alias option is an alias -for. +specifies which option a cl::alias option is +an alias for.The cl::values attribute specifies the string-to-value mapping to be used by the generic parser. It takes a -null terminated list of (option, value, description) triplets that +clEnumValEnd terminated list of (option, value, description) triplets +that specify the option name, the value mapped to, and the description shown in the --help for the tool. Because the generic parser is used most frequently with enum values, two macros are often useful: @@ -1020,6 +1151,16 @@ and the second is the description. You will get a compile time error if you try to use cl::values with a parser that does not support it. +The cl::multi_val +attribute specifies that this option takes has multiple values +(example: -sectalign segname sectname sectvalue). This +attribute takes one unsigned argument - the number of values for the +option. This attribute is valid only on cl::list options (and +will fail with compile error if you try to use it with other option +types). It is allowed to use all of the usual modifiers on +multi-valued options (besides cl::ValueDisallowed, +obviously). +These options fall into five main catagories:
+These options fall into five main categories:
-
- Hiding an option from --help output
@@ -1049,9 +1190,9 @@ your application well.- Miscellaneous option modifiers
It is not possible to specify two options from the same catagory (you'll get +
It is not possible to specify two options from the same category (you'll get a runtime error) to a single option, except for options in the miscellaneous -catagory. The CommandLine library specifies defaults for all of these settings +category. The CommandLine library specifies defaults for all of these settings that are the most useful in practice and the most common, which mean that you usually shouldn't have to worry about these.
@@ -1073,15 +1214,15 @@ compiled program:
The formatting option group is used to specify that the command line option has special abilities and is otherwise different from other command line -arguments. As usual, you can only specify at most one of these arguments.
+arguments. As usual, you can only specify one of these arguments at most.The CommandLine library does not restrict how you use the cl::Prefix or cl::Grouping -modifiers, but it is possible to specify ambiguous argument settings. Thus, it -is possible to have multiple letter options that are prefix or grouping options, -and they will still work as designed.
+The CommandLine library does not restrict how you use the cl::Prefix or cl::Grouping modifiers, but it is possible to +specify ambiguous argument settings. Thus, it is possible to have multiple +letter options that are prefix or grouping options, and they will still work as +designed.
To do this, the CommandLine library uses a greedy algorithm to parse the input option into (potentially multiple) prefix and grouping options. The strategy basically looks like this:
-parse(string OrigInput) { +
}
+So far, the only miscellaneous option modifier is the -cl::CommaSeparated modifier.
+So far, these are the only three miscellaneous option modifiers.
+ +Some systems, such as certain variants of Microsoft Windows and +some older Unices have a relatively low limit on command-line +length. It is therefore customary to use the so-called 'response +files' to circumvent this restriction. These files are mentioned on +the command-line (using the "@file") syntax. The program reads these +files and inserts the contents into argv, thereby working around the +command-line length limits. Response files are enabled by an optional +fourth argument to +cl::ParseEnvironmentOptions +and +cl::ParseCommandLineOptions. +
+ +The cl::ParseCommandLineOptions function requires two parameters (argc and argv), but may also take an optional third parameter which holds additional extra text to emit when the ---help option is invoked.
+--help option is invoked, and a fourth boolean parameter that enables +response files.It takes three parameters: first, the name of the program (since -argv may not be available, it can't just look in argv[0]), -second, the name of the environment variable to examine, and third, the optional +
It takes four parameters: the name of the program (since argv may +not be available, it can't just look in argv[0]), the name of the +environment variable to examine, the optional additional extra text to emit when the ---help option is invoked.
+--help option is invoked, and the boolean +switch that controls whether response files +should be read.cl::ParseEnvironmentOptions will break the environment variable's value up into words and then process them using @@ -1362,6 +1550,27 @@ input.
+ + + +The cl::SetVersionPrinter function is designed to be called +directly from main and before +cl::ParseCommandLineOptions. Its use is optional. It simply arranges +for a function to be called in response to the --version option instead +of having the CommandLine library print out the usual version string +for LLVM. This is useful for programs that are not part of LLVM but wish to use +the CommandLine facilities. Such programs should just define a small +function that takes no arguments and returns void and that prints out +whatever version information is appropriate for the program. Pass the address +of that function to cl::SetVersionPrinter to arrange for it to be +called when the --version option is given by the user.
+ ++namespace cl { template <class DataType, bool ExternalStorage = false, class ParserClass = parser<DataType> > class opt; } -+The first template argument specifies what underlying data type the command line argument is, and is used to select a default parser implementation. The @@ -1408,13 +1617,13 @@ href="#customparser">custom parser.
line options. It too is a templated class which can take up to three arguments: -+namespace cl { template <class DataType, class Storage = bool, class ParserClass = parser<DataType> > class list; } -+This class works the exact same as the cl::opt class, except that the second argument is @@ -1424,6 +1633,31 @@ be used.
The cl::bits class is the class used to represent a list of command +line options in the form of a bit vector. It is also a templated class which +can take up to three arguments:
+ +
+namespace cl {
+ template <class DataType, class Storage = bool,
+ class ParserClass = parser<DataType> >
+ class bits;
+}
+This class works the exact same as the cl::lists class, except that the second argument +must be of type unsigned if external storage is used.
+ +The cl::alias class is a nontemplated class that is used to form aliases for other arguments.
-+namespace cl { class alias; } -+The cl::aliasopt attribute should be used to specify which option this is an alias for. Alias arguments default to @@ -1447,6 +1681,34 @@ the conversion from string to data.
The cl::extrahelp class is a nontemplated class that allows extra +help text to be printed out for the --help option.
+ +
+namespace cl {
+ struct extrahelp;
+}
+To use the extrahelp, simply construct one with a const char* +parameter to the constructor. The text passed to the constructor will be printed +at the bottom of the help message, verbatim. Note that multiple +cl::extrahelp can be used, but this practice is discouraged. If +your tool needs to print additional help information, put all that help into a +single cl::extrahelp instance.
+For example:
+
+ cl::extrahelp("\nADDITIONAL HELP:\n\n This is the extra help\n");
+
This approach has the advantage that users of your custom data type will automatically use your custom parser whenever they define an option with a value type of your data type. The disadvantage of this approach is that it doesn't -work if your fundemental data type is something that is already supported.
+work if your fundamental data type is something that is already supported. @@ -1556,7 +1824,7 @@ it.This approach works well in situations where you would line to parse an option using special syntax for a not-very-special data-type. The drawback of this approach is that users of your parser have to be aware that they are using -your parser, instead of the builtin ones.
+your parser instead of the builtin ones. @@ -1571,34 +1839,34 @@ this the default for all unsigned options.To start out, we declare our new FileSizeParser class:
-+struct FileSizeParser : public cl::basic_parser<unsigned> { // parse - Return true on error. bool parse(cl::Option &O, const char *ArgName, const std::string &ArgValue, unsigned &Val); }; -+Our new class inherits from the cl::basic_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 that we parse into 'unsigned' variables.
+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 that we parse into 'unsigned' variables.)For most purposes, the only method that must be implemented in a custom parser is the parse method. The parse method is called whenever the option is invoked, passing in the option itself, the option name, the string to parse, and a reference to a return value. If the string to parse -is not well formed, the parser should output an error message and return true. +is not well-formed, the parser should output an error message and return true. Otherwise it should return false and set 'Val' to the parsed value. In our example, we implement parse as:
-+bool FileSizeParser::parse(cl::Option &O, const char *ArgName, const std::string &Arg, unsigned &Val) { const char *ArgStart = Arg.c_str(); char *End; - + // Parse integer part, leaving 'End' pointing to the first non-integer char Val = (unsigned)strtol(ArgStart, &End, 0); @@ -1615,11 +1883,11 @@ our example, we implement parse as: default: // Print an error message if unrecognized character! - return O.error(": '" + Arg + "' value invalid for file size argument!"); + return O.error("'" + Arg + "' value invalid for file size argument!"); } } } -+This function implements a very simple parser for the kinds of strings we are interested in. Although it has some holes (it allows "123KKK" for @@ -1628,25 +1896,25 @@ itself to print out the error message (the error method always returns true) in order to get a nice error message (shown below). Now that we have our parser class, we can use it like this:
-+static cl::opt<unsigned, false, FileSizeParser> MFS("max-file-size", cl::desc("Maximum file size to accept"), cl::value_desc("size")); -+Which adds this to the output of our program:
-+OPTIONS: -help - display available options (--help-hidden for more) ... -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):
-+$ ./test MFS: 0 $ ./test -max-file-size=123MB @@ -1655,7 +1923,7 @@ $ ./test -max-file-size=3G MFS: 3221225472 $ ./test -max-file-size=dog -max-file-size option: 'dog' value invalid for file size argument! -+It looks like it works. The error message that we get is nice and helpful, and we seem to accept reasonable file sizes. This wraps up the "custom parser" @@ -1669,8 +1937,16 @@ tutorial.
Several of the LLVM libraries define static cl::opt instances that + will automatically be included in any program that links with that library. + This is a feature. However, sometimes it is necessary to know the value of the + command line option outside of the library. In these cases the library does or + should provide an external storage location that is accessible to users of the + library. Examples of this include the llvm::DebugFlag exported by the + lib/Support/Debug.cpp file and the llvm::TimePassesIsEnabled + flag exported by the lib/VMCore/Pass.cpp file.
-TODO: fill in this section
+TODO: complete this section
+