Standard command-line options
This page describes just some usual conventions used when interpreting command-line options by my programs (actually, these conventions are widely known and used by most good programs in the world) :
Long options start with -- (two dashes), like --long-option. Short options start with - (one dash) and consist of one letter, like -p. The advantage of the long form is that you can easily remember it, the advantage of the short form is that you have less typing. Many options have both forms : long and short and you can use whichever you want.
All my programs should accept option --help (short form -h). Using this option instructs the program to print some short usage instructions and a short description of available options.
All my programs should accept option --version (short form -v). Using this option instructs the program to print version number. Here's a description of versioning scheme used in all my programs (link to vrmlengine.sf.net). Version number is always printed on standard output, never in some message box or something that; this allows to use calls like program_name --version in batch scripts, makefiles etc.
Note for Windows users of my programs that don't create a console (e.g. malfunction (link to vrmlengine.sf.net), kambi_lines (link to vrmlengine.sf.net) or glViewImage (link to vrmlengine.sf.net)): when Windows program does not explicitly create a console, it usually has no standard output available. You must explicitly redirect it's stdout when using option --version.
If option requires one argument, you can give it as
--long-option=argument (with '=') or
--long-option argument (passing argument as separate parameter) or
-p=argument (same as the first one, but using short form) or
-p argument (same as the second one, but using short form).E.g. following methods of running view3dscene (link to vrmlengine.sf.net) are equivalent:
view3dscene --navigation=Examine scene.wrl view3dscene --navigation Examine scene.wrl
If option allows but not requires an argument, you have to use --long-option=argument or -p=argument if you want to give an argument.
Short options can be combined. This means that you can put more than one short option in a one parameter, e.g.
program -abc
means the same asprogram -a -b -c
Note that only the last option in such "combined parameter" may take an argument, e.g.
program -de=50
means the same asprogram -d -e=50
but if you want to give an argument for -d and -e, you can't combine them : you must use something likeprogram -d=40 -e=50
Special option -- means "do not interpret following parameters". You can use it if you have files with names beginning with a '-'.
E.g. suppose you have a file named --file.png and you want to view it using glViewImage (link to vrmlengine.sf.net). If you call
glViewImage --file.png
then glViewImage will exit with an error 'invalid long option "--file.png"'. Even worse, if you have a file named --geometry (--geometry not only begins with a dash but it even IS a valid option for glViewImage) and you callglViewImage --geometry
then glViewImage will try to interpret the --geometry option and will give an error 'missing argument for "--geometry"'. So you can force glViewImage to treat --file.png or --geometry as file names using :glViewImage -- --file.png glViewImage -- --geometry