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

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

0N/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

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

576N/A

379N/A---------------------------------------------------

379N/AUsing Checkstyle

379N/A---------------------------------------------------

379N/A

379N/ATo check that your code follows the standard coding conventions,

379N/Ayou can use checkstyle from http://checkstyle.sourceforge.net/

379N/A

379N/AFirst you must download checkstyle from http://checkstyle.sourceforge.net/ ,

398N/AYou need Version 5.0-beta01 (or newer). Extract the package you have

398N/Adownloaded, and create a symbolic link to it from ~/.ant/lib/checkstyle,

379N/Ae.g. like this:

379N/A

379N/A cd ~/.ant/lib

398N/A unzip ~/Desktop/checkstyle-5.0-beta01.zip

398N/A ln -s checkstyle-5.0-beta01 checkstyle

379N/A

379N/AYou also have to create symbolic links to the jar files:

379N/A

379N/A cd checkstyle

398N/A ln -s checkstyle-5.0-beta01.jar checkstyle.jar

398N/A ln -s checkstyle-all-5.0-beta01.jar checkstyle-all.jar

379N/A

379N/ATo run checkstyle on the source code, just run ant checkstyle:

379N/A

379N/A ant checkstyle

379N/A

411N/AOutput from the command will be stored in the checkstyle directory.

379N/A

398N/AIf you want to install checkstyle some other place than ~/.ant/lib, you can

398N/Auntar the .tar.gz file to a directory, and use the checkstyle.home property

398N/Ato tell ant where to find checkstyle, like this (if you have installed

398N/Acheckstyle under the lib directory):

379N/A

379N/A ant checkstyle -Dcheckstyle.home=lib/checkstyle

379N/A

411N/A---------------------------------------------------

411N/AUsing PMD

411N/A---------------------------------------------------

411N/A

411N/ATo check the quality of the OpenGrok code you can also use PMD

411N/Afrom http://pmd.sourceforge.net/.

411N/A

411N/AHow to install:

411N/A

411N/A cd ~/.ant/lib

411N/A unzip ~/Desktop/pmd-bin-4.2.2.zip

411N/A ln -s pmd-4.2.2/ pmd

411N/A

411N/AYou also have to make links to the jar files:

411N/A

411N/A cd ~/.ant/lib/pmd/lib

411N/A ln -s pmd-4.2.2.jar pmd.jar

411N/A ln -s jaxen-1.1.1.jar jaxen.jar

411N/A

411N/ATo run PMD on the rource code, just run ant pmd:

411N/A

411N/A ant pmd

411N/A

411N/AOutout from the command will be stored in the pmd subdirectory.

411N/A

411N/A % ls pmd

411N/A pmd_report.html pmd_report.xml

411N/A

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):

411N/A

411N/A ant pmd -Dpmd.home=lib/pmd-4.2.3

411N/A

624N/A---------------------------------------------------

624N/AUsing JDepend

624N/A---------------------------------------------------

624N/ATo see dependencies in the source code, you can use JDepend from

624N/Ahttp://clarkware.com/software/JDepend.html.

624N/A

624N/AHow to install:

624N/A

624N/A cd ~/.ant/lib

624N/A unzip ~/Desktop/jdepend-2.9.zip

624N/A ln -s jdepend-2.9/ jdepend

624N/A cd jdepend/lib

624N/A ln -s jdepend-2.9.jar jdepend.jar

624N/A

624N/AHow to analyze:

624N/A

624N/A ant jdepend

624N/A

624N/AOutput is stored in the jdepend directory:

624N/A

624N/A $ ls jdepend/

624N/A report.txt report.xml

624N/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