ator@ator-hp-prodesk-680-g4-mt:/opt/opengrok-1.1-rc3/doc$ cat README.txt
#
# Copyright (c) 2006, 2017, Oracle and/or its affiliates. All rights reserved.
#
OpenGrok - a wicked fast source browser
---------------------------------------
1. Introduction
2. Requirements
3. Usage
4. OpenGrok install
5. OpenGrok setup
6. Optional Command Line Interface Usage
7. Change web application properties or name
8. Information for developers
9. Tuning OpenGrok for large code bases
10. Authors
11. Contact us
1. Introduction
---------------
OpenGrok is a fast and usable source code search and cross reference
engine, written in Java. It helps you search, cross-reference and navigate
your source tree. It can understand various program file formats and
version control histories of many source code management systems.
Offical page of the project is on:
http://opengrok.github.com/OpenGrok/
2. Requirements
---------------
* Latest Java (At least 1.8)
http://www.oracle.com/technetwork/java/
* A servlet container like Tomcat (8.x or later)
supporting Servlet 2.5 and JSP 2.1
http://tomcat.apache.org/
* Exuberant Ctags or Universal Ctags
http://ctags.sourceforge.net/
https://ctags.io/
* Source Code Management installation
depending on type of repositories indexed
* If you want to build OpenGrok:
- Ant (1.9.4 and later)
http://ant.apache.org/
- JFlex
http://www.jflex.de/
- Netbeans (optional, at least 8.2, will need Ant 1.9.4)
http://netbeans.org/
3. Usage
--------
OpenGrok usually runs in servlet container (e.g. Tomcat).
SRC_ROOT environment variable refers to the directory containing your source
tree. OpenGrok analyzes the source tree and builds a search index along with
cross-referenced hypertext versions of the source files. These generated
data files will be stored in directory referred to with environment variable
called DATA_ROOT.
3.1 Projects
------------
OpenGrok has a concept of Projects - one project is one directory underneath
SRC_ROOT directory which usually contains a checkout of a project sources.
(this can be branch, version, ...)
Projects effectively replace the need to have more web applications, each with
opengrok .war file. Instead it leaves you with one indexer and one web
application serving multiple source code repositories - projects.
Then you have a simple update script and simple index refresher script in
place, which simplifies management of more repositories.
A nice concept is to have a naming convention for directories underneath
SRC_ROOT, thereby creating a good overview of projects (e.g.
name-version-branch).
For example, the SRC_ROOT directory can contain the following directories:
openssl-head
openssl-0.9.8-stable
openssl-1.0.0-stable
Each of these directories was created with 'cvs checkout' command (with
appropriate arguments to get given branch) and will be treated by OpenGrok
as a project.
3.2 Messages
------------
Deployed OpenGrok can receive couple of messages through the active socket which
usually listens for the main configuration file. These are used in the web
application and displayed to the users. One can easily notify users about some
important events, for example that the reindex is being in progress and that
the searched information can be inconsistent.
The OpenGrok comes with a tool which allows you to send these messages without
any problem. It is called Messages and it is located under the tools directory.
See the file for usage and more information.
3.2.1 Tags
----------
Any message can use tags which makes it more specific for the application.
Messages which tag match some OpenGrok project are considered project specific
and the information contained in them are displayed only for the specific projects.
There is a key tag "main" which is exclusive for displaying
messages on the OpenGrok landing page - like a common information.
3.2.2 Types
-----------
Currently supported message types:
1) NormalMessage (normal)
This message is designed to display some information in the web application.
Use tags to target a specific project.
2) AbortMessage (abort)
This message can delete some already published information in
the web application.
Use tags to restrict the deletion only to specific projects.
3) StatsMessage (stats)
This message is designed to retrieve some information from the web application.
The purpose of the message is specified in the text field as one of:
- "reload" the application reloads the statistics file
and returns the loaded statistics
- "clean" the application cleans its current statistics
and returns the empty statistics
- "get" the application returns current statistics
4) ConfigMessage (config)
This message retrieves or sends a configuration to the webapp,
depending on tag. "setconf" tag sends config to webapp and requires
file as argument. "set" tag sets particular configuration option in the webapp.
5) RefreshMesssage (refresh)
Sent at the end of partial reindex to trigger refresh of SearcherManagers.
4. OpenGrok install
-----------------
4.1 Installing on Solaris from *.p5p file
-----------------
4.1.0 Install
-----------------
The file <package_name>.p5p you can easily use as a new publisher for the pkg command.
# pkg install --no-refresh -g /path/to/file/<package_name>.p5p opengrok
4.1.1 Update
-----------------
You can also update OpenGrok software with the *.p5p file by running a command
# pkg update --no-refresh -g /path/to/file/<package_name>.p5p 'pkg://opengrok/*'
5. OpenGrok setup
-----------------
To setup OpenGrok it is needed to prepare the source code, let OpenGrok index
it and start the web application.
5.1 Setting up the sources
--------------------------
Source base should be available locally for OpenGrok to work efficiently.
No changes are required to your source tree. If the code is under source
control management (SCM) OpenGrok requires the checked out source tree under
SRC_ROOT.
By itself OpenGrok does not perform the setup of the source code repositories
or sychronization of the source code with its origin. This needs to be done by
the user or by using automatic scripts.
It is possible for SCM systems which are not distributed (Subversion, CVS)
to use a remote repository but this is not recommended due to the performance
penalty. Special option when running the OpenGrok indexer is needed to enable
remote repository support ("-r on").
In order for history indexing to work for any SCM system it is necessary
to have environment for given SCM systems installed and in a path accessible
by OpenGrok.
Note that OpenGrok ignores symbolic links.
If you want to skip indexing the history of a particular directory
(and all of it's subdirectories), you can touch '.opengrok_skip_history' file
at the