libUTL++ Documentation

1. Introduction

libUTL++ is a home for code that I've reused across C++ projects over the years.

Here's a brief (incomplete) overview of what's in the library:

2. License

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

libUTL++ also bundles randutils.hpp by Melissa E. O'Neill, which she has shared under the MIT License. randutils "makes good seeding easier, and makes using RNGs easy while retaining all the power". In my own words: Melissa's work builds on top of the standard library's RNG facilities to provide easy access to good RNG. The STL's RNG facilities only seem "over-engineered" when there is no convenient wrapper for them. Also, std::random_device can't be depended on to provide a good seed, even though it may seem at first glance to be suitable for that purpose. I hope to see randutils (or something much like it) adopted into the standard library in the future.

A few links for randutils:

3. Supported Platforms

Currently Linux and Windows/MinGW amd64 targets are supported, as these are the platforms I've targeted in my projects. The library should also work for those systems on x86 (32-bit), but I haven't been testing that myself lately. Not many people care about 32-bit anymore.

4. Building libUTL++

4.1 Required Software

You will need the following packages to build the library:

You need these installed when building for Linux:

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 & g++ compiler are accessible in the system PATH and named with the prefix x86_64-w64-mingw32-. For example, on my Debian system I installed the package g++-mingw-w64, and the MinGW-targeted g++ is named x86_64-w64-mingw32-g++.

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++:

% 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++ should be able to happily coexist with other libraries:

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

One thing to watch for is that in a DEBUG build, libUTL++ overloads the new operator to keep track of active allocations (remembering the source file and line # where they were made). 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@.nosp@m.acms.nosp@m.proje.nosp@m.ct.o.nosp@m.rg

Please contact me if you've found a bug, or if you have any ideas for improving the library. Logo