C++ Library API Design

Question

I'm looking for a good resource for learning about good API design for C++ libraries, looking at shared objects/dlls etc. There are many resources on writing nice APIs, nice classes, templates and so on at source level, but barely anything about putting things together in shared libs and executables. Books like Large-Scale C++ Software Design by John Lakos are interesting but massively outdated.

What I'm looking for is advice i.e. on handling templates. With templates in my API I often end up with library code in my executable (or other library) so if I fix a bug in there I can't simply roll out the new library but have to recompile and redistribute all clients of that code. (and yes, I know some solutions like trying to instantiate at least the most common versions inside the library etc.)

I'm also looking for other caveats and things to mind for keeping binary compatibility while working on C++ libraries.

Is there a good website or book on such things?

• tp1: I handled it this way: sivut.koti.soon.fi/~terop/GameApi.html -- i.e. while there are templates inside the lib, none of it is in the api...
• DeadMG: std::unique_ptr is pretty new stuff. What exactly did you think was more suitable about your proposed API? The way in which you had to manually manage all the resources, virtually guaranteeing leaks and double deletes, for example? Or the way in which many of your types had one or two letter names, making divining their purpose impossible?
• DeadMG: @tp1: But you didn't take any care to see that I did handle them. You just said "HANDLE THEM" without doing anything about it. I didn't handle them and now what? Instead of using an RAII class which does not permit such mistakes. If you had used unique_ptr it would not be possible to write code like that.
• DeadMG: @tp1: I noticed that the Env can be destroyed. That's pretty much it. There doesn't appear to be any functionality to manage objects, at all. If I wanted to manage memory more fine grained than "Everything I ever created" or "Nothing", it would appear that I'm screwed.
• ChrisF: Please take any extended conversation to Software Engineering Chat. Can any useful information be incorporated in the question or an answer?

Answer 1

There is in-fact a book that is precisely what you seek. It is call, appropriately enough, API Design for C++.The book's website has source code from the book and Errata as well.

• zxcdw: Definite +1 for the book! I came to suggest this but turns out you beat me to it.
• Korchkidu: +1: I am finishing reading this book and it is a great resource. Highly recommended.

Answer 2

This is pretty much impossible. The simple fact is that sometimes, you need the compiler to do a job, and you can't just magic that necessity away. There is no function that can make std::vector not a header-only library. The compiler can make many magics work, but you can't have them without invoking it, and that's a fact of life.

Here's what you can do: don't use templates where you don't need them. Here's what you can't do: anything else.

The simple fact is that recompiling with the new version really isn't that big of a burden compared to the advantages of performance, safety, and functionality you can get with statically typed libraries.

• johannes: I mentioned that as an example to think about. what I'm looking for is guidance on other similar issues which I should prepare for, and best practices to handle those.
• Deduplicator: Well, if all new versions breaking ABI-compatibility are put into a new inline-namespace, what does it matter whether it's a header-only library or not?