Back to files

Aargh

1. INTRODUCTION

Aargh is a code generator. It generates C or C++ code to parse the command line, using the traditional argc and argv arguments to main(). The generated code uses the getopt() function normally available in Linux, UNIX, and similar systems.

For more information, see the HTML documentation included in this distribution. For the most up to date information, see:

http://home.swbell.net/mck9/aargh/

2. LICENSING

Aargh is distributed under the terms of the GNU General Public License (GPL), Version 2. See the COPYING file for the text of the license itself. If it is not included in the distribution you receive, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

For parsing XML, aargh uses version 2.4.3 of the TinyXml routines by Lee Thomason, as included in this distribution. Other release levels of TinyXml will probably work but may require some tweaking of the aargh source code. TinyXml is released under the zlib License. For more information about TinyXml, see:

http://www.grinninglizard.com/tinyxml/index.html

Note that I have made a minor change to the Makefile for TinyXml, so as to use std::string instead of the tiXmlString class. The latter is provided for platforms where std::string is not available. Since aargh itself uses the Standard Template Library, which includes std::string, there is no reason not to use std::string.

In order to save bandwidth, I also removed the documentation that comes with the TinyXml distribution. If all you want to do is build aargh, you don't need that documentation. If you want to tinker with the source code, or develop other projects using TinyXml, by all means get the full TinyXml package, with documentation, from one of the mirrors.

3. COMPILING

The following compiling procedure works under SUSE Linux v9.3. You may need to adjust it here and there according to your local environment.

1. Place the aargh tarball in the directory of your choice. For purposes of illustration I shall call it ~/proj.
2. From within the ~/proj directory, run the following command:

tar -xvzf aargh_1_2_2.tar.gz

The file name may of course be somewhat different depending on the version number.

On some platforms, tar does not support the -z option. In that case you will need to unzip and untar in two separate steps:

        gunzip aargh_1_2_2.tar.gz
        tar -zvf aargh_1_2_2.tar

c. tar will have created a directory named ~/proj/aargh_1_2_2

(or something similar depending on the version number). cd to that directory and run the following command:

./build_aargh

Note that build_aargh is a shell script using /bin/bash. If your platform keeps bash in a different directory, edit the script accordingly. If bash is not available on your platform, edit the first line of the script to invoke /usr/bin/ksh.

d. Watch the messages scroll past. If all goes well, the build

procedure will build the TinyXml routines in a subdirectory named ~/proj/aargh_1_2_2/tinyxml, load them into a library in ~/proj/aargh_1_2_2, call make to build aargh, and finally report success.

The Makefile expects to use /usr/bin/g++ as the C++ compiler. If your platform uses a different compiler, or keeps g++ in a different location, then edit the Makefile as needed.

e. As a test, execute the following command:

./aargh sample.xml

If aargh has been built successfully, it will create two new files: sample_opts.h and sample_opts.C.

f. Install aargh in the directory of your choice, such as

/usr/local/bin, so that you can use it without specifying a full path. You will likely need root authority to install it.

If build_aargh fails somewhere in the middle, after finding and fixing the problem you should be able to run build_aargh again without further ado. The script is designed to figure out how far you've already gotten and resume wherever you left off. However it's a fairly simple script. If all else fails you can read the script, figure out what it's trying to do, and do it yourself manually.

Note that the aargh distribution includes a file named aargh.xml. This is the file I use to generate code to parse aargh's command line. Aargh is recursive that way.

Of course you can't use aargh.xml until you have compiled aargh. I include aargh.xml for documentation. Also you may find it useful if you want to modify aargh.

4. COMPILE-TIME MACROS

As noted elsewhere: when the XML input file specifies file names without extensions, aargh completes the file names by appending a period and a default extension: "h" for header files, "c" for C source files, and "C" for C++ source files.

You can override these defaults from the aargh command line, but maybe you'd rather not have to. Maybe you always want to use "hpp" and "cpp" instead of "h" and "C", and it's annoying to have to specify those options all the time.

When you compile aargh you can change those defaults by defining appropriate macros, typically by passing them to the compiler via the -D option:

AARGH_C_EXT extension for C source files AARGH_C_HDR_EXT extension for C header files AARGH_CXX_EXT extension for C++ source files AARGH_CXX_HDR_EXT extension for C++ header files

The values for these macros must include the enclosing double quotes, but not the period.

5. PORTING

I developed aargh at home using Linux, but at work I use HP-UX. When I tried to compile aargh at work I ran into a variety of problems, mostly because the C++ implementation available to me there was not standards-compliant.

Here's how I got around the problems. You may need to take similar measures depending on your environment.

1. The Makefile provided with TinyXml used some gmake extensions that the HP-UX make utility didn't recognize. Solution: write your own Makefile for TinyXml.
2. The C++ compiler supports namespaces but it doesn't define namespace std. Consequently, references to things like std::string wouldn't compile. Solution: globally replace "std::" with the empty string.
3. I had to change the #includes so as to look for <fstream.h> and <iostream.h> instead of <fstream> and <iostream>, respectively.
4. The STL implementation didn't provide <sstream>, nor any version of ostringstream, which one of the TinyXml routines uses. Fortunately it's an output routine, not an input routine, and aargh doesn't need it. Solution: in the function:

std::string & operator<<( std::string& out, const TiXmlNode& base )

...comment out everything but the return statement. This function won't be good for anything any more, but it will satisfy the compiler. If you ever need TinyXml to produce output to a string without using an ostringstream, you'll have to go to a lot more trouble.