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 - Download systemtap sources:
  42   http://sources.redhat.com/systemtap/ftp/releases/
  43   http://sources.redhat.com/systemtap/ftp/snapshots/
  44   (or)
  45   git clone git://sources.redhat.com/git/systemtap.git
  46       (or) http://sources.redhat.com/git/systemtap.git
  47
  48 - Build systemtap normally:
  49   % .../configure [other autoconf options]
  50   Or, with build it with a bundled internal copy of elfutils:
  51   % .../configure --with-elfutils=ELFUTILS-SOURCE-DIR [other autoconf options]
  52
  53   Consider configuring with "--enable-dejazilla" to automatically
  54   contribute to our public test result database.
  55
  56   Consider configuring with "--prefix=DIRECTORY" to specify an
  57   installation directory other than /usr/local.  It can be an ordinary
  58   personal directory.
  59
  60   % make all
  61   % sudo make install
  62
  63   To uninstall systemtap:
  64   % sudo make uninstall
  65
  66 - Run systemtap:
  67
  68   To run systemtap after installation, add $prefix/bin to your $PATH, or
  69   refer to $prefix/bin/stap directly.  If you keep your build tree
  70   around, you can also use the "stap" binary there.
  71
  72   Some samples should be available under $prefix/share/doc/systemtap/examples.
  73
  74   Normally, run "stap" as root.  If desired, create "stapdev" and
  75   "stapusr" entries in /etc/groups.  Any users in "stapdev" will be
  76   able to run systemtap as if with root privileges.  Users in "stapusr"
  77   can only launch (with "staprun") pre-compiled probe modules (created
  78   by "stap -p4 ...") that a system administrator copied under
  79   /lib/modules/`uname -r`/systemtap.
  80
  81   To run the full test suite from the build tree.
  82   % sudo make installcheck
  83
  84
  85 Tips:
  86
  87 - By default, systemtap looks for the debug info in these locations:
  88   /boot/vmlinux-`uname -r`
  89   /usr/lib/debug/lib/modules/`uname -r`/vmlinux
  90   /lib/modules/`uname -r`/vmlinux
  91   /lib/modules/`uname -r`/build/vmlinux
  92
  93 Building a kernel.org kernel:
  94
  95 - Build the kernel using your normal procedures.  Enable
  96   CONFIG_DEBUG_INFO, CONFIG_KPROBES, and optionally CONFIG_RELAY and
  97   CONFIG_DEBUG_FS.
  98 - Run "make install modules_install headers_install" as needed.
  99 - Boot into the kernel.
 100 - Make sure the large unstripped kernel image 'vmlinux' from your
 101   build can be found by systemtap (see above)  You can just symlink
 102   it to one of these locations.
 103 - Symlink your build directory to here:
 104   /lib/modules/`uname -r`/build
 105 - For example, if your kernel source is in /home/me/linux/2.6.17-rc6
 106   and you build your kernel in the source directory, you would do
 107   this (be sure you are running the right kernel or `uname -r`
 108   will be wrong:)
 109      ln -s /home/me/linux/2.6.17-rc6/vmlinux /boot/vmlinux-`uname -r`
 110      mkdir /usr/src/kernels  (if needed)
 111      ln -s /home/me/linux/2.6.17-rc6 /usr/src/kernels/`uname -r`
 112      mkdir /lib/modules/`uname -r`  (if needed)
 113      ln -s /home/me/linux/2.6.17-rc6 /lib/modules/`uname -r`/build
 114      ln -s /home/me/linux/2.6.17-rc6 /lib/modules/`uname -r`/source