How To Integrate Emacs & Cscope To Browse Linux Kernel Source Code


This year I am going to study Linux kernel,  As a first step I grabbed a copy of Understanding the Linux Kernel By Daniel P. Bovet, Marco Cesati. The problem started when I had to go through actual code. I tried to use usual command line utilities to locate files and code inside the kernel source tree. Though it is not impossible, it is very time consuming and inefficient way to  browse the kernel source. Withing an hour of doing this I was sure that there ought to be a better way… and the better way is to use cscope source code browser and best way is to integrate it with emacs (or vi).

This post is about cscope integration with emacs, for more details about cscope itself please refer to cscope home page  and cscope man page.

Installation:

To get started we need to install emacs, cscope and xcscope emacs extension. As per cscope documentation the emacs support for cscope is provided in cscope/contrib/xcscope folder, however the ubuntu package did not have this folder as part of cscope package. It is provided as additional package called cscope-el (The cscope-el package installs /usr/share/emacs23/site-lisp/cscope/xcscope.elc). So install all these packages using:

sudo apt-get install emacs23 cscope cscope-el

Download the required kernel source tar ball from kernel.org, I wanted linux-2.6.11.12. It can be downloaded using wget as:

cd ~/Downloads
wget ftp://ftp.kernel.org/pub/linux/kernel/v2.6/linux-2.6.11.12.tar.bz2

 Configuration:

We need to configure emacs to load cscope support, edit your ~/.emacs or ~/.emacs.d/init.el to include following line.

(require 'xcscope)

Generate Cscope Database:

There are two ways to generate cscope database from kernel source, first is to use kernel make file and second is to use cscope directly. But first we need to extract the kernel source from the downloaded tar ball as given below.

cd ~/Downloads
tar -jxvf linux-2.6.11.12.tar.bz2

Method1: Generate cscope database using kernel make file, by using this method, list of files to be scanned by cscope is also generated by kernel make file. The file containing this list is named cscope.files. This is safer method if you don’t know which files to be included.

cd ~/Downloads/linux-2.6.11.12
make cscope

Method2: Generate cscope database directly using cscope.

In this method you can either scan all files in the current folder recursively by passing -R command line option to cscope or  you need to create a file named cscope.files  which can either contain list of files to be scanned (one file on each line) or using the special find construct as explained in Using cscope on large project page. The following command will scan the complete kernel source code tree, the -k option ensures that include files in /usr/include are ignored while building the database.

cd ~/Downloads/linux-2.6.11.12
cscope -b -q -k -R

Irrespective of the method the database file named cscope.out will be created.

Browsing the code:

To browse the code from emacs, first we need to tell the location of the database. This is done by executing command “M-x cscope-set-initial-directory” and specify the directory containing the cscope database. This step is not required if emacs is lanuched from the same directory.

Once the initial directory is set, you can search the code for given symbol using “M-x cscope-find-this-symbol” command, the text near cursor will be the default symbol to find. You can move through the results using p (previous match) and n (next match) keys, the corresponding files are opened in other buffer in emacs. Example output for symbol KERN_ALERT is shown below.

Emacs and Xcscope Find Symbol Output

The other useful commands include:

Find symbol.
Find global definition.
Find functions calling a function.
Find called functions (list functions called from a function).
Find text string.
Find egrep pattern.
Find a file.

For a complete list of commands supported by xcscope please refer to xcscope man page.

What didn’t Work for Me:

Using xcscope.el: If you download the xcscope.el and try to add it in emacs through config file as:

(load-file "/usr/share/emacs/site-lisp/xcscope.el")
(require 'xcscope)

I got the following error at emacs startup:

Warning (initialization): An error occurred while loading `/home/dzambare/.emacs.d/init.el':

File error: Cannot open load file, xcscope

To ensure normal operation, you should investigate and remove the
cause of the error in your initialization file.  Start Emacs with
the `--debug-init' option to view a complete error backtrace.

The solution is to get rid of this file and install cscope-el package as explain in Installation section above.

Alternate Interface:

You can also use cscope’s inbuilt console based UI to browse and edit files. It can be launched by following command from the directory containing cscope database. The screenshot below shows how it looks like.

cscope -d
Cscope in-build user interface

Cscope in-build user interface

End Notes:

  1. Even though this post is related to Linux kernel source, same method will work fine for any c project.
  2. Cscope scans all files only during first run, during subsequent executions it will only scan the files changed since last run.
  3. When you invoke first emacs command related to cscope it will automatically invokes cscope to make the database up to date.
  4. Example of xcscope key binding are provided in xcscope man page

Version Nos of Key Components:

  • OS: Kubuntu 11.10
  • Cscope:  15.7a
  • Xcscope: 15.7a

Links Related to This Post:

Advertisements
This entry was posted in Free Software, GNU GPL, How To, Kernel, Kubuntu, Tips and tagged , , , , , , . Bookmark the permalink.

4 Responses to How To Integrate Emacs & Cscope To Browse Linux Kernel Source Code

  1. Pingback: Emacs browser | Bestpricemotor

  2. Pingback: Daily Task 2012 Week24 (6/10 – 6/16) « Artist of Code

  3. Pingback: Emacs Hints and Tips | Multics69's Blog

  4. Craig R says:

    Instead of:

    (load-file “/usr/share/emacs/site-lisp/xcscope.el”)
    (require ‘xcscope)

    You want:

    (add-to-list ‘load-path “/usr/share/xemacs/site-packages/lisp”)
    (require ‘xcscope)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s