Version 11 (modified by Beman Dawes, 6 years ago) (diff)

--

Getting Started with Modular Boost Library Development

This is a work in progress

Prerequisites

Overview

  • Your library has its own public repository that has a "develop" branch for development work, and a "master" branch for your releases, which occur asynchronously from Boost releases. You may also have other branches, but that's up to you.
  • The Boost super project has its own public repository. It treats your library as a sub-module, i.e. a link to a particular release in your library's public GitHub? repository.
  • You (and the rest of your team) do day-to-day development using private repositories on your local machines. You push changes from these local private repos up to your library's public repo whenever you want. The local repos may also have private branches that are never pushed to the public repo.
  • Your library's directory structure conforms to Boost directory structure conventions, so both users and automatic processes can find header files, test files, build configurations, and the like. Beyond the conventions, your library's directory structure is up to you.

Directory Structure

For Modular Boost, header files are placed in a include/boost header hierarchy within your main directory. Here is what a very simple header-only library named simple would look like:

     simple
       include
         boost
           simple
             twice.hpp
       test
         twice_test.cpp
         Jamfile.v2
       index.html   

Creating the simple library

  • With your web browser, sign into your GitHub account and create a repository named simple. Select the option to automatically create a README file. Copy the URL of the newly created repository to your clipboard.
  • The remainder of the steps are run from the command line.
  • cd to the libs sub-directory of the Boost installation root directory, clone the newly created repository, and create the library's directory structure:
    cd boost-root/libs
    git clone git@github.com:Beman/simple.git
    cd simple
    mkdir include
    mkdir test
    cd include
    mkdir boost
    cd boost
    mkdir simple
    cd ../../../../boost
    
  • Create a symlink to simulate your library being installed as part of Boost:
    • Windows: mklink /d simple ..\libs\simple\include\boost\simple
    • POSIX: ln -s ../libs/simple/include/boost/simple simple
  • Using a text editor, create a file named twice.hpp in boost-root/libs/simple/include/boost/simple:
    #include <string>
    namespace boost { namespace simple {
    inline std::string twice(const std::string& s)
    {
      return s + s;
    }
    }}
    
  • cd to boost-root/libs/simple/test. The remaining steps are done in that directory.
  • Create a file named twice_test.cpp using a text editor:
    #include <boost/simple/twice.hpp>
    #include <boost/detail/lightweight_test.hpp>
    
    int main()
    {
      BOOST_TEST(boost::simple::twice("foo") == "foofoo");
      return ::boost::report_errors();
    }
    
  • Create a file named Jamfile.v2 using a text editor. Be careful to leave spaces between syntax elements as they are required:
    test-suite simple :
        [ run twice_test.cpp ]
        ;
    

  • Run the test by invoking b2 with no arguments. The output should look something like this:
    ...found 26 targets...
    ...updating 11 targets...
    common.mkdir ..\..\..\bin.v2\libs\simple
    common.mkdir ..\..\..\bin.v2\libs\simple\test
    common.mkdir ..\..\..\bin.v2\libs\simple\test\twice_test.test
    common.mkdir ..\..\..\bin.v2\libs\simple\test\twice_test.test\msvc-10.0express
    common.mkdir ..\..\..\bin.v2\libs\simple\test\twice_test.test\msvc-10.0express\debug
    common.mkdir ..\..\..\bin.v2\libs\simple\test\twice_test.test\msvc-10.0express\debug\threading-multi
    compile-c-c++ ..\..\..\bin.v2\libs\simple\test\twice_test.test\msvc-10.0express\debug\threading-multi\twice_test.obj
    twice_test.cpp
    msvc.link ..\..\..\bin.v2\libs\simple\test\twice_test.test\msvc-10.0express\debug\threading-multi\twice_test.exe
    msvc.manifest ..\..\..\bin.v2\libs\simple\test\twice_test.test\msvc-10.0express\debug\threading-multi\twice_test.exe
    testing.capture-output ..\..\..\bin.v2\libs\simple\test\twice_test.test\msvc-10.0express\debug\threading-multi\twice_test.run
            1 file(s) copied.
    **passed** ..\..\..\bin.v2\libs\simple\test\twice_test.test\msvc-10.0express\debug\threading-multi\twice_test.test
    ...updated 11 targets...
    

Committing and pushing

OK, the basic structure and files of the library are present, so it is time to commit the changes to the local repo.

Hint: (((git help command-name}}} will launch a browser window with documentation for command-name.

Execute these commands in boost-root/libs/simple (shown with typical output):

>git add .

>git commit -m "Initial commit" --dry-run
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       new file:   include/boost/simple/twice.hpp
#       new file:   test/Jamfile.v2
#       new file:   test/twice_test.cpp
#

>git commit -m "Initial commit"
[master 3a3a654] Initial commit
 3 files changed, 18 insertions(+)
 create mode 100644 include/boost/simple/twice.hpp
 create mode 100644 test/Jamfile.v2
 create mode 100644 test/twice_test.cpp

Since the test passed (as indicated by the **passed** message), we will also push these changes up to the public repository:

>git push
Counting objects: 10, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (9/9), 817 bytes, done.
Total 9 (delta 0), reused 0 (delta 0)
To git@github.com:Beman/simple.git
   9356e19..3a3a654  master -> master

Your output, of course, will show your GitHub account name rather than mine.