wiki:BestPracticeHandbook

Version 2 (modified by Niall Douglas, 7 years ago) ( diff )

--

Links To Examples Of Best Practice For C++ 11/14 Boost Libraries

originally written by ​Niall Douglas May 2015

As part of preparing my ​C++ Now 2015 presentation "​A review of C++ 11/14 only Boost libraries" I examined ten C++ 11/14 mandatory libraries heading towards Boost. This wiki provides a shortlist of suggested best practices which Boost library authors may find useful when developing their own Boost libraries. To a large extent, this shortlist is mainly about achieving best practice in C++ 11/14 libraries of any kind and should be useful to anyone so interested.

  1. Links To Examples Of Best Practice For C++ 11/14 Boost Libraries
    1. 1. Strongly consider using git and ​GitHub to …
    2. 2. Consider making it possible to use Boost.Test for the unit testing, …

1. Strongly consider using git and ​GitHub to host a copy of your library and its documentation

All the Boost libraries are on github, and all the free tooling exampled below integrates easily with github. Choosing github makes your life much easier. Note that as git is a distributed source code control system, you can keep a canonical master copy anywhere and write a script which autorefreshes the github copy, thus triggering any of the free tooling you have integrated there.

Github also provides free website hosting for HTML. Have a script automatically generate documentation and commit it to the gh-pages branch in your normal repo. This should present a copy of your HTML at ​http://''username''.github.io/''repository.

This is the script which generates the documentation for ​proposed Boost.AFIO, and indeed you can see the exact output generated by this script at ​http://boostgsoc13.github.io/boost.afio/. You may find it useful. 

cd boost-local
rm -rf libs/afio/doc/doxy/doxygen_output/html
mkdir -p libs/afio/doc/doxy/doxygen_output/html
cd doc
../b2 -a ../libs/afio/doc
cd ../..
if [ ! -e publish ]; then
git clone -b gh-pages git@github.com:BoostGSoC13/boost.afio.git publish
fi
cd publish
git reset --hard b1414e11be50ff81124e2e1583f1bbb734ad9ead
cd ..
rm -rf publish/*
mkdir -p publish/doc/html
cp -a boost-local/doc/html/afio* publish/doc/html/
cp -a doc/src publish/doc/
cp -a doc/src/images/boost.png publish/
cp -af boost-local/doc/src publish/doc/
mkdir -p publish/libs/afio/doc
cp -a doc/* publish/libs/afio/doc/
cd boost-local/libs/afio/doc/doxy
doxygen
cd ../../../../../publish
cp -a ../boost-local/libs/afio/doc/doxy/doxygen_output/html .
cp -a ../Readme.md .
cp -a ../Readme.md Readme.html
echo '<html><head><title>Boost.AFIO documentation</title><meta http-equiv="refresh" content="300"/><body>
<h1>Boost.AFIO documentation</h1>
<p><a href="doc/html/afio.html">BoostBook format documentation</a></p>
<p><a href="html/index.html">Doxygen format documentation</a></p>
<p><a href="afio-stable.tar.bz2">Ready to go stable AFIO distribution with all git submodules (from master branch)</a></p>
<p></p>' > index.html
cat Readme.md | tail -n +4 >> index.html
echo '
</body></html>' >> index.html
git add .
git commit -a -m 'SHA stamp by Jenkins as building correctly' || true
git push -f

Some may wonder what the hard git reset to a SHA is for. This prevents the gh-pages branch continuously growing in storage by breaking history for the branch, and therefore making git clone times grow excessively. As the branch is purely for HTML publishing, breaking history like this is safe.

Other examples of libraries which use github for their documentation:

2. Consider making it possible to use Boost.Test for the unit testing, even if not enabled by default

A very noticeable trend in C++ 11/14 mandatory Boost libraries is that less than half are able to use Boost.Test, and use alternative unit testing systems.

There are many very good reasons not to use Boost.Test, but there are few good reasons to not be able to use Boost.Test at all.

TODO IN PROGRESS

Note: See TracWiki for help on using the wiki.