# Troubleshooting

Various problems and their solutions are described here. If you encounter a problem not described here, please file a bug.

## Install Script Errors

This section describes different errors that could occur from running the install scripts (i.e. `install.sh` or `install-noconsolehelper.sh`)

### Error: script must be run as the root user

You attempted to run the script as an ordinary, non-root user. You must be the root user to run the install script, as the scripts edit files located in root-owned directories.

Solution: Run the command `su -` to become the root user, or run the script as the root user with `su -c './install.sh'`.

### Error: script must be run with pwd in script dir

Your current working directory must be the `natives/linux/scripts` subdirectory of the OProfile core plug-in; running the script relative from another location will not work.

Solution: Simply follow the steps on Step 1 - Locate the Installation Scripts to find the `natives/linux/scripts` subdirectory of the OProfile core plug-in.

### Error: required binaries do not exist, OProfile not installed?

The OProfile plug-in could not find the `oprofiled` and `opcontrol` binaries. This could mean they are not in their default directory (`/usr/bin`), or they do not exist at all.

Solution: If the binaries are on your system (and in your `PATH`) but not in those directories, you can either remove these checks from the install script or create symlinks in the `/usr/bin` directory. Of course, if the binaries do not exist on your system, then install the `oprofile` package.

### Error: /usr/bin/consolehelper does not exist, run install-noconsolehelper.sh instead

You ran the `install.sh` script, but `consolehelper` was not installed on your system. As described in Step 2 - Choose Which Installation Script To Run, if `consolehelper` is not installed, then you will need to use a root authentication mode that uses the `sudo` mechanism.

Solution: Run the `install-noconsolehelper.sh` script instead.

### Error: cannot create opcontrol wrapper in <directory>

The `ln` command reports that the symlink could not be created. This can occur if the `natives/linux/scripts` subdirectory is located on an NFS mount; the NFS server will not allow the local root user to create files in the directory.

Solution: Before running the `install.sh` script, first create the symlink as a regular user by running the command `ln -s /usr/bin/consolehelper opcontrol`. Then, remove the following section from the `install.sh` script:

    #create the sym link to consolehelper
    test -L ./opcontrol || { rm -f ./opcontrol && ln -s /usr/bin/consolehelper opcontrol ; }
    if [ $? -ne 0 ]; then
      echo Error: cannot create opcontrol wrapper in `pwd`
      exit 1
    fi

The `install.sh` script is fixed in the most recent version of the OProfile plug-in for Eclipse, but not in the 0.2.0 release.

### Error: cannot find opxml binary, required plugin missing (Deprecated)

NOTE: As of Linux Tools version 0.7.0 opxml is NOT required anymore.

This can occur if the native binary `opxml` is not found. This binary is required for proper operation of the oprofile plug-in version < 0.7.0 plug-in. `opxml` is not required for oprofile >= 0.7.0.

Solution: If the `org.eclipse.linuxtools.oprofile.core.linux.{x86,x86_64,ppc}` directories exist (in the Eclipse `plugins` directory), refer to the Rebuilding opxml section for instructions on rebuilding the binary and placing it in the proper directory. Otherwise, re-install the plug-in.

## No Samples From A Profile

It is possible for a profile run of a program to return no samples, resulting in no `current` session displayed. This is not always indicative of a problem with either OProfile or the profiled program. OProfile is a system-wide profiling tool; hence, other active processes running on your system may overshadow your program. This is particularly true if the profiled program is not CPU intensive.

In addition, the Event you choose (selected through the Events tab, as described in Regular Mode) could cause a profile to return no samples; for example the event BR_CND_MISSP_EXEC will only provide samples if a branch was mispredicted by the processor. Note also that due to the statistical nature of OProfile, profiling is neither deterministic nor consistent; two subsequent runs may output very different results. In some cases, one run can result in no samples, while another run on the same program can result in many samples. The OProfile online documentation has other useful information here.

Solution: The following suggestions could help you generate more samples from a profile run:

- run your program with a larger input
- halt or kill as many other non-essential processes as possible
- reduce the Count in the Event Configuration tab
- launch a profile several times

If you are unsure whether your configuration is working correctly, try profiling the sample project in the Example Project section.

## Log Reader Hangs

If the OProfile daemon log file is too large, the log reader may hang and possibly cause the OProfile plug-in to crash. This occurs when the verbosity option is set to `all`, which results in several hundred MiB of text in the log over several profile runs. If you do require all this data in the log file, do not launch the log reader. Delete or backup the log file before running the log reader again.

## Errors Related to opxml (Deprecated)

NOTE: As of Linux Tools version 0.7.0 opxml is NOT required anymore.

`opxml` is the native program that bridges OProfile and the OProfile plug-in for Eclipse. In some cases, some errors may be caused by problems with `opxml`. To verify if this is the case, run `opxml`.

`opxml` is normally located in the Eclipse `plugins` directory, similar to the install scripts described in Step 1 - Locate the Installation Scripts. However, depending on your platform, the location of `opxml` will be different. To determine what your platform is, run the following command at a terminal:

     uname -m

Depending on the output, locate the following directory in the same manner as Step 1 - Locate the Installation Scripts, and change into that directory:

Output from `uname -m` | Directory to use in `find` command | Sub-directory to change to
--- | --- | ---
i386, i468, i568, i686, x86 | org.eclipse.linuxtools.oprofile.core.linux.x86 | os/linux/x86
x86_64 | org.eclipse.linuxtools.oprofile.core.linux.x86_64 | os/linux/x86_64
ppc, ppc64 | org.eclipse.linuxtools.oprofile.core.linux.ppc | os/linux/ppc

For example, if you are running Eclipse on a 64bit machine (i.e. x86_64), you should run the following command to find the location of `opxml`:

     $ find /home/ksebasti/eclipse -name 'org.eclipse.linuxtools.oprofile.core.linux.x86_64_*'

This will display the following output (or similar):

     /home/ksebasti/eclipse/plugins/org.eclipse.linuxtools.oprofile.core.linux.x86_64_0.2.0.200904201514

Navigate into that directory:

     $ cd /home/ksebasti/eclipse/plugins/org.eclipse.linuxtools.oprofile.core.linux.x86_64_0.2.0.200904201514/os/linux/x86_64

Once you have navigated to the right directory, run the following command:

     ./opxml info

Check that the paths in the `defaults` section are correct. If the output is similar to the output of the command `ophelp`, but formatted as XML, then this might not be the problem. However, if running `opxml` produces an error, it may be the root cause. A common error on some systems is that they use an older version of the C runtime libraries (i.e. `glibc`). Refer to Rebuilding opxml for a solution to this error.

In any case, if there is an error please look for an existing bug or if one does not exist, file a new bug.

## Rebuilding opxml (Deprecated)

NOTE: As of Linux Tools version 0.7.0 opxml is NOT required anymore.

You will need to rebuild the `opxml` binary if running it returns an error similar to the following:

     opxml: /some/path/libc.so.6: version `GLIBC_2.8' not found (required by opxml)

Warning: this is rarely necessary; in some cases, rebuilding the `opxml` binary may break an otherwise working OProfile plug-in installation. You should only rebuild the `opxml` binary if you are sure that doing so is the only remaining option in fixing the OProfile plug-in for Eclipse.

To rebuild the `opxml` binary, perform the following steps

1. Follow the exact same steps as Step 1 - Locate the Installation Scripts, except instead of changing to the `natives/linux/scripts` sub-directory, change to the `natives/linux/opxml` sub-directory of the core plugin. The source files for the `opxml` binary should be located here.
2. Rebuilding `opxml` requires `make`, `g++`, the `libbfd` libraries and the OProfile development libraries. In Fedora, the `oprofile-devel` package contains the OProfile development libraries; for information about the OProfile development libraries in Ubuntu, refer to Ubuntu - Extra Requirements.
3. Run `make` to build the binary.
4. Run `make install` to install the binary into the correct plug-in directory.
5. Run `make clean` to remove the extra files created during the build process.

### Ubuntu - Extra Requirements

Ubuntu and other Debian-based systems do not provide the OProfile development libraries in their packaging management system, so we must build them by hand. To do so, perform the following steps:

1. Install the packages `binutils-dev` and `libpopt-dev`.
   - `sudo apt-get install binutils-dev libpopt-dev`
2. Download the OProfile source.
   - `apt-get source oprofile`
3. Unpack the OProfile source tarball.
   - `cd oprofile-0.9.3 ; tar -zxf oprofile_0.9.3-1.1ubuntu2.tar.gz`
4. Run the `configure` tool.
   - `cd oprofile-0.9.3 ; ./configure --without-kernel-support`
5. Compile the required libraries.
   - `make`
6. Move the libraries into the include path.
   - `sudo mv libutil/op_types.h libop/op_sample_file.h libutil/op_list.h libop/op_events.h libop/op_cpu_type.h libop/op_config.h libdb/odb.h /usr/include`
   - `sudo mv libop/libop.a libdb/libodb.a /usr/lib`
   - `sudo mv libabi/libabi.a /usr/lib/libopabi.a`
   - `sudo mv libutil/libutil.a /usr/lib/liboputil.a`
   - `sudo mv libutil++/libutil++.a /usr/lib/liboputil++.a`

The required libraries should now be in the proper place for compiling. Continue the steps in the Rebuilding opxml section.

Note: The procedure for building the OProfile development libraries for Ubuntu (described in this section) was tested on Ubuntu 10.04 with Eclipse, the CDT, oprofile and all its dependencies already installed via `apt`.