Directory Structure


Libraries should have the following directory structure.

<libraryname>
  build/ // if your using bjam
    Jamroot.jam // if using bjam build
  CMake // if you're using CMake
    CMakeList.txt
    CTestConfig.cmake
  include/
    boost/  // you could use your own name here
      <library_name>
        ...
  src/ // not required for header only libraries
    cpp files ...
    Jamfile.jam
    // other build systems - optional
    vcide
    ...
  example/
    cpp and hpp files
    Jamfile.jam
    // other build systems - optional
    vcide
    ...
  test/
    cpp and hpp files
    Jamfile.jam
    // other build systems - optional
      vcide
      ...
  doc/
    html/
      boostbook.css
      html files ....
      images/
        png files ...
    // document source files - maybe one of those below
    docbook/  // optional
      xml files ...
      // scripts which create html
      makehtml.bat
      makehtml.sh 
    boostbook/ // optional
      xml files ...
      // scripts which create html
      makehtml.bat
      makehtml.sh 
    quickbook/ // optional
      qbk files ...
      // scripts which create html
      makehtml.bat
      makehtml.sh 

This is identical to the recently updated Boost directory structure requirements. It's designed so that the library is contained in one directory structure and need not occupy a specific place within any higher level structure.

  • The library directory and files can be placed anywhere in the users file hierarchy.

  • There is no requirement to alter the users Boost directory. The library can be used just by making sure the include directory is available during the compilations of source files which use it.

  • If the library user prefers to have all his "boost like" libraries in the boost header space, he can make a link or forwarding header in his boost directory tree to accomplish this.

  • The library may include files named Jamroot.jam to support the Bjam build system.

  • The library may include files named CMakeLists.txt to support the CMake build system

  • Other build system support is optional. If supplied it should be either as one file (example: bjam) or as a subdirectory with multiple files.

Note that there is no reason that support for more than one build system cannot be included.

There are 3 comments and replies

Comment on This Page

  • dvicino says:

    In the directory structure, the Jamroot.jam is shown to be inside the build folder.
    I’m a newbie in boost.build, but if I understood right, that file needs to be in the root folder to be read when recursing back the directory structure to prevent the following error: “Did not find Jamfile.jam or Jamroot.jam in any parent directory.”

    • Robert Ramey says:

      The “boost way” is to specify libs/ /build/Jamfile.v2

      This works when one is building all of boost while starting at the top of the boost directory structure. It also works when building/testing one particular library from within the library directory itself. It’s very clever this way. In fact, it is the very cleverness which makes it so confusing. For more information on this subject see Simple Tools/Bjam. There are some links there to more information regarding Bjam. I especially recommend the links to “high score”. Note that I’ve been working with Boost Build for over 10 years and I don’t feel that I understand it.

      • dvicino says:

        I checked that documentation and it says that Jam will recurse directories up until find the Jamroot.
        I checked other projects in the Incubator using bjam for building (Application and Compute) and they both include the Jamroot file in the repository root in place of the build directory.
        I saw others use Jamfile.v2 in place Jamfile.jam and Jamroot as suggested in this page.