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
End Notes:
- Even though this post is related to Linux kernel source, same method will work fine for any c project.
- Cscope scans all files only during first run, during subsequent executions it will only scan the files changed since last run.
- When you invoke first emacs command related to cscope it will automatically invokes cscope to make the database up to date.
- 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:
