Best folder structure for C++ cross-platform library and bindings

Question

I am about to begin work on a cross-platform library to be written in C++. Down the road, I intend to implement bindings for other languages such as Python, Java, etc. The library needs to be available on the major platforms: win32, Linux and Mac OSX.

Although the application is really a library, some basic console programs will be bundled along with it for demonstration and testing.

I'd like to come up with an optimum folder structure before I start storing stuff in Subversion.

I am thinking of something like:

/project                    //Top level folder

        /bin                //Binaries ready for deployment
            /linux_amd64    //Linux AMD64 platform
                  /debug    //Debug build - duplicated in all platforms
                  /release  //Release build - duplicated in all platforms
            /linux_i386     //Linux 32-bit platform
            /macosx         //Mac OS X
            /win32          //Windows 32-bit platform
                  /cygwin   //Windows 32-bit platform compiled with Cygwin
                  /vs.net   //Windows 32-bit platform compiled with Visual Studio .NET
            /win64          //Windows 64-bit platform

        /build              //Make and build files, IDE project files
            /linux_amd64    //Linux AMD64 platform
            /linux_i386     //Linux 32-bit platform
            /macosx         //Mac OS X
            /win32          //Windows 32-bit platform
            /win64          //Windows 64-bit platform

        /config             //Configuration files that accompany the binaries

        /data               //Data files that accompany the binaries

        /doc                //Documentation

        /lib                //External or third-party libraries
            /platforms      //Platform-specific code for ...
                      /linux_amd64    //Linux AMD64 platform
                      /linux_i386     //Linux 32-bit platform
                      /macosx         //Mac OS X
                      /win32          //Windows 32-bit platform
                      /win64          //Windows 64-bit platform
            /src            //Available library source code in subfolders

        /src                //Source code tree - this will contain main.cpp
            /bindings       //Bindings to other languages such as ...
                      /python
                      /java
            /h              //Header files
            /modules        //Platform-independent modules, components or subprojects
            /platforms      //Platform-specific code for ...
                      /linux_amd64 //Linux AMD64 platform-specific code
                      /linux_i386  //Linux 32-bit platform-specific code
                      /macosx
                      /win32       //Windows 32-bit platform-specific code
                      /win64       //Windows 64-bit platform

        /test               //Automated test scripts

If you have suggestions, I'd love to hear them. I wonder if there is a tool that can help create this structure.

I am planning on using CMake and Subversion.

Answer 1

Why you need different platform folders for binary files? You going to build this source code under different platoforms but with same file system?

If yes, I think you need compiller specific folders too.

Why you don't use different folders for debug and release build, maybe unicode and non-unicode, single-threading or multithreading builds?

Look on bjam or Scons make replacers. Maybe you don't need different folders in build directory.

I think it will be better if all modules from "modules" directory will contain "tests" directory for test self.

---

And last - see boost library, this platofrm independed library which have nice structure.

Also try to get ideas from antother platform independed projects.

Boost folders structure:

boost - root dir
- boost - library header lib ( for users )
- libs - library source dir ( one dir per lib )
    - build - library build files ( if they are needed )
    - doc - documentation files
    - example - sample programs
    - src - library source files
    - test - programs and srcipts for testing module
- bin - created by bjam build system
    - libs
     - <lib-name>
      for all compiled folders from libs [example|test|build]
       - <compiler-name>/<[static|dynamic]-link>/<[debug|release]>/<[threading mode]>
        contain builded [obj|dll|lib|pdb|so|o|etc] files see detailed information in bjam build system

- doc
- tools

If you choose bjam - you will not be concerned on build and bin folders structure.

Also your libs/src/ dir could contain own for all platform files and couple dirs for platform spcific files.

I don't see any serious problems in your folders structre, maybe you will see them when start write project prototype.

Answer 2

The structure looks good to me, but there are a few points:

• it's normal to separate C++ header and source files into different directories, or maybe there is structure in the modules directory you are not showing?
• you probably want directories to put intermediate files like *.obj in
• you will need different directories for debug and release output files
• a directory for installers like InnoSetup and their install files can be useful - you have to make the philosphical decision about whether to version control these

As for tools to create the structure, a few minutes spent writing a bash script is all you need - it's worth having the same tools (like bash) available on all platforms.

Answer 3

I recently posted a question about packaging headers in just one directory, decided to go with a small number of include directories.

Are you going to cater for Win64? That will be an increasingly important target.

Do not put your build intermediate files anywhere under a tree being checked into svn. If you do so, depending on your svn client tools, they will generate a lot of noise as files which are not in the repository. That makes it hard to see files you've added that should be in the repository.

Instead, if your compiler allows it, put the intermediate directories off to one side.

Otherwise, make sure you add the entire intermediate directories to your svn exclusion properties. Some GUI's make that easier than others (Tortoise on Windows, Cornerstone or Versions on OS/X).