complete installation tips for installing LXR on Centos 6.3

[kernelony]

This is a naive, step by step guide to installing LXR on a Centos 6.3 machine. This is only a recommendation, it might not fit your needs and might contain inaccuracies but it worked for me - I have indexed the linux kernel. I used ' ' to signify a command to be entered to the shell, for example 'ls -a'.
Please also go over the LXR manual in their site (for version 1.0 and above), as it provides many insights too.

Installing a blank Linux machine

1. Download CentOS-6.3-x86_64-bin-DVD1.iso from http://mirrors.usc.edu/pub/linux/distributions/centos/6.3/isos/x86_64/
2. In VmWare, create a new virtual machine with enough computing power (let's say 4 cores, 4GB of RAM). One network interface should suffice.
3. power on the machine and boot it from this ISO.
4. You will be asked several questions throughout the installation process:
   • should test HW? --> can skip
   • storage devices --> choose basic
   • disk partitioning --> choose 'use all space'
   • type of machine to be used --> choose web server - as we are going to need the apache web server (LXR is accessed via web)

5. Networking

   • if you'd like to use a dynamic IP (DHCP): 'dhclient -v eth0' - this should give eth0 an IP.

   • if you'd like to use a static IP:
     -set a static IP for the machine
     -go to /etc/sysconfig/network-scripts/ifcfg-eth0
     -add/modify the following lines, to get the following text (up to the IPs which of course depend on your setup):
     DEVICE="eth0"
     BOOTPROTO=static
     HWADDR="00:50:56:9C:0C:49"
     NM_CONTROLLED="yes"
     ONBOOT="yes"
     TYPE="Ethernet"
     UUID="6f15493e-4f97-4676-b9a4-3d9075a175fc"
     IPADDR=10.100.46.75
     PREFIX=24
     BROADCAST=10.10.46.255
     -set a default GW:
     -'vi /etc/sysconfig/static-routes'
     -add the following line, according to your default GW: any net 0.0.0.0 gw 10.100.46.254
     -set DNS server: go to /etc/resolve.conf and add dns entries

   • to apply this, do: 'service network restart'

   • At this point, YUM should be working, so we can start installing stuff.

Installing prerequisites

-MySQL (the database)
    -'yum install mysql'
    -'yum install mysql-server.x86_64'
    -by default, you'll have a 'root' user with an empty password
-ctags - install by "yum install ctags"
-perl should be already installed, if not - 'yum install perl'
-perl related:
    -'cpan App::cpanminus'
    -'cpanm File::MMagic'
    -'cpanm DBI::DBD'
-installing glimpse:
    -'yum install gcc' (making glimpse requires a c compiler)
    -'yum install flex.x86_64'
    -'yum install flex-devel.x86_64'
    -get glimpse_installation and put it in the machine
    -do: 'tar -xzvf glimpse-latest.tar.gz'
    -then go inside the extracted folder and do: './configure'
    -then: 'make'
    -then: 'make install'

install LXR - version 2.0.3

- I've tried both versions 0.11 and 2.0.3 - I recommend 2.0.3 because it has less problems, though it might be a bit slower.
- Download the LXR tarball (version 2.0.3) - lxr-2.0.3.tgz from sourceforge
- copy it to /root/downloads
- go to /usr/local/share
- untar it: tar -zxf /root/downloads/lxr-2.0.3.tgz
- change the name of the extracted directory to 'lxr'
- now enter lxr directory
- do './genxref --checkonly'
    - genxref is the script which is responsible for cross referencing the source code.
    - full operation of it will be possible only when the DB is ready and LXR is configured.
    - --checkonly flag will allow you to make sure all prerequisites are installed.
- Configuring LXR
    - This means to edit the file /usr/local/share/lxr/custom/lxr.conf
    - This file includes important data which teaches LXR about our environment:
        - how to browse to it (IP addresses, aliases)
        - where we put our source code
        - where we want the indexing data to be stored, etc.
    - Inside the LXR directory, do: './scripts/configure-lxr.pl -vv '
    - A wizard will open and ask you questions, and in the end it will edit the lxr.conf file for you.
    - This is how I answered the questions:
        - Configure for single/multiple trees? [S/m] > S
        - Do you intend to add other trees later? [yes/NO] > NO
        - Server type? [dedicated/SHARED] > dedicated       (I was using the server only for LXR, so I wanted it to be the main directory. This means I can browse using http://<IP>/source instead of http://<IP>/lxr/source)
        - --- Host name or IP? [//localhost] >
        - --- Alias name or IP? > put you IP, for example //10.100.46.75
        - Database engine? [MYSQL/oracle/postgres/sqlite] > MYSQL
        - --- Directory for glimpse databases? > /usr/local/share/glimpse_databases    (that's where the indexing output is stored!)
        - Is your Apache version 2.4 or higher? [YES/no] > do httpd -v and answer accordingly
        - --- Use 'buttons-and-menus' instead of 'link' interface? [YES/no] > no (a matter of taste, changes the display a bit)
        - --- Caption in page header? (e.g. Project XYZZY displayed by LXR) > give a title here (e.g. 'my LXR tree')
        - Do you need a specific encoding for this tree ? [yes/NO] > NO
        - How is your tree stored? [FILES/cvs/git/svn/hg/bk] > FILES
        - --- Source directory? (e.g. /home/myself/project-tree) > /usr/local/share/source_code/   (this is where you put the source code - important note about that - you need to create subdirectories to this directory - one for each version - and inside them put the actual code. E.G. put the code for version 1 inside /usr/local/share/source_code/version1))
        - Name to display for the path root? (e.g. Project or $v for version) [$v] > just hit 'enter'
        - Label for version selection menu?  [Version] > just hit 'enter'
        - Version enumeration method? [LIST/file/function] >  LIST
        - --- Version name? this one's important. If you created a subdirectory inside the source code directory (e.g. version1), you need to enter it here. 
        - --- Default displayed version is first in 'range'? [YES/no] > YES
        - --- Directory to ignore, e.g. CVSROOT or CVS? (hit return to stop) > just hit 'enter'
        - --- Include directory, e.g. /include? (hit return to stop) > just hit 'enter'
        - --- Database name? > lxr_myproject
        - --- DB user name? [lxr] >  just hit 'enter'
        - --- DB password? [lxrpw] >  just hit 'enter'
        - --- DB table prefix? [lxr_] > just hit 'enter'
    - The wizard will now create three important files inside /usr/local/share/lxr/custom and exit:
        - initdb.sh - the script which creates a DB user for LXR
        - lxr.conf - which istructs the LXR scripts as noted above
        - apache-lxrserver.conf - which will refer the apache server to the LXR scripts
- create the DB user:
    - do: 'service mysqld start'
    - do: './custom.d/initdb.sh' - it will ask for a password - just hit enter (mysql has an empty password in default state)
- move /usr/local/share/lxr/custom/lxr.conf to /usr/local/share/lxr
- now actually create the directories you have specified to the wizard:
    - the source code directory, with the sub directories of the versions. Put the source code there
    - the directory for glimpse indexing output files
- run the indexing script:
    - './genxref --url=http://localhost/ --version=version1 --checkonly'
    - This will do some basic checks
    - Now repeat it without the '--checkonly' flag: './genxref --url=http://localhost/ --version=version1'
    - This script does the following:
        - creates subdirectories inside the glimpse dir you gave to the wizard (/usr/local/share/glimpse_databases) which match the subdirectories of the versions
        - indexes the code of version 1 and puts the outputs inside /usr/local/share/glimpse_databases/version1
    - You can index all versions at once by './genxref --url=http://localhost/ --allversions'
    - This can take a while if the source code is big.

Get the apache to work

- A few words regarding the apache web server:
    - The apache (httpd) configuration resides in /etc/httpd/conf/httpd.conf
    - the httpd.conf file also has a line which says it should take into account other scripts that were put inside the dir /etc/httpd/conf.d. For this reason, the LXR manual tells us to put the file 'apache-lxrserver.conf' (which was generated by the wizard earlier) inside /etc/httpd/conf.d.  this will tell the apache to refer to LXR scripts
    - there is an error log for the apache in /var/log/https/error_log - this should help you debug problems if you'll encounter any.
- First, move the file /usr/local/share/lxr/custom/apache-lxrserver.conf to /etc/httpd/conf.d/
- Then:
    - edit the httpd configuration file: vi /etc/httpd/conf/httpd.conf.
    - You need to add there the line (anywhere you want) 'ServerName 127.0.0.1'.
    - if you don't do that, it will give you something like "starting httpd: httpd: apr_sockaddr_info_get() failed" when you try to start the httpd service
- Disable iptables (firewall), so that you can browse to the server from a remote PC:
    - 'service iptables stop'
    - 'chkconfig iptables off' (for next time)
- now:
    - 'service httpd start'
    - go to the browser and browse to http://<your LXR server IP>/source
    - this will launch the source script resides in the lxr directory - which is resposible to display the page.
    - you should see the source code and be able to navigate it, do identifier search, etc.
    - if you have an error like "the directory / doesn't exist", it means that the apache cannot access the source_code directory - so try to put it somewhere else and repeat the process (the paths I've mentioned here should work though).

Adding new code/changing existing code

- if you modify or update the source code (say, of version1) you need to index version 1 again. just run  './genxref --url=http://localhost/ --version=version1' again
- if you want to add more code/versions, do the following - say you want to add version2:
    - Create a new dir inside your source code directory - e.g.  /usr/local/share/source_code/version2
    - edit /usr/local/share/lxr/lxr.conf - look for 'range' - you should find somehing like this 
        , 'range' => [qw(version1)]
    - Change it to , 'range' => [qw(version1 version2)]
    - Now run  './genxref --url=http://localhost/ --version=version2'
    - when you browse to LXR you'll see this new version and can navigate/search in it.
- By editing /usr/local/share/lxr/lxr.conf you can also modify the source code dir (called sourceroot in lxr.conf) and the glimpse databases dir (called glimpsedirbase in lxr.conf)

[Andre-Littoz]

Thanks a lot, I'll add it in the Tips section of the site as soon as I have free time. I'll send you a notice through here, so that you can give me feed back (and correct my misspellings since I'm not a native English speaker).

[Andre-Littoz]

Hi kernelony,

I managed to upload your guide. Could you check it at
http://lxr.sourceforge.net/en/Tips/tipcentos.php

Since it is in "beta" state, you can access it presently only through this link (or direct URL). I'll put a link from the Tips page when you tell me you're OK.

I'm not sure the first part (Installing a blank Linux machine) accurately reflects the screens. I've tried to render what should be displayed. If I incorrectly interpreted your text, don't hesitate to patch.

If you'd like to fiddle yourself with the HTML, I can send you the page source. Just drop me a line through my SF @ddress (giving a private answer @ddress -- it won't show here).