README.txt revision 398
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
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
379N/AOutput from the command will bw 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
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