0N/AOpenGrok - a wicked fast source browser
0N/A---------------------------------------
1298N/AOpenGrok is a fast and usable source code search and cross reference
1298N/Aengine, written in Java. It helps you search, cross-reference and navigate
1298N/Ayour source tree. It can understand various program file formats and
1298N/Aversion control histories like SCCS, RCS, CVS, Subversion and Mercurial.
1298N/AOpenGrok is the tool used for the OpenSolaris Source Browser.
1298N/A * A servlet container like Tomcat (
5.x or later)
1298N/A supporting Servlet 2.4 and JSP 2.0
1298N/A * Subversion 1.3.0 or later if SVN support is needed
0N/A * Mercurial 0.9.3 or later if Mercurial support is needed
1298N/A * JFlex Ant task (If you want to build OpenGrok)
1298N/ASRC_ROOT refers to the directory containing your source tree.
1298N/AOpenGrok analyzes the source tree and builds a search index along with
1298N/Across-referenced hypertext versions of the source files. These generated
1298N/Adata files will be stored in DATA_ROOT directory.
1073N/AOpenGrok setup Step.0 - Setting up the Sources.
1298N/A----------------------------------------------
0N/ASource base must be available locally for OpenGrok to work efficiently. No
1298N/Achanges are required to your source tree. If the code is under source control
1298N/Amanagement (SCM) OpenGrok requires the checked out source tree under SRC_ROOT.
0N/AIt is possible for some SCM systems to use a remote repository (Subversion),
0N/Abut this is not recommended due to the performance penalty. CVS must have a
115N/ANote that OpenGrok ignores symbolic links.
1298N/A---------------------------------------------------
1298N/AUsing command line interface.
1298N/A---------------------------------------------------
1298N/AStep.1 - Populate DATA_ROOT Directory
1298N/A=====================================
0N/AOption 1. OpenGrok: There is a sample shell script OpenGrok that is suitable
1298N/Afor using in a cron job to run regularly. Modify the variables in the script
1298N/Ato point appropriate directories, or as the code suggests factor your local
1298N/Aconfiguration into a separate file and simplify future upgrades.
1298N/Athe sources are all located in a directory SRC_ROOT and the data and
1298N/Ahypertext files generated by OpenGrok are to be stored in DATA_ROOT, run
1298N/A===============================================
1298N/A * HEADER: is the fragment of HTML that will be used to display title or
1298N/A * SRC_ROOT: the absolute path name of the root directory of your source tree
1298N/A * DATA_ROOT: absolute path of the directory where OpenGrok data
1298N/AOptional Step.3 - Path Descriptions
1298N/A-----------------------------------
1298N/AOpenGrok uses path descriptions in various places (For eg. while showing
1298N/Adirectory listings or search results) Example descriptions are in
paths.tsv 1298N/Afile. You can list descriptions for directories one per line tab separated
0N/Aformat path tab description. Refer to example 4 below.
1298N/ANote 1 - Changing webapp parameters:
web.xml is the deployment descriptor
1298N/A Then copy the war files to <i>TOMCAT</i>/webapps directory.
1298N/A * Option 3: Edit the Context container element for the webapp
1298N/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:
1298N/A <Parameter name="HEADER" value='...' override="false" />
1298N/A - Create a Context file for the webapp
1298N/A This file will be named `<webapp>.xml'.
1298N/A For Tomcat, the file will be located at:
1298N/A is the Engine that is processing requests and <hostname> is a Host
1298N/A associated with that Engine. By default, this path is
1298N/A This file will contain something like the Context described above.
1298N/A---------------------------------------------------
1298N/AUsing Java DB for history cache
975N/A(instead of gzipped xml files)
975N/A---------------------------------------------------
1298N/AYou need Java DB 10.5.3 or later
975N/A(OpenSolaris: # pkg install SUNWjavadb or SUNWj6dev ,
975N/AThere are two modes, having Java DB embedded, or running a Java DB server.
975N/AJava DB server is default option, I will not describe how to set up embedded
975N/AAlso the Java DB server has to be running during indexing and for the web application.
975N/ANote: To use a bigger database buffer, which may improve performance of both
1298N/A---------------------------------------------------
975N/A---------------------------------------------------
975N/Ayou have to download Findbugs to your machine, and install it where you have
975N/AYou can now run ant with the findbugs target:
975N/A [findbugs] Executing findbugs from ant task
1298N/A [findbugs] Running FindBugs...
1298N/A [findbugs] Warnings generated: nnn
975N/AIf you want to install findbugs some other place than ~/.ant/lib, you can untar the
975N/Afindbugs, like this (if you have installed fundbugs under the lib directory):
975N/AThere is also a findbugs-xml ant target that can be used to generate XML files that can
975N/A---------------------------------------------------
975N/A---------------------------------------------------
975N/AIf you want to check test coverage on OpenGrok, download Emma from
975N/ANow you can instrument your classes, and create a jar file:
1298N/AIf you are using NetBeans, select File - "opengrok" Properties
975N/AIf you are not using netbeans, you have to edit the file
1298N/ANow you can put the classes into jars and generate distributables:
1298N/Athe run time analysis, use these properties:
975N/Adirectory for easy analyzation.
984N/AIf you want to test the coverage of the unit tests, you can
1298N/A ant test (Or Alt+F6 in NetBeans)
0N/ANow you should get some output saying that Emma is placing runtime
1298N/ATo generate reports, run ant again:
0N/ANote: For full coverage report your system has to provide proper junit test
0N/Aenvironment, that would mean:
0N/A- you have to use ant 1.7 and above
0N/A- at least junit-4.?.jar has to be in ants classpath (
e.g. in ./lib)
0N/A- your PATH must contain exuberant ctags binary
1298N/A- your PATH variable must contain binaries of appropriate SCM SW, so commands
0N/Ahg, sccs, cvs, git, bzr, svn (svnadmin too) must be available for full report
0N/A---------------------------------------------------
1298N/A---------------------------------------------------
0N/ATo check that your code follows the standard coding conventions,
0N/AYou need Version 5.0-beta01 (or newer). Extract the package you have
1290N/A ln -s checkstyle-5.0-beta01 checkstyle
1298N/AYou also have to create symbolic links to the jar files:
0N/ATo run checkstyle on the source code, just run ant checkstyle:
116N/AOutput from the command will be stored in the checkstyle directory.
0N/AIf you want to install checkstyle some other place than ~/.ant/lib, you can
979N/Ato tell ant where to find checkstyle, like this (if you have installed
0N/Acheckstyle under the lib directory):
979N/A---------------------------------------------------
0N/A---------------------------------------------------
0N/ATo check the quality of the OpenGrok code you can also use PMD
116N/AYou also have to make links to the jar files:
979N/ATo run PMD on the rource code, just run ant pmd:
116N/AOutout from the command will be stored in the pmd subdirectory.
979N/AIf you want to install PMD some other place than ~/.ant/lib, you can
979N/Aunzip the .zip file to a directory, and use the
pmd.home property
979N/Ato tell ant where to find PMD, like this (if you have installed
979N/APMD under the lib directory):
975N/A---------------------------------------------------
1298N/A---------------------------------------------------
1298N/ATo see dependencies in the source code, you can use JDepend from
1298N/AOutput is stored in the jdepend directory:
863N/AMartin Englund, Sun Microsystems
1298N/AKnut Anders Hatlen, Sun Microsystems