tools/perf/Documentation/Build.txt

   1
   2 1) perf build
   3 =============
   4 The perf build process consists of several separated building blocks,
   5 which are linked together to form the perf binary:
   6   - libperf library (static)
   7   - perf builtin commands
   8   - traceevent library (static)
   9   - GTK ui library
  10
  11 Several makefiles govern the perf build:
  12
  13   - Makefile
  14     top level Makefile working as a wrapper that calls the main
  15     Makefile.perf with a -j option to do parallel builds.
  16
  17   - Makefile.perf
  18     main makefile that triggers build of all perf objects including
  19     installation and documentation processing.
  20
  21   - tools/build/Makefile.build
  22     main makefile of the build framework
  23
  24   - tools/build/Build.include
  25     build framework generic definitions
  26
  27   - Build makefiles
  28     makefiles that defines build objects
  29
  30 Please refer to tools/build/Documentation/Build.txt for more
  31 information about build framework.
  32
  33
  34 2) perf build
  35 =============
  36 The Makefile.perf triggers the build framework for build objects:
  37    perf, libperf, gtk
  38
  39 resulting in following objects:
  40   $ ls  *-in.o
  41   gtk-in.o  libperf-in.o  perf-in.o
  42
  43 Those objects are then used in final linking:
  44   libperf-gtk.so <- gtk-in.o  libperf-in.o
  45   perf           <- perf-in.o libperf-in.o
  46
  47
  48 NOTE this description is omitting other libraries involved, only
  49      focusing on build framework outcomes
  50
  51 3) Build with ASan or UBSan
  52 ==========================
  53   $ cd tools/perf
  54   $ make DESTDIR=/usr
  55   $ make DESTDIR=/usr install
  56
  57 AddressSanitizer (or ASan) is a GCC feature that detects memory corruption bugs
  58 such as buffer overflows and memory leaks.
  59
  60   $ cd tools/perf
  61   $ make DEBUG=1 EXTRA_CFLAGS='-fno-omit-frame-pointer -fsanitize=address'
  62   $ ASAN_OPTIONS=log_path=asan.log ./perf record -a
  63
  64 ASan outputs all detected issues into a log file named 'asan.log.<pid>'.
  65
  66 UndefinedBehaviorSanitizer (or UBSan) is a fast undefined behavior detector
  67 supported by GCC. UBSan detects undefined behaviors of programs at runtime.
  68
  69   $ cd tools/perf
  70   $ make DEBUG=1 EXTRA_CFLAGS='-fno-omit-frame-pointer -fsanitize=undefined'
  71   $ UBSAN_OPTIONS=print_stacktrace=1 ./perf record -a
  72
  73 If UBSan detects any problem at runtime, it outputs a “runtime error:” message.
  74
  75 4) Cross compilation
  76 ====================
  77 As Multiarch is commonly supported in Linux distributions, we can install
  78 libraries for multiple architectures on the same system and then cross-compile
  79 Linux perf. For example, Aarch64 libraries and toolchains can be installed on
  80 an x86_64 machine, allowing us to compile perf for an Aarch64 target.
  81
  82 Below is the command for building the perf with dynamic linking.
  83
  84   $ cd /path/to/Linux
  85   $ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -C tools/perf
  86
  87 For static linking, the option `LDFLAGS="-static"` is required.
  88
  89   $ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- \
  90     LDFLAGS="-static" -C tools/perf
  91
  92 In the embedded system world, a use case is to explicitly specify the package
  93 configuration paths for cross building:
  94
  95   $ PKG_CONFIG_SYSROOT_DIR="/path/to/cross/build/sysroot" \
  96     PKG_CONFIG_LIBDIR="/usr/lib/:/usr/local/lib" \
  97     make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- -C tools/perf
  98
  99 In this case, the variable PKG_CONFIG_SYSROOT_DIR can be used alongside the
 100 variable PKG_CONFIG_LIBDIR or PKG_CONFIG_PATH to prepend the sysroot path to
 101 the library paths for cross compilation.