Usage

scorep-wrapper --create COMPILER [BINDIR]
scorep-<compiler> [COMPILER_FLAGS...]

Description

The scorep-wrapper script instances (like scorep-gcc, see below for a list of provided instances) are intended to simplify configuration and instrumentation of applications where the usual means of instrumentation, i.e., prefixing the compilation command with scorep, does not work out of the box. This applies, e.g., to applications that use autotools or CMake.

The intended usage of the wrapper instances is to replace the application's compiler and linker with the corresponding wrapper at configuration time so that they will be used at build time. As compiler and linker commands are usually assigned to build variables like CC, CXX, or F77 (e.g., CC=gcc), using the corresponding wrapper is as simple as prefixing the value with scorep- (e.g., CC=scorep-gcc).

E.g., say the original compile command is

$ gcc COMPILER_FLAGS...

Using the wrapper instead

$ scorep-gcc COMPILER_FLAGS...

will expand to the following call:

$ scorep $SCOREP_WRAPPER_INSTRUMENTER_FLAGS \
    gcc $SCOREP_WRAPPER_COMPILER_FLAGS \
    COMPILER_FLAGS...

Used at build time, this expansion performs the desired Score-P instrumentation.

The variables SCOREP_WRAPPER_INSTRUMENTER_FLAGS and SCOREP_WRAPPER_COMPILER_FLAGS can be used to pass extra arguments to scorep and to the compiler, respectively. Please see the Examples section below for details.

If the application's build system includes a configuration step (like it is the case for autotools and CMake based projects) the expansion needs to be prevented at this stage (the configuration step compiles and runs lots of small test programs; instrumenting these would in almost all cases result in failure of the configuration). To do so, one needs to set the variable SCOREP_WRAPPER to off when invoking the configuration command. The wrapper command from above will then expand to the original compile command:

$ gcc COMPILER_FLAGS...

Wrapper Instances

The installation provides wrapper instances based on the compilers used to build Score-P. Run scorep-wrapper --help to see a listing of all default instances of the used Score-P installation.

Additional wrapper instances can be created with scorep-wrapper --create.

Examples

The most prominent use case is the CMake build system. As CMake prohibits to change the compiler after the CMake step and it also prohibits that the compiler variable value includes any flags (which renders the usual prefixing scorep gcc to a non-functional value). One needs to use a wrapper script which introduces the Score-P instrumenter as a compiler replacement to CMake as early as possible so that they are hard-coded into the generated build files. Apart from that one needs to make sure that the wrappers don't perform their usual instrumentation at this early stage or else the configuration step is likely to fail. However, at make time we want the wrappers to do the actual instrumentation. These goals can be achieved by invoking cmake like follows:
```
$ SCOREP_WRAPPER=off cmake .. \
    -DCMAKE_C_COMPILER=scorep-gcc \
    -DCMAKE_CXX_COMPILER=scorep-g++
```
The SCOREP_WRAPPER=off disables the instrumentation only in the environment of the cmake command. Subsequent calls to make are not affected and will instrument the application as expected.

Please note, that CMake 3.18.0 and 3.18.1 broke this workflow. But it was reinstated with 3.18.2.

For autotools based build systems it is recommended to configure in the following way:

$ SCOREP_WRAPPER=off ../configure \
    CC=scorep-gcc \
    CXX=scorep-g++ \
    --disable-dependency-tracking

Both autoconf and CMake based build systems, may automatically re-configure the build tree when calling make, because some build related files have changed (i.e., Makefile.am or CMakeLists.txt files). This usage is not supported by the Score-P wrapper. Please re-start the configuration from an empty build directory again as described above.
To pass options to the scorep command in order to diverge from the default instrumentation or to activate verbose output, use the variable SCOREP_WRAPPER_INSTRUMENTER_FLAGS at make time:
```
$ make SCOREP_WRAPPER_INSTRUMENTER_FLAGS=--verbose
```
This will result in the execution of:
```
$ scorep --verbose gcc ...
```
The wrapper also allows to pass flags to the wrapped compiler call by using the variable SCOREP_WRAPPER_COMPILER_FLAGS:
```
$ make SCOREP_WRAPPER_COMPILER_FLAGS="-D_GNU_SOURCE"
```
Will result in the execution of:
```
$ scorep gcc -D_GNU_SOURCE ...
```
If there is a need to create additional wrapper instances, e.g., if your build system already uses compiler wrappers, you can do so by calling the scorep-wrapper script with the --create option:
```
$ scorep-wrapper --create cc
```
This will create a new wrapper instance for the cc compiler named scorep-cc in the same directory where scorep-wrapper resides.