Thread: [Lxr-commits] CVS: lxr INSTALL,1.4,1.5 CREDITS.txt,1.3,1.4
Brought to you by:
ajlittoz
From: Malcolm B. <mb...@us...> - 2002-01-23 15:14:11
|
Update of /cvsroot/lxr/lxr In directory usw-pr-cvs1:/tmp/cvs-serv16574 Modified Files: INSTALL CREDITS.txt Log Message: Updated INSTALL document from Guido Sohne. Index: INSTALL =================================================================== RCS file: /cvsroot/lxr/lxr/INSTALL,v retrieving revision 1.4 retrieving revision 1.5 diff -u -d -r1.4 -r1.5 --- INSTALL 2001/08/04 18:53:57 1.4 +++ INSTALL 2002/01/23 15:14:07 1.5 @@ -2,58 +2,172 @@ ------------ 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 +1) A recent version of the exuberant ctags program. Available from + http://sf.net/projects/ctags -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. +2) A relational database - MySQL (http://www.mysql.com) and Postgresql + (http://www.postgresql.org) are supported. +3) Apache with mod_perl - http://www.apache.org + +If you want to be able to do free text searchs of your repository as +well as browse it you will have to obtain and install glimpse from +http://glimpse.cs.arizona.edu 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. +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. -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. +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. -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. +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. + +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 + +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 ------------------------ -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. +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' + +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". 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 +"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. -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. +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 @@ -61,24 +175,37 @@ CGI scripts. Since mod_perl is an Apache add-on, this means using Apache at the moment. -In httpd.conf +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 /path/to/lxr -<Directory /path/to/lxr/> -AllowOverride All +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 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). +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. -Possible problems and solutions: -------------------------------- +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...@li... + + + +Troubleshooting: +--------------- + ** Fatal: Can't find database This message comes from the DB backend. The likely cause is that the @@ -93,3 +220,4 @@ 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! + Index: CREDITS.txt =================================================================== RCS file: /cvsroot/lxr/lxr/CREDITS.txt,v retrieving revision 1.3 retrieving revision 1.4 diff -u -d -r1.3 -r1.4 --- CREDITS.txt 2001/11/28 13:04:51 1.3 +++ CREDITS.txt 2002/01/23 15:14:07 1.4 @@ -23,6 +23,7 @@ Jason Dorie Short <js...@de...> File re-org Joseph Corral <jos...@hp...> Kristoffer Gleditsch <to...@pi...> Postgres patches +Guido Sohne Updated INSTALL document |