Getting Started with Modular Boost Library Development using Git

This page describes the mechanics of creating a new modular Boost library using Git.

The intended audience:

• Developers who want to create a new library to be proposed for eventual inclusion in Boost.
• Developers of existing pre-modular Boost libraries who want to understand the mechanics of modular Boost and Git.

Prerequisites

• An understanding of Boost culture and the Developer's mailing list. Read more.
• An understanding of Boost Library Requirements and Guidelines.
• The Git version control system. Read about Getting Started with Git. If you are new to Git, install it and experiment a bit before coming back here.
• A (free) ​GitHub account. Read about Getting Started with GitHub.
• Your favorite compiler and development environment.
• A recent version of Boost installed. See Boost Getting Started. (Either modular or pre-modular Boost will work.)
• The b2 executable, created in the boost root directory during installation, added to your path.

Overview

Creating the simple library

This procedure will create a trivial library named simple. Its public repository will be hosted in your own ​GitHub account. You will do development using a private repository that is located within a Boost installation on your local machine. This simulates your library being a sub-module of the ​Boost super-project.

• 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 >b2.log. The b2.log file should look something like this, modulo obvious differences for POSIX-like systems:

  ...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...
  

The log file will come in handy if you run into problems and request help. Attaching a log avoids email end-of-line mutilation and overlong message bodies.

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.