This program generates a C function that uses getopt_long function to parse the command line options, to validate them and fills a struct .
Thus your program can now handle options such as:
myprog --input foo.c -o foo.o --no-tabs -i 100 *.classAnd both long options (those that start with --) and short options (start with - and consist of only one character) can be handled. For standards about short and long options you may want to take a look at the GNU Coding Standards .
gengetopt is free software.
Please see the file LICENSE and COPYING
for details.
Notice that: Use of gengetopt does not impose any particular
license on the generated code: the code generated is not under any
license.
For documentation, please read this file.
gengetopt is perfect if you are too lazy (like me) to write all
stuff required to call getopt_long, and when you have a
program and wish it took options.
Generated code works if you use GNU Autoconf or GNU Automake .
Gengetopt has originally been written by Roberto Arturo Tena Sanchez <arturo@directmail.org>, and currently maintained by Lorenzo Bettini <bettini@gnu.org>.
Gengetopt is a GNU program and its
main home page is at GNU site:
http://www.gnu.org/software/gengetopt/gengetopt.html
,
I do not distribute Windows binaries anymore; since, they can be easily built by using Cygnus C/C++ compiler, available at http://www.cygwin.com/. However, if you don't feel like downloading such compiler, you can request such binaries directly to me, by e-mail (bettini@gnu.org ) and I can send them to you.
You may also want to check the md5sum of the archives, which are also digitally signed by me (Lorenzo Bettini) with GNU gpg (http://www.gnupg.org). My GPG public key can be found at my home page (see at the end of this doc).
You can also get the patches, if they are available for a particular release (see below for patching from a previous version).
cvs -d:pserver:anoncvs@subversions.gnu.org:/cvsroot/gengetopt login
cvs -z3 -d:pserver:anoncvs@subversions.gnu.org:/cvsroot/gengetopt co gengetoptFurther instructions can be found at the address: http://savannah.gnu.org/projects/gengetopt .
cd <source code main directory>Note: unless you specify a different install directory by --prefix option of configure (e.g. ./configure --prefix=<your home> ), you must be root to 'make install'.
./configure
make
make install
You can also run some tests by issuing 'make check'.
Files will be installed in the following directories:
getopt_long function is usually in the standard C library, but there may be some C libraries which don't include it; in this case you have to link the program that uses the file generated by gengetopt with the files getopt.c and getopt1.c and include getopt.h in your project. You may also need to link alloca.c.We obviously provide these files in the utility files directory (/prefix/share/gengetopt). These files are part of the GNU C library. You may want to take a look at getopt man page. Read also no_getopt_long.txt. for instuctions on how to check if getopt_long and alloca are part of the library and how to deal with their lacking (using autoconf and automake).
gengetopt has been developed under Linux, using gcc, and bison (yacc) and flex (lex), and ported under Windows with Cygnus C/C++ compiler, available at http://www.cygnus.com/. I used the excellent GNU Autoconf and Automake. I also used Autotools (ftp://ftp.ugcs.caltech.edu/pub/elef/autotools ) which creates a starting source tree (according to GNU standards) with autoconf, automake starting files, and getopt_long (for command line parsing). Moreover Gengen (http://www.lorenzobettini.it/software/gengen/ ) is used for automatically generating the code that generates the command line parser.
Actually, unless you want to develop gengetopt, you don't need all these tools to build gengetopt because I provide generated sources; you don't need neither bison (yacc) nor flex (lex), for the same reason. Actually programs that use lex generated files need to link with library libfl (or libl for lex); anyway configuration phase can discover if this library is missing and in that case it sets the program to link with a source file I provide. This hack works for flex: I don't know about lex generated scanners. But, again, this is a problem only if you develop gengetopt and you use lex.
Should you want to act on the generated code you may want to download Gengen that speeds up this part (http://www.lorenzobettini.it/software/gengen/ ).
gunzip -cd ../gengetopt-1.3-1.3.1.patch.gz | patch -p1and restart the compilation process (if you had already run configure a simple make will do).
package <packname>Where:
version <version>
option <long> <short> <desc> <argtype> {default="<default value>"} <required> {multiple}
option <long> <short> <desc> flag <onoff>
option <long> <short> <desc> no
packname
Double quoted string.version
Double quoted string.purpose
What the program does (even on more than one line), it will be printed with the help. Double quoted string.long
The long option, a double quoted string with upper and lower case chars, digits, '-' and '.'. No spaces allowed. The name of the variables generated to store arguments are long options converted to be legal C variable names. This means, '.' and '-' are both replaced by '_'. '_arg' is appended, or '_flag' for a flag.short
The short option, a single upper or lower case char, or a digit. If a '-' is specified, then no short option is considered for the long option (thus long options with no associated short options are allowed).desc
Double quoted string with upper and lower case chars, digits, '-', '.' and spaces. First character must not be a space.argtype
string, int, short, long, float, double, longdouble or longlong.default
an optional default value for the option. The value must always be specified as a double quoted string.required
yes or no.multiple
If this flag is specified then this option can be specified more than once at command line; all the values for this option are stored in an array. See multiple options in the Advanced Features section.onoff
on or off. This is the state of the flag when the program starts. If user specifies the option, the flag toggles.The third type of option is used when the option does not take any argument. It must not be required.
Comments begins with '#' in any place of the line and ends in the end of line.
Here's an example of such a file (the file is called sample1.ggo)
# file sample1.ggo option "str-opt" s "A string option" string no option "my-opt" m "Another integer option" int no option "int-opt" i "A int option" int yes option "flag-opt" - "A flag option" flag off option "funct-opt" F "A function option" no option "long-opt" - "A long option" long no option "def-opt" - "A string option with default" string default="Hello" no |
The simplest way to use gengetopt is to pass this file as the standard input, i.e.:
gengetopt < sample1.ggoby default gengetopt generates cmdline.h and cmdline.c . Otherwise we can specify these names with a command line option:
gengetopt < sample1.ggo --file-name=cmdline1 --unamed-optsThe option --unamed-opts allows the generated command line parser to accept also names, without an option (for instance you can pass a file name without an option in front of it, and also use wildcards, such as *.c, foo*.? and so on).
In cmdline1.h you'll find the generated C struct:
/* cmdline1.h */ |
Notice that by default the generated function is called cmdline_parser
(see the command line options below, to override this name), and it
takes the arguments that main receives and a pointer to such a
struct, that it will be filled.
And here's how this function can be used inside the main program:
/* main1.cc */ |
Now you can compile main1.cc and the cmdline1.c generated by gengetopt and link all together to obtain sample1 executable:
gcc -c cmdline1.c(Here we assume that getopt_long is included in the standard C library; see 'What you need to build gengetopt' section).
g++ -c main1.cc
g++ -o sample1 cmdline1.o main1.o
Now let's try some tests with this program:
$ ./sample1 -s "hello" --int-opt 1234You can also pass many file names to the command line (this also shows how flags work):
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
Here are the options you passed...
You inserted hello for --str-opt option.
This is the integer you input: 1234.
The flag is off.
Have a nice day! :-)
$ ./sample1 *.h -i -100 -xAnd if we try to omit the --int-opt (or -i), which is required, we get an error:
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
Here are the options you passed...
file: cmdline1.h
file: cmdline2.h
file: cmdline.h
file: getopt.h
This is the integer you input: -100.
The flag is on.
Have a nice day! :-)
$ ./sample1If you're curious you may want to take a look at the generated C file.
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
sample1: `--int-opt' (`-i') option required!
You may find other examples in /prefix/share/doc/gengetopt.
defgroup "<group name>" {yes}If a group is defined as required, then one (but only one) option belonging to the group has to be specified.
groupoption <long> <short> <desc> <argtype> group="<group name>"
defgroup "grp2"The group grp1 is required, so either opta or optb has to be specified (but only one of them). Here's the output of some executions:
defgroup "grp1" yes
groupoption "opta" a "string a" group="grp1"
groupoption "optb" b "string b" group="grp1"
groupoption "optc" c "string c" group="grp2"
groupoption "optd" d "string d" group="grp2"
$ ./test_groups
gengetopt: 0 options of group grp1 were given. One is required
$ ./test_groups -a OK
$ ./test_groups -a -b
gengetopt: 2 options of group grp1 were given. One is required
$ ./test_groups -a -c OK
$ ./test_groups -a -c -d
gengetopt: 2 options of group grp2 were given. At most one is required
intThe config file has the following simple syntax: lines starting with # are considered comments and:
<cmd_parser_name>_configfile (char * const filename,
struct gengetopt_args_info *args_info,
int override);
/* test_conf_parser.c test */ /* test all kinds of options and the conf file parser */ #include <stdlib.h> #include <stdio.h> #include "test_conf_parser_cmd.h" static struct gengetopt_args_info args_info; int main (int argc, char **argv) { |
# required optionand we run test_conf_parser like that we will have
required "foo"
float 3.14
no-short
string another
./test_conf_parser -r bar -i 100 --conf-file test_conf.conf
value of required: "foo"
value of string: another
value of no-short: 1
value of int: 100
value of float: 3.140000
# test options that can be given more than once
option "int" i "int option" int no multiple |
|
./test_multiple -s "foo" -s "bar" -s "hello" -i 100 -i 200 -s "world"The output of the program will be
passed string: world
passed string: hello
passed string: bar
passed string: foo
passed int: 200
passed int: 100
$ gengetopt --helpThe options should be clear; in particular:
gengetopt 2.9
Purpose:
This program generates a C function that uses getopt_long function
to parse the command line options, validate them and fill a struct.
Usage: gengetopt [OPTIONS]...
-h --help Print help and exit
-V --version Print version and exit
-iSTRING --input=STRING input file (default std input)
-fSTRING --func-name=STRING name of generated function (default='cmdline_parser')
-FSTRING --file-name=STRING name of generated file (default='cmdline')
-l --long-help long usage line in help
-u --unamed-opts accept filenames
--no-handle-help do not handle --help|-h automatically
--no-handle-version do not handle --version|-V automatically
--no-handle-error do not exit on errors
--conf-parser generate a config file parser
Maintained by Lorenzo Bettini <bettini@gnu.org>
Report bugs to <bug-gengetopt@gnu.org>
purpose "This program generates a C function that uses getopt_long function option "input" i "input file. default std input" string no |
In particular the command line for gengetopt itself is generated with the following command:
gengetopt --input=cmdline.ggo --no-handle-version --no-handle-help --no-handle-errorIndeed when --help|-h is passed on the command line, gengetopt will call cmdline_parser_print_help() and then the lines for reporting bugs. When --version|-V is passed, it will call cmdline_parser_print_version() and then prints a copyright.
$ ./gengetopt --zzzz
./gengetopt: unrecognized option `--zzzz'
Run gengetopt --help to see the list of options.
Actually we want to extend it, so if you have some ideas... The most import one will be to make gengetopt more customizable :-)
Please send all bug reports by electronic mail to:
bug-gengetopt@gnu.org
Lorenzo Bettini http://www.lorenzobettini.it <bettini@gnu.org>. |
Roberto Arturo Tena Sanchez http://arturo.directmail.org <arturo@directmail.org>, |
gengetopt is free software. See the file LICENSE and COPYING for copying conditions. Anyway we won't get offended if you send us a postcard :-)
C/C++ files are formatted with GNU Source-highlight (http://www.gnu.org/software/src-highlite/ ) by Lorenzo Bettini.
Return to GNU's home page.
Please send FSF & GNU inquiries & questions to gnu@gnu.org . There are also other ways to contact the FSF.
Please send comments on these web pages to webmasters@gnu.org , send other questions to gnu@gnu.org .
Copyright (C) 2001 Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
Updated:9 Jan 2001 mhw