15

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?

Improve this question
21
  • 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...
    – tp1
    Commented Sep 2, 2012 at 14:36
  • 1
    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
    Commented Sep 2, 2012 at 16:09
  • 1
    @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
    Commented Sep 2, 2012 at 16:23
  • 1
    @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.
    – DeadMG
    Commented Sep 2, 2012 at 16:33
  • 4
    Please take any extended conversation to Software Engineering Chat. Can any useful information be incorporated in the question or an answer?
    – ChrisF ♦
    Commented Sep 2, 2012 at 18:19

2 Answers 2

Reset to default
14

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.

Improve this answer
2
  • 2
    Definite +1 for the book! I came to suggest this but turns out you beat me to it.
    – zxcdw
    Commented Sep 2, 2012 at 15:48
  • 1
    +1: I am finishing reading this book and it is a great resource. Highly recommended.
    – Korchkidu
    Commented Jul 11, 2013 at 17:19
5

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.

Improve this answer
2
  • 3
    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.
    – johannes
    Commented Sep 2, 2012 at 17:16
  • 1
    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?
    – Deduplicator
    Commented Oct 15, 2015 at 0:56

Not the answer you're looking for? Browse other questions tagged or ask your own question.