libmboard: the Message Board Library
The Message Board Library is a data management and communication library developed for multi-agent simulations generated using the FLAME framework.
As agents only interact with its environment (and each other) via messages, the Message Board library serves as a means of achieving parallelisation. Agents can be farmed out across multiple processors and simulated concurrently, while a coherent simulation is maintained through a unified view of the distributed Message Boards.
Synchronisation of the message boards are non-blocking as they are performed on a separate communication thread, allowing much of the communication time to be overlapped with computation.
Copyright (c) 2007-2012 STFC Rutherford Appleton Laboratory
If you have any problems or enquiries, you should raise a GitHub issue.
You will need the following:
- a C compiler, e.g. GCC
- GNU Make
If you are building on Linux then you will likely already have those installed.
If you want to build libmboard from a clone of the libmboard Git repository (very likely) then you will also need:
- GNU Autoconf (version >= 2.56)
- GNU Automake (version >= 1.8)
Again, if you are building on Linux then you will likely already have those installed.
To compile the parallel version of the library, you will also need:
To generate the documentation, you will also need:
To compile the unit tests, you will also need:
(Only) if you are trying to build libmboard from a clone of the libmboard Git repository, you first need to run:
Configure the source using the
./configurescript. This will prepare the source code and check that all pre-requisites are met.
Changing installation directory: By default, the library will be configure for installation within your system (typically in
/usr/localfor Linux systems). This will allow users to link to the library without having to specify the library location. This however would require you to have administrator privileges (root).
If you wish to change the installation destination (this may be necessary if you do not have root access, of if you wish to maintain multiple versions of the library), you can use the
--prefixoption to specify an alternative installation location.
$ ./configure --prefix=/home/lsc/build/libmboard
Disabling some components: You can disable the inclusion of unit tests (if you do not have CUnit) by appending
--disable-teststo the list of arguments to
You can also disable the compilation of parallel libraries (if you do not have pthreads and MPI support) by appending the
More options: For more configuration options, run
$ ./configure --help
Once the configuration is successful, you can compile and install the library.
$ make $ make install
For more details on installation, see the INSTALL file.
Using the library
For information on how to use the library, view the User Manual. The manual can be generated by running:
$ make doc
You can then view the user documentation using:
$ firefox doc/user/html/index.html
And view the developer documentation using:
$ firefox doc/develop/serial/html/index.html
$ firefox doc/develop/parallel/html/index.html
You can also browse the User Manual online although note that this may not correspond exactly to the version of libmboard you have installed.
Running unit tests
Compile the tests using
$ make test
Four tests binaries will be produced, each testing different aspects of the library.
./tests/run_test_utils: Test utility code used by both serial and parallel modules
./tests/run_test_serial: Test serial libmboard API
./tests/run_test_parallel_utils: Test utility code used only by the parallel modules
./tests/run_test_parallel: Test parallel libmboard API
You will need to run the parallel tests using your standard MPI job launcher (e.g.
Performing Test Coverage analysis
Configure the package using
--enable-coverage, and compile the code using
$ ./configure --enable-coverage $ make coverage
If the code compiles and the tests run successfully,
the coverage report will be available in the
index.html file in your favourite browser to view the report e.g.
$ firefox ./coverage_html/index.html
When done, you can clean up your source directives by running
$ make vclean
From a developer's source tree, you can generate a distribution version by running: