The FLAME libmboard
C Objective-C M4 Shell Makefile C++
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

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

Requirements:

You will need the following:

  • a C compiler, e.g. GCC
  • GNU Make
  • libtool
  • Doxygen (optional, to generate documentation)

To compile the parallel version of the library, you will also need:

To compile the unit tests, you will also need:

Installation:
  1. Configure the source using the ./configure script. This will prepare the source code and check that all pre-requisites are met.

    # ./configure
    

    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".

  2. 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) ++

Requirements:

Apart from the requirements listed above, you will also need:

  • GNU Autoconf (version >= 2.56)
  • GNU Automake (version >= 1.8)
Bootstrapping:

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:

./autogen.sh

Upon successful bootstrapping, proceed by following the installation instructions above.

Creating Distributions:

From the developer's source tree, you can generate a distribution version by running the following command:

./create_distribution.sh