LXR Cross Referencer Git repo

251 lines (184 with data), 9.1 kB

Installation
------------
The current version of the lxr depends on the following 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) A webserver - Apache httpd (http://httpd.apache.org/) with mod_perl
   (http://perl.apache.org/) is recommended

4) For freetext searching, either Glimpse (http://glimpse.cs.arizona.edu) or
   Swish-e (http://swish-e.org) version 2.1 or later.
   Swish-e is fully GPL'ed, while Glimpse is only free for
   non-commercial use.

5) The Perl database driver interface DBI and the relevant DBD driver for the
   database you're using.  If you don't already have these, they can be
   installed via CPAN.  See http://dbi.perl.org/index.html for more info.

6) The Perl File::MMagic module, available from CPAN

7) If using the CVS support, you will need rcs installed as well.

8) If you are using the BitKeeper support, you will need:
	BitKeeper (bk) installed
	Digest::SHA module (available from CPAN)

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.  If you want a custom prefix for the table names, you must
manually edit the initdb script by replaceing every 'lxr_' with your prefix.
Don't forget to set the 'dbprefix' in lxr.conf.
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'
 'glimpseindex' => '/path/to/your/glimpseindex/executable'
 
If you have swish-e installed, you should set

 'swishbin' => '/path/to/your/swishe-e/executable'

Comment out the variables for the indexer you are not using.
Set 'htmlsearch' to either 'html-search-swish.html' or
'html-search-glimpse.html' depending on which indexer
you are using.

Now remember you copied the perl modules 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'
 'ectagsconf' => '/usr/lib/perl5/site_perl/Lang/ectags.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
----------------------------
Currently LXR cannot index CVS files with glimpse.  You must use swish-e.

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
----------------------
Create a directory for the swish index files to go in, and put the
path of this directory in the 'swishdir' variable.

Using Glimpse with LXR
--------------------------------
Create a directory for the swish index files to go in, and put the
path of this directory in the 'glimpsedir' variable.

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, you
probably want to use the 'head' version (default).

  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 supplied can run with Apache mod_perl or as cgi
scripts.

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
<Directory /usr/local/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 are using Apache without mod_perl (running scripts as CGI),
instead of 'Alias' in httpd.conf use 'ScriptAlias'.  Also, delete
.htaccess and rename .htaccess_cgi to .htaccess.

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.

If you are using a webserver other than Apache, you need to provide:
/icons/back.gif
/icons/folder.gif
/icons/c.gif
/icons/text.gif
/icons/compressed.gif
/icons/image2.gif
/icons/generic.gif

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!