README.md

   1 <!--
   2 SPDX-FileCopyrightText: 2024 EfficiOS, Inc.
   3
   4 SPDX-License-Identifier: MIT
   5 -->
   6
   7 # lttng-ust-mpi
   8
   9 Auto generation of instrumentation library for MPI with LTTng.
  10
  11 # Requirements
  12
  13 - babeltrace (check program)
  14 - clang
  15 - gcc
  16 - lttng-tools (check program)
  17 - lttng-ust (>= 2.13)
  18 - make
  19 - openmpi or craympi
  20 - openssh or srun (check program)
  21 - pkg-config
  22 - python-clang
  23
  24 # Build
  25
  26 Call `make` and that is it.  You can pass `MPI_HEADER=path-to-mpi.h`.  This will
  27 bypass the pkg-config finding of mpi.h.  You can also pass
  28 `PROVIDER=my_provider` if you want to change the default provider name (mpi).
  29
  30 The resulting `lttng-ust-mpi.so` can be used to instrument OpenMPI or CrayMPI
  31 with LTTng.  See the `check` script for usage example.
  32
  33 # Usage
  34
  35 For programs that have a direct dependency on `libmpi.so` (e.g. they are listed
  36 as NEEDED in the dynamic section of an ELF binary), the following can be used
  37 to activate tracing:
  38
  39 ```
  40 LD_PRELOAD=liblttng-ust-mpi.so ./program
  41 ```
  42
  43 However, if the the program in question loads `libmpi.so` dynamically during
  44 execution a work around is required to ensure the library is already. The
  45 following command can be used as a work-around until a more robust solution
  46 is put in place:
  47
  48 ```
  49 LD_PRELOAD=liblttng-ust-mpi.so:libmpi.so ./program
  50 ```
  51
  52 # Set of ignored functions
  53
  54 The only function ignored is `MPI_Pcontrol`.  One can extend the `forbiden_list`
  55 in `lttng-auto-mpi-wrappers` to ignore more functions.
  56
  57 # Development
  58
  59 If using the `guix` package manager, simply do `./dev-env`.