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.

Quick Installation Guide

  1. Extract the package 
      gunzip zxvf ompi-X.Y.Z.tar.gz
  2. Configure the package (see below for advanced configuration options) 
      ./configure --prefix=‹install-dir›
    More configuration options

    If you want to enable debugging, give the --enable-debug option to ./configure (turned off by default).

    The compiler flags used to build the compiler & the libraries are just -O3. More often than not you may want to use different ones (such as -g). In such cases use:

      ./configure CFLAGS= CPPFLAGS= ...

    The default compiler is determined by configure itself (and is usually gcc). If you want to use a different compiler (e.g. Intel icc), use:

      ./configure CC=icc ...
    Advanced configuration: portable OMPi

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

      ./configure --enable-portable --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

    The compiler & flags that OMPi will later use for compiling user programs are by default the ones used in ./configure time. If you want different ones, define OMPI_CC, OMPI_CPP, OMPI_CFLAGS and OMPI_CPPFLAGS environmental variables, before running ompicc, as described below.

    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:

      ./configure --with-ortlib=‹name› ...

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

    Advanced configuration: devices/modules

    OMPi can support multiple OpenMP4 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:

      ./configure --with-modules="‹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 
      make
  make install
  4. Make sure ‹install-dir›/bin is in your PATH

For information about the configure script, see INSTALL in the bundled documentation.

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

Since OpenMP 4.0, OMPi supports attached devices that can execute offloaded code. Automatically configured devices are shown with the --dev(v)info flag. To target specific devices, use the --devs option as shown below.

  • --devs="‹name› ‹name› ..." : target the given devices
  • --devinfo : show short information about configured devices.
  • --devvinfo : show longer information about configured 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.