0N/AOpenGrok - a wicked fast source browser
0N/A---------------------------------------
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
115N/Aversion control histories like SCCS, RCS, CVS, Subversion and Mercurial.
0N/AOpenGrok is the tool used for the OpenSolaris Source Browser.
116N/A * A servlet container like Tomcat (
5.x or later)
116N/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
115N/A * JFlex Ant task (If you want to build OpenGrok)
0N/ASRC_ROOT refers to the directory containing your source tree.
0N/AOpenGrok analyzes the source tree and builds a search index along with
0N/Across-referenced hypertext versions of the source files. These generated
0N/Adata files will be stored in DATA_ROOT directory.
975N/AProject concept - one project is one directory underneath SRC_ROOT and
975N/Ausually contains a checkout of a project(or it's branch, version, ...)
975N/Asources, it can have several attributes (in its XML description), note that
975N/Ainterface of projects is being stabilized so it can change. Projects
975N/Aeffectively replace need for more web applications with opengrok .war and
975N/Aleave you with one indexer and one web application serving MORE source code
975N/Arepositories - projects. A nice concept is to have directories underneath
975N/ASRC_ROOT with a naming convention, thereby creating a good overview of
975N/Aprojects (
e.g. name-version-branch). Then you have a simple update script &
975N/Asimple index refresher script in place, which simplifies management of more
0N/AOpenGrok setup Step.0 - Setting up the Sources.
0N/A----------------------------------------------
0N/ASource base must be available locally for OpenGrok to work efficiently. No
115N/Achanges are required to your source tree. If the code is under source control
115N/Amanagement (SCM) OpenGrok requires the checked out source tree under SRC_ROOT.
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 is needed to enable remote repository support(-r on).
0N/ANote that OpenGrok ignores symbolic links.
0N/A---------------------------------------------------
975N/AUsing Opengrok wrapper script(Solaris and Linux) to create indexes.
975N/A---------------------------------------------------
975N/AStep.1 - Deploy the web application
975N/A=====================================
975N/AWe provided you with OpenGrok wrapper script, which should aid in deploying
975N/APlease change to opengrok directory (can vary on your system)
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
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/AStep.2 - Populate DATA_ROOT Directory, let the indexer generate the project
975N/A=====================================
975N/ASecond step is to just run the indexing (can take a lot of time). After this
975N/Ais done, indexer automatically attempts to upload newly generated
975N/Aconfiguration to the web application. Most probably you will not be able to
975N/Ause {Opengrok before this is done.
975N/APlease change to opengrok directory (can vary on your system)
975N/Aotherwise (if SRC_ROOT is in different directory) run:
975N/A# ./OpenGrok index <absolute_path_to_your_SRC_ROOT>
975N/AAbove command should try to upload latest index status reflected into
975N/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.
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/Aopengrok installation! :-)
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/AThis can be easily achieved by using environment variable
975N/AOPENGROK_INSTANCE_BASE .
975N/A# OPENGROK_REMOTE_REPOS=true OPENGROK_VERBOSE=true \
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
975N/AA lot more 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
975N/A---------------------------------------------------
975N/AUsing smf service(Solaris and OpenSolaris only) to maintain opengrok indexes.
975N/A---------------------------------------------------
975N/AIf you installed opengrok from a package, then configure the service like this:
975N/Athen make the service start the indexing, at this point it would be nice if
975N/Athe web application is already running.
975N/A# svcadm enable opengrok
975N/Ato force a rebuild just run:
975N/A# svcadm refresh opengrok
975N/A---------------------------------------------------
975N/AUsing command line interface(general pointers) to create indexes.
0N/A---------------------------------------------------
0N/AStep.1 - Populate DATA_ROOT Directory
0N/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
0N/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
0N/A * SRC_ROOT: the absolute path name of the root directory of your source tree
0N/A * DATA_ROOT: absolute path of the directory where OpenGrok data
0N/AOptional Step.3 - Path Descriptions
0N/A-----------------------------------
0N/AOpenGrok uses path descriptions in various places (For eg. while showing
0N/Adirectory listings or search results) Example descriptions are in
paths.tsv 0N/Afile. You can list descriptions for directories one per line tab separated
0N/Aformat path tab description. Refer to example 4 below.
115N/ANote 1 - Changing webapp parameters:
web.xml is the deployment descriptor
0N/Afor the web application. It is in a Jar file named
source.war, you can
0N/A Then copy the war files to <i>TOMCAT</i>/webapps directory.
116N/A * Option 3: Edit the Context container element for the webapp
116N/A When invoking OpenGrok to build the index, use -w <webapp> to set the
116N/A After the index is built, there's a couple different ways to set the
116N/A Context for the servlet container:
116N/A <Parameter name="HEADER" value='...' override="false" />
116N/A - Create a Context file for the webapp
116N/A This file will be named `<webapp>.xml'.
116N/A For Tomcat, the file will be located at:
116N/A is the Engine that is processing requests and <hostname> is a Host
116N/A associated with that Engine. By default, this path is
116N/A This file will contain something like the Context described above.
0N/A---------------------------------------------------
863N/AUsing Java DB for history cache
863N/A(instead of gzipped xml files)
863N/A---------------------------------------------------
901N/AYou need Java DB 10.5.3 or later
901N/A(OpenSolaris: # pkg install SUNWjavadb or SUNWj6dev ,
863N/AThere are two modes, having Java DB embedded, or running a Java DB server.
863N/AJava DB server is default option, I will not describe how to set up embedded
863N/AAlso the Java DB server has to be running during indexing and for the web application.
863N/ANote: To use a bigger database buffer, which may improve performance of both
863N/A---------------------------------------------------
975N/AOptional CLI - Command Line Interface Usage
975N/A---------------------------------------------------
975N/A You need to pass location of project file + the query to Search class,
e.g. 975N/A---------------------------------------------------
975N/AOptional need to change web application properties or name
975N/A---------------------------------------------------
975N/A You 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,
975N/A * but advised(since there is no authentification) 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
975N/A-----------------------------------
975N/A * Option 1: Use browser and log into glassfish web administration
975N/A Common Tasks / Applications / Web Applications , button Deploy and point
975N/A * to deploy it "automagically".
975N/A * Option 3: Use cli from GLASSFISH directory:
975N/ADeploy the modified .war file in tomcat:
975N/A-----------------------------------
975N/A---------------------------------------------------
295N/A---------------------------------------------------
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
341N/AIf you want to install findbugs some other place than ~/.ant/lib, you can untar the
341N/Afindbugs, like this (if you have installed fundbugs under the lib directory):
341N/AThere is also a findbugs-xml ant target that can be used to generate XML files that can
301N/A---------------------------------------------------
301N/A---------------------------------------------------
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
301N/ANow you can put the classes into jars and generate distributables:
301N/Athe run time analysis, use these properties:
301N/Adirectory for easy analyzation.
301N/AIf you want to test the coverage of the unit tests, you can
301N/A ant test (Or Alt+F6 in NetBeans)
301N/ANow you should get some output saying that Emma is placing runtime
301N/ATo generate reports, run ant again:
576N/ANote: For full coverage report your system has to provide proper junit test
576N/Aenvironment, that would mean:
576N/A- you have to use ant 1.7 and above
576N/A- at least junit-4.?.jar has to be in ants classpath (
e.g. in ./lib)
576N/A- your PATH must contain exuberant ctags binary
576N/A- your PATH variable must contain binaries of appropriate SCM SW, so commands
576N/Ahg, sccs, cvs, git, bzr, svn (svnadmin too) must be available for full report
379N/A---------------------------------------------------
379N/A---------------------------------------------------
379N/ATo check that your code follows the standard coding conventions,
975N/AYou need Version 5.1 (or newer). Extract the package you have
975N/A ln -s checkstyle-5.1 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/A---------------------------------------------------
411N/A---------------------------------------------------
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:
411N/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):
624N/A---------------------------------------------------
624N/A---------------------------------------------------
624N/ATo see dependencies in the source code, you can use JDepend from
624N/A ln -s jdepend-2.9/ jdepend
624N/AOutput is stored in the jdepend directory:
13N/AMartin Englund, Sun Microsystems
136N/AKnut Anders Hatlen, Sun Microsystems
975N/ALubos Kosco, Sun Microsystems