3853N/A# Copyright (c) 2006, 2012, Oracle
and/or its affiliates. All rights reserved.
3853N/AOpenGrok - a wicked fast source browser
3853N/A---------------------------------------
3853N/A5. Optional Command Line Interface Usage
3853N/A6. Change web application properties or name
3853N/A8. Information for developers
3853N/AOpenGrok is a fast and usable source code search and cross reference
3853N/Aengine, written in Java. It helps you search, cross-reference and navigate
5960N/Ayour source tree. It can understand various program file formats and
3853N/Aversion control histories like SCCS, RCS, CVS, Subversion, Mercurial etc.
3853N/AOffical page of the project is on:
3853N/A * Latest Java (At least 1.6)
3853N/A * A servlet container like Tomcat (
6.x or later)
3853N/A supporting Servlet 2.4 and JSP 2.0
3853N/A * Subversion 1.3.0 or later if SVN support is needed
4134N/A * Mercurial 0.9.3 or later if Mercurial support is needed
3853N/A * If you want to build OpenGrok:
3853N/A - Netbeans (optional, at least 7.1, will need Ant 1.8.1)
3853N/AOpenGrok usually runs in servlet container (
e.g. Tomcat).
3853N/ASRC_ROOT environment variable refers to the directory containing your source
3853N/Atree. OpenGrok analyzes the source tree and builds a search index along with
3853N/Across-referenced hypertext versions of the source files. These generated
3853N/Adata files will be stored in directory referred to with environment variable
3853N/AOpenGrok has a concept of Projects - one project is one directory underneath
3853N/ASRC_ROOT directory which usually contains a checkout of a project sources.
4134N/A(this can be branch, version, ...)
4134N/AProjects effectively replace the need to have more web applications, each with
4134N/Aopengrok .war file. Instead it leaves you with one indexer and one web
4134N/Aapplication serving multiple source code repositories - projects.
4134N/AThen you have a simple update script and simple index refresher script in
4134N/Aplace, which simplifies management of more repositories.
4134N/AA nice concept is to have a naming convention for directories underneath
5319N/ASRC_ROOT, thereby creating a good overview of projects (
e.g. 4134N/AFor example, the SRC_ROOT directory can contain the following directories:
4134N/AEach of these directories was created with 'cvs checkout' command (with
4134N/Aappropriate arguments to get given branch) and will be treated by OpenGrok
4134N/ATo setup OpenGrok it is needed to prepare the source code, let OpenGrok index
4134N/Ait and start the web application.
4134N/ASource base must be available locally for OpenGrok to work efficiently.
4134N/ANo changes are required to your source tree. If the code is under source
4134N/Acontrol management (SCM) OpenGrok requires the checked out source tree under
4134N/ABy itself OpenGrok does not perform the setup of the source code repositories
4134N/Aor sychronization of the source code with its origin. This is to be done by
4134N/Athe user or automatic scripts.
4134N/AIt is possible for some SCM systems to use a remote repository (Subversion,
4134N/ACVS), but this is not recommended due to the performance penalty. Special
5319N/Aoption when running the OpenGrok indexer is needed to enable remote repository
3853N/ANote that OpenGrok ignores symbolic links.
3853N/A4.2 Using Opengrok wrapper script to create indexes
3853N/A---------------------------------------------------
3853N/AFor *nix systems there is a shell script called OpenGrok which simplifies most
3853N/Aof the tasks. It has been tested on Solaris and Linux distributions.
3853N/A4.2.1 - Deploy the web application
3853N/A----------------------------------
3853N/AFirst please change to opengrok directory where the OpenGrok shell script is
3853N/Astored (can vary on your system).
3853N/ANote that now you might need to change to user which owns the target
3853N/Aits directory to one of detected web application containers.
3853N/APlease follow the error message it provides.
3853N/AIf it fails to discover your container, please refer to optional steps on
3853N/Achanging web application properties below, which explains how to do this.
3853N/Aavailable to user running opengrok with all permissions. In root user case
3853N/Ait will create all the directories needed, otherwise you have to manually
3853N/Acreate the directory and grant all permissions to the user used.
3853N/A4.2.2 - Populate DATA_ROOT Directory
3853N/A------------------------------------
5960N/ADuring this process the indexer will generate OpenGrok XML configuration file
3853N/AThe indexing can take a lot of time. After this is done, indexer automatically
3853N/Aattempts to upload newly generated configuration to the web application.
3853N/AMost probably you will not be able to use Opengrok before this is done for the
3853N/APlease change to opengrok directory (can vary on your system)
3853N/Aotherwise (if SRC_ROOT is in different directory) run:
3853N/A $ ./OpenGrok index <absolute_path_to_your_SRC_ROOT>
3853N/AThe above command attempts to upload the latest index status reflected into
3853N/AOnce above command finishes without errors
3853N/A(
e.g. SEVERE: Failed to send configuration to localhost:2424),
3853N/Ayou should be able to enjoy your opengrok and search your sources using
3853N/ACongratulations, you should now be able to point your browser to
3853N/Ahttp://<YOUR_WEBAPP_SERVER>:<WEBAPPSRV_PORT>/source to work with your fresh
3853N/AAt this time we'd like to point out some customization to OpenGrok script
3853N/AA common case would be, that you want the data in some other directory than
3853N/ASince above will also change default location of config file, beforehands(or
3853N/Arestart your web container after creating this symlink) I suggest doing
3853N/AMore customizations can be found inside the script, you just need to
3853N/Ahave a look at it, eventually create a configuration out of it and use
3853N/AOPENGROK_CONFIGURATION environment variable to point to it. Obviously such
3853N/Asetups can be used for nightly cron job updates of index or other automated
3853N/A4.3 Using SMF service (Solaris) to maintain OpenGrok indexes
3853N/A------------------------------------------------------------
3853N/AIf you installed OpenGrok from the OSOLopengrok package, it will work out of
3853N/Athe box. Should you need to configure it (
e.g. because of non-default SRC_ROOT
3853N/Aor DATA_ROOT paths) it is done via the 'opengrok' property group of the
3853N/A # svccfg -s opengrok setprop \
3853N/AThen make the service start the indexing, at this point it would be nice if
3853N/Athe web application is already running.
3853N/A # svcadm enable -rs opengrok
3853N/ANote that this will enable tomcat6 service as dependency.
3853N/AWhen the service starts indexing for first time, it's already enabled and
3853N/Adepending on tomcat6, so at this point the web application should be
3853N/ANote that indexing is not done when the opengrok service is disabled.
3853N/ATo rebuild the index later (
e.g. after source code changed) just run:
3853N/AThe service makes it possible to supply part of the configuration via the
3853N/ANote: before removing the package please disable the service.
3853N/AIf you don't do it, it will not be removed automatically.
3853N/AIn such case please remove it manually.
3853N/A4.4 Using command line interface to create indexes
3853N/A--------------------------------------------------
3853N/AThere are 2 (or 3) steps needed for this task.
3853N/A4.4.1 - Populate DATA_ROOT Directory
3853N/A------------------------------------
3853N/AOption 1. OpenGrok: There is a sample shell script OpenGrok that is suitable
3853N/Afor using in a cron job to run regularly. Modify the variables in the script
3853N/Ato point appropriate directories, or as the code suggests factor your local
3853N/Aconfiguration into a separate file and simplify future upgrades.
3853N/Athe sources are all located in a directory SRC_ROOT and the data and
3853N/Ahypertext files generated by OpenGrok are to be stored in DATA_ROOT, run
3853N/A----------------------------------------------
3853N/A * HEADER: is the fragment of HTML that will be used to display title or
3853N/A * SRC_ROOT: absolute path name of the root directory of your source tree
3853N/A * DATA_ROOT: absolute path of the directory where OpenGrok data
3853N/A - Header file 'header_include' can be created under DATA_ROOT.
3853N/A The contents of this file file will be appended to the header of each
3853N/A web page after the OpenGrok logo element.
3853N/A - Footer file 'footer_include' can be created under DATA_ROOT.
3853N/A The contents of this file file will be appended to the footer of each
3853N/A web page after the information about last index update.
3853N/A4.4.3 - Path Descriptions (optional)
3853N/A------------------------------------
3853N/AOpenGrok can use path descriptions in various places (
e.g. while showing
3853N/Adirectory listings or search results). Example descriptions are in
paths.tsv 3853N/AThe
paths.tsv file is read by OpenGrok indexing script from the configuration
3853N/Athen be used by the webapp to display the descriptions.
3853N/AThe file contains descriptions for directories one per line. Path to the
3853N/Adirectory and its description are separated by tab. The path to the directory
3853N/Ais absolute path under the SRC_ROOT directory.
3853N/AFor example, if the SRC_ROOT directory contains the following directories:
3853N/ANote that only some paths can have a description.
3853N/A4.4.4 - Changing webapp parameters (optional)
4134N/A---------------------------------------------
4134N/Aweb.xml is the deployment descriptor for the web application. It is in a Jar
edit
web.xml and re-package the jar file.
Then copy the war files to <i>TOMCAT</i>/webapps directory.
* Option 3: Edit the Context container element for the webapp
When invoking OpenGrok to build the index, use -w <webapp> to set the
After the index is built, there's a couple different ways to set the
Context for the servlet container:
<Parameter name="HEADER" value='...' override="false" />
- Create a Context file for the webapp
This file will be named `<webapp>.xml'.
For Tomcat, the file will be located at:
`
TOMCAT/conf/<engine_name>/<hostname>', where <engine_name>
is the Engine that is processing requests and <hostname> is a Host
associated with that Engine. By default, this path is
This file will contain something like the Context described above.
4.4.5 Custom ctags configuration
--------------------------------
specify configuration file with extra configuration options for ctags.
This can be done by setting OPENGROK_CTAGS_OPTIONS_FILE environment variable
when running the OpenGrok shell script (or directly with the -o option for
opengrok.jar). Default location for the configuration file in the OpenGrok
Sample configuration file for Solaris code base is delivered in the doc/
4.5 Using Java DB for history cache
-----------------------------------
By default OpenGrok stores history indexes in gzipped xml files. An alternative
is to use Java DB instead. This has the advantage of less disk space and
incremental indexing. Also, for some Source Code Management systems the
History view will show a list of files modified with given change.
On the other hand it consumes more system memory because the database has to
You need Java DB 10.5.3 or later. To install it peform the following steps:
# apt-get install sun-java6-javadb
There are two modes, having Java DB embedded, or running a Java DB server.
Java DB server is the default option, we will not describe how to set up the
Use one of the following methods to start the database:
E.g. for Tomcat it is located in the WEB-INF directory which was created
For example on Solaris 11 with bundled Java DB and Tomcat the command
This is achieved by setting the OPENGROK_DERBY environment variable when
using the OpenGrok shell script.
The Java DB server has to be running during indexing and for the web
Note: To use a bigger database buffer, which may improve performance of both
the JavaDB data directory and add this line to it:
- If using specific data directory:
- Using default directory on Solaris with JavaDB being run from SMF:
5. Optional Command Line Interface Usage
----------------------------------------
You need to pass location of project file + the query to Search class,
e.g.6. Change web application properties or name
--------------------------------------------
You might need to modify the web application if you don't store the
configuration file in the default location
To configure the webapp
source.war, look into the parameters defined in
parameters appropriately. These sample parameters need modifying(there are
more options, refer to manual or read param comments).
* CONFIGURATION - the absolute path to XML file containing project
* ConfigAddress - port for remote updates to configuration, optional,
* but advised(since there is no authentication) to be set to
* localhost:<some_port> (
e.g. localhost:2424), if you choose some_port
* below 1024 you have to have root privileges
If you need to change name of the web application from source to something
else you need to use special option -w <new_name> for indexer to create
proper xrefs, besides changing the .war file name. Examples below show just
* Option 1: Use browser and log into glassfish web administration interface
Common Tasks / Applications / Web Applications , button Deploy and point
to deploy it "auto magically".
* Option 3: Use cli from GLASSFISH directory:
Deploy the modified .war file in tomcat:
The indexer can be setup with agent and systray GUI control application.
This is optional step for those who wish to monitor and configure OpenGrok
from their desktop using systray application.
starting special OpenGrok Agent, where you can connect with a systray GUI
To start the indexer with configuration run:
Then from the remote machine one can run:
assuming configuration permits remote connections (
i.e. not listening on
localhost, but rather on a physical network interface).
This agent is work in progress, so it might not fully work.
8. Information for developers
-----------------------------
Just run 'ant' from command line in the top-level directory or use build
process driven by graphical developer environment such as Netbeans.
Run 'ant package' to create package (specific for the operating system this is
being executed on) under the dist/ directory.
Note: For full coverage report your system has to provide proper junit test
environment, that would mean:
- you have to use Ant 1.7 and above
- Example install in the top of the opengrok repository:
- install
derby.jar to ant's classpath so that Java DB tests can be run
- your PATH must contain directory with exuberant ctags binary
- Note: make sure that the directory which contains exuberant ctags binary
is prepended before the directory with plain ctags program.
- your PATH variable must contain directories which contain binaries of
appropriate SCM software which means commands hg, sccs, cvs, git, bzr, svn
(svnadmin too). They must be available for the full report.
The tests are then run as follows:
To check if the test completed without error look for AssertionFailedError
you have to download Findbugs to your machine, and install it where you have
checked out your OpenGrok source code, under the
lib/findbugs directory,
You can now run ant with the findbugs target:
[findbugs] Executing findbugs from ant task
[findbugs] Running FindBugs...
[findbugs] Warnings generated: nnn
If you want to install findbugs some other place than ~/.ant/lib, you can
tell ant where to find findbugs, like this (if you have installed fundbugs
under the lib directory):
There is also a findbugs-xml ant target that can be used to generate XML files
that can later be parsed,
e.g. by Jenkins.
If you want to check test coverage on OpenGrok, download Emma from
Now you can instrument your classes, and create a jar file:
If you are using NetBeans, select File - "opengrok" Properties
- libraries - Compile tab. Press the "Add
JAR/Folder" and select
If you are not using netbeans, you have to edit the file
Now you can put the classes into jars and generate distributable:
the run time analysis, use these properties:
directory for easy analyze.
If you want to test the coverage of the unit tests, you can
Alternatively press Alt+F6 in NetBeans to achieve the same.
Now you should get some output saying that Emma is placing runtime
To generate reports, run ant again:
To check that your code follows the standard coding conventions,
You need Version 5.3 (or newer). Extract the package you have
$ ln -s checkstyle-5.3 checkstyle
You also have to create symbolic links to the jar files:
To run checkstyle on the source code, just run ant checkstyle:
Output from the command will be stored in the checkstyle directory.
If you want to install checkstyle some other place than ~/.ant/lib, you can
to tell ant where to find checkstyle, like this (if you have installed
checkstyle under the lib directory):
To check the quality of the OpenGrok code you can also use PMD
You also have to make links to the jar files:
To run PMD on the rource code, just run ant pmd:
Outout from the command will be stored in the pmd subdirectory:
If you want to install PMD some other place than ~/.ant/lib, you can
unzip the .zip file to a directory, and use the
pmd.home property
to tell ant where to find PMD, like this (if you have installed
PMD under the lib directory):
To run CPD, just use the same as above, but use targets:
To see dependencies in the source code, you can use JDepend from
$ ln -s jdepend-2.9/ jdepend
Output is stored in the jdepend directory:
The project has been originally conceived in Sun Microsystems by Chandan
B.N.Martin Englund, Sun Microsystems
Feel free to participate in discussion on opengrok-discuss@opensolaris.org.
You can subscribe via web interface on: