README.txt
1 OpenGrok - a wicked fast source browser
2 ---------------------------------------
3
4 OpenGrok is a fast and usable source code search and cross reference
5 engine, written in Java. It helps you search, cross-reference and navigate
6 your source tree. It can understand various program file formats and
7 version control histories like SCCS, RCS, CVS, Subversion and Mercurial.
8
9 OpenGrok is the tool used for the OpenSolaris Source Browser.
10
11 Requirements
12 ------------
13 * Latest Java http://java.sun.com/ (At least 1.5)
14 * A servlet container like Tomcat (5.x or later)
15 http://tomcat.apache.org/
16 supporting Servlet 2.4 and JSP 2.0
17 * Exuberant Ctags http://ctags.sourceforge.net/
18 * Subversion 1.3.0 or later if SVN support is needed
19 http://subversion.tigris.org/
20 * Mercurial 0.9.3 or later if Mercurial support is needed
21 http://www.selenic.com/mercurial/wiki/
22 * JFlex Ant task (If you want to build OpenGrok)
23 http://www.jflex.org/
24
25
26 Usage
27 -----
28 SRC_ROOT refers to the directory containing your source tree.
29 OpenGrok analyzes the source tree and builds a search index along with
30 cross-referenced hypertext versions of the source files. These generated
31 data files will be stored in DATA_ROOT directory.
32
33 OpenGrok setup Step.0 - Setting up the Sources.
34 ----------------------------------------------
35 Source base must be available locally for OpenGrok to work efficiently. No
36 changes are required to your source tree. If the code is under source control
37 management (SCM) OpenGrok requires the checked out source tree under SRC_ROOT.
38 It is possible for some SCM systems to use a remote repository (Subversion),
39 but this is not recommended due to the performance penalty. CVS must have a
40 local repository.
41 Note that OpenGrok ignores symbolic links.
42
43 ---------------------------------------------------
44 Using command line interface.
45 ---------------------------------------------------
46
47 Step.1 - Populate DATA_ROOT Directory
48 =====================================
49 Option 1. run.sh: There is a sample shell script run.sh that is suitable
50 for using in a cronjob to run regularly. Modify the variables in the script
51 to point appropriate directories.
52
53 Option 2. opengrok.jar: You can also directly use the Java application. If
54 the sources are all located in a directory SRC_ROOT and the data and
55 hypertext files generated by OpenGrok are to be stored in DATA_ROOT, run
56
57 $ java -jar opengrok.jar -s SRC_ROOT -d DATA_ROOT
58
59 See opengrok.jar manual below for more details.
60
61 Step.2 - Configure and Deploy source.war Webapp
62 ===============================================
63 To configure the webapp source.war, look into the parameters defined in
64 web.xml of source.war file and change them (see note1) appropriately.
65
66 * HEADER: is the fragment of HTML that will be used to display title or
67 logo of your project
68 * SRC_ROOT: the absolute path name of the root directory of your source tree
69 * DATA_ROOT: absolute path of the directory where OpenGrok data
70 files are stored
71
72
73 Optional Step.3 - Path Descriptions
74 -----------------------------------
75 OpenGrok uses path descriptions in various places (For eg. while showing
76 directory listings or search results) Example descriptions are in paths.tsv
77 file. You can list descriptions for directories one per line tab separated
78 format path tab description. Refer to example 4 below.
79
80 Note 1 - Changing webapp parameters: web.xml is the deployment descriptor
81 for the web application. It is in a Jar file named source.war, you can
82 change the :
83
84 * Option 1: Unzip the file to TOMCAT/webapps/source/ directory and
85 change the source/WEB-INF/web.xml and other static html files like
86 index.html to customize to your project.
87
88 * Option 2: Extract the web.xml file from source.war file
89
90 $ unzip source.war WEB-INF/web.xml
91
92 edit web.xml and re-package the jar file.
93
94 $ zip -u source.war WEB-INF/web.xml
95
96 Then copy the war files to <i>TOMCAT</i>/webapps directory.
97
98 * Option 3: Edit the Context container element for the webapp
99
100 Copy source.war to TOMCAT/webapps
101
102 When invoking OpenGrok to build the index, use -w <webapp> to set the
103 context.
104
105 After the index is built, there's a couple different ways to set the
106 Context for the servlet container:
107 - Add the Context inside a Host element in TOMCAT/conf/server.xml
108
109 <Context path="/<webapp>" docBase="source.war">
110 <Parameter name="DATA_ROOT" value="/path/to/data/root" override="false" />
111 <Parameter name="SRC_ROOT" value="/path/to/src/root" override="false" />
112 <Parameter name="HEADER" value='...' override="false" />
113 <Parameter name="SCAN_REPOS" value="false" override="false" />
114 </Context>
115
116 - Create a Context file for the webapp
117
118 This file will be named `<webapp>.xml'.
119
120 For Tomcat, the file will be located at:
121 `TOMCAT/conf/<engine_name>/<hostname>', where <engine_name>
122 is the Engine that is processing requests and <hostname> is a Host
123 associated with that Engine. By default, this path is
124 'TOMCAT/conf/Catalina/localhost' or 'TOMCAT/conf/Standalone/localhost'.
125
126 This file will contain something like the Context described above.
127
128 Optional Step 4 -- Subversion setup
129 -----------------------------------
130 Some additional setup is needed if you are using Subversion. OpenGrok uses
131 the Subversion javahl bindings, which must be installed separately.
132
133 svn-javahl.jar must be inserted in OpenGrok's classpath (you may do
134 this by copying the file into the lib-subdirectory in your OpenGrok
135 installation).
136 svn-javahl.jar is also needed by the web application, and you may
137 either copy the jar-file into WEB-INF/lib-directory or insert it into the
138 common directory for all web applications (For Tomcat 5.x, this is
139 `TOMCAT/common/lib/svn-javahl.jar')
140
141 The path to the native library svnjavahl needs to be added to
142 java.library.path for both the OpenGrok application and the OpenGrok
143 web application.
144
145 ex:
146 java -Djava.library.path=/usr/lib/svn -jar opengrok.jar ....
147 or, by using LD_LIBRARY_PATH
148 LD_LIBRARY_PATH=/usr/lib/svn java -jar opengrok.jar ...
149
150 ---------------------------------------------------
151 Using Standalone Swing GUI
152 ---------------------------------------------------
153 opengrok.jar when invoked without any arguments, opens up the GUI search window.
154 The interface is similar to cscope.
155
156 To create an index, first select the browse button for "Search" drop down list.
157 Choose a directory to store the index (DATA_ROOT), and select the source tree
158 (SRC_ROOT). You may have to also select path to ctags in the Advanced Options,
159 if exuberant ctags can not be found in the PATH.
160
161 Clicking "Update" will create or update the search index.
162
163 The index can be searched using the cscope like GUI, which lets you customize
164 your favorite editor to open the matching files.
165
166 AUTHORS
167 -------
168 Chandan B.N, Sun Microsystems. https://blogs.sun.com/chandan
169 Trond Norbye, norbye.org
170 Knut Pape, eBriefkasten.de
171 Martin Englund, Sun Microsystems
172 Knut Anders Hatlen, Sun Microsystems
173