Installation ------------ The current version of the lxr depends on three things: 1) A recent version of the exuberant ctags program. Available from http://sf.net/projects/ctags 2) A relational database - MySQL (http://www.mysql.com), Postgresql (http://www.postgresql.org) and Oracle are supported. You will also need the right Perl DBI drivers for your particular database, usually available from CPAN. 3) Apache with mod_perl - http://www.apache.org 4) For freetext searching, either Glimpse (http://glimpse.cs.arizona.edu) or Swish-e (http://swish-e.org). You need the development version of swish-e (i.e. 2.1.x or later). Swish-e is fully GPL'ed, while Glimpse is only free for non-commercial use. Installing the database ----------------------- You will need to create a database for lxr, and possibly create a user as well. If you are unsure how to do this, or don't have admin rights to the database, consult the documentation or your sysadmin respectively. The steps below assume you know what you're doing. For Postgresql: Create a user for lxr and give the user permission to create databases: createuser lxr Create a database for lxr: createdb -U lxr lxr Initialise the database: psql -U lxr lxr \i initdb-postgres Just ignore the errors about unimplemented functions. For MySQL: Run 'mysql' and then read in the initdb-mysql file using '\. initdb-mysql'. This will create the database and a user called lxr with access rights to the database. For Oracle Start script in sqlplus with: @/[pathTo]/initdb-oracle.sql; Create lxr installation directory --------------------------------- Expand the tarball in the LXR distribution into a directory of your choice. A good choice could be /usr/local/lxr so you would do cd /usr/local/ tar -zxf /path/to/lxr/lxr-x.x.tgz (as root or with appropriate permissions) Now you have to put the perl modules that LXR uses into a directory on your system that will be searched by mod_perl when the LXR scripts are executed. Execute: cp /usr/local/lxr/Local.pm /usr/lib/perl5/site_perl/ cp -r /usr/local/lxr/lib/LXR /usr/lib/perl5/site_perl Now you should copy the template files for LXR to your installation mv /usr/local/lxr/templates/* /usr/local/lxr/ Edit the lxr config file ------------------------ Go through the config file and fill in the relevant values. If you have glimpse installed, you should set 'glimpsebin' => '/path/to/your/glimpse/executable' Now remember you copied the perl modules for Glimpse to a directory in your perl module search path ? The example path I used was /usr/lib/perl5/site_perl which is also needed in lxr.conf 'genericconf' => '/usr/lib/perl5/site_perl/LXR/Lang/generic.conf' Next set your base URL and virtual root for LXR by setting 'baseurl' => 'http://your.host.name/your_lxr_virtual_root 'virtroot' => '/your_lxr_virtual_root' Fill in the dbname, dbpass and dbuser variable to the right values for the database you created above. The 'v' (Version) variable needs to have the list of versions of your sourcecode that you want to index. This list can be in the lxr.conf file, read from a file or calculated at runtime. Select the right method for your setup in the lxr.conf file. Set the 'sourceroot' variable to point to the source code that you want to index and browse. You may also want to configure the 'graphicfile', 'filetype' and 'incprefix' variables, but the defaults should be reasonable for most setups. Getting lxr to work with CVS ---------------------------- If you want lxr to work on files that are located in a CVS repository, edit lxr.conf and set the range variable so that it uses a subroutine instead of the default setting that reads the src/cvsversions file. 'range' => sub { return ($files->allreleases($LXR::Common::pathname), $files->allrevisions($LXR::Common::pathname)) }, # deferred function call. You should also set the default version retrieved to a version that really does exist otherwise you will receive errors when generating your index. A good value for the default version is head. 'default' => 'head' Next, set the source root variable to point to the directory containing the versions of your project in CVS. If your cvs repository in stored in /path/to/cvs/repository and your cvs module is called lxr then set 'sourceroot' => 'cvs:/path/to/cvs/repository/lxr' 'sourcerootname' => 'A Friendly Name For Your Repository' Using Swish-e with LXR ---------------------- This is simple: 1) Put the paths to swish-e and swish-search in the 'swishindex' and 'swishsearch' variables in lxr.conf. If there is no swish-search executable on your system, use the path to swish-e as the 'swishsearch' value. 2) Create a directory for the swish index files to go in, and put the path of this directory in the 'swishdir' variable. 3) Comment out the 'glimpsebin' variable Now re-run genxref and it should build the swish indexes for you and you're done. Getting Glimpse to work with LXR -------------------------------- Create a directory in your LXR directory called glimpse mkdir /usr/local/lxr/glimpse If you are using CVS, checkout a copy of your project in the LXR directory, for example cd /usr/local/lxr cvs checkout my_project otherwise just use the path to your project instead in the example below find /usr/local/lxr/my_project/ -name *.java | glimpseindex -H /usr/local/lxr/glimpse -o -F Be sure that the glimpse indexes are readable by the user that Apache is running as. You can do chmod a+x /usr/local/lxr/glimpse/.* Now edit lxr.conf again and add the following variable for the URL section that you configured earlier 'strip' => '/usr/local/lxr/sikasem' This munges the output of glimpse so that you can go straight to the file that contains a match for a search term. Generate index. --------------- It is now time to generate the index. This is done using the program "genxref". genxref takes two arguments --url= and --version= where is the url where the lxr cgi scripts are found. Version is a tag from cvs if you are using the cvs backend or the name of a directory in your "sourceroot" directory. It is worth noting that one lxr.conf file can be used for several different configurations. Which config block to use is selected according to the url argument. If you are setting up LXR to use files in a CVS repository, genxref will most likely run without printing out any error messages. This is *not* what you want. You have to explicitly state a version to use. genxref --url=/path/to/lxr --version=head You can also use the --allversions argument to automatically index all the versions defined in the versions variable. Note that genxref can be a very slow process the first time it is run, for example on a 4Gb source tree a full run can take several days. However, on future runs it will only index changed files, thus speeding the process. Set up webserver ---------------- The browsing scripts currently supplied depend on mod_perl to execute properly, although it should be easy to modify them to work as plain CGI scripts. Since mod_perl is an Apache add-on, this means using Apache at the moment. You may need to edit httpd.conf to point to the lxr files, for example if you have installed the lxr files in /usr/local/lxr and you want to have your URL be http://mysite/lxr then you would add: Alias /lxr /usr/local/lxr AllowOverride All The distribution contains a .htaccess file set up to ensure that lxr will work. Edit it if you have special local policies. That's it - lxr should now work. Fire up your webbrowser and go to http://yoursite/lxr/source and you should see the listing for the top of your source tree. Getting help if it doesn't work: -------------------------------- If you can't get LXR to work then you can try asking on the mailing list or the support forums. Do check the archives of both first though - your question may already have been answered. By web: http://sourceforge.net/forum/forum.php?forum_id=86145 By email: Send a mail to lxr-general@lists.sf.net Troubleshooting: --------------- ** Fatal: Can't find database This message comes from the DB backend. The likely cause is that the webserver url passed to the browsing scripts does not match the url in lxr.conf. This means the configuration will not be found, and thus the database will not be found HTTP headers appearing in the html, or output not being interpreted as HTML This can be caused by warning messages output before the script outputs the right headers to tell the browser that the output is HTML. This can normally be solved by changing the value of $wwwdebug to 0 in Common.pm. But please report the warning message as a bug at http://sf.net/projects/lxr first!