libUTL++ Documentation

1. Introduction

libUTL++ is a cross-platform C++ class library that provides a set of commonly useful functionality and abstractions to expedite C++ application development.

Here's a brief overview:

2. License

libUTL++ 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 libUTL++ is easily portable to any platform that libUTL++ itself has been ported to. Currently Linux and Windows/MinGW (32- and 64-bit) are supported, as these are the platforms I've targeted in my projects.

4. Building libUTL++

4.1 Required Tools

You will need to have the following installed:

4.2 MinGW-w64 Build Environment

The MinGW-w64 project has made it easy to cross-compile for Windows on the Linux platform. The included build configuration for MinGW-w64 assumes the cross-targeted binutils & gcc compiler are installed in /opt/mingw-w64/. You also will need the gendef program (installed in /opt/mingw-w64/bin/). You can download gendef as well as pre-built Mingw-w64 here. On my Debian system I also had to install libmpfr-dev, and create a symlink: /usr/lib/ -> /usr/lib/x86_64-linux-gnu/

4.3 Build Procedure

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

% tar xzvf libutl-1.1.x.tar.gz # unpack sources
% cd libutl-1.1.x # change into source root directory

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

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

Then build and install libUTL++, like this:

% make install-dist

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

% make INST_ROOT=/usr/local/ install-dist

The build process may take a few minutes. Several versions of the library will be built, including:

  • DEBUG : libutl_g.a,
    [built with -g, enabled runtime assertions and debug new/delete]
  • DEBUG_RELEASE : libutl_gr.a,
    [built with -g, disabled runtime assertions and debug new/delete]
  • RELEASE : libutl.a,
    [built with -Ofast, disabled runtime assertions and debug new/delete]

5. Using libUTL++

To use libUTL++ in your project:

  • #include <libutl/libutl.h> near the start of your source files
    (before #include'ing any other header files from libUTL++)
  • call utl::init() when your application starts
  • call utl::deInit() before your application exits
  • link against the appropriate version of the library

If you subclass utl::Application, it will take care of the utl::init() and utl::deInit() calls for you.

To learn the library, the best way to get started is to study the bundled applications and example programs (installed in $INST_ROOT/share/libutl/), as well as the documentation (installed in $INST_ROOT/share/doc/libutl-doc/).

6. Compatibility With Other Libraries

libUTL++ can (in general) happily coexist with other libraries:

  • C++ symbols are in the utl namespace
  • most preprocessor symbols are prefixed with UTL_

You should be able to use many other libraries without any conflict.

One thing to watch for is that in a DEBUG build, libUTL++ overloads the new operator to remember the source file and line # of allocations, and this can be a problem when including some C++ header files. You can solve it this way:

#undef new
#include <some/thing.h>
#include <libutl/gblnew_macros.h>

7. Links

8. Contact the Author

You can reach me via e-mail: adam at mckeecs dot com.

Please contact me with bug reports or any ideas for improvements. Logo