Installation

This chapter discusses MSG installation in detail. If you just want to get up and running, have a look at the Quick Start chapter.

Pre-Requisites

To compile and use MSG, you’ll need the following software components:

  • A modern (2008+) Fortran compiler

  • The LAPACK linear algebra library

  • The LAPACK95 Fortran 95 interface to LAPACK

  • The fypp Fortran pre-processor

  • The HDF5 data management library

  • The pkgconf package management tool

On Linux and MacOS platforms, these components are bundled together in the MESA Software Development Kit (SDK). Using this SDK is strongly recommended.

If you’re planning on using the pymsg Python module, then you’ll also need the following components:

Building MSG

Download the MSG source code, and unpack it from the command line using the tar utility:

$ tar xf msg-dev.tar.gz

Set the MSG_DIR environment variable with the path to the newly created source directory; this can be achieved, e.g., using the realpath command[1]:

$ export MSG_DIR=$(realpath msg-dev)

Finally, compile MSG using the make utility:

$ make -j -C $MSG_DIR

(the -j flags tells make to use multiple cores, speeding up the build). If things go awry, consult the Troubleshooting chapter.

Testing MSG

To test MSG, use the command

$ make -C $MSG_DIR test

This runs unit tests for the various Fortran modules that together compose the MSG library. At the end of the test sequence, a summary of the number of tests passed and failed is printed. All tests should pass; if one or more fails, then please open an issue to report the problem.

Installing the pymsg Module

To install the pymsg Python module, use the pip tool:

$ pip install $MSG_DIR/python

You can alternatively add the $MSG_DIR/python/src directory to the PYTHONPATH environment variable. Note that in order for pymsg to function correctly, the MSG_DIR environment variable must be set at Python runtime (this variable allows the module to find the Python extension that interfaces to the back-end).

Custom Builds

Custom builds of MSG can be created by setting certain environment variables to the value yes. The following variables are currently supported:

DEBUG

Enable debugging mode (default no)

SHARED

Enable building of shared libraries (default yes)

FPE

Enable floating point exception checks (default yes)

OMP

Enable OpenMP parallelization (default yes)

PYTHON

Enable building of the Python extension (default yes)

TEST

Enable building of testing tools (default yes)

TOOLS

Enable building of development tools (default yes)

If an environment variable is not set, then its default value is assumed.

GitHub Access

Sometimes, you’ll want to try out new features in MSG that haven’t yet made it into a formal release. In such cases, you can check out MSG directly from the https://github.com/rhdtownsend/msg git repository on GitHub:

$ git clone --recurse-submodules https://github.com/rhdtownsend/msg.git

However, a word of caution: MSG is under constant development, and features in the main branch can change without warning.

footnote