= Getting Started with Modular Boost Library Development using Git =
[[PageOutline]]

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. [http://www.boost.org/community/ Read more.]
 * An understanding of [http://www.boost.org/development/requirements.html Boost Library Requirements and Guidelines].
 * The Git version control system. [wiki:Git/GitHome Read about Getting Started with Git.] If you are new to Git, install it and experiment a bit before coming back here.
 * A (free) [http://www.github.com GitHub] account. [wiki:StartGitHub Read about Getting Started with GitHub.]
 * Your favorite compiler and development environment.
 * A recent version of Boost installed. See [http://www.boost.org/more/getting_started/index.html 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 [http://github.com 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 [https://github.com/boostorg/boost Boost super-project]. 

 * With your web browser, sign into your [https://github.com 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.