4789N/AOpenGrok - a wicked fast source browser

176N/A---------------------------------------

4789N/A

176N/AOpenGrok is a fast and usable source code search and cross reference

176N/Aengine, written in Java. It helps you search, cross-reference and navigate

176N/Ayour source tree. It can understand various program file formats and

176N/Aversion control histories like SCCS, RCS, CVS, Subversion and Mercurial.

176N/A

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

176N/A

176N/ARequirements

176N/A------------

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

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

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

176N/A supporting Servlet 2.4 and JSP 2.0

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

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

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

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

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

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

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

176N/A

176N/A

176N/AUsage

176N/A-----

176N/ASRC_ROOT refers to the directory containing your source tree.

176N/AOpenGrok analyzes the source tree and builds a search index along with

176N/Across-referenced hypertext versions of the source files. These generated

176N/Adata files will be stored in DATA_ROOT directory.

176N/A

176N/AOpenGrok setup Step.0 - Setting up the Sources.

2134N/A----------------------------------------------

4789N/ASource base must be available locally for OpenGrok to work efficiently. No

176N/Achanges are required to your source tree. If the code is under source control

176N/Amanagement (SCM) OpenGrok requires the checked out source tree under SRC_ROOT.

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

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

176N/Alocal repository.

176N/ANote that OpenGrok ignores symbolic links.

176N/A

176N/A---------------------------------------------------

176N/AUsing command line interface.

176N/A---------------------------------------------------

176N/A

176N/AStep.1 - Populate DATA_ROOT Directory

176N/A=====================================

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

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

to point appropriate directories.

Option 2. opengrok.jar: You can also directly use the Java application. If

the sources are all located in a directory SRC_ROOT and the data and

hypertext files generated by OpenGrok are to be stored in DATA_ROOT, run

$ java -jar opengrok.jar -s SRC_ROOT DATA_ROOT

See opengrok.jar manual below for more details.

Step.2 - Configure and Deploy source.war Webapp

===============================================

To configure the webapp source.war, look into the parameters defined in

web.xml of source.war file and change them (see note1) appropriately.

* HEADER: is the fragment of HTML that will be used to display title or

logo of your project

* SRC_ROOT: the absolute path name of the root directory of your source tree

* DATA_ROOT: absolute path of the directory where OpenGrok data

files are stored

Optional Step.3 - Path Descriptions

-----------------------------------

OpenGrok uses path descriptions in various places (For eg. while showing

directory listings or search results) Example descriptions are in paths.tsv

file. You can list descriptions for directories one per line tab separated

format path tab description. Refer to example 4 below.

Note 1 - Changing webapp parameters: web.xml is the deployment descriptor

for the web application. It is in a Jar file named source.war, you can

change the :

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

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

index.html to customize to your project.

* Option 2: Extract the web.xml file from source.war file

$ unzip source.war WEB-INF/web.xml

edit web.xml and re-package the jar file.

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

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

* Option 3: Edit the Context container element for the webapp

Copy source.war to TOMCAT/webapps

When invoking OpenGrok to build the index, use -w <webapp> to set the

context.

After the index is built, there's a couple different ways to set the

Context for the servlet container:

- Add the Context inside a Host element in TOMCAT/conf/server.xml

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

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

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

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

<Parameter name="SCAN_REPOS" value="false" override="false" />

</Context>

- Create a Context file for the webapp

This file will be named `<webapp>.xml'.

For Tomcat, the file will be located at:

`TOMCAT/conf/<engine_name>/<hostname>', where <engine_name>

is the Engine that is processing requests and <hostname> is a Host

associated with that Engine. By default, this path is

'TOMCAT/conf/Catalina/localhost' or 'TOMCAT/conf/Standalone/localhost'.

This file will contain something like the Context described above.

Optional Step 4 -- Subversion setup

-----------------------------------

Some additional setup is needed if you are using Subversion. OpenGrok uses

the Subversion javahl bindings, which must be installed separately.

svn-javahl.jar must be inserted in OpenGrok's classpath (you may do

this by copying the file into the lib-subdirectory in your OpenGrok

installation).

svn-javahl.jar is also needed by the web application, and you may

either copy the jar-file into WEB-INF/lib-directory or insert it into the

common directory for all web applications (For Tomcat 5.x, this is

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

The path to the native library svnjavahl needs to be added to

java.library.path for both the OpenGrok application and the OpenGrok

web application.

ex:

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

or, by using LD_LIBRARY_PATH

LD_LIBRARY_PATH=/usr/lib/svn java -jar opengrok.jar ...

---------------------------------------------------

Using Standalone Swing GUI

---------------------------------------------------

opengrok.jar when invoked without any arguments, opens up the GUI search window.

The interface is similar to cscope.

To create an index, first select the browse button for "Search" drop down list.

Choose a directory to store the index (DATA_ROOT), and select the source tree

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

if exuberant ctags can not be found in the PATH.

Clicking "Update" will create or update the search index.

The index can be searched using the cscope like GUI, which lets you customize

your favorite editor to open the matching files.

AUTHORS

-------

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

Trond Norbye, norbye.org

Knut Pape, eBriefkasten.de

Martin Englund, Sun Microsystems

Knut Anders Hatlen, Sun Microsystems