6.0 (revision 14673)
Score-P User Library Wrapping


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

Initializes the working directory for creating a user library wrapper, named wrappername, into workspacedir. The final wrapper will be installed into directory. language has to be either c or c++ plus optionally a standard, e.g., c++11. The default workspace is the current directory.



User library wrapping enables users to install library wrappers for any C or C++ library they want.

Without this mechanism, in order to intercept calls to a library, users need to either build this library with Score-P or add manual instrumentation to the application using the library. Another advantage of user library wrapping is you don't need access to the source code of the to-be-wrapped library. Headers and library files suffice.

This feature requires Score-P to be configured with libclang. You can find out whether user library wrapping is enabled in the configure summary or via scorep-info config-summary in Section "Score-P (libwrap)".

There exist two ways to wrap calls to the to-be-wrapped (or target-) library. The main difference lies in when the actual wrapping takes place - at linktime or runtime. While they are in essence the same, they differ in which function calls can be intercepted. Specifically:

You can choose linktime or runtime wrapping manually via the --libwrap flag by prefixing the wrapper name with either linktime: or runtime:.

When creating a wrapper, the build infrastructure automatically builds all wrapper libraries supported by your Score-P installation. If the target library only provides a static library, the runtime wrapper and the shared wrapper library of the linktime wrapper will not work. In this case you should reinitialize the workspace by appending --update --static-only-target-library to your scorep-libwrap-init command line.

Workflow for wrapping a library

Step 1: Initialize the working directory

To initialize the working directory for a new library wrapper use the scorep-libwrap-init command. scorep-libwrap-init has a number of obligatory and optional arguments. You need to supply:

Optional arguments:


$ scorep-libwrap-init --name=mylib --display-name="My Lib" -x c \
    --cppflags="-DSOME_DEFINE -I/opt/mylib/include -I/opt/somelib/include" \
    --ldflags="-L/opt/mylib/lib -L/opt/somelib/lib" \
    --libs="-lmylib -lsomelib -lz -lm" \

This step tries to find shared library files matching the supplied --libs-flags. During application runtime, these will be used for calling dlopen and opening the target library and depending libraries. If scorep-libwrap-init cannot find them, it will provide a warning. You can add these shared libraries manually to Makefile via the LW_LIBLIST variable. If you do not intend to use runtime wrapping, and only use linktime wrapping, you can ignore this warning. It is only needed for runtime wrapping via dlopen.

On completion, scorep-libwrap-init prints a short-form of how to build and use the wrapper library to the terminal.

scorep-libwrap-init creates a number of files in the working directory:

Step 2: Add library headers

The next step is to add #include-statements to libwrap.h. The included files should be headers that applications using the target library usually include.

Step 3: Create a simple example application

After this, add some basic calls to the target library to main.c. This file will later be compiled, linked and executed to test whether the target library and wrapper work correctly.

Step 4: Further configure the build parameters

There are a number of variables at the top of Makefile that can be adjusted:

There are more variables that hopefully need no manual adjustment.

Step 5: Build the wrapper


$ make

Possible errors:

Possible warnings:

This step creates a number of files:

If you change libwrap.h, main.c, Makefile or *.filter repeat this step. I.e., execute make again. Usually the wrapper creation workflow requires to run make, make check and after adjusting the wrapper settings to account for errors and warnings you again run make and make check. It can also take more iterations.

Step 6: Verify the wrapper


$ make check

For each function found in the header files this step first checks whether there is a corresponding symbol in the library files. Second, it checks whether this symbol is also present when linking without the target library, i.e., is present in the executable or system libraries itself.

A list of functions that have no corresponding symbol in the target library is provided in the filter file missing.filter. If there are symbols in it you want to wrap, reconsider your wrapper settings, if not add these symbols to the filter file for this wrapper.

If there are symbols that are also present when linking without the target library, the file uncertain.filter, containing these symbols, is created. Calls to these functions might not be intercepted. It is up to you to decide whether this behavior is OK or not. You can, but don't have add some or all of these symbols to the filter file for this wrapper.

As mentioned in the last paragraph of the previous section, repeat make and make check if you adjust your wrapper.

Step 7: Install the wrapper

Once the wrapper builds without errors, you are ready to install it. Run

$ make install

This step installs the wrapper into the Score-P installation or the directory specified via --prefix, and prints a short description of how to use the wrapper.

Step 8: Verify the installed wrapper


$ make installcheck

Links main.c in up to four different ways using Score-P and the --libwrap-flag. There are now a number of files beginning with main_. Execute them to make sure they are working. Executing these applications will create Score-P experiment directories with measurements of main.c and the wrapped target library. Inspect the experiments to make sure the wrapper works as expected.

Step 9: Use the wrapper

If you installed the wrapper to somewhere other than the Score-P installation via the --prefix-flag, add the appropriate prefix to SCOREP_LIBWRAP_PATH.


You can then use Score-P to link your application in the usual way and additionally provide --libwrap=<wrappername> to enable library wrapping for the target library. Note, library wrapping happens at link time. Thus, you can apply the --libwrap flag only to the link command of the application. No need to re-compile the whole application, if this was necessary in the first place.

Example with only relinking the application:

$ scorep --libwrap=mylib,myotherlib gcc -o main main.o \
    -L/opt/mylib/lib -L/opt/myotherlib/lib -L/opt/somelib/lib \
    -lmylib -myotherlib -lsomelib -lz -lm

Example with both recompiling and linking the application:

$ scorep --libwrap=mylib,myotherlib --nocompiler gcc -o main \
    -DSOME_DEFINE -I/opt/mylib/include -I/opt/myotherlib/include
    -I/opt/somelib/include main.c \
    -L/opt/mylib/lib -L/opt/myotherlib/lib -L/opt/somelib/lib \
    -lmylib -myotherlib -lsomelib -lz -lm

You can manually choose between linktime and runtime wrapping by prepending linktime: or runtime: to the wrapper name provided to --libwrap.

In order to use multiple wrappers for one application you can use --libwrap=<wrap-mode>:lib1,lib2,.... In order to mix linktime and runtime wrapping, you add two --libwrap-arguments, one with each mode.

To find out which user library wrappers are installed call

$ scorep-info libwrap-summary

It lists all found wrappers, either installed into Score-P's installation directory or found via the SCOREP_LIBWRAP_PATH environment variable. Optionally you can run

$ scorep-info libwrap-summary <wrappername>

to show the configuration of a specific wrapper.

Workflow in short

$ scorep-libwrap-init --name=<name> -x c --cppflags="<>" --ldflags="<>" \
      --libs="<>" <workingdir>
$ cd <workingdir>
# Add headers to libwrap.h
# Add example to main.c
$ make
$ make check
# Remove errors by adjusting the wrapper settings and adding symbols to
# filter
# Repeat make && make check until all errors are solved
$ make install
$ make installcheck
$ scorep --libwrap=<name> gcc -o myprogram ...
$ ./myprogram
# Inspect the experiment directory scorep-*

Implementation details

Score-P user library wrapping enables users to intercept and analyse any C or C++ library. For this we rely on libclang to produce a list of functions from the header files of the target library. The wrapper itself relies on symbol-based wrapping supplied by the linker and dynamic linker.

Many C++-libraries rely heavily on inlining and templates. Wrapping libraries based on symbols being present in the target library means that this technique is unable to intercept any inlined function calls.

libclang's ability to detect to-be-inlined functions in header files improved with LLVM 3.9. For LLVM versions <= 3.8 the library wrapper generator will likely generate function wrappers for functions that are inlined and cannot be wrapped. The workflow will provide you with a warning and what to do in this case.

In contrast to wrappers integrated into Score-P, e.g., PThreads, MPI, and OpenCL, user library wrappers do not extract semantic information from the library. It only intercepts function calls and provides their timing information.


$ make show-summary

This command displays how the wrapper is currently configured. Use this information to, e.g., redo the wrapper, or update the wrapper files via --update if, e.g., there is new Score-P version.