README.txt revision 115
5f5870385cff47efd2f58e7892f251cf13761528Timo SirainenOpenGrok - a wicked fast source browser
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen---------------------------------------
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenOpenGrok is a fast and usable source code search and cross reference
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenengine, written in Java. It helps you search, cross-reference and navigate
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenyour source tree. It can understand various program file formats and
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenversion control histories like SCCS, RCS, CVS, Subversion and Mercurial.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenOpenGrok is the tool used for the OpenSolaris Source Browser.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen * Latest Java http://java.sun.com/ (At least 1.5)
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen * A servlet container like Tomact (5.x or later)
77bc2bda5b781c4ffddc8a74b175cf32e9e2c2ecTimo Sirainen * Exuberant Ctags http://ctags.sourceforge.net/
77bc2bda5b781c4ffddc8a74b175cf32e9e2c2ecTimo Sirainen * Subversion 1.3.0 or later if SVN support is needed
40a5aeebf6b4858b93f0ddff0bf12fba769cf903Timo Sirainen * Mercurial 0.9.3 or later if Mercurial support is needed
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen * JFlex Ant task (If you want to build OpenGrok)
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo SirainenSRC_ROOT refers to the directory containing your source tree.
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo SirainenOpenGrok analyzes the source tree and builds a search index along with
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainencross-referenced hypertext versions of the source files. These generated
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainendata files will be stored in DATA_ROOT directory.
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo SirainenOpenGrok setup Step.0 - Setting up the Sources.
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen----------------------------------------------
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo SirainenSource base must be available locally for OpenGrok to work efficiently. No
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainenchanges are required to your source tree. If the code is under source control
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainenmanagement (SCM) OpenGrok requires the checked out source tree under SRC_ROOT.
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo SirainenIt is possible for some SCM systems to use a remote repository (Subversion),
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainenbut this is not recommended due to the performance penalty. CVS must have a
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainenlocal repository.
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo SirainenNote that OpenGrok ignores symbolic links.
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen---------------------------------------------------
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo SirainenUsing command line interface.
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen---------------------------------------------------
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo SirainenStep.1 - Populate DATA_ROOT Directory
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainen=====================================
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo SirainenOption 1. run.sh: There is a sample shell script run.sh that is suitable
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainenfor using in a cronjob to run regularly. Modify the variables in the script
5da1aa5197a43d83f0fb3eeb83125c7cd73d1b62Timo Sirainento point appropriate directories.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenOption 2. opengrok.jar: You can also directly use the Java application. If
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenthe sources are all located in a directory SRC_ROOT and the data and
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenhypertext files generated by OpenGrok are to be stored in DATA_ROOT, run
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen $ java -jar opengrok.jar -s SRC_ROOT DATA_ROOT
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenSee opengrok.jar manual below for more details.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenStep.2 - Configure and Deploy source.war Webapp
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen===============================================
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenTo configure the webapp source.war, look into the parameters defined in
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenweb.xml of source.war file and change them (see note1) appropriately.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen * HEADER: is the fragment of HTML that will be used to display title or
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen logo of your project
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen * SRC_ROOT: the absolute path name of the root directory of your source tree
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen * DATA_ROOT: absolute path of the directory where OpenGrok data
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen files are stored
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenOptional Step.3 - Path Descriptions
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen-----------------------------------
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenOpenGrok uses path descriptions in various places (For eg. while showing
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainendirectory listings or search results) Example descriptions are in paths.tsv
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenfile. You can list descriptions for directories one per line tab separated
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenformat path tab description. Refer to example 4 below.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenNote 1 - Changing webapp parameters: web.xml is the deployment descriptor
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenfor the web application. It is in a Jar file named source.war, you can
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen * Option 1: Unzip the file to TOMCAT/webapps/source/ directory and
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen change the source/WEB-INF/web.xml and other static html files like
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen index.html to customize to your project.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen * Option 2: Extract the web.xml file from source.war file
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen edit web.xml and re-package the jar file.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen Then copy the war files to <i>TOMCAT</i>/webapps directory.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen---------------------------------------------------
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenUsing Standalone Swing GUI
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen---------------------------------------------------
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenopengrok.jar when invoked without any arguments, opens up the GUI search window.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenThe interface is similar to cscope.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenTo create an index, first select the browse button for "Search" drop down list.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenChoose a directory to store the index (DATA_ROOT), and select the source tree
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainen(SRC_ROOT). You may have to also select path to ctags in the Advanced Options,
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenif exuberant ctags can not be found in the PATH.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenClicking "Update" will create or update the search index.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenThe index can be searched using the cscope like GUI, which lets you customize
1279090ba03f9c176976a69ab7718f0ed77b19afTimo Sirainenyour favorite editor to open the matching files.
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenChandan B.N, Sun Microsystems. https://blogs.sun.com/chandan
1279090ba03f9c176976a69ab7718f0ed77b19afTimo SirainenMartin Englund, Sun Microsystems