Building rdmini
Code organisation
The top-level directories in the rdmini
project are organised as follows:
build/
- Out-of-source build directory, with Makefile.
demo/
- Source for demonstration and informal test code.
doc/
- Documentation source, primarily in Pandoc-flavoured Markdown.
gtest-1.7.0/
- Google test sources.
src/
- Source and internal headers for
rdmini
core functionality. include/rdmini/
- Public headers for
rdmini
. scripts/
- Miscellaneous scripts used in the build process or for parsing results.
test/
- Source for unit tests.
yaml-0.1.6/
- Subset of libyaml sources.
Building the executables
The standard procedure for building the demo and test executables is:
cd build;
make
Tests can be run with make test
, which will also write the test results in xUnit XML format to the subdirectory test-xml
.
The rdmini
source is written in C++11, and thus requires a C++11 capable compiler. Everything should build ‘out of the box’ with gcc version 5 or later.
The C and C++ compilers used in the Makefile are the default from the environment, and can be specified via the CC
and CXX
environment variables, or overriden on the make
command-line. The corresponding compiler options though are not automatically deduced, and must be specified explicitly by setting the variable COMPILER
in the Makefile directly, or via the make
command-line. Options are included in the Makefile for the cases when COMPILER
is gnu
, clang
, pgi
or cray
.
Inter-source dependencies are determined automatically with gcc
and clang
, but for pgi
and cray
these must be built explicitly with make depend
.
Building the documentation
The documentation tree is built with make doc
, which will compile the markdown documentation into an HTML hierarchy under www/
in the build directory.
This build process uses Hakyll and Pandoc. Hakyll is a Haskell-based library for the compilation and deployment of HTML sites; building the documentation requires first the compilation of the site builder program in doc/src/site.hs
, and then running it to produce the final HTML.
Building the documentaion thus requires a Haskell compiler and the Hakyll package and its dependencies. The current site.hs
has been verified to build with GHC 7.6.3 and Hakyll version 4.7.5.1. Installation of Hakyll is probably best performed using Haskell Cabal.
Publishing the documentation
The online documentation consists of the contents of the gh-pages
branch of the BlueBrain repository.
The gh-pages
make target builds the documentation and then uses the included commit-dir
script to commit the compiled documentation tree into a local gh-pages
branch. The script constructs the commit as a merge commit between the previous state of the gh-pages
branch, and the latest commit on the current branch.
Updating the online documentation to match the latest commit on master then consists of:
Ensure that the local repository master and gh-pages branches match those of
bluebrain/rdmini
.Build and update the gh-pages branch locally with
make gh-pages
.Either push the updated gh-pages branch back to
bluebrain/rdmini
, or push the branch to one’s GitHub repository and submit a pull request.
Cleanup
Intermediate object files and temporary files will be removed with make clean
.
All executables, libraries, dependency files and generated documentation will be removed with make realclean
.