README

   1 systemtap: a linux trace/probe tool
   2
   3 Visit the project web site at <http://sources.redhat.com/systemtap>,
   4 for documentation and mailing lists for developers and users.
   5
   6 This is free software.
   7 See the COPYING file for redistribution/modification terms.
   8 See the INSTALL file for generic build instructions.
   9
  10 Prerequisites:
  11
  12 - linux kernel with kprobes (mainline 2.6.11+ or backport)
  13 - kernel module build environment (kernel-devel rpm)
  14 - kernel debugging information (kernel-debuginfo rpm)
  15 - C compiler (same as what kernel was compiled with)
  16 - elfutils with libdwfl for debugging information parsing
  17 - root privileges
  18
  19 Installation steps:
  20
  21 - Install the kernel development and gcc packages.
  22 - Install any debuginfo packages you need, for kernel and/or userspace.
  23   (Beware of confusion between kernel vs. kernel-debug vs kernel-PAE etc.
  24   variants.  Each likely has a corresponding development and debuginfo
  25   package.)
  26 - Install the systemtap package, if one already exists.
  27
  28 Build steps:
  29
  30 - Install the kernel-debuginfo, kernel-devel, gcc and dependent
  31   packages (or see below if you are building your own kernels from source).
  32
  33 - If available, install your distribution's copy of elfutils and its
  34   development headers/libraries.
  35   Or if desired, download an elfutils source release to build in
  36   "bundled mode" (below), and untar it into some new directory.
  37   Or if desired, build elfutils separately one time, and install
  38   it to /usr/local.
  39   See http://fedorahosted.org/elfutils/
  40
  41 - On modern Fedora, install general optional build-requisites:
  42   # yum-builddep systemtap
  43   On modern Debian/Ubuntu, similarly:
  44   # apt-get build-dep systemtap
  45
  46 - Download systemtap sources:
  47   http://sources.redhat.com/systemtap/ftp/releases/
  48   http://sources.redhat.com/systemtap/ftp/snapshots/
  49   (or)
  50   git clone git://sources.redhat.com/git/systemtap.git
  51       (or) http://sources.redhat.com/git/systemtap.git
  52
  53 - Build systemtap normally:
  54   % .../configure [other autoconf options]
  55   Or, with build it with a bundled internal copy of elfutils:
  56   % .../configure --with-elfutils=ELFUTILS-SOURCE-DIR [other autoconf options]
  57   (Note that elfutils > 0.139 requires gcc > 4.0 or else the
  58   appropriate elfutils-portability.patch.)
  59
  60   Consider configuring with "--enable-dejazilla" to automatically
  61   contribute to our public test result database.
  62
  63   Consider configuring with "--prefix=DIRECTORY" to specify an
  64   installation directory other than /usr/local.  It can be an ordinary
  65   personal directory.
  66
  67   % make all
  68   % sudo make install
  69
  70   To uninstall systemtap:
  71   % sudo make uninstall
  72
  73 - Run systemtap:
  74
  75   To run systemtap after installation, add $prefix/bin to your $PATH, or
  76   refer to $prefix/bin/stap directly.  If you keep your build tree
  77   around, you can also use the "stap" binary there.
  78
  79   Some samples should be available under $prefix/share/doc/systemtap/examples.
  80
  81   Normally, run "stap" as root.  If desired, create "stapdev" and
  82   "stapusr" entries in /etc/groups.  Any users in "stapdev" will be
  83   able to run systemtap as if with root privileges.  Users in "stapusr"
  84   can only launch (with "staprun") pre-compiled probe modules (created
  85   by "stap -p4 ...") that a system administrator copied under
  86   /lib/modules/`uname -r`/systemtap.
  87
  88   To run the full test suite from the build tree.
  89   % sudo make installcheck
  90
  91
  92 Tips:
  93
  94 - By default, systemtap looks for the debug info in these locations:
  95   /boot/vmlinux-`uname -r`
  96   /usr/lib/debug/lib/modules/`uname -r`/vmlinux
  97   /lib/modules/`uname -r`/vmlinux
  98   /lib/modules/`uname -r`/build/vmlinux
  99
 100
 101 Building a kernel.org kernel:
 102
 103 - Consider applying the utrace patches, if you wish to probe
 104   user-space applications.  http://people.redhat.com/roland/utrace/
 105
 106 - Build the kernel using your normal procedures.  Enable
 107   CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS,
 108   CONFIG_MODULES, CONFIG_MODULES_UNLOAD, CONFIG_UTRACE if able
 109 - % make modules_install install headers_install
 110 - Boot into the kernel.
 111
 112 - If you wish to leave the kernel build tree in place, simply run
 113   % stap -r /path/to/kernel/build/tree [...]
 114   You're done.
 115
 116 - Or else, if you wish to install the kernel build/debuginfo data into
 117   a place where systemtap will find it without the "-r" option:
 118   % ln -s /path/to/kernel/build/tree /lib/modules/RELEASE/build
 119
 120 - Instead of using the "-r" option, you can also use the environment
 121   variable SYSTEMTAP_RELEASE to direct systemtap to the kernel data.
 122