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