Instructions below are given for a simple project tree.
The Linux kernel is a complex case
if you want to enable all the hyperlink possibilities.
Refer to this tip
once you have setup LXR at least on an easy case.
The outcome of the configuration step consists of a number of files
(master configuration file, server configuration files and,
most important, database schema).
All interactions and incompatibilities between parameters are taken into
account by the configuration wizard.
Since the rules are rather complex,
don't ever attempt a manual configuration:
you are likely to forget some important point
and your LXR will not work.
The configuration wizard configure-lxr.pl builds tailored copies from templates located in the
templates/ subdirectory
and stores them in the custom.d/ directory.
At the end of this step,
a file named lxr.conf
must be copied into the LXR root directory to be activated.
LXR and database configurations
Create both LXR and database configuration with script
configure-lxr.pl
$ ./scripts/configure-lxr.pl -vv
Apart from -vv (very verbose output),
the command uses default options,
i.e. output of lxr.conf configuration file
and init-db.sh database creation script
into custom.d/ directory based on template
lxr.conf.
*** LXR configurator (version: 2.2) ***
LXR root directory is /home/myself/lxr
Configuration will be stored in custom.d/
The configuration script builds a custom lxr.conf file
from the answers to a few questions.
Default answer (the one selected when you just hit "return")
is shown in uppercase.
You do not need to fully write the selected choice,
type enough characters to make the answer unambiguous.
When selecting an answer among proposed choices,
case does not matter: upper and lowercase are equivalent.
Tree-independent part
- Releases 1.1 and higher
Since configuring the web server is a bit tricky,
the following questions are intended to ease this task.
Configure for single/multiple trees? [S/m] >
Important!
This is the only choice which cannot be changed later
because it configures the web server in a non trivial way.
Answer S if you'll serve only a single tree for ever
(if you change your mind about it,
you'll have to start over from scratch,
erasing the existing database).
This is a perfect choice for a first trial.
Answer M if you intend to add another tree
some time in an undefined future.
Do you intend to add other trees later? [yes/NO] >
This question offers the possibility to correct a mistake.
Let's assume the default S choice was correct.
*** LXR web server configuration ***
Correctly managing the target tree in the URL means
coding the URL in a specific way.
The LXR design is to have LXR service designated after the host name,
then the desired tree.
If the only pages offered on the server come from LXR,
service name (usually /lxr) can be omitted.
This corresponds to the case of a site dedicated to LXR only.
In single tree context, there is no need to designate this unique tree.
This suppresses later the question about the virtual root.
- Releases 2.0 and higher
Many different configurations are possible, they are related to the way
LXR service is accessed, i.e. to the structure of the URL.
Refer to the User's Manual for a description of the variants.
LXR can be located at the server-root (so called dedicated)
or lower in the server hierarchy (shared because there are
usually other pages or sections).
Server type? [dedicated/SHARED] >
The default answer is accepted, so that the server may also dispkay other pages.
The computer hosting the server is described by an URL.
The form is !scheme://host_name:port
where:
- ! is an optional flag (see below),
- scheme is either http or https,
- host_name can be given as an IPv4 address such as 123.45.67.89,
an IPv6 address like [fe80::1234:90ab]
or a domain name like localhost or lxr.url.example,
- port is 1 to 65535.
Scheme: or :port must be specified if you want to restrict
access to the tree through the designated scheme or port.
This restriction is requested with the ! prefix flag.
- Releases 1.1 or higher
--- Host name or IP? [//localhost] >
The default local server is usually //localhost,
so just hit return.
--- Alias name ? (hit return to stop) > //mycomputer.example.com
--- Alias name ? (hit return to stop) >
Give as many aliases (eventually none) as you need.
URL section name for LXR in your server? [/lxr] >
This is the name under which LXR service will be accessed
through the URL.
CAUTION!
If you answer /,
you revert to case "dedicated" without warning.
This may cause serious malfunction in your existing web server.
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] >
Select the database engine according to your site policy
or to its availability.
- Releases 1.1 and higher
No specific question here
--- Directory for glimpse databases? > /home/myself/glimpse_DB
The configuration script detected the installed search engine
and requests a directory for its auxiliary files.
This directory will be created later by LXR if it does not exist.
CAUTION!
If you provide this directory yourself,
make sure it is "world-readable".
Tune Apache configuration
- Releases 2.1 and higher
Nothing is necessary because file apache-lxrserver.conf
now contains directive able to dynamically detect Apache version
and to react accordingly.
file .htaccess written into LXR root directory
file apache2-require.pl written into configuration directory
file apache-lxrserver.conf written into configuration directory
file lighttpd-lxrserver.conf written into configuration directory
file nginx-lxrserver.conf written into configuration directory
file thttpd-lxrserver.conf written into configuration directory
Mercurial support files written into configuration directory
This concludes the general purpose configuration part.
The script opens the master configuration file.
*** LXR master configuration file setup ***
Global section part
*** Configuring auxiliary tool paths
*** Configuring host name or IP (as http://...)
- Releases 1.1 or higher
*** Host name previously defined as //localhost
This line echoes the hostname
you defined during web server configuration above.
*** Configuring HTML parameters
- Releases 1.1 or higher
'Buttons-and-menus' interface is recommended for the kernel
to avoid screen cluttering.
--- Use 'buttons-and-menus' instead of 'link' interface? [YES/no] >
buttons-and-menus interface offers a denser layout
than the traditional link interface.
It is highly recommended in situations where the source tree
has many versions or,
as is the case with the Linux kernel,
where some kind of configuration control is implemented through
many auxiliary LXR variables.
*** Configuring file subsection
*** Configuring "common factors"
*** Marking tree section
The tree-independent part is now configured.
Tree-dependent part
*** 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.
- Release 1.1 or higher
*** You previously defined the virtual root as /lxr
This line echoes the virtual root
implied or defined during web server configuration above.
--- Caption in page header? (e.g. Project XYZZY displayed by LXR) > LXR first trial
This defines the title in the header area of every page.
Do you need a specific encoding for this tree ? [yes/NO] >
The default encoding is UTF-8.
If your tree uses another encoding, answer Y
and enter an IANA-registered encoding, such as iso-8859-1.
*** Describing tree location
How is your tree stored? [FILES/cvs/git/subversion/bitkeeper] >
*** A source directory contains one sub-directory for every version.
--- Source directory? (e.g. /home/myself/project-tree) > /home/myself/my-project
Make your first trial on a tree composed of real files and directories
(i.e. not stored in a VCS repository).
Note that the path to the project directory is in
OS-absolute form.
REMINDER!
LXR is aimed at browsing among different versions of a project.
Consequently, it expects to find version directories in the designated
source directory,
such as /home/myself/my-project/v1, …,
even if you have only one version.
Name to display for the path root? (e.g. Project or $v for version) [$v] >
This is a replacement for the source directory part of a file path
to be displayed in the page header.
The default $v answer dynamically inserts the version
name.
*** Enumerating versions
Label 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) > v1
--- 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] >
Tell LXR how many versions there are in the source directory.
To stop version request, answer with an empty name
(just hit "return").
Tip:
To have the latest version displayed by default,
list them in reverse chronological order,
latest first, oldest last.
*** 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 .git? (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) >
Leave aside these questions for simple user source tree.
They allow to "hide" some subdirectories from LXR
and to resolve the include directives in the source.
*** Configuring data storage
--- Database name? > lxr_myproject
--- DB user name? [lxr] >
--- DB password? [lxrpw] >
--- DB table prefix? [lxr_] >
configuration saved in custom.d/lxr.conf
DB initialisation sript is custom.d/initdb.sh
Give a name to the database according to your site rules.
Anyway, it is a good idea to have it unique,
unless you define this database as a specific set of tables
in an existing one.
In this case, give a unique table prefix
instead of the default lxr_.
The tree-specific part is now configured
and you're done.
Database creation
The database initialisation script does its job under the master user
(by default root for MySQL
and postgres for PostgreSQL).
If it has been changed on your computer,
edit initdb.sh.
Launch the script generated in the previous step.
$ ./custom.d/initdb.sh
Note:
Under MySQL, the master passsword is requested
several times.
Ignore the errors about inexistent objects
(user, database, tables, …).
This script proceeds by tentatively deleting the objects
before creating them,
so that it can be used anytime to restart in a consistent state.
CAVEAT!
It is safer to delete this script as soon as it has been run
since script configure-lxr.pl always adds at the end
of initdb.sh without erasing
(this feature allows to split a multiple-trees configuration
into several sessions and run database initialisation only once
at the end of the process).
Failing to delete keeps all previous database creations.
When the script is run again, new databases are created
and older ones are recreated, thus losing their content.
Copy lxr.conf to its final location
Eventually, manually tune the configuration parameters before the copy.
$ cp custom.d/lxr.conf .
Use of cp instead of mv allows to add other
trees later without reconfiguring everything.
For an example of parameter values
for the demo trees on SourceForge,
see here.
You're now ready to load the database with your data.
