Garrett Rooney wrote an article called “Preserving Backward Compatibility” where he talked about how backward and forward compatibility is maintained for Subversion,  client/server source control management (SCM) system. Garrett talks about the importance of planning ahead, not throwing anything away, and of hiding the details. He also talks about exposing and hiding the dependencies of your API. This is a great article to read about how backward compatibility is maintained in a complex real-world system.

• http://onlamp.com/pub/a/onlamp/2005/02/17/backwardscompatibility.html?page=2

The Nokia Qt library provides a cross-platform application and UI framework for C++. It is often used to create user interfaces for programs that must run on several different platforms, but it also includes a large array of lower-level functionality, such as classes to handle threads, database access, regular expressions, networks, and XML.

Several of the Qt developers have written on the topic of good API design for C++. For example, Matthias Ettrich wrote an article on designing Qt-style C++ APIs that covers many good issues such as characteristics of good APIs, the boolean parameter trap, and the art of naming. See:

• http://doc.trolltech.com/qq/qq13-apis.html
• http://qt.gitorious.org/qt/pages/ApiDesignPrinciples

Also, Jasmin Blanchette wrote a document called “The Little Manual of API Design” that provides a similar treatment but with a bit more detail and covers more material on the design process and design guidelines. See:

• http://www.scribd.com/doc/15729315/The-Little-Manual-of-API-Design

John Lakos wrote the book Large-Scale C++ Software Design, in which he describes many issues of developing C++ software for large projects. As part of this book, he also provided a number of utilities to manage dependencies in a C++ project. This include:

• adep: creates aliases to group files into cohesive components
• cdep: extracts compile-time dependencies from several files
• ldep: analyzes link-time dependencies among various components

These utilities were originally written in the mid-1990s, though some engineers have attempted to make these utilities work with modern compilers. Here are some links if you’re interested in looking into these:

• http://rdfintrospector.blogspot.com/2006/08/configuration-tools-part-1-lsc-large.html
• http://prdownloads.sourceforge.net/introspector/LSC-rpkg-0.1.tgz?download

Andrei Alexandrescu published an excellent book called “Modern C++ Design.” In this book, he introduced the notion of policy-based templates as a way to provide highly-configurable solutions to various design patterns. He made the source code for these templates available via his Loki library, available at:

• http://sourceforge.net/projects/loki-lib/

The KDE Project offers some guidance on the difference between source and binary compatibility, and provides a great list of Do’s and Don’ts if you want to maintain binary compatibility for an API.

• http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++

This document defines binary and source compatibility as:

A library is binary compatible, if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn’t require any further modifications, the library is source compatible.

DynObj is a C/C++ library for creating cross-compiler plugin libraries from Arne Steinarson. It’s based on a shared type information system and allows you to load binary plugins and to interact with them in type safe ways.

• http://dynobj.sourceforge.net/
• http://www.codeproject.com/KB/library/dynobj.aspx

The author notes the following potential uses of DynObj

1. A program working with sound can install additional effect filters while running.
2. A file manager can add plugins that handles new archive types.
3. Or it can add file popup menu handlers, or toolbar commands from plugins.
4. A text editor can add an editing mode (say Python editing) when the text editor is running.

Arne also provides a great background to the problem of creating cross-platform and cross-compiler plugins.

This article by Markus Ewald guides you through the design of a simple C++ plugin architecture based upon Factory classes. He also includes a fully working example implementation of his plugin system for you to download.

• http://www.nuclex.org/articles/cxx/4-building-a-better-plugin-architecture

Markus presents a number of benefits of using plugins:

1. Increased clarity and uniformity of code
2. Improved modularization of code
3. Shorter compile times
4. Replacing/adding components

He also lists a further benefit of being able to use GPL code in a closed source project, although I do not believe that the GPL license allows this. The GPL FAQ states:

“If the program uses fork and exec to invoke plug-ins, then the plug-ins are separate programs, so the license for the main program makes no requirements for them. So you can use the GPL for a plug-in, and there are no special requirements. If the program dynamically links plug-ins, and they make function calls to each other and share data structures, we believe they form a single program, which must be treated as an extension of both the main program and the plug-ins. This means that combination of the GPL-covered plug-in with the non-free main program would violate the GPL.”

This Dr. Dobb’s article by Gigi Sayfan talks you through the various issues of creating a cross-platform plugin API in C/C++. This does a good job of diving into the binary compatibility issues with C++ plugins and presents a flexible framework that you can use on Windows, Mac OS X, and Linux. Sayfan uses the example of a simple role-playing game to demonstrate the ability to add non-player character plugins.

• http://www.drdobbs.com/cpp/204202899