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=====================================

0N/AOption 1. run.sh: There is a sample shell script run.sh that is suitable

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

0N/Ato point appropriate directories.

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

0N/A $ java -jar opengrok.jar -s SRC_ROOT 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

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