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 github issue.
Installing from a distribution file
You will need the following:
- a C compiler, e.g. GCC
- GNU Make
- Doxygen (optional, to generate documentation)
- available from http://www.doxygen.org
To compile the parallel version of the library, you will also need:
- An MPI Library, e.g. MPICH
- available from http://www.mcs.anl.gov/research/projects/mpich2/
- Support for pthreads
To compile the unit tests, you will also need:
- available from http://cunit.sourceforge.net/
Configure the source using the ./configure script. 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/local for 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 --prefix option 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) installed by including the --disable-tests option.
You can also disable the compilation of parallel librarys (if you do not have pthreads and MPI support) by using the --disable-paralle option.
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 also browse the User Manual online at: http://www.softeng.cse.clrc.ac.uk/libmboard/
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.
Performing Test Coverage analysis
Configure the package using --enable-coverage, and compile the code using the "coverage" target
# ./configure --enable-coverage # make coverage
If the code compiles and the tests run successfully, the coverage report will be available in the ./coverage_html directory. Load the index.html file in your favourite browser to view the report. Example:
# firefox ./coverage_html/index.html
When done, you can clean up your source directives by running "make vclean".
=============================================================================== ++ Installing from Git (developer's version) ++
Apart from the requirements listed above, you will also need:
- GNU Autoconf (version >= 2.56)
- GNU Automake (version >= 1.8)
Before you can configure and install the project, you will first need to process the pristine source through GNU Autotools. This can be done by running the following command:
Upon successful bootstrapping, proceed by following the installation instructions above.
From the developer's source tree, you can generate a distribution version by running the following command: