0N/AOpenGrok - a wicked fast source browser
0N/A---------------------------------------
1298N/AOpenGrok is a fast and usable source code search and cross reference
1298N/Aengine, written in Java. It helps you search, cross-reference and navigate
1298N/Ayour source tree. It can understand various program file formats and
1298N/Aversion control histories like SCCS, RCS, CVS, Subversion and Mercurial.
1298N/AOpenGrok is the tool used for the OpenSolaris Source Browser.
1298N/A * A servlet container like Tomcat (
5.x or later)
1298N/A supporting Servlet 2.4 and JSP 2.0
1298N/A * Subversion 1.3.0 or later if SVN support is needed
0N/A * Mercurial 0.9.3 or later if Mercurial support is needed
1298N/A * JFlex Ant task (If you want to build OpenGrok)
1298N/ASRC_ROOT refers to the directory containing your source tree.
1298N/AOpenGrok analyzes the source tree and builds a search index along with
1298N/Across-referenced hypertext versions of the source files. These generated
1298N/Adata files will be stored in DATA_ROOT directory.
1298N/AProject concept - one project is one directory underneath SRC_ROOT and
1073N/Ausually contains a checkout of a project(or it's branch, version, ...)
1298N/Asources, it can have several attributes (in its XML description), note that
0N/Ainterface of projects is being stabilized so it can change. Projects
1298N/Aeffectively replace need for more web applications with opengrok .war and
1298N/Aleave you with one indexer and one web application serving MORE source code
0N/Arepositories - projects. A nice concept is to have directories underneath
0N/ASRC_ROOT with a naming convention, thereby creating a good overview of
115N/Aprojects (
e.g. name-version-branch). Then you have a simple update script &
115N/Asimple index refresher script in place, which simplifies management of more
1298N/AOpenGrok setup Step.0 - Setting up the Sources.
1298N/A----------------------------------------------
1298N/ASource base must be available locally for OpenGrok to work efficiently. No
1298N/Achanges are required to your source tree. If the code is under source control
1298N/Amanagement (SCM) OpenGrok requires the checked out source tree under SRC_ROOT.
0N/AIt is possible for some SCM systems to use a remote repository (Subversion,
1298N/ACVS), but this is not recommended due to the performance penalty. Special
1298N/Aoption is needed to enable remote repository support(-r on).
1298N/ANote that OpenGrok ignores symbolic links.
1298N/A---------------------------------------------------
1298N/AUsing Opengrok wrapper script(Solaris and Linux) to create indexes.
1298N/A---------------------------------------------------
1298N/AStep.1 - Deploy the web application
1298N/A=====================================
1298N/AWe provided you with OpenGrok wrapper script, which should aid in deploying
1298N/APlease change to opengrok directory (can vary on your system)
1298N/ANote that now you might need to change to user which owns the target
1298N/Adirectories for data,
e.g. on Solaris you'd do # pfexec su - webservd
1298N/Aits directory to one of detected web application containers.
1298N/APlease follow the error message it provides.
1298N/AIf it fails to discover your container, please refer to optional steps on
1298N/Achanging web application properties, which has manual steps on how to do
1298N/Aavailable to user running opengrok with all permissions. In root user case
1298N/Ait will create all the directories needed, otherwise you have to manually
1298N/Acreate the directory and grant all permissions to the user used.
1298N/AStep.2 - Populate DATA_ROOT Directory, let the indexer generate the project
1298N/A=====================================
1298N/ASecond step is to just run the indexing (can take a lot of time). After this
1298N/Ais done, indexer automatically attempts to upload newly generated
1298N/Aconfiguration to the web application. Most probably you will not be able to
1298N/Ause {Opengrok before this is done.
1298N/APlease change to opengrok directory (can vary on your system)
1298N/Aotherwise (if SRC_ROOT is in different directory) run:
1298N/A$ ./OpenGrok index <absolute_path_to_your_SRC_ROOT>
975N/AAbove command should try to upload latest index status reflected into
1298N/AOnce above command finishes without errors(
e.g. SEVERE: Failed to send
1298N/Aconfiguration to localhost:2424
0N/A), you should be able to enjoy your opengrok and search your sources using
0N/Alatest indexes and setup.
975N/ACongratulations, you should now be able to point your browser to
975N/Ahttp://<YOUR_WEBAPP_SERVER>:<WEBAPPSRV_PORT>/source to work with your fresh
1298N/AAt this time we'd like to point out some customization to OpenGrok script
975N/AA common case would be, that you want the data in some other directory than
1298N/AThis can be easily achieved by using environment variable
975N/ASince above will also change default location of config file, beforehands(or
975N/Arestart your web container after creating this symlink) I suggest doing
975N/AA lot more customizations can be found inside the script, you just need to
975N/Ahave a look at it, eventually create a configuration out of it and use
975N/AOPENGROK_CONFIGURATION environment variable to point to it. Obviously such
975N/Asetups can be used for nightly cron job updates of index or other automated
975N/A---------------------------------------------------
975N/AUsing smf service(OpenSolaris) to maintain opengrok indexes.
975N/A---------------------------------------------------
1298N/AIf you installed opengrok from a package, then configure the service like this:
1298N/Athen make the service start the indexing, at this point it would be nice if
975N/Athe web application is already running.
975N/A# svcadm enable -rs opengrok
1298N/A(which will enable tomcat6 as dependency)
975N/AWhen the service starts indexing for first time, it's already enabled and
975N/Adepending on tomcat6, so at this point the web application should be
975N/AThe indexing is not done when opengrok service is disabled.
975N/ATo rebuild the index later (
e.g. after source code changed)just run:
975N/ANote: before removing opengrok package please disable the service.
975N/AIf you don't do it, it will not be removed automatically.
975N/AIn such case please remove it manually.
975N/A---------------------------------------------------
975N/AUsing command line interface(general pointers) to create indexes.
975N/A---------------------------------------------------
975N/AStep.1 - Populate DATA_ROOT Directory
1298N/A=====================================
975N/AOption 1. OpenGrok: There is a sample shell script OpenGrok that is suitable
975N/Afor using in a cron job to run regularly. Modify the variables in the script
975N/Ato point appropriate directories, or as the code suggests factor your local
975N/Aconfiguration into a separate file and simplify future upgrades.
975N/Athe sources are all located in a directory SRC_ROOT and the data and
1298N/Ahypertext files generated by OpenGrok are to be stored in DATA_ROOT, run
975N/A===============================================
1298N/A * HEADER: is the fragment of HTML that will be used to display title or
1298N/A * SRC_ROOT: the absolute path name of the root directory of your source tree
975N/A * DATA_ROOT: absolute path of the directory where OpenGrok data
975N/AOptional Step.3 - Path Descriptions
975N/A-----------------------------------
1298N/AOpenGrok uses path descriptions in various places (For eg. while showing
1298N/Adirectory listings or search results) Example descriptions are in
paths.tsv 975N/Afile. You can list descriptions for directories one per line tab separated
975N/Aformat path tab description. Refer to example 4 below.
1298N/ANote 1 - Changing webapp parameters:
web.xml is the deployment descriptor
1298N/A Then copy the war files to <i>TOMCAT</i>/webapps directory.
984N/A * Option 3: Edit the Context container element for the webapp
975N/A When invoking OpenGrok to build the index, use -w <webapp> to set the
984N/A After the index is built, there's a couple different ways to set the
975N/A Context for the servlet container:
1298N/A <Parameter name="HEADER" value='...' override="false" />
299N/A - Create a Context file for the webapp
299N/A This file will be named `<webapp>.xml'.
0N/A For Tomcat, the file will be located at:
0N/A is the Engine that is processing requests and <hostname> is a Host
0N/A associated with that Engine. By default, this path is
0N/A This file will contain something like the Context described above.
0N/A---------------------------------------------------
1298N/AUsing Java DB for history cache
1298N/A(instead of gzipped xml files)
1298N/A---------------------------------------------------
0N/AYou need Java DB 10.5.3 or later
0N/A(OpenSolaris: # pkg install SUNWjavadb or SUNWj6dev ,
0N/AThere are two modes, having Java DB embedded, or running a Java DB server.
1298N/AJava DB server is default option, I will not describe how to set up embedded
0N/AAlso the Java DB server has to be running during indexing and for the web application.
0N/ANote: To use a bigger database buffer, which may improve performance of both
979N/A---------------------------------------------------
0N/AOptional CLI - Command Line Interface Usage
979N/A---------------------------------------------------
116N/A You need to pass location of project file + the query to Search class,
e.g. 979N/A---------------------------------------------------
979N/AOptional need to change web application properties or name
979N/A---------------------------------------------------
979N/A You might need to modify the web application if you don't store the
116N/Aconfiguration file in the default location
979N/Aparameters appropriately. These sample parameters need modifying(there are
979N/Amore options, refer to manual or read param comments).
979N/A * CONFIGURATION - the absolute path to XML file containing project
1298N/A * ConfigAddress - port for remote updates to configuration, optional,
1298N/A * but advised(since there is no authentification) to be set to
1298N/A * localhost:<some_port> (
e.g. localhost:2424), if you choose some_port
1298N/A * below 1024 you have to have root privileges
1298N/AIf you need to change name of the web application from source to something
1298N/Aelse you need to use special option -w <new_name> for indexer to create
863N/Aproper xrefs, besides changing the .war file name. Examples below show just
1298N/A-----------------------------------
1298N/A * Option 1: Use browser and log into glassfish web administration
1298N/A Common Tasks / Applications / Web Applications , button Deploy and point
863N/A * to deploy it "automagically".
863N/A * Option 3: Use cli from GLASSFISH directory:
1298N/ADeploy the modified .war file in tomcat:
863N/A-----------------------------------
1298N/A---------------------------------------------------
1298N/AOptional opengrok indexer setup with agent and systray GUI control application
1298N/A---------------------------------------------------
1298N/Astarting special OpenGrok Agent, where you can connect with a systray GUI
1298N/ATo start the indexer with configuration run:
863N/Athen from the remote machine one can run:
1298N/Aassuming configuration permits remote connections(so not listening on
1298N/Alocalhost, but rather on a physical network interface)
1298N/AThis agent is work in progress, so it might not fully work.
863N/A---------------------------------------------------
1298N/A---------------------------------------------------
1298N/Ayou have to download Findbugs to your machine, and install it where you have
1298N/AYou can now run ant with the findbugs target:
975N/A [findbugs] Executing findbugs from ant task
975N/A [findbugs] Running FindBugs...
1298N/A [findbugs] Warnings generated: nnn
1298N/AIf you want to install findbugs some other place than ~/.ant/lib, you can untar the
1298N/Afindbugs, like this (if you have installed fundbugs under the lib directory):
975N/AThere is also a findbugs-xml ant target that can be used to generate XML files that can
975N/A---------------------------------------------------
975N/A---------------------------------------------------
975N/AIf you want to check test coverage on OpenGrok, download Emma from
975N/ANow you can instrument your classes, and create a jar file:
1086N/AIf you are using NetBeans, select File - "opengrok" Properties
975N/AIf you are not using netbeans, you have to edit the file
975N/ANow you can put the classes into jars and generate distributables:
975N/Athe run time analysis, use these properties:
975N/Adirectory for easy analyzation.
975N/AIf you want to test the coverage of the unit tests, you can
1298N/A ant test (Or Alt+F6 in NetBeans)
1298N/ANow you should get some output saying that Emma is placing runtime
1298N/ATo generate reports, run ant again:
979N/ANote: For full coverage report your system has to provide proper junit test
979N/Aenvironment, that would mean:
1298N/A- you have to use ant 1.7 and above
1298N/A- at least junit-4.?.jar has to be in ants classpath (
e.g. in ./lib)
1298N/A- your PATH must contain exuberant ctags binary
1298N/A- your PATH variable must contain binaries of appropriate SCM SW, so commands
1298N/Ahg, sccs, cvs, git, bzr, svn (svnadmin too) must be available for full report
1298N/A---------------------------------------------------
979N/A---------------------------------------------------
1298N/ATo check that your code follows the standard coding conventions,
1298N/AYou need Version 5.1 (or newer). Extract the package you have
295N/A ln -s checkstyle-5.1 checkstyle
295N/AYou also have to create symbolic links to the jar files:
1298N/ATo run checkstyle on the source code, just run ant checkstyle:
1298N/AOutput from the command will be stored in the checkstyle directory.
295N/AIf you want to install checkstyle some other place than ~/.ant/lib, you can
295N/Ato tell ant where to find checkstyle, like this (if you have installed
295N/Acheckstyle under the lib directory):
295N/A---------------------------------------------------
1298N/A---------------------------------------------------
1298N/ATo check the quality of the OpenGrok code you can also use PMD
1298N/AYou also have to make links to the jar files:
301N/ATo run PMD on the rource code, just run ant pmd:
301N/AOutout from the command will be stored in the pmd subdirectory.
301N/AIf you want to install PMD some other place than ~/.ant/lib, you can
301N/Aunzip the .zip file to a directory, and use the
pmd.home property
1086N/Ato tell ant where to find PMD, like this (if you have installed
301N/APMD under the lib directory):
301N/A---------------------------------------------------
301N/A---------------------------------------------------
301N/ATo see dependencies in the source code, you can use JDepend from
301N/A ln -s jdepend-2.9/ jdepend
301N/AOutput is stored in the jdepend directory:
576N/AMartin Englund, Sun Microsystems
576N/AKnut Anders Hatlen, Sun Microsystems
1298N/ALubos Kosco, Sun Microsystems