OMPi @ ppg — basic installation & usage

Here you can find short installation and usage guides, as well as some documents about OMPi internals. More documentation is provided within the source distribution, found in our download page.

Prerequisites

The basic requirements for building and installing OMPi on your system are:

  1. The meson build system (version 0.58.0 or later required)
  2. A C compiler (e.g. gcc)

Quick Installation Guide

  1. Extract the package 
      tar xvf ompi-X.Y.Z.tar.xz
  2. Prepare for building and installing (see below for advanced configuration options) 
      meson setup build --prefix=‹install-dir›

    This will create a directory named build where OMPi will be built; install-dir is the directory OMPi will be installed at. If omitted, /usr/local/ will be used by default.

    More configuration options

    If you want to enable debugging, give the -Denable-debug=true option to meson setup (turned off by default).

    The compiler flags used to build the compiler & the libraries are just -O2. In case you want to use different/additional ones, edit the top-level meson.build file and put your flags in the standard_cflags array.

    The default compiler is determined by meson itself. If you want to use a different compiler you need to set the CC environment variable before executing the meson setup command

    Advanced configuration: portable OMPi

    You can have a portable build of OMPi in linux as follows:

      meson setup build -Dportable=true --prefix=‹install-dir› ...

    You can then build and install OMPi as normal, but now you can move the install_dir contents anywhere you like; you can execute ompicc within the new directory, or by giving the full path as in:

      /new/path/bin/ompicc myfile.c

    Everything will work as normal, even if it has been moved away from the initial install-dir.

    Advanced configuration: thread libraries

    OMPi comes with multiple thread libraries, and can support even more (see the bundled doc/runtime.txt); “pthreads”, based on POSIX threads, is the default one. You can choose which one OMPi will be built with as follows:

      meson setup build -Dortlib=‹name› ...

    where ‹name› is any of the included libraries, or any other library you have developed.

    Advanced configuration: devices/modules

    OMPi can support multiple OpenMP devices through device modules; by default, at configuration time it checks and builds all device modules that may be supported. You can choose which ones OMPi should be built with as follows:

      meson setup build -Dmodules="‹name› ‹name› ..." ...

    i.e. space-seperated module names, where each ‹name› is any of the modules OMPi ships with, or any other module you may have developed.

  3. Compile and install the package 
      cd build/
  meson compile
  meson install
  4. Make sure ‹install-dir›/bin is in your PATH

Quick Usage Guide

Usage: ompicc [options] files.c

Example:

  ompicc -o executable file1.c file2.c

Basic options:

  • all (g)cc flags
  • -k : the generated (transformed) file is kept after compilation
  • -K : all intermediate generated files are kept after compilation
  • -v : be verbose (shows all steps of the translation process)
  • --options : show all available options (see below for some of them)
Some handy options
  • --info envs 
    • show all OpenMP and extra OMPi environmental variables names
  • --info clause <name>

    • show all OpenMP directives that accept <name> as a clause
  • --taskopt=<type>

    • select tasking optimization type among size, speed, speed+ (speed is the default)
  • --nolineno 
    • useful when debugging compiler errors; as a source-to-source compiler, OMPi may not always produce very accurate position information for problematic transformed code. This option makes OMPi produce exact source line information but requires all the intermediate files to be kept (with the -K option).
Device options

Following OpenMP 4.0, OMPi supports attached devices that can execute offloaded code. Automatically configured devices are shown with the ompiconf utility, as follows:

  • ompiconf --devinfo[=devs] : show short information about configured devices.
  • ompiconf --devvinfo[=devs] : show longer information about configured devices.

To target specific devices when compiling an application, pass the --devs option to ompicc, as shown below.

  • --devs="‹name› ‹name› ..." : target the given devices
  • --devopt [options] : options for particular devices.
More usage details

OMPi is a source-to-source compiler, so after generating the multithreaded C program, it runs the system compiler — which by default is the one used during OMPi’s installation.

If you want to play with different system compilers, and different compilation flags, you can set three environmental variables to whatever you like: OMPI_CPP, OMPI_CC, OMPI_CPPFLAGS, OMPI_CFLAGS and OMPI_LDFLAGS. The first two specify the system preprocessor and compiler you like to use and the last three ones the particular flags you want. Make sure you set their values before running ompicc.

The --ort=‹libname› option lets you select any runtime library you might have built. For more information on this topic, please refer to the bundled doc/runtime.txt file.

Don’t forget to consult the implementation-specific OpenMP behaviors which are bundled with the OMPi source code package.