config the opengrok

Concepts:
source.war is a web app that runs in tomcat to read the index/xref created by opengork.
opengork.jar is jar package that runs with java to parse the code and build the index/xref/history.
We need first create the index/xref/history by using opengork.jar. Then we set the configuration.xml
for tomcat and show the result in web browser.

1. Windows.

2. Ubuntu.

• install open jdk

• download opengork

• download tomcat

• To run opengork
  java -jar /opt/opengork/lib/opengork.jar
  -c /path/to/universal/ctags
  -s /var/opengrok/src -d /var/opengrok/data -H -P -S -G
  -W /var/opengrok/etc/configuration.xml -U http://localhost:8080/source
  -Djava.util.logging.config.file=/var/opengrok/logging.properties

or

java -Djava.util.logging.config.file=/var/opengrok/logging.properties -jar lib/opengrok.jar -c /usr/bin/ctags -s /home/roger/bin/opengrok-1.2.7/src -d /home/roger/bin/opengrok-1.2.7/data -H -P -S -G -W /home/roger/bin/opengrok-1.2.7/data/configuration.xml

reference:
https://github.com/oracle/opengrok/wiki/How-to-setup-OpenGrok

• config tomcat

  1. copy source.war to E:\swInstallPackage\apache-tomcat-8.5.40-windows-x64\apache-tomcat-8.5.40\webapps
  2. run localhost:8080\source in web browser, a source folder will be created in tomcat's webapps folder
  3. set in xml
     edit web.xml in E:\swInstallPackage\apache-tomcat-8.5.40-windows-x64\apache-tomcat-8.5.40\webapps\source\WEB-INF

• help for opengrok.jar
  Usage: java -jar opengrok.jar [options] [subDir1 [...]]

  -h, -?, --help
  Display this usage summary.

  --detailed
  Display additional help with -h,--help.

  -A, --analyzer (.ext|prefix.)😦-|analyzer)
  Files with the named prefix/extension should be analyzed
  with the given analyzer, where 'analyzer' may be specified
  using a simple class name (RubyAnalyzer) or language name (C)
  (Note, analyzer specification is case sensitive)
  Ex: -A .foo:CAnalyzer
  will use the C analyzer for all files ending with .FOO
  Ex: -A bar.:Perl
  will use the Perl analyzer for all files starting
  with "BAR" (no full-stop)
  Ex: -A .c:-
  will disable specialized analyzers for all files ending with .c

  -c, --ctags /path/to/ctags
  Path to Universal Ctags
  By default takes the Universal Ctags in PATH.

  --checkIndexVersion
  Check if current Lucene version matches index version

  -d, --dataRoot /path/to/data/root
  The directory where OpenGrok stores the generated data.

  --depth number
  Scanning depth for repositories in directory structure relative to
  source root. Default is 3.

  -e, --economical
  Economical, consumes less disk space.
  It does not generate hyper text cross reference files offline,
  but will do so on demand, which could be sightly slow.

  -G, --assignTags
  Assign commit tags to all entries in history for all repositories.

  -H, --history
  Enable history.

  -I, --include pattern
  Only files matching this pattern will be examined.
  (supports wildcards, example: -I *.java -I *.c)

  -i, --ignore pattern
  Ignore the named files (prefixed with 'f:')
  or directories (prefixed with 'd:').
  Supports wildcards (example: -i *.so -i *.dll)

  -l, --lock on|off|simple|native
  Set OpenGrok/Lucene locking mode of the Lucene database
  during index generation. "on" is an alias for "simple".
  Default is off.

  --leadingWildCards on|off
  Allow or disallow leading wildcards in a search.

  -m, --memory number
  Amount of memory that may be used for buffering added documents and
  deletions before they are flushed to the directory (default 16.0MB).
  Please increase JVM heap accordingly, too.

  --man
  Generate OpenGrok XML manual page.

  --mandoc /path/to/mandoc
  Path to mandoc(1) binary.

  -n, --noIndex
  Do not generate indexes and other data (such as history cache and xref files), but process all other command line options.

  -O, --optimize on|off
  Turn on/off the optimization of the index database
  as part of the indexing step.

  -o, --ctagOpts path
  File with extra command line options for ctags.

  -P, --projects
  Generate a project for each top-level directory in source root.

  -p, --defaultProject /path/to/default/project
  This is the path to the project that should be selected
  by default in the web application (when no other project
  set either in cookie or in parameter). May be used multiple
  times for several projects. Use "all" for all projects.
  You should strip off the source root.

  --profiler
  Pause to await profiler or debugger.

  --progress
  Print per project percentage progress information.
  (I/O extensive, since one read through directory structure is
  made before indexing, needs -v, otherwise it just goes to the log)

  -Q, --quickScan on|off
  Turn on/off quick context scan. By default, only the first
  1024k of a file is scanned, and a '[..all..]' link is inserted
  when the file is bigger. Activating this may slow the server down.
  (Note: this is setting only affects the web application)

  -q, --quiet
  Run as quietly as possible.
  Sets logging level to WARNING.

  --repository repository
  Generate history for specific repository specified as relative path to source root.
  Can be used multiple times. Assumes history is on.

  -R /path/to/configuration
  Read configuration from the specified file.

  -r, --remote on|off|uionly|dirbased
  Specify support for remote SCM systems.
  on - allow retrieval for remote SCM systems.
  off - ignore SCM for remote systems.
  uionly - support remote SCM for user interface only.
  dirbased - allow retrieval during history index only for repositories
  which allow getting history for directories.

  --renamedHistory on|off
  Enable or disable generating history for renamed files.
  If set to on, makes history indexing slower for repositories
  with lots of renamed files.

  -S, --search
  Search for "external" source repositories and add them.

  -s, --source /path/to/source/root
  The root directory of the source tree.

  --style path
  Path to the subdirectory in the web-application containing the
  requested stylesheet. The factory-setting is: "default".

  --symlink /path/to/symlink
  Allow this symlink to be followed. Option may be repeated.
  By default only symlinks directly under source root directory
  are allowed.

  -T, --threads number
  The number of threads to use for index generation.
  By default the number of threads will be set to the number
  of available CPUs.

  -t, --tabSize number
  Default tab size to use (number of spaces per tab character).

  -U, --uri protocol://webappURI:port/contextPath
  Send the current configuration to the specified webappURI

  --updateConfig
  Populate the webapp with bare configuration and exit.

  --userPage URL
  Base URL of the user Information provider.
  Example: "http://www.myserver.org/viewProfile.jspa?username=".
  Use "none" to disable link.

  --userPageSuffix URL-suffix
  URL Suffix for the user Information provider. Default: "".

  -V, --version
  Print version and quit.

  -v, --verbose
  Set logging level to INFO.

  --webappCtags on|off
  Web application should run ctags when necessary. Default is off.

  -W, --writeConfig /path/to/configuration
  Write the current configuration to the specified file
  (so that the web application can use the same configuration)