0N/AOpenGrok - a wicked fast source browser
0N/A---------------------------------------
0N/A5. Optional Command Line Interface Usage
0N/A6. Change web application properties or name
0N/A8. Information for developers
0N/AOpenGrok is a fast and usable source code search and cross reference
115N/Aengine, written in Java. It helps you search, cross-reference and navigate
115N/Ayour source tree. It can understand various program file formats and
115N/Aversion control histories like SCCS, RCS, CVS, Subversion, Mercurial etc.
0N/AOffical page of the project is on:
0N/A * Latest Java (At least 1.6)
975N/A * A servlet container like Tomcat (
6.x or later)
975N/A supporting Servlet 2.4 and JSP 2.0
975N/A * Subversion 1.3.0 or later if SVN support is needed
975N/A * Mercurial 0.9.3 or later if Mercurial support is needed
975N/A * If you want to build OpenGrok:
0N/A - Ant (1.7 and later)
115N/A - Netbeans (optional, at least 7.1)
0N/AOpenGrok usually runs in servlet container (
e.g. Tomcat).
975N/ASRC_ROOT environment variable refers to the directory containing your source
975N/Atree. OpenGrok analyzes the source tree and builds a search index along with
975N/Across-referenced hypertext versions of the source files. These generated
975N/Adata files will be stored in directory referred to with environment variable
979N/AOpenGrok has a concept of Projects - one project is one directory underneath
979N/ASRC_ROOT directory which usually contains a checkout of a project sources.
975N/A(this can be branch, version, ...)
975N/AProjects effectively replace the need to have more web applications, each with
975N/Aopengrok .war file. Instead it leaves you with one indexer and one web
975N/Aapplication serving multiple source code repositories - projects.
979N/AThen you have a simple update script and simple index refresher script in
975N/Aplace, which simplifies management of more repositories.
975N/AA nice concept is to have a naming convention for directories underneath
975N/ASRC_ROOT, thereby creating a good overview of projects (
e.g. 975N/AFor example, the SRC_ROOT directory can contain the following directories:
975N/AEach of these directories was created with 'cvs checkout' command (with
975N/Aappropriate arguments to get given branch) and will be treated by OpenGrok
975N/ATo setup OpenGrok it is needed to prepare the source code, let OpenGrok index
975N/Ait and start the web application.
975N/A4.1 Setting up the sources
975N/A--------------------------
979N/ASource base must be available locally for OpenGrok to work efficiently.
975N/ANo changes are required to your source tree. If the code is under source
975N/Acontrol management (SCM) OpenGrok requires the checked out source tree under
975N/ABy itself OpenGrok does not perform the setup of the source code repositories
975N/Aor sychronization of the source code with its origin. This is to be done by
975N/Athe user or automatic scripts.
975N/AIt is possible for some SCM systems to use a remote repository (Subversion,
975N/ACVS), but this is not recommended due to the performance penalty. Special
975N/Aoption when running the OpenGrok indexer is needed to enable remote repository
975N/ANote that OpenGrok ignores symbolic links.
975N/A4.2 Using Opengrok wrapper script to create indexes
975N/A---------------------------------------------------
975N/AFor *nix systems there is a shell script called OpenGrok which simplifies most
975N/Aof the tasks. It has been tested on Solaris and Linux distributions.
975N/A4.2.1 - Deploy the web application
975N/A----------------------------------
975N/AFirst please change to opengrok directory where the OpenGrok shell script is
975N/Astored (can vary on your system).
975N/ANote that now you might need to change to user which owns the target
975N/Adirectories for data,
e.g. on Solaris you'd do:
979N/Aits directory to one of detected web application containers.
975N/APlease follow the error message it provides.
975N/AIf it fails to discover your container, please refer to optional steps on
975N/Achanging web application properties, which has manual steps on how to do
975N/Aavailable to user running opengrok with all permissions. In root user case
975N/Ait will create all the directories needed, otherwise you have to manually
975N/Acreate the directory and grant all permissions to the user used.
975N/A4.2.2 - Populate DATA_ROOT Directory
975N/A------------------------------------
975N/ADuring this process the indexer will generate OpenGrok XML configuration file
979N/AThe indexing can take a lot of time. After this is done, indexer automatically
979N/Aattempts to upload newly generated configuration to the web application.
975N/AMost probably you will not be able to use Opengrok before this is done for the
975N/APlease change to opengrok directory (can vary on your system)
984N/Aotherwise (if SRC_ROOT is in different directory) run:
975N/A $ ./OpenGrok index <absolute_path_to_your_SRC_ROOT>
984N/AAbove command should try to upload latest index status reflected into
984N/AOnce above command finishes without errors(
e.g. SEVERE: Failed to send
975N/Aconfiguration to localhost:2424
975N/A), you should be able to enjoy your opengrok and search your sources using
975N/Alatest indexes and setup.
0N/ACongratulations, you should now be able to point your browser to
0N/Ahttp://<YOUR_WEBAPP_SERVER>:<WEBAPPSRV_PORT>/source to work with your fresh
0N/AOpenGrok installation! :-)
911N/AAt this time we'd like to point out some customization to OpenGrok script
911N/AA common case would be, that you want the data in some other directory than
0N/AOPENGROK_INSTANCE_BASE.
0N/ASince above will also change default location of config file, beforehands(or
0N/Arestart your web container after creating this symlink) I suggest doing
0N/AMore customizations can be found inside the script, you just need to
0N/Ahave a look at it, eventually create a configuration out of it and use
0N/AOPENGROK_CONFIGURATION environment variable to point to it. Obviously such
0N/Asetups can be used for nightly cron job updates of index or other automated
0N/A4.3 Using smf service (Solaris) to maintain OpenGrok indexes
0N/A------------------------------------------------------------
0N/AIf you installed opengrok from a package, then configure the service like this:
115N/A # svccfg -s opengrok setprop \
0N/AThen make the service start the indexing, at this point it would be nice if
979N/Athe web application is already running.
0N/ANow enable the service:
0N/A # svcadm enable -rs opengrok
979N/ANote that this will enable tomcat6 service as dependency.
0N/AWhen the service starts indexing for first time, it's already enabled and
979N/Adepending on tomcat6, so at this point the web application should be
0N/ANote that indexing is not done when the opengrok service is disabled.
116N/ATo rebuild the index later (
e.g. after source code changed) just run:
116N/A # svcadm refresh opengrok
979N/ANote: before removing opengrok package please disable the service.
116N/AIf you don't do it, it will not be removed automatically.
979N/AIn such case please remove it manually.
979N/A4.4 Using command line interface to create indexes
116N/A--------------------------------------------------
979N/AThere are 2 (or 3) steps needed for this task.
979N/A4.4.1 - Populate DATA_ROOT Directory
979N/A------------------------------------
979N/AOption 1. OpenGrok: There is a sample shell script OpenGrok that is suitable
116N/Afor using in a cron job to run regularly. Modify the variables in the script
979N/Ato point appropriate directories, or as the code suggests factor your local
116N/Aconfiguration into a separate file and simplify future upgrades.
979N/Athe sources are all located in a directory SRC_ROOT and the data and
979N/Ahypertext files generated by OpenGrok are to be stored in DATA_ROOT, run
863N/A----------------------------------------------
863N/A * HEADER: is the fragment of HTML that will be used to display title or
863N/A * SRC_ROOT: absolute path name of the root directory of your source tree
863N/A * DATA_ROOT: absolute path of the directory where OpenGrok data
863N/A - Header file 'header_include' can be created under DATA_ROOT.
863N/A The contents of this file file will be appended to the header of each
863N/A web page after the OpenGrok logo element.
863N/A - Footer file 'footer_include' can be created under DATA_ROOT.
863N/A The contents of this file file will be appended to the footer of each
863N/A web page after the information about last index update.
863N/A4.4.3 - Path Descriptions
863N/A-------------------------
863N/AOpenGrok uses path descriptions in various places (For eg. while showing
863N/Adirectory listings or search results) Example descriptions are in
paths.tsv 863N/Afile. You can list descriptions for directories one per line tab separated
863N/Aformat path tab description. Refer to example 4 below.
863N/ANote 1 - Changing webapp parameters:
web.xml is the deployment descriptor
975N/A Then copy the war files to <i>TOMCAT</i>/webapps directory.
975N/A * Option 3: Edit the Context container element for the webapp
979N/A When invoking OpenGrok to build the index, use -w <webapp> to set the
975N/A After the index is built, there's a couple different ways to set the
975N/A Context for the servlet container:
975N/A <Parameter name="HEADER" value='...' override="false" />
975N/A - Create a Context file for the webapp
975N/A This file will be named `<webapp>.xml'.
975N/A For Tomcat, the file will be located at:
975N/A is the Engine that is processing requests and <hostname> is a Host
975N/A associated with that Engine. By default, this path is
975N/A This file will contain something like the Context described above.
975N/A4.5 Using Java DB for history cache
975N/A-----------------------------------
975N/ABy default OpenGrok stores history indexes in gzipped xml files. An alternative
975N/Ais to use Java DB instead. This has the advantage of less disk space and
975N/Aincremental indexing. On the other hand it consumes more system memory because
975N/Athe database has to run in background.
975N/AYou need Java DB 10.5.3 or later. To install it peform the following steps:
975N/A # apt-get install sun-java6-javadb
975N/AThere are two modes, having Java DB embedded, or running a Java DB server.
975N/AJava DB server is default option, we will not describe how to set up embedded
975N/A Use one of the following methods to start the database:
975N/A a) via SMF (preferred):
295N/AThe Java DB server has to be running during indexing and for the web
295N/ANote: To use a bigger database buffer, which may improve performance of both
295N/A5. Optional Command Line Interface Usage
295N/A----------------------------------------
295N/AYou need to pass location of project file + the query to Search class,
e.g. 341N/A6. Change web application properties or name
341N/A--------------------------------------------
341N/AYou might need to modify the web application if you don't store the
341N/Aconfiguration file in the default location
336N/Aparameters appropriately. These sample parameters need modifying(there are
301N/Amore options, refer to manual or read param comments).
301N/A * CONFIGURATION - the absolute path to XML file containing project
301N/A * ConfigAddress - port for remote updates to configuration, optional,
301N/A * but advised(since there is no authentication) to be set to
301N/A * localhost:<some_port> (
e.g. localhost:2424), if you choose some_port
301N/A * below 1024 you have to have root privileges
301N/AIf you need to change name of the web application from source to something
301N/Aelse you need to use special option -w <new_name> for indexer to create
301N/Aproper xrefs, besides changing the .war file name. Examples below show just
301N/A * Option 1: Use browser and log into glassfish web administration interface
301N/A Common Tasks / Applications / Web Applications , button Deploy and point
301N/A to deploy it "auto magically".
301N/A * Option 3: Use cli from GLASSFISH directory:
301N/ADeploy the modified .war file in tomcat:
301N/AThe indexer can be setup with agent and systray GUI control application.
301N/AThis is optional step for those who wish to monitor and configure OpenGrok
301N/Afrom their desktop using systray application.
301N/Astarting special OpenGrok Agent, where you can connect with a systray GUI
576N/ATo start the indexer with configuration run:
576N/AThen from the remote machine one can run:
379N/Aassuming configuration permits remote connections (
i.e. not listening on
379N/Alocalhost, but rather on a physical network interface).
379N/AThis agent is work in progress, so it might not fully work.
975N/A8. Information for developers
398N/A-----------------------------
379N/Ayou have to download Findbugs to your machine, and install it where you have
379N/AYou can now run ant with the findbugs target:
398N/A [findbugs] Executing findbugs from ant task
398N/A [findbugs] Running FindBugs...
398N/A [findbugs] Warnings generated: nnn
411N/AIf you want to install findbugs some other place than ~/.ant/lib, you can
411N/Atell ant where to find findbugs, like this (if you have installed fundbugs
411N/Aunder the lib directory):
411N/AThere is also a findbugs-xml ant target that can be used to generate XML files
411N/AIf you want to check test coverage on OpenGrok, download Emma from
411N/ANow you can instrument your classes, and create a jar file:
411N/AIf you are using NetBeans, select File - "opengrok" Properties
411N/AIf you are not using netbeans, you have to edit the file
411N/ANow you can put the classes into jars and generate distributable:
624N/Athe run time analysis, use these properties:
624N/Adirectory for easy analyze.
624N/AIf you want to test the coverage of the unit tests, you can
624N/AAlternatively press Alt+F6 in NetBeans to achieve the same.
624N/ANow you should get some output saying that Emma is placing runtime
624N/ATo generate reports, run ant again:
0N/ANote: For full coverage report your system has to provide proper junit test
13N/Aenvironment, that would mean:
975N/A - you have to use ant 1.7 and above
- at least junit-4.?.jar has to be in ants classpath (
e.g. in ./lib)
- your PATH must contain exuberant ctags binary
- your PATH variable must contain binaries of appropriate SCM SW, so
commands hg, sccs, cvs, git, bzr, svn (svnadmin too) must be available for
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: