Directory structure for C++ library

Question

I am working on a c++ library. Ultimately, I would like to make it publicly available for multiple platforms (linux/windows at least), along with some examples and python bindings. Work is progressing nicely, but at the moment the project is quite messy, built solely in and for VC++ and not multi platform at all.

Therefore, I feel a cleanup is in order. The first thing I'd like to improve is the project's directory structure. I'd like to create a structure that is suitable for the automake tools to allow easy compilation on multiple platforms, but I've never used these before. Since I'll still be doing (most of the) coding in visual studio, I'll need somewhere to keep my visual studio project and solution files as well.

I tried to google for terms like "c++ library directory structure", but nothing useful seems to come up. I found some very basic guidelines, but no crystal clear solutions.

While looking at some open source libraries, I came up with the following:

\mylib
    \mylib <source files, read somewhere to avoid 'src' directory>
        \include? or just mix .cpp and .h
    \bin <compiled examples, where to put the sources?>
    \python <python bindings stuff>
    \lib <compiled library>
    \projects <vc++ project files, .sln goes in project root?>
    \include? 
    README
    AUTHORS
    ...

I have no/little previous experience with multi platform development/open source projects, and am quite amazed that I cannot find any good guidelines on how to structure such a project.

How should one generally structure such a library project? Any recommended reading? Any good examples?

Answer 1

One thing that's very common among Unix libraries is that they are organized such that:

./         Makefile and configure scripts.
./src      General sources
./include  Header files that expose the public interface and are to be installed
./lib      Library build directory
./bin      Tools build directory
./tools    Tools sources
./test     Test suites that should be run during a `make test`

It somewhat reflects the traditional Unix filesystem under /usr where:

/usr/src      Sometimes contains sources for installed programs
/usr/include  Default include directory
/usr/lib      Standard library install path
/usr/share/projectname   Contains files specific to the project.

Of course, these may end up in /usr/local (which is the default install prefix for GNU autoconf), and they may not adhere to this structure at all.

There's no hard-and-fast rule. I personally don't organize things this way. (I avoid using a ./src/ directory at all except for the largest projects, for example. I also don't use autotools, preferring instead CMake.)

My suggestion to you is that you should choose a directory layout that makes sense for you (and your team). Do whatever is most sensible for your chosen development environment, build tools, and source control.

Answer 2

I don't think there's actually any good guidelines for this. Most of it is just personal preference. Certain IDE's will determine a basic structure for you, though. Visual Studio, for example, will create a separate bin folder which is divided in a Debug and Release subfolders. In VS, this makes sense when you're compiling your code using different targets. (Debug mode, Release mode.)

As greyfade says, use a layout that makes sense to you. If someone else doesn't like it, they will just have to restructure it themselves. Fortunately, most users will be happy with the structure you've chosen. (Unless it's real messy.)

Answer 3

I find wxWidgets library (open source) to be a good example. They support many different platforms (Win32, Mac OS X, Linux, FreeBSD, Solaris, WinCE...) and compilers (MSVC, GCC, CodeWarrior, Watcom, etc.). You can see the tree layout here:

http://svn.wxwidgets.org/viewvc/wx/wxWidgets/trunk/