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. OpenGrok: There is a sample shell script OpenGrok that is suitable
50 for using in a cronjob to run regularly. Modify the variables in the script
51 to point appropriate directories, or as the code suggests factor your local
52 configuration into a seperate file and simplify future upgrades.
53
54 Option 2. opengrok.jar: You can also directly use the Java application. If
55 the sources are all located in a directory SRC_ROOT and the data and
56 hypertext files generated by OpenGrok are to be stored in DATA_ROOT, run
57
58 $ java -jar opengrok.jar -s SRC_ROOT -d DATA_ROOT
59
60 See opengrok.jar manual below for more details.
61
62 Step.2 - Configure and Deploy source.war Webapp
63 ===============================================
64 To configure the webapp source.war, look into the parameters defined in
65 web.xml of source.war file and change them (see note1) appropriately.
66
67 * HEADER: is the fragment of HTML that will be used to display title or
68 logo of your project
69 * SRC_ROOT: the absolute path name of the root directory of your source tree
70 * DATA_ROOT: absolute path of the directory where OpenGrok data
71 files are stored
72
73
74 Optional Step.3 - Path Descriptions
75 -----------------------------------
76 OpenGrok uses path descriptions in various places (For eg. while showing
77 directory listings or search results) Example descriptions are in paths.tsv
78 file. You can list descriptions for directories one per line tab separated
79 format path tab description. Refer to example 4 below.
80
81 Note 1 - Changing webapp parameters: web.xml is the deployment descriptor
82 for the web application. It is in a Jar file named source.war, you can
83 change the :
84
85 * Option 1: Unzip the file to TOMCAT/webapps/source/ directory and
86 change the source/WEB-INF/web.xml and other static html files like
87 index.html to customize to your project.
88
89 * Option 2: Extract the web.xml file from source.war file
90
91 $ unzip source.war WEB-INF/web.xml
92
93 edit web.xml and re-package the jar file.
94
95 $ zip -u source.war WEB-INF/web.xml
96
97 Then copy the war files to <i>TOMCAT</i>/webapps directory.
98
99 * Option 3: Edit the Context container element for the webapp
100
101 Copy source.war to TOMCAT/webapps
102
103 When invoking OpenGrok to build the index, use -w <webapp> to set the
104 context.
105
106 After the index is built, there's a couple different ways to set the
107 Context for the servlet container:
108 - Add the Context inside a Host element in TOMCAT/conf/server.xml
109
110 <Context path="/<webapp>" docBase="source.war">
111 <Parameter name="DATA_ROOT" value="/path/to/data/root" override="false" />
112 <Parameter name="SRC_ROOT" value="/path/to/src/root" override="false" />
113 <Parameter name="HEADER" value='...' 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 ---------------------------------------------------
129 Using Java DB for history cache
130 (instead of gzipped xml files)
131 ---------------------------------------------------
132
133 You need Java DB 10.5.3 or later
134 (OpenSolaris: # pkg install SUNWjavadb or SUNWj6dev ,
135 Debian/Ubuntu: # apt-get install sun-java6-javadb).
136 There are two modes, having Java DB embedded, or running a Java DB server.
137 Java DB server is default option, I will not describe how to set up embedded
138 option.
139
140 1) Start the server:
141 $ mkdir -p $DATA_ROOT/derby
142
143 OpenSolaris:
144 # svcadm enable javadb
145 OR
146 $ java -Dderby.system.home=$DATA_ROOT/derby -jar /opt/SUNWjavadb/lib/derbynet.jar start
147 OR
148 $ java -Dderby.system.home=$DATA_ROOT/derby -jar /usr/jdk/instances/jdk1.6.0/db/lib/derbynet.jar start
149
150 Debian:
151 $ java -Dderby.system.home=$DATA_ROOT/derby -jar /usr/lib/jvm/java-6-sun/db/lib/derbynet.jar start
152
153
154 2) You need to have the derbyclient.jar in lib directory of opengrok.jar and in source.war WEB-INF/lib
155 Copy it over from
156 OpenSolaris: /opt/SUNWjavadb/lib/derbyclient.jar OR /usr/jdk/instances/jdk1.6.0/db/lib/derbyclient.jar
157 Debian: /usr/lib/jvm/java-6-sun/db/lib/derbyclient.jar
158
159 3) Use these options with indexer when indexing/generating the configuration:
160 -D -H
161
162 Also the Java DB server has to be running during indexing and for the web application.
163
164 Note: To use a bigger database buffer, which may improve performance of both
165 indexing and fetching of history, create a file named derby.properties in
166 $DATA_ROOT/derby and add this line to it:
167 derby.storage.pageCacheSize=25000
168
169 ---------------------------------------------------
170 Using Findbugs
171 ---------------------------------------------------
172 If you want to run Findbugs (http://findbugs.sourceforge.net/) on OpenGrok,
173 you have to download Findbugs to your machine, and install it where you have
174 checked out your OpenGrok source code, under the lib/findbugs directory,
175 like this:
176
177 cd ~/.ant/lib
178 wget http://..../findbugs-x.y.z.tar.gz
179 gtar -xf findbugs-x.y.z.tar.gz
180 mv findbugs-x.y.z findbugs
181
182 You can now run ant with the findbugs target:
183
184 ant findbugs
185 ...
186 findbugs:
187 [findbugs] Executing findbugs from ant task
188 [findbugs] Running FindBugs...
189 [findbugs] Warnings generated: nnn
190 [findbugs] Output saved to findbugs/findbugs.html
191
192 Now, open findbugs/findbugs.html in a web-browser, and start fixing bugs!
193
194 If you want to install findbugs some other place than ~/.ant/lib, you can untar the
195 .tar.gz file to a directory, and use the findbugs.home property to tell ant where to find
196 findbugs, like this (if you have installed fundbugs under the lib directory):
197
198 ant findbugs -Dfindbugs.home=lib/findbug
199
200 There is also a findbugs-xml ant target that can be used to generate XML files that can
201 later be parsed, e.g. by Hudson.
202
203 ---------------------------------------------------
204 Using Emma
205 ---------------------------------------------------
206 If you want to check test coverage on OpenGrok, download Emma from
207 http://emma.sourceforge.net/. Place emma.jar and emma-ant.jar in the
208 opengrok/trunk/lib directory, or ~/.ant/lib.
209
210 Now you can instrument your classes, and create a jar file:
211
212 ant emma-instrument
213
214 If you are using NetBeans, select File - "opengrok" Properties
215 - libraries - Compile tab. Press the "Add JAR/Folder" and select
216 lib/emma.jar and lib/emma_ant.jar
217
218 If you are not using netbeans, you have to edit the file
219 nbproject/project.properties, and add "lib/emma.jar" and
220 "lib/emma_ant.jar" to the javac.classpath inside it.
221
222 Now you can put the classes into jars and generate distributables:
223
224 ant dist
225
226 The classes inside opengrok.jar should now be instrumented.
227 If you use opengrok.jar for your own set of tests, you need
228 emma.jar in the classpath.If you want to specify where to store
229 the run time analysis, use these properties:
230
231 emma.coverage.out.file=path/coverage.ec
232 emma.coverage.out.merge=true
233
234 The coverage.ec file should be placed in the opengrok/trunk/coverage
235 directory for easy analyzation.
236
237 If you want to test the coverage of the unit tests, you can
238 run the tests:
239
240 ant test (Or Alt+F6 in NetBeans)
241
242 Now you should get some output saying that Emma is placing runtime
243 coverage data into coverage.ec.
244
245 To generate reports, run ant again:
246
247 ant emma-report
248
249 Look at coverage/coverage.txt, coverage/coverage.xml and
250 coverage/coverage.html to see how complete your tests are.
251
252 Note: For full coverage report your system has to provide proper junit test
253 environment, that would mean:
254 - you have to use ant 1.7 and above
255 - at least junit-4.?.jar has to be in ants classpath (e.g. in ./lib)
256 - your PATH must contain exuberant ctags binary
257 - your PATH variable must contain binaries of appropriate SCM SW, so commands
258 hg, sccs, cvs, git, bzr, svn (svnadmin too) must be available for full report
259
260 ---------------------------------------------------
261 Using Checkstyle
262 ---------------------------------------------------
263
264 To check that your code follows the standard coding conventions,
265 you can use checkstyle from http://checkstyle.sourceforge.net/
266
267 First you must download checkstyle from http://checkstyle.sourceforge.net/ ,
268 You need Version 5.0-beta01 (or newer). Extract the package you have
269 downloaded, and create a symbolic link to it from ~/.ant/lib/checkstyle,
270 e.g. like this:
271
272 cd ~/.ant/lib
273 unzip ~/Desktop/checkstyle-5.0-beta01.zip
274 ln -s checkstyle-5.0-beta01 checkstyle
275
276 You also have to create symbolic links to the jar files:
277
278 cd checkstyle
279 ln -s checkstyle-5.0-beta01.jar checkstyle.jar
280 ln -s checkstyle-all-5.0-beta01.jar checkstyle-all.jar
281
282 To run checkstyle on the source code, just run ant checkstyle:
283
284 ant checkstyle
285
286 Output from the command will be stored in the checkstyle directory.
287
288 If you want to install checkstyle some other place than ~/.ant/lib, you can
289 untar the .tar.gz file to a directory, and use the checkstyle.home property
290 to tell ant where to find checkstyle, like this (if you have installed
291 checkstyle under the lib directory):
292
293 ant checkstyle -Dcheckstyle.home=lib/checkstyle
294
295 ---------------------------------------------------
296 Using PMD
297 ---------------------------------------------------
298
299 To check the quality of the OpenGrok code you can also use PMD
300 from http://pmd.sourceforge.net/.
301
302 How to install:
303
304 cd ~/.ant/lib
305 unzip ~/Desktop/pmd-bin-4.2.2.zip
306 ln -s pmd-4.2.2/ pmd
307
308 You also have to make links to the jar files:
309
310 cd ~/.ant/lib/pmd/lib
311 ln -s pmd-4.2.2.jar pmd.jar
312 ln -s jaxen-1.1.1.jar jaxen.jar
313
314 To run PMD on the rource code, just run ant pmd:
315
316 ant pmd
317
318 Outout from the command will be stored in the pmd subdirectory.
319
320 % ls pmd
321 pmd_report.html pmd_report.xml
322
323 If you want to install PMD some other place than ~/.ant/lib, you can
324 unzip the .zip file to a directory, and use the pmd.home property
325 to tell ant where to find PMD, like this (if you have installed
326 PMD under the lib directory):
327
328 ant pmd -Dpmd.home=lib/pmd-4.2.3
329
330 ---------------------------------------------------
331 Using JDepend
332 ---------------------------------------------------
333 To see dependencies in the source code, you can use JDepend from
334 http://clarkware.com/software/JDepend.html.
335
336 How to install:
337
338 cd ~/.ant/lib
339 unzip ~/Desktop/jdepend-2.9.zip
340 ln -s jdepend-2.9/ jdepend
341 cd jdepend/lib
342 ln -s jdepend-2.9.jar jdepend.jar
343
344 How to analyze:
345
346 ant jdepend
347
348 Output is stored in the jdepend directory:
349
350 $ ls jdepend/
351 report.txt report.xml
352
353 AUTHORS
354 -------
355 Chandan B.N, Sun Microsystems. https://blogs.sun.com/chandan
356 Trond Norbye, norbye.org
357 Knut Pape, eBriefkasten.de
358 Martin Englund, Sun Microsystems
359 Knut Anders Hatlen, Sun Microsystems
360