Tool Time Plus: How to Create Wrappers for an External Library for Score-P

In this article, we describe how to create measurement wrappers for an external library for Score-P. We will use the FFTW3 library as an example.

To use library wrapping we need a version of Score-P which has been configured for this. To verify if Score-P has the required feature we need to execute following

% scorep-info config-summary

and search for "libwrap" in the output

    Score-P (libwrap):
    Library wrapper support: no, llvm-config not found

The message above tells us that we do not have the necessary infrastructure to enable library wrapping. To enable it, we need a LLVM compiler infrastructure, i.e. "llvm-config", and "libclang" and its developer packages during configuration. Once these packages are installed and Score-P reconfigured and re-installed we should see following message in "scorep-info config-summary". This means our Score-P version supports library wrapping and we are ready to go.

    Score-P (libwrap):
    Library wrapper support: yes, using llvm-config
    C compiler used: clang
    C++ compiler used: clang++

Now we are ready to create the wrapper like this 

% scorep-libwrap-init --name <wrappername> -x <language> [options]

where we need to specify the wrapper name, the implementation language of the library, and the compiler flags, paths to headers and libraries, and linker flags to build the "hello world" example. If the external library we are interested in has already been used, we should not have problem to complete this task. If the library is touched for the first time, we can look into examples which are usually provided with the library.

For the FFTW example, that meant calling:

% scorep-libwrap-init --name=fftw3 --display-name="FFTW3" -x c \
    --cppflags="-I<path-to-fftw-include-directory>" \
    --ldflags="-L<path-to-fftw-lib-directory>" \
    --libs="-lfftw3"

If this step was successful, Score-P will provide detailed instructions what to do next. We will demonstrate the steps for the FFTW3 example:

  1. Go to ‘build’ directory

  2. Prepare a simple "hello world" example that requires linking the library. We can simply initialize the library or take an example from the examples provided with the library. Here, we reuse the example mentioned in this blog article. Then we need to modify two of the generated files. The first one is ‘main.c’ where we insert our example code. The second one is ‘libwrap.h’ where we insert header files we want to wrap, in this case the public header of FFTW ‘fftw3.h’.  Also, we have to remove the corresponding #include statements from 'main.c'.

    Please note that if the library provides separate C and C++ interfaces, we need to prepare separate sets of files and repeat the procedure for each language.

  3. Compile wrapper with make. It will most probably fail at first 

    % make
    CCLD main
    CPP libwrap.i
    GEN scorep_libwrap_fftw3.c
    QUICK-CHECK
[Score-P] Error: There is mismatch between functions found in the header files
[Score-P]     and the symbols present in the target library.
[Score-P]     Use 'make check' to get a list of missing symbols and add
[Score-P]     them to fftw3.filter. After that repeat this step.
make: *** [quick-check] Error 1

    Check if all functions defined in header exist.

    % make check

    The output will be like this

    . . . .
FOUND fftw_execute
FOUND fftw_plan_dft
FOUND fftw_plan_dft_1d
MISSING fftw_plan_with_nthreads
MISSING fftw_init_threads
. . . .

    This can be a very time consuming procedure depending on a number of functions in the header and available symbols in the library. We can sit back and have a drink or meal. At the end of execution we should see following

    [Score-P] Error: Symbols that are not present in the target library have been
[Score-P]     wrapped. The filter file 'missing.filter' containing these
[Score-P]     symbols has been created. Reconsider your wrapper settings, or
[Score-P]     add these symbols to fftw3.filter if they should not be
[Score-P]     wrapped. Then repeat 'make' and 'make check'.

  4. Follow instructions and add missing symbols from "missing.filter" to "fftw3.filter" and repeat "make" and "make check". Both should not provide errors this time.

    It should be pointed out the prepared set of files (i.e. the "hello world" example, the header, and the filter file with missing symbols) can be re-used for future installations but require wrapper re-generation as the library path and dependencies can be hard-coded. Moreover, if the API of the library changes, we would need to adjust the wrapper.

  5. Install library wrapper with "make install" and "make installcheck"

Congratulations! We have successfully wrapped and installed the FFTW library wrapper. We are ready to use it!

To check whether the installation was successful, we can do the following

% scorep-info libwrap-summary
fftw3
    Display name:
        FFTW3
    Prefix:
        <path_to_the_wrapper>

If we installed the wrapper to somewhere else other than the Score-P installation directory via the --prefix flag, we can add the appropriate prefix to $SCOREP_LIBWRAP_PATH.