libUTL++ Documentation

1. Introduction

UTL++ is an object-oriented C++ application development framework. I initially wrote it for my own use, and I've definitely found it useful enough myself to justify the effort I've put into it. I've made UTL++ available to the public under the GNU GPL in the hope that others can benefit from it also. In particular, I want UTL++ to help you achieve the following goals:

2. License

UTL++ is licensed under the GNU GPL. Make sure you read and understand the license, because it describes your rights in regards to the use and redistribution of this software.

3. Supported Platforms

Code written on top of UTL++ is easily portable to any platform that UTL++ itself has been ported to.

The following platforms are supported as of this writing:

Future ports may include:

Of course the effort to do these ports will depend on interest. The OS/X and *BSD ports should be relatively easy because these systems share much in common with Linux.

4. Reporting Bugs

Most of UTL++ has been well tested, but even in a project of this modest size, there will be bugs. If you come across one - please take a few minutes to send me the following:

5. Building libUTL++

5.1 Required Tools

You will need to have the following installed:

5.2 MinGW Build Environment

5.2.1 Cygwin + MinGW Basic Setup

Here's a quick rundown of how I set up a build environment for MinGW. The general idea is to have the toolchain (binutils, gcc, g++) in MinGW, whereas everything else (i.e. GNU make, bash, etc.) is from Cygwin.

So, starting from scratch, first install Cygwin to "C:\Cygwin". Take everything you want from Cygwin, but don't install binutils or gcc or g++.

Make sure you install the following items from Cygwin:

Next, install these packages (or newer versions) from MinGW:

To install those, simply unpack them into "C:\MinGW".

Make a symlink "/mingw" pointing to the MinGW root, like so:

   % ln -sf cygdrive/c/MinGW /mingw

You may need to make symlinks for gcc and g++, like so:

   % ln -sf gcc-dw2.exe /mingw/bin/gcc
   % ln -sf g++-dw2.exe /mingw/bin/g++

Finally, put /mingw/bin at the start of your PATH, so that MinGW binaries (i.e. the toolchain) can be found, and so they'll take precedence over any Cygwin versions that may be installed.

5.2.2 MinGW DLL Troubles

I had trouble using libUTL++ in a DLL. It seems that any exception thrown from inside the DLL (but not caught there) will instantly terminate execution of the program, as if the exception had not been caught ("terminate called after throwing an instance of ..."). I recommend static linking for now, although I'm sure the DLL can be made to work (soon if not now).

5.2.3 MinGW Exception Handling: DWARF2 vs. SJLJ

SJLJ EH (exception handling) is a method of unwinding the stack that uses setjump() and longjump(). SJLJ EH is the official standard on MinGW, because it works reliably in all cases, but it has the disadvantage of being tremendously inefficient. For that reason, I recommend you use gcc with DWARF2 EH (exception handling). However, there there is a limitation of DWARF2 EH that you need to be aware of - which is that an exception thrown inside code compiled with DWARF2 EH cannot propagate through any code that was not compiled with DWARF2 EH. For an example of that, consider the case where an exception is thrown from inside a callback, and the exception isn't caught from inside the callback, but instead propagates back up to the Windows DLL that invoked the callback (perhaps to be caught inside the main message loop). I personally don't find this limitation to be a problem, unlike the severely poor performance of SJLJ EH...

5.3 Build Procedure

First, unpack the sources and change into the UTL++ source root directory:

   % tar xzvf libutl-1.0.5.tar.gz    # unpack sources
   % cd libutl-1.0.5                 # change into UTL++ source root directory

Next, if you're building on a system other than Linux (such as MinGW), you have to configure the UTL++ build system for that target by using the config shell script located in the makefiles directory. For example:

   % cd makefiles                    # change into makefiles directory
   % ./config mingw                  # configure build system for MinGW target
   % cd ..                           # change back to UTL++ source root

If you're using gcc/g++ older than 4.2.1, you'll need to make a symlink for atomicity.h, so it can be found. For example if you were building with g++ 4.1.2:

   % su # become root
   % ln -sf ../bits/atomicity.h /usr/include/c++/4.1.2/ext

Finally, we're ready to build and install UTL++, like this:

   % make install_dist

You can use INST_ROOT to override the installation root. For example:

   % make INST_ROOT=/usr/local install_dist

Depending on how fast your system is, the build process could take anywhere from a little while to a long while. Several versions of the library will be built, including:

When you build on a 64-bit system, both 32- and 64-bit versions of the above libraries will be built. The 64-bit versions will have "64" appended to their name, so for example libutl_dbg64.a is the static 64-bit DEBUG build of the library.

6. Using libUTL++

To get started using libUTL++ in your project:

If you subclass utl::Application, its ctor and dtor will take care of the utl::init and utl::deInit calls for you.

That's a quick crash course in getting started with libUTL++, but the best way to get familiarized with the library is to study the included source documentation, example programs, and the source code.

7. libUTL++ Design Philosophy

UTL++ generally favours an object-oriented design, and like other OO frameworks it features a singly-rooted class hierarchy. utl::Object is an ancestor to just about every class in UTL++ ; it provides a standard interface for common object functionality such as copying/cloning, comparison, and serialization. It's also a good idea to have your own classes inherit from utl::Object when you program with UTL++ ; in the true spirit of object-orientation, many classes in UTL++ are written with the idea that you will subclass them to implement the specialized behavior you need.

In C++ you will find situations where generic programming is a better fit than OO. Although UTL++ does include some template functions and classes, I've purposely avoided overlap with the STL. The good news is that you don't have to choose between UTL++ and the STL: you can use each when it suits you. I've taken care to make UTL++ "play nice" with other libraries by putting almost all symbols in the utl namespace.

8. Links

9. Contact the Author

You can reach me via e-mail at prof dot hate at gmail dot com.

SourceForge.net Logo

Generated on Fri Aug 10 15:47:04 2007 for libUTL++ by  doxygen 1.5.3