0N/AOpenGrok - a wicked fast source browser

0N/A---------------------------------------

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/A

0N/AOpenGrok is the tool used for the OpenSolaris Source Browser.

0N/A

0N/ARequirements

0N/A------------

115N/A * Latest Java http://java.sun.com/ (At least 1.5)

116N/A * A servlet container like Tomcat (5.x or later)

0N/A http://tomcat.apache.org/

116N/A supporting Servlet 2.4 and JSP 2.0

0N/A * Exuberant Ctags http://ctags.sourceforge.net/

0N/A * Subversion 1.3.0 or later if SVN support is needed

0N/A http://subversion.tigris.org/

115N/A * Mercurial 0.9.3 or later if Mercurial support is needed

115N/A http://www.selenic.com/mercurial/wiki/

115N/A * JFlex Ant task (If you want to build OpenGrok)

13N/A http://www.jflex.org/

0N/A

0N/A

0N/AUsage

0N/A-----

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.

0N/A

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.

115N/AIt is possible for some SCM systems to use a remote repository (Subversion),

115N/Abut this is not recommended due to the performance penalty. CVS must have a

115N/Alocal repository.

0N/ANote that OpenGrok ignores symbolic links.

0N/A

0N/A---------------------------------------------------

0N/AUsing command line interface.

0N/A---------------------------------------------------

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

0N/Afor using in a cronjob to run regularly. Modify the variables in the script

299N/Ato point appropriate directories, or as the code suggests factor your local

299N/Aconfiguration into a seperate file and simplify future upgrades.

0N/A

0N/AOption 2. opengrok.jar: You can also directly use the Java application. If

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

205N/A $ java -jar opengrok.jar -s SRC_ROOT -d DATA_ROOT

0N/A

0N/ASee opengrok.jar manual below for more details.

0N/A

0N/AStep.2 - Configure and Deploy source.war Webapp

0N/A===============================================

0N/ATo configure the webapp source.war, look into the parameters defined in

0N/Aweb.xml of source.war file and change them (see note1) appropriately.

0N/A

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/A files are stored

0N/A

0N/A

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.

0N/A

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

116N/Achange the :

0N/A

0N/A * Option 1: Unzip the file to TOMCAT/webapps/source/ directory and

0N/A change the source/WEB-INF/web.xml and other static html files like

0N/A index.html to customize to your project.

0N/A

0N/A * Option 2: Extract the web.xml file from source.war file

0N/A

0N/A $ unzip source.war WEB-INF/web.xml

0N/A

0N/A edit web.xml and re-package the jar file.

0N/A

0N/A $ zip -u source.war WEB-INF/web.xml

0N/A

0N/A Then copy the war files to <i>TOMCAT</i>/webapps directory.

0N/A

116N/A * Option 3: Edit the Context container element for the webapp

116N/A

116N/A Copy source.war to TOMCAT/webapps

116N/A

116N/A When invoking OpenGrok to build the index, use -w <webapp> to set the

116N/A context.

116N/A

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 - Add the Context inside a Host element in TOMCAT/conf/server.xml

116N/A

116N/A <Context path="/<webapp>" docBase="source.war">

116N/A <Parameter name="DATA_ROOT" value="/path/to/data/root" override="false" />

116N/A <Parameter name="SRC_ROOT" value="/path/to/src/root" override="false" />

116N/A <Parameter name="HEADER" value='...' override="false" />

164N/A <Parameter name="SCAN_REPOS" value="false" override="false" />

116N/A </Context>

116N/A

116N/A - Create a Context file for the webapp

116N/A

116N/A This file will be named `<webapp>.xml'.

116N/A

116N/A For Tomcat, the file will be located at:

116N/A `TOMCAT/conf/<engine_name>/<hostname>', where <engine_name>

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 'TOMCAT/conf/Catalina/localhost' or 'TOMCAT/conf/Standalone/localhost'.

116N/A

116N/A This file will contain something like the Context described above.

116N/A

120N/AOptional Step 4 -- Subversion setup

120N/A-----------------------------------

177N/ASome additional setup is needed if you are using Subversion. OpenGrok uses

177N/Athe Subversion javahl bindings, which must be installed separately.

120N/A

177N/Asvn-javahl.jar must be inserted in OpenGrok's classpath (you may do

177N/Athis by copying the file into the lib-subdirectory in your OpenGrok

177N/Ainstallation).

177N/Asvn-javahl.jar is also needed by the web application, and you may

177N/Aeither copy the jar-file into WEB-INF/lib-directory or insert it into the

177N/Acommon directory for all web applications (For Tomcat 5.x, this is

177N/A`TOMCAT/common/lib/svn-javahl.jar')

177N/A

177N/AThe path to the native library svnjavahl needs to be added to

177N/Ajava.library.path for both the OpenGrok application and the OpenGrok

177N/Aweb application.

177N/A

177N/Aex:

177N/A java -Djava.library.path=/usr/lib/svn -jar opengrok.jar ....

177N/Aor, by using LD_LIBRARY_PATH

177N/A LD_LIBRARY_PATH=/usr/lib/svn java -jar opengrok.jar ...

120N/A

0N/A---------------------------------------------------

0N/AUsing Standalone Swing GUI

0N/A---------------------------------------------------

0N/Aopengrok.jar when invoked without any arguments, opens up the GUI search window.

0N/AThe interface is similar to cscope.

0N/A

0N/ATo create an index, first select the browse button for "Search" drop down list.

0N/AChoose a directory to store the index (DATA_ROOT), and select the source tree

0N/A(SRC_ROOT). You may have to also select path to ctags in the Advanced Options,

0N/Aif exuberant ctags can not be found in the PATH.

0N/A

0N/AClicking "Update" will create or update the search index.

0N/A

0N/AThe index can be searched using the cscope like GUI, which lets you customize

0N/Ayour favorite editor to open the matching files.

0N/A

295N/A---------------------------------------------------

295N/AUsing Findbugs

295N/A---------------------------------------------------

295N/AIf you want to run Findbugs (http://findbugs.sourceforge.net/) on OpenGrok,

295N/Ayou have to download Findbugs to your machine, and install it where you have

295N/Achecked out your OpenGrok source code, under the lib/findbugs directory,

295N/Alike this:

295N/A

341N/A cd ~/.ant/lib

295N/A wget http://..../findbugs-x.y.z.tar.gz

295N/A gtar -xf findbugs-x.y.z.tar.gz

295N/A mv findbugs-x.y.z findbugs

295N/A

295N/AYou can now run ant with the findbugs target:

295N/A

295N/A ant findbugs

295N/A ...

295N/A findbugs:

295N/A [findbugs] Executing findbugs from ant task

295N/A [findbugs] Running FindBugs...

295N/A [findbugs] Warnings generated: nnn

295N/A [findbugs] Output saved to findbugs/findbugs.html

295N/A

295N/ANow, open findbugs/findbugs.html in a web-browser, and start fixing bugs!

295N/A

341N/AIf you want to install findbugs some other place than ~/.ant/lib, you can untar the

341N/A.tar.gz file to a directory, and use the findbugs.home property to tell ant where to find

341N/Afindbugs, like this (if you have installed fundbugs under the lib directory):

341N/A

341N/A ant findbugs -Dfindbugs.home=lib/findbug

341N/A

341N/AThere is also a findbugs-xml ant target that can be used to generate XML files that can

341N/Alater be parsed, e.g. by Hudson.

341N/A

301N/A---------------------------------------------------

301N/AUsing Emma

301N/A---------------------------------------------------

301N/AIf you want to check test coverage on OpenGrok, download Emma from

301N/Ahttp://emma.sourceforge.net/. Place emma.jar and emma-ant.jar in the

336N/Aopengrok/trunk/lib directory, or ~/.ant/lib.

301N/A

301N/ANow you can instrument your classes, and create a jar file:

301N/A

301N/A ant emma-instrument

301N/A

301N/AIf you are using NetBeans, select File - "opengrok" Properties

301N/A- libraries - Compile tab. Press the "Add JAR/Folder" and select

301N/Alib/emma.jar and lib/emma_ant.jar

301N/A

301N/AIf you are not using netbeans, you have to edit the file

301N/Anbproject/project.properties, and add "lib/emma.jar" and

301N/A"lib/emma_ant.jar" to the javac.classpath inside it.

301N/A

301N/ANow you can put the classes into jars and generate distributables:

301N/A

301N/A ant dist

301N/A

301N/AThe classes inside opengrok.jar should now be instrumented.

301N/AIf you use opengrok.jar for your own set of tests, you need

301N/Aemma.jar in the classpath.If you want to specify where to store

301N/Athe run time analysis, use these properties:

301N/A

301N/A emma.coverage.out.file=path/coverage.ec

301N/A emma.coverage.out.merge=true

301N/A

301N/AThe coverage.ec file should be placed in the opengrok/trunk/coverage

301N/Adirectory for easy analyzation.

301N/A

301N/AIf you want to test the coverage of the unit tests, you can

301N/Arun the tests:

301N/A

301N/A ant test (Or Alt+F6 in NetBeans)

301N/A

301N/ANow you should get some output saying that Emma is placing runtime

301N/Acoverage data into coverage.ec.

301N/A

301N/ATo generate reports, run ant again:

301N/A

301N/A ant emma-report

301N/A

301N/ALook at coverage/coverage.txt, coverage/coverage.xml and

301N/Acoverage/coverage.html to see how complete your tests are.

301N/A

0N/AAUTHORS

0N/A-------

0N/AChandan B.N, Sun Microsystems. https://blogs.sun.com/chandan

0N/ATrond Norbye, norbye.org

0N/AKnut Pape, eBriefkasten.de

13N/AMartin Englund, Sun Microsystems

136N/AKnut Anders Hatlen, Sun Microsystems