Installation
------------
The current version of the lxr depends on three things:

1) A recent version of the exuberant ctags program
2) A relational database.  MySQL has been tested, and there is code
for Postgresql as well.
3) Apache with mod_perl

At the moment the DBI backend works, this means that you will have to
set up a relational database like MySQL. The DBI backend currently in
CVS has been tested with MySQL.  There is a DB backend for Berkeley
dbm file support, but it has not been tested recently.

Installing the database
-----------------------
First install the DBMS and create a lxr database. The files
initdb-<name> where <name> is the name of your database contain the
commands to create the correct database.

If you are running postgres the initialization can be done by running
'psql lxr' and reading the file "initdb-postgres" by entering '\i
createdb'. Just ignore the errors about unimplemented functions.
The user running your cgi-scripts must be able to use the postgres
database. This user is usually nobody, create the postgres user by
entering "createuser nobody" at the shell prompt.

If you are using 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.

Edit the lxr config file
------------------------
When the database is initialized, copy templates/* to . ("cp templates/* .").
Then edit lxr.conf, it should contain enough comments to get you
started.  You may also wish to edit the lxr HTML files.

Generate index.
---------------
It is now time to generate the index. This is done using the program
"genxref". The new genxref is much smarter than the old one. Our
intention is that you configure everything inside lxr.conf, the file
is read by genxref and all paths are set up so the cgi-scripts will
find the files. genxref takes two arguments --url=<url> and
--version=<ver> where <url> 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.

Note that genxref can be a very slow process the first time it's 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.

In httpd.conf

Alias /lxr /path/to/lxr
<Directory /path/to/lxr/>
AllowOverride All
</Directory>

The distribution contains a .htaccess file set up to ensure that lxr
will work. Edit it if you have special local policies.

If you have problems with the LXR modules not being found by mod_perl,
you may need to install the LXR module under the normal perl module
directory i.e. copy/link lib/LXR into /usr/lib/perl5/site_perl/5.6.0
(assuming this is where your perl is installed).

Possible problems and solutions:
-------------------------------

** 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!
