= 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 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 #include 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 ..." 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.