Indicate that lttng-ust 2.13+ is required

[deliverable/lttng-ust-mpi.git] / README.md

<!--
SPDX-FileCopyrightText: 2024 EfficiOS, Inc.

SPDX-License-Identifier: MIT
-->

# lttng-ust-mpi

Auto generation of instrumentation library for MPI with LTTng.

# Requirements

- babeltrace (check program)
- clang
- gcc
- lttng-tools (check program)
- lttng-ust (>= 2.13)
- make
- openmpi or craympi
- openssh or srun (check program)
- pkg-config
- python-clang

# Build

Call `make` and that is it.  You can pass `MPI_HEADER=path-to-mpi.h`.  This will
bypass the pkg-config finding of mpi.h.  You can also pass
`PROVIDER=my_provider` if you want to change the default provider name (mpi).

The resulting `lttng-ust-mpi.so` can be used to instrument OpenMPI or CrayMPI
with LTTng.  See the `check` script for usage example.

# Usage

For programs that have a direct dependency on `libmpi.so` (e.g. they are listed
as NEEDED in the dynamic section of an ELF binary), the following can be used
to activate tracing:

```
LD_PRELOAD=liblttng-ust-mpi.so ./program
```

However, if the the program in question loads `libmpi.so` dynamically during
execution a work around is required to ensure the library is already. The
following command can be used as a work-around until a more robust solution
is put in place:

```
LD_PRELOAD=liblttng-ust-mpi.so:libmpi.so ./program
```

# Set of ignored functions

The only function ignored is `MPI_Pcontrol`.  One can extend the `forbiden_list`
in `lttng-auto-mpi-wrappers` to ignore more functions.

# Development

If using the `guix` package manager, simply do `./dev-env`.