|
http://www.ittc.ku.edu/~niehaus/classes/800-s04/notes/lxr_setup_new.txt
TO SETUP LXR AND INDEX SOURCE ----------------------------- The main goal of the LXR (linux cross reference) project is to create a cross-referencing tool for relatively large code repositories. We will talk about how to create a cross-reference for the linux kernel source. The client application is any web-browser. The indexer of the application has ability to jump easily to the declaration of any global identifier in the source. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Steps in installation and configuration: --------------------------------------- Packages required ----------------- 1. LXR - Linux Cross Reference Tool Download the latest LXR binaries available as a gzipped tar from http://sourceforge.net/projects/lxr 2. Glimpse - the free text search utility Download Glimpse from http://glimpse.cs.arizona.edu OR http://webglimpse.net/download.php 3. Apache or any other web-server with perl-CGI capabilities Example : Apache (We shall consider apache as the webserver in this document) Download apache from the links available at http://apache.org 4. Linux Kernel Sources or the source tree you want to index. We shall talk about indexing the linux kernel tree here, but the instructions are similar for any source tree that you may want to cross-reference. TAR Files ---------- The rest of the instructions assume you have these TAR files available. The rest of these instructions assume that the TAR files are available in $LXR_TAR_FILES host% export LXR_TAR_FILES=<path name> Assumed Directory Structures ------------------------------ 1) Assume that the root directory for this work is any directory you wish, and that the path to it has been placed in the LXR_ROOT symbol host% export LXR_ROOT=<root path> 2) We will need a "dbdir" directory within this root, so host% cd $LXR_ROOT host% mkdir dbdir Now, proceed to unpack the Lxr, Apache, Glimpse, and the kernel sources you wish to index as described in the next few steps. Installing LXR --------------- You can be anywhere to unpack the LXR software, and then we will install into $LXR_ROOT. host% cd /tmp 1. Untar the LXR archive host% tar zxvf $LXR_TAR_FILES/lxr-0.3.1.tar.gz 2. Edit the Makefile in the lxr-0.3 directory and change INSTALLPREFIX to point to the directory where you want LXR to be installed. That is the path given by $LXR_ROOT/lxr. host% cd lxr-0.3 host% emacs Makefile change INSTALLPREFIX to the expansion of $LXR_ROOT/lxr 3. Make and install the LXR software host% make host% make install The LXR software should now be in the $LXR_ROOT/lxr directory host% ls $LXR_ROOT/lxr bin http source Installing Glimpse ------------------ You can be anywhere to unpack the Glimpse Archive: host% cd /tmp 1. Untar the GLIMPSE archive host% tar zxvf $LXR_TAR_FILES/glimpse-latest.tar.gz 2. Configure using the options "--prefix=PREFIX" and "--exec-prefix=EPREFIX" to specify where you want the glimpse tool-set to be installed. Here we assume it will be in $LXR_ROOT/glimpse: host% cd glimpse-4.17.4 host% ./configure --prefix=$LXR_ROOT/glimpse --exec-prefix=$LXR_ROOT/glimpse 3. Build and install glimpse: "make", followed by a "make install" host% make host% make install Installing apache ----------------- Again, we can unpack apache anywhere so: host% cd /tmp 1. Untar the archive and configure; again, when configuring use the "--prefix" option to tell the tool where to install apache host% tar zxvf $LXR_TAR_FILES/apache_1.3.29.tar.gz host% cd apache_1.3.29 host% ./configure --prefix=$LXR_ROOT/apache 2. Build apache: host% make host% make install Unpacking the Kernel Source to be cross-referenced ------------------------------------------------- It does matter were the soruce for the kernel is unpacked, so: host% cd $LXR_ROOT host% tar zxvf $LXR_TAR_FILES/linux-2.4.22.tar.gz This should create a "kernel" directory in the $LXR_ROOT directory and the kernel source you will index is under there. SETTING UP LXR -------------- 1. Edit the LXR config file: $LXR_ROOT/lxr/http/lxr.conf 2. Modify the "glimpsebin" variable in lxr.conf file to reflect the glimpse binary path as prodiced by the following command: host% echo $LXR_ROOT/glimpse/bin 3. Modify the "baseurl" variable to the variable where you will access your kernel sources on the web. This variable will tell the lxr tool the base url where the sources will be available for access. Note that you shall then use this path when setting up Apache, such that the $LXR/http directory is mapped to this URL. Example: baseurl: http://localhost:8080/kernel/ 4. Modify htmlhead, htmltail and htmldir entries in the lxr.conf file to point to the actual locations of these files on your filesystem. host% echo $LXR_ROOT <$LXR_ROOT ouput> In the lxr.conf file: htmlhead: <$LXR_ROOT ouput>/lxr/http/template-head htmltail: <$LXR_ROOT ouput>/lxr/http/template-tail htmldir: <$LXR_ROOT ouput>/lxr/http/template-dir 5. Modify "sourceroot" to point to the kernel sources host% echo $LXR_ROOT <$LXR_ROOT ouput> sourceroot: <$LXR_ROOT ouput>/kernel 6. Modify "dbdir" to point to the location where the indexed source files shall be found. The indexing shall be done in a later step. This directive tells the tool where the database files will be found. Note that you will have to place or create the index files in this directory. dbdir: <$LXR_ROOT ouput>/dbdir After these edits, our lxr.conf file looks like the following for $LXR_ROOT= "/local-800-aos/lxr-kurt2": ==================== begin ================================== # Configuration file. # Define typed variable "v", read valueset from file. variable: v, Version, [/local/lxr/source/versions], [/local/lxr/source/defversion] # Define typed variable "a". First value is default. variable: a, Architecture, (i386, alpha, m68k, mips, ppc, sparc, sparc64) # Define the base url for the LXR files. baseurl: http://localhost/kernel/ # These are the templates for the HTML heading, directory listing and # footer, respectively. htmlhead: /local-800-aos/lxr-kurt2/lxr/http/template-head htmltail: /local-800-aos/lxr-kurt2/lxr/http/template-tail htmldir: /local-800-aos/lxr-kurt2/lxr/http/template-dir # The source is here. sourceroot: /local-800-aos/lxr-kurt2/kernel srcrootname: Linux # "#include <foo.h>" is mapped to this directory (in the LXR source # tree) incprefix: /include # The database files go here. dbdir: /local-800-aos/lxr-kurt2/dbdir # Glimpse can be found here. glimpsebin: /local-800-aos/lxr-kurt2/glimpse/bin # The power of regexps. This is pretty Linux-specific, but quite # useful. Tinker with it and see what it does. (How's that for # documentation?) map: /include/asm[^\/]*/ /include/asm-$a/ map: /arch/[^\/]+/ /arch/$a/ ==================== end ================================== INDEXING THE SOURCE -------------------- Goto the directory where you specified in the lxr.conf file that your database files shall be present (dbdir) - $LXR_ROOT/dbdir host% cd $LXR_ROOT/dbdir 1. Index the source to generate the database file (takes a decent amount of time) host% $LXR_ROOT/lxr/bin/genxref $LXR_ROOT/kernel 2. Now generate the free text search database by using the glimpse utility. The glimpse tools are present in the bin directory of the glimpse directory of the installation you did previously. host% $LXR_ROOT/glimpse/bin/glimpseindex -H . $LXR_ROOT/kernel 3. The $LXR_ROOT/lxr/http directory should be reflected as a directory that contains CGI scripts in the apache webserver configuration. The Apache webserver configuration file should be modified to make the $LXR_ROOT/lxr/http directory appear as a CGI scripts directory. You can add the following directives to $LXR_ROOT/apache/conf/httpd.conf: host% echo $LXR_ROOT <$LXR_ROOT ouput> =============== Append these lines ================== ScriptAlias /kernel "<$LXR_ROOT ouput>/lxr/http" <Directory "<$LXR_ROOT ouput>/lxr/http"> AllowOverride None Options None Order allow,deny Allow from all </Directory> ==================== end ================================== 4. OPTIONAL: The template files controlling the display under LXR are in the directory: $LXR_ROOT/lxr/http. The "templat-head" file efines the page header, while "template-tail" defines the foooter. The information in between is controlled by the "template-dir" file. 6. We ran these instructions as root, and this leaves some files without proper permissions for access from the Apache server. host% cd $LXR_ROOT/dbdir host% chmod og+r * .* Note that the .* was required because many of the files in this directory begin with a period ".". You can see this by: host% ls -a 6. Next you should start the apache server: host% $LXR_ROOT/apache/bin/apachectl start or, if apache is already running, you will want to restart: host% $LXR_ROOT/apache/bin/apachectl restart 7. Now the cross-referenced kernel source is available at the URL; http://localhost/kernel/source Note that the source component of this URL is a CGI-bin script which will display the root of LXR source index. |
