源码阅读工具 lxr 安装配置初探

说明：本文是第一次安装 lxr 的记录文章，适合加深对 lxr 的理解；如果是想迅速使用 lxr 的话，本文中有些地方对 lxr 的配置不太妥当，建议先阅读本文，然后再以 《LXRUserManual-1.2-en_UK-1.4.pdf》 为主实践
==================================
安装 Apache, MySQL, ctags, mod_perl
==================================

$ sudo yum install mysql mysql-server mysql-devel$ sudo yum install httpd$ sudo yum install ctags

官网有一句 "Apache httpd with mod_perl is recommended", 所以最好是现在就将 mod_perl 一起安装，后面可以省去很多麻烦（麻烦见下文），由于 Apache 是用 yum 方式安装的，所以 mod_perl 最好也用 yum 安装，否则后面会一堆麻烦（见下文）

$ sudo yum install mod_perl

$ sudo service mysqld stop$ sudo service mysqld start$ mysqladmin -u root password <password>$ sudo service httpd stop$ sudo service httpd start

============
安装 glimpse
============

$ ./configure$ make...make[1]: Leaving directory `/share/linux-data/Downloads/glimpse-4.18.6/index'make[1]: Entering directory `/share/linux-data/Downloads/glimpse-4.18.6/dynfilters'flex -F -8 htuml2txt.lexmake[1]: flex: Command not foundmake[1]: *** [lex.yy.c] Error 127make[1]: Leaving directory `/share/linux-data/Downloads/glimpse-4.18.6/dynfilters'make: *** [build-sub] Error 2$ sudo yum install flex$ make$ make install

=============
安装 lxr
=============

$ cd /usr/local/share$ tar -xzvf lxr-1.2.0.tgz$ mv lxr-1.2.0.tgz lxr$ cd lxr

LXR root directory 为 "/usr/local/share/lxr"

====================
genxref --checkonly
====================

$ ./genxref --checkonlyCan't locate File/MMagic.pm in @INC (@INC contains: lib scripts /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5 .) at ./genxref line 30.BEGIN failed--compilation aborted at ./genxref line 30.[hwx@hwx lxr]$ ./genxref --checkonlyCan't locate File/MMagic.pm in @INC (@INC contains: lib scripts /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5 .) at ./genxref line 30.BEGIN failed--compilation aborted at ./genxref line 30.$ sudo yum install perl-File-MMagic$ ./genxref --checkonlyERROR: could not open configuration file lxr.conf[  OK  ]     Perl     version ... 5.10.1Parameter 'ectagsbin' not defined - trying to find ctagsctags found at /usr/bin/ctags[  OK  ]     ctags    version ... 5.8Parameter 'glimpsebin' not defined - trying to find glimpseglimpse found at /usr/local/bin/glimpseChecked:    glimpse   version ... 4.18.5Parameter 'glimpseindex' not defined - trying to find glimpseindexglimpseindex found at /usr/local/bin/glimpseindexChecked: glimpseindex version ... 4.18.5Parameter 'swishbin' not defined - trying to find swish-eswish-e not found, `command -v swish-e` returned a null stringgenxref stopped without indexing by --checkonly option

========================================
配置 lxr(./scripts/configure-lxr.pl -vv)
========================================

$ ./scripts/configure-lxr.pl -vv*** LXR configurator (version: 1.13) ***LXR root directory is /usr/local/share/lxrConfiguration will be stored in custom.d/mkdir custom.d: Permission denied at ./scripts/configure-lxr.pl line 223[hwx@hwx lxr]$ sudo ./scripts/configure-lxr.pl -vv[sudo] password for root: *** LXR configurator (version: 1.13) ***LXR root directory is /usr/local/share/lxrConfiguration will be stored in custom.d/directory custom.d createdConfigure for single/multiple trees? [S/m] > m*** LXR web server configuration ***LXR can be configured as the default server (the only service in your computer),a section of this default server or an independent server (with its ownhost name).Refer to the User's Manual for a description of the differences.Web server type? [1.DEFAULT/2.section in default/3.indepedent/4.section in indepedent] > 2The computer hosting the server is described by an URL.The form is scheme://host_name:portwhere:  - scheme is either http or https (http: can be omitted),  - host_name can be given as an IP address such as 123.45.67.89              or a domain name like localhost or lxr.url.example,  - port may be omitted if standard for the scheme.The following question asks for a primary URL. Later, you'll havethe opportunity to give aliases to this primary URL.--- Host name or IP? [//localhost] > URL section name for LXR in your server? [/lxr] > The built-in method to manage several trees with a single instance of LXR is to includea designation of the tree in the URL at the end of the section name.This sequence after host name is called "virtual root".Supposing one of your trees is to be referred as "my-tree", an URL to list the contentof the default version directory would presently be:     //localhost/lxr/my-tree/sourcewith virtual root equal to /lxr/my-treeUse built-in multiple trees management with tree designation at end of virtual root? [YES/no] > YES*** LXR database configuration ***The choice of the database engine can make a difference in indexing performance,but resource consumption is also an important factor.  * For a small personal project, try SQLite which do not    need a server and is free from configuration burden.  * For medium to large projects, choice is between MySQL,    PostgreSQL and Oracle.    Oracle is not a free software, its interface has not been    tested for a long time.  * PostgreSQL databases are smaller than MySQL's    and performance is roughly equivalent.  * MySQL is at its best with large-sized projects    (such as kernel cross-referencing) where it is fastest at the cost    of bigger databases.  * Take also in consideration the number of connected users.Database engine? [MYSQL/oracle/postgres/sqlite] > MYSQLThe safest option is to create one database per tree.You can however create a single database for all your trees with a specific set oftables for each tree (though this is not recommended).How do you setup the databases? [PER TREE/global] > globalName of global database? [lxr] > All databases can be accessed with the same username andcan also be described under the same names.Will you share database characteristics? [YES/no] > YES--- DB user name? [lxr] > --- DB password ? [lxrpw] > ERROR: neither glimpse nor swish-e found in $PATH!Is your source tree stored in a VCS repository? [yes/NO] > NODoes one of them exist in a non standard directory? [YES/no] > YES--- Which is it? [GLIMPSE/swish-e] > GLIMPSE--- Location? (e.g. /usr/share/glimpse-dir/glimpse) > /usr/local/bin/glimpse--- Location of indexer? (e.g. /usr/share/glimpse-dir/glimpseindex) > /usr/local/bin/glimpseindex--- Directory for glimpse databases? > /hwx/hwx/glimpse_DBtemplates directory templates/ now protected read-onlyIs your Apache version 2.4 or higher? [YES/no] > nofile .htaccess written into LXR root directoryfile apache2-require.pl written into configuration directoryfile apache-lxrserver.conf written into configuration directoryfile lighttpd-lxrserver.conf written into configuration directoryMercurial support files written into configuration directory*** LXR master configuration file setup ***    Global section part*** Configuring auxiliary tool paths*** Configuring host name or IP (as http://...)*** Host name previously defined as //localhost--- Alias name ? (hit return to stop) > lxr.hwx.com--- Alias name ? (hit return to stop) > *** Configuring HTML parameters*** 'Buttons-and-menus' interface is recommended for the kernel*** to avoid screen cluttering.--- Use 'buttons-and-menus' instead of 'link' interface? [YES/no] > YES*** Configuring file subsection*** Configuring "common factors"*** Marking tree section*** LXR master configuration file setup ***    Tree section part    SQL script for database initialisation*** Configuring LXR server parameters*** The virtual root is the fixed URL part after the hostname.*** The tree needs to be uniquely identified as e.g. /lxr/the_tree--- Tree designation for URL? (e.g. the_tree) > the_tree--- Caption in page header? (e.g. Project XYZZY displayed by LXR) > hwx's LXRDo you want a speed switch button for this tree ? [YES/no] > YES--- Short title for button? (e.g. XYZZY) > speed-hwxDo you need a specific encoding for this tree ? [yes/NO] > yes--- Encoding name? (e.g. iso-8859-1) > UTF-8*** Describing tree locationHow is your tree stored? [FILES/cvs/git/svn/hg/bk] > /hwx/hwx/lxr-tree/linux-2.6.11.1ERROR: invalid answer, try again ...How is your tree stored? [FILES/cvs/git/svn/hg/bk] > FILES*** A source directory contains one sub-directory for every version.--- Source directory? (e.g. /home/myself/project-tree) > /hwx/hwx/lxr-tree/linux-2.6.11.1Name to display for the path root? (e.g. Project or $v for version) [$v] > *** Enumerating versionsLabel for version selection menu?  [Version] > *** Versions can be explicitly enumerated, be read from a file or computed*** by a function. The latter case is recommended for VCS-stored trees.Version enumeration method? [LIST/file/function] > --- Version name? (hit return to stop) > 2.6.11.1--- Version name? (hit return to stop) > *** By default, first version in list is displayed. You may also indicate*** a prefered version.--- Default displayed version is first in 'range'? [YES/no] > YES*** Setting directory lists*** Some directories may contain non-public project data (binaries,*** compilers caches, SCM control data, ...). They can be hidden from LXR.--- Directory to ignore, e.g. CVSROOT or CVS? (hit return to stop) > *** If your source code uses "include" statements (#include, require, ...)*** LXR needs hints to resolve the destination file.--- Include directory, e.g. /include? (hit return to stop) > *** Configuring data storage--- DB table prefix? [lxr_] > *** Configure another tree? [YES/no] > noconfiguration saved in custom.d/lxr.confDB initialisation sript is custom.d/initdb.sh

==============================
配置数据库(./custom.d/initdb.sh)
==============================

$ sudo ./custom.d/initdb.sh [sudo] password for root: *** MySQL - Creating global user lxrEnter password: Enter password: *** MySQL - Creating global database lxr*** MySQL - Configuring tables lxr_ in database lxr

查看 ./custom.d/initdb.sh 文件内容，再登录到 MySQL 看 lxr 用户、lxr 数据库、表是否跟 ./custom.d/initdb.sh 文件中的一致

拷贝刚刚生成的 lxr 配置文件

$ sudo cp custom.d/lxr.conf .

=========
生成索引
=========

$ sudo ./genxref --url=http://localhost/lxr/the_tree --version=2.6.11.1syntax error at configuration file line 252, next token ???  (Might be a runaway multi-line LL string starting on line 165)

$ sudo vim ./custom.d/lxr.conf

发现 line 165:

'caption' => 'hwx's LXR'

很明显，这里有语法问题，改为 'hwx-LXR'

$ sudo cp custom.d/lxr.conf .

$ sudo ./genxref --url=http://localhost/lxr/the_tree --version=2.6.11.1[  OK  ]     Perl     version ... 5.10.1[  OK  ]     ctags    version ... 5.8Checked:    glimpse   version ... 4.18.5Checked: glimpseindex version ... 4.18.5Parameter 'swishbin' not defined - trying to find swish-eswish-e not found, `command -v swish-e` returned a null stringProcessing http://localhost/lxr/the_tree  == Version 2.6.11.1 This is glimpseindex version 4.18.5, 2006.permission denied or non-existent: /hwx/hwx/lxr-tree/linux-2.6.11.1/2.6.11.1Size of files being indexed = 0 B, Total #of files = 0Index-directory: "/hwx/hwx/glimpse_DB/lxr/the_tree/2.6.11.1"Glimpse-files created here:-rw-------. 1 root root      2 May 22 00:32 .glimpse_filenames-rw-------. 1 root root      0 May 22 00:32 .glimpse_filenames_index-rw-------. 1 root root      0 May 22 00:32 .glimpse_filetimes-rw-------. 1 root root     18 May 22 00:32 .glimpse_index-rw-------. 1 root root    163 May 22 00:32 .glimpse_messages-rw-------. 1 root root      0 May 22 00:32 .glimpse_partitions-rw-------. 1 root root    124 May 22 00:32 .glimpse_statistics-rw-------. 1 root root 262144 May 22 00:32 .glimpse_turbo*** 2.6.11.1 /*** 2.6.11.1 /

发现建立索引很快就完成了，内核这么大的文件，不可能这么快，发现：

permission denied or non-existent: /hwx/hwx/lxr-tree/linux-2.6.11.1/2.6.11.1Size of files being indexed = 0 B, Total #of files = 0

所以，索引根本就没有建立

$ sudo vim ./custom.d/lxr.conf

将

'sourceroot' => '/hwx/hwx/lxr-tree/linux-2.6.11.1'

改为

'sourceroot' => '/hwx/hwx/lxr-tree/linux'

然后将 linux-2.6.11.1 的路径由 "/hwx/hwx/lxr-tree/linux-2.6.11.1" 变为 “/hwx/hwx/lxr-tree/linux/2.6.11.1”


重新运行

$ sudo ./genxref --url=http://localhost/lxr/the_tree --version=2.6.11.1

开始建立索引
官方文档又这样一段话：
As an example, indexing the single 3.1 kernel took 2 hours 39 minutes on a high-end computer (Intel i5 3.3GHz processor and 4GB memory under Fedora 17, MySQL and Glimpse).
看到彻底无语，等到索引完毕，鸡都叫了，个还睡不睡啊？


==========
配置 Apache
==========
$ cp custom.d/apache-lxrserver.conf /etc/httpd/conf.d
$ chcon --reference /var/www/cgi-bin -R .


重启 Apache:

$ sudo service httpd stop停止 httpd：                                               [确定][hwx@hwx lxr]$ sudo service httpd start正在启动 httpd：Syntax error on line 41 of /etc/httpd/conf.d/apache-lxrserver.conf:Invalid command 'PerlTaintCheck', perhaps misspelled or defined by a module not included in the server configuration                                                           [失败]

探明原因（"Apache httpd with mod_perl is recommended"），应该是 mod_perl 的问题

用 yum 方式成功安装 mod_perl 之后重启 Apache:

$ sudo service httpd start正在启动 httpd：[Wed May 22 10:08:24 2013] [warn] module perl_module is already loaded, skippinghttpd: Could not reliably determine the server's fully qualified domain name, using hwx.centos for ServerName                                                           [确定]

To enable directory listing by Apache server:
将 ./.htaccess 中的

Options -Indexes

改为

Options +Indexes

==============
浏览器访问 tree
==============

http://localhost/lxr/the_tree/source

==============
安装 mod_perl
==============
说明：下面是一系列的蛋疼，用 yum 方式安装 mod_perl 的话，这些“蛋疼”就可以省去了（见前文）

$ perl Makefile.PL MP_APXS=/usr/local/apache2/bin/apxsCan't locate ExtUtils/Embed.pm in @INC (@INC contains: lib Apache-Test/lib /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5 .) at lib/Apache2/Build.pm line 27.BEGIN failed--compilation aborted at lib/Apache2/Build.pm line 27.Compilation failed in require at Makefile.PL line 37.BEGIN failed--compilation aborted at Makefile.PL line 37.

$ sudo yum install perl-devel perl-ExtUtils-Embed

$ perl Makefile.PL MP_APXS=/usr/local/apache2/bin/apxsReading Makefile.PL args from @ARGV   MP_APXS = /usr/local/apache2/bin/apxsno conflicting prior mod_perl version found - good.************* WARNING *************  Your Perl is configured to link against libgdbm,  but libgdbm.so was not found.  You could just symlink it to /usr/lib64/libgdbm.so.2.0.0************* WARNING *************[  error] Unable to determine server version, aborting.[  error] Invalid MP_APXS specified?

$ locate libgdbm.so/usr/lib64/libgdbm.so.2/usr/lib64/libgdbm.so.2.0.0$ cd /usr/lib64/$ sudo ln -s libgdbm.so.2.0.0 libgdbm.so

$ perl Makefile.PL MP_APXS=/usr/local/apache2/bin/apxsReading Makefile.PL args from @ARGV   MP_APXS = /usr/local/apache2/bin/apxsno conflicting prior mod_perl version found - good.[  error] Unable to determine server version, aborting.[  error] Invalid MP_APXS specified?

由于我是用 yum 安装的 apache, bin 文件的默认路径是 /usr/sbin, 而 "MP_APXS=/usr/local/apache2/bin/apxs" 说明 bin 文件路径为 "MP_APXS=/usr/local/apache2/bin", 因此改为 "MP_APXS=/usr/sbin/apxs"

$ perl Makefile.PL MP_APXS=/usr/sbin/apxsReading Makefile.PL args from @ARGV   MP_APXS = /usr/sbin/apxsno conflicting prior mod_perl version found - good.Configuring Apache/2.2.15 mod_perl/2.0.7 Perl/v5.10.1Checking if your kit is complete...Looks goodChecking if your kit is complete...Looks goodWriting Makefile for Apache2::ReloadChecking if your kit is complete...Looks goodWriting Makefile for Apache2::SizeLimitSubroutine MY::postamble redefined at ./Makefile.PL line 149.Subroutine MY::test redefined at ./Makefile.PL line 168.Subroutine MY::constants redefined at ./Makefile.PL line 188.[   info] generating script t/TEST[   info] generating script ./t/cgi-bin/cookies.pl[   info] generating script ./t/cgi-bin/next_available_port.plWriting Makefile for Apache::TestChecking for File::Spec...okChecking for Cwd...ok[   info] generating script t/TESTChecking if your kit is complete...Looks goodWriting Makefile for ModPerl::RegistryWriting Makefile for APR::Base64Writing Makefile for APR::BrigadeWriting Makefile for APR::BucketWriting Makefile for APR::BucketAllocWriting Makefile for APR::BucketTypeWriting Makefile for APR::DateWriting Makefile for APR::ErrorWriting Makefile for APR::FinfoWriting Makefile for APR::IpSubnetWriting Makefile for APR::OSWriting Makefile for APR::PoolWriting Makefile for APR::SockAddrWriting Makefile for APR::SocketWriting Makefile for APR::StatusWriting Makefile for APR::StringWriting Makefile for APR::TableWriting Makefile for APR::URIWriting Makefile for APR::UUIDWriting Makefile for APR::UtilWriting Makefile for APRWriting Makefile for Apache2::AccessWriting Makefile for Apache2::CmdParmsWriting Makefile for Apache2::CommandWriting Makefile for Apache2::ConnectionWriting Makefile for Apache2::ConnectionUtilWriting Makefile for Apache2::DirectiveWriting Makefile for Apache2::FilterWriting Makefile for Apache2::FilterRecWriting Makefile for Apache2::HookRunWriting Makefile for Apache2::LogWriting Makefile for Apache2::MPMWriting Makefile for Apache2::ModuleWriting Makefile for Apache2::ProcessWriting Makefile for Apache2::RequestIOWriting Makefile for Apache2::RequestRecWriting Makefile for Apache2::RequestUtilWriting Makefile for Apache2::ResponseWriting Makefile for Apache2::ServerRecWriting Makefile for Apache2::ServerUtilWriting Makefile for Apache2::SubProcessWriting Makefile for Apache2::SubRequestWriting Makefile for Apache2::URIWriting Makefile for Apache2::UtilWriting Makefile for Apache2Writing Makefile for ModPerl::GlobalWriting Makefile for ModPerl::UtilWriting Makefile for ModPerlWriting Makefile for ModPerl::WrapXSWriting Makefile for APRWriting Makefile for APR::ConstWriting Makefile for APR::PerlIOWriting Makefile for libaprextWriting Makefile for APR_buildWriting Makefile for Apache2::ConstWriting Makefile for Apache2_buildWriting Makefile for ModPerl::ConstWriting Makefile for ModPerlWriting Makefile for ModPerl::XSWriting Makefile for mod_perl2[warning] mod_perl dso library will be built as mod_perl.so[warning] You'll need to add the following to httpd.conf:[warning] [warning]   LoadModule perl_module modules/mod_perl.so[warning] [warning] depending on your build, mod_perl might not live in[warning] the modules/ directory.[warning] Check the results of[warning] [warning]   $ /usr/sbin/apxs -q LIBEXECDIR[warning] [warning] and adjust the LoadModule directive accordingly.

$ sudo make...cp lib/ModPerl/StructureMap.pm blib/lib/ModPerl/StructureMap.pmcp lib/Apache2/BuildConfig.pm blib/lib/Apache2/BuildConfig.pmcp lib/Apache2/porting.pm blib/lib/Apache2/porting.pmmake[1]: Entering directory `/share/linux-data/Downloads/mod_perl-2.0.7/Apache-Reload'cp lib/Apache/Reload.pm ../blib/lib/Apache/Reload.pmcp lib/Apache2/Reload.pm ../blib/lib/Apache2/Reload.pmManifying ../blib/man3/Apache::Reload.3pmCan't write-open ../blib/man3/Apache::Reload.3pm: Invalid argument at /usr/share/perl5/ExtUtils/Command/MM.pm line 141make[1]: *** [manifypods] Error 22make[1]: Leaving directory `/share/linux-data/Downloads/mod_perl-2.0.7/Apache-Reload'make: *** [subdirs] Error 2

问题始终解决不了，推测应该是 yum 安装 Apache 的路径跟源码安装 Apache 的方式不同，而源码安装 mod_perl 是遵从后者的，因此尝试用 yum 安装 mod_perl(见前文)，问题解决，重启 Apache 成功


=======
说明
=======
LXR root directory 即 "/usr/local/share/lxr"


==============
References
==============
LXR User's Manual, http://iweb.dl.sourceforge.net/project/lxr/doc/LXRUserManual-1.2-en_UK-1.4.pdf

LXR 1.0+ Installation Instructions, http://lxr.sourceforge.net/en/1-0-InstallSteps/1-0-install.shtml
配置多个项目, http://lxr.sourceforge.net/en/advancedconfig.shtml