tools/perf/Documentation/Build.txt

1) perf build
=============
The perf build process consists of several separated building blocks,
which are linked together to form the perf binary:
  - libperf library (static)
  - perf builtin commands
  - traceevent library (static)
  - GTK ui library

Several makefiles govern the perf build:

  - Makefile
    top level Makefile working as a wrapper that calls the main
    Makefile.perf with a -j option to do parallel builds.

  - Makefile.perf
    main makefile that triggers build of all perf objects including
    installation and documentation processing.

  - tools/build/Makefile.build
    main makefile of the build framework

  - tools/build/Build.include
    build framework generic definitions

  - Build makefiles
    makefiles that defines build objects

Please refer to tools/build/Documentation/Build.txt for more
information about build framework.


2) perf build
=============
The Makefile.perf triggers the build framework for build objects:
   perf, libperf, gtk

resulting in following objects:
  $ ls  *-in.o
  gtk-in.o  libperf-in.o  perf-in.o

Those objects are then used in final linking:
  libperf-gtk.so <- gtk-in.o  libperf-in.o
  perf           <- perf-in.o libperf-in.o


NOTE this description is omitting other libraries involved, only
     focusing on build framework outcomes

3) Build with ASan or UBSan
==========================
  $ cd tools/perf
  $ make DESTDIR=/usr
  $ make DESTDIR=/usr install

AddressSanitizer (or ASan) is a GCC feature that detects memory corruption bugs
such as buffer overflows and memory leaks.

  $ cd tools/perf
  $ make DEBUG=1 EXTRA_CFLAGS='-fno-omit-frame-pointer -fsanitize=address'
  $ ASAN_OPTIONS=log_path=asan.log ./perf record -a

ASan outputs all detected issues into a log file named 'asan.log.<pid>'.

UndefinedBehaviorSanitizer (or UBSan) is a fast undefined behavior detector
supported by GCC. UBSan detects undefined behaviors of programs at runtime.

  $ cd tools/perf
  $ make DEBUG=1 EXTRA_CFLAGS='-fno-omit-frame-pointer -fsanitize=undefined'
  $ UBSAN_OPTIONS=print_stacktrace=1 ./perf record -a

If UBSan detects any problem at runtime, it outputs a “runtime error:” message.

4) Cross compilation
====================
As Multiarch is commonly supported in Linux distributions, we can install
libraries for multiple architectures on the same system and then cross-compile
Linux perf. For example, Aarch64 libraries and toolchains can be installed on
an x86_64 machine, allowing us to compile perf for an Aarch64 target.

Below is the command for building the perf with dynamic linking.

  $ cd /path/to/Linux
  $ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -C tools/perf

For static linking, the option `LDFLAGS="-static"` is required.

  $ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- \
    LDFLAGS="-static" -C tools/perf

In the embedded system world, a use case is to explicitly specify the package
configuration paths for cross building:

  $ PKG_CONFIG_SYSROOT_DIR="/path/to/cross/build/sysroot" \
    PKG_CONFIG_LIBDIR="/usr/lib/:/usr/local/lib" \
    make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -C tools/perf

In this case, the variable PKG_CONFIG_SYSROOT_DIR can be used alongside the
variable PKG_CONFIG_LIBDIR or PKG_CONFIG_PATH to prepend the sysroot path to
the library paths for cross compilation.

5) Build with Clang
===================
By default, the makefile uses GCC as compiler. With specifying environment
variables HOSTCC, CC and CXX, it allows to build perf with Clang.

Using Clang for a native build:

  $ HOSTCC=clang CC=clang CXX=clang++ make -C tools/perf

Specifying ARCH and CROSS_COMPILE for cross compilation:

  $ HOSTCC=clang CC=clang CXX=clang++ \
    ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- \
    make -C tools/perf