1 Configuration
Izzy edited this page 4 years ago

Configuration takes place using *.ini files. With HyperSQL.ini, the distribution ships an example – which is also used as the default configuration file if you do not specify a project (see Usage).

Generally, the config file should use the same encoding as the project source files you intend to process – the default is UTF-8 if not specified. This may be unimportant as long as you use "plain ASCII" characters – but as soon as you start using special characters as e.g. German umlauts or French accents, it comes into play. If you are using a character set other than UTF-8, make sure to mention it in the General section.

The configuration file has multiple sections:

General

As the name suggests, this section serves some general settings:

  • title_prefix: used as prefix for the HTML title on generated pages
  • project_info: a short text describing your project. This will be included with the main index page.
  • project_info_file: full path to a (text) file with additional information to be displayed at the main index page. You can use HTML tags in this file.
  • project_logo: (path and) filename of a graphics file to be used as logo on the main index page
  • project_logo_url: if this is specified, it takes precedence over the previous setting: No file will be copied, this URL will be used directly instead.
  • ticket_url: URL to your projects bug tracking system to be used with the @bugzilla JavaDoc tag, with a placeholder for the ticket ID. An example entry here could look like this: ticket_url = http://bugzilla.domain.com/show_bug.cgi?id=%{id} or ticket_url = http://trac.domain.com/ticket/%{id}. This should work with most web-based tracking systems. Default is an empty string, so no bugzilla URLs are created. Having this URL setup correctly, ticket:123 in JavaDoc <text> elements will automatically be converted into a link to the corresponding ticket in your tracking system.
  • wiki_url: URL to your projects wiki system to be used for the @wiki JavaDoc tag, with a placeholder for the page. An example entry could look like wiki_url = http://wiki.domain.com/index.php/%{page} (Mediawiki) or wiki_url = http://trac.domain.com/wiki/%{page} (Trac). It should work with most wiki systems. The default is an empty string, so no wiki links will be created.
    Having this URL setup correctly, wiki:Somepage in JavaDoc <text> elements will automatically be converted into a link to the corresponding wiki page.
  • encoding: character set encoding of your source files. As this is not trivial to determine automatically, but usually all files of the same project use the same encoding, please set it in your config. Default is utf-8 – for a list of valid encodings, please see Wikipedia and IANA.

FileNames

All about file names – concerning the target HTML files:

  • top_level_directory: the top level directory of the source code to parse. HyperSQL will investigate all directories below this recursively.
  • rcsnames: directory names to exclude from parsing (below the top_level_directory)
  • ignorefile: placing a file with the name specified here into some directory in your source tree makes HyperSQL ignore that directory
  • sql_file_exts: specify extensions of files to be treated as SQL files. Separate multiple extensions using spaces.
  • cpp_file_exts: the similar for C++ files
  • htmldir: where the HTML output should go to
  • css_file: the main stylesheet file to include in the generated HTML pages
  • custom_css_files: use this if you want to override styling with your own specific CSS file(s). You can set it to a single file; multiple files must be separated by a space
  • css_url: used as (additional) CSS link - so you can use both entries
  • unittest_dir: XML exports of UnitTests are stored here

Additionally, the keywords from the PageNames section apply here as well if you want to specify different file names for them.

On Unix / Linux systems (including Cygwin), keep in mind that file names are case sensitive. So if you e.g. define sql_file_exts = sql pks pkb pkg pls, a file named SAMPLE.SQL will not be considered an SQL file (upper-case extension was not defined).

PageNames

Here you do not call the pages names – but you can specify their description for the URLs, i.e. what is displayed in the Index pages navigation. Usually, this part is handled by localization – so your config file should not contain this section: Keep in mind, the link names will no longer be translated if you define them here!

In some cases, this might still be useful – but handle it with care. The options are named similar to their corresponding file names options, so:

  • bug: the central bug list
  • depgraph: dependency graph
  • filepath: File Index With Pathnames
  • file: File Index Without Pathnames
  • form: Oracle Forms
  • form_full: Oracle Forms
  • function: guessed right, HTML file for the function index
  • mview: materialized views
  • package: package index
  • package_full: Index of packages including all their functions and procedures
  • procedure: procedure index HTML file
  • report: verification report (see Verification below)
  • sequence: list of sequences
  • stat: code statistics (lines of code, some file stats, etc.)
  • synonym: synonyms listing
  • tab: tables
  • todo: the central todo list
  • trigger: trigger
  • type: types
  • view: the views listing

Pages

At this place you can define which pages shall be created. Again the same naming as above (so please look there). The value is interpreted as Boolean – so best is to use 0 to turn a page off, and 1 to turn it on. By default, the following pages are enabled (and correspondingly, the following objects processed): file, filepath, function, package and procedure. Additionally, some statistical pages are enabled as well: bug, todo, depgraph. This is valid if there is no config file present overriding any of these settings – and of course you can do so in either HyperSQL.ini (for settings inherited by all your projects) or your projects *.ini file(s).

Process

Here come processing options:

  • blind_offset: How many lines before/after the CREATE statement shall we check for "anonymous javadoc blocks", i.e. those missing to name the object they describe. This is just for compatibility for a quick start – usually, you should leave it to the default of 0. You may however use any positive integer here – but keep in mind: the larger it is, the more it finds - which may not always fit …
  • cache: whether caching should be enabled (1, default) or not (0)
  • export_unittests: whether to export detected unit-tests to XML (0/1)
  • include_source: whether you want to include the (syntax-highlighted) source code with your web pages
  • include_source_limit: limit source inclusion by file size in kilobytes (default: '0' = no limit). Files exceeding this limit will have their source not included at all.
  • javadoc: whether JavaDoc should be processed (default: 1)
  • link_code_calls: whether calls to functions/procedures should be linked to their targets (1, default) in the highlighted code or not (0)
  • purge_on_start: whether to purge the target HTML directory from files of previous runs (if any) before generating new ones
  • whereused_scan_instring: boolean setting, default 0 (off/disabled). If enabled, HyperSQL will also scan in 'strings' for calls to functions/procedures. Again, this may lead to many "false positives" and hence is disabled by default. If you frequently use "dynamic SQL" (e.g. with EXECUTE IMMEDIATE in Oracle), and construct your statements as strings for this, you may wish to enable this feature (and possibly have to live with the added "false positives").
  • whereused_scan_shortrefs: boolean setting. With this set to 0 (False, Default), calls to procedures/functions will be only be detected if they are "fully qualified", i.e. <package_name>.<function_name>. Within the same package one often omits the <package_name>. part. Turning this option on will also scan for those – but be warned that this may lead to many "false positives" (which is why it is disabled by default).

Logging

Several logging features are available, which can be configured here. As for log levels, chose between NONE, DEBUG, INFO, WARNING, ERROR and CRITICAL – all levels right-hand from the chosen one are automatically included as well.

  • screenlevel: what should be logged to the screen (aka STDOUT). Defaults to ERROR
  • filelevel: what should be logged to the log file specified. Defaults to DEBUG
  • logfile: File name of the log file. Defaults to HyperSQL.log
  • progress: whether to output progress information to STDOUT. Boolean, defaults to 1 (aka True)
  • verification: if javadoc verification is enabled, violations will be recorded for the corresponding report. Decide here whether they should also be recorded to the log file (1, as in HyperSQL before v2.9) or not (0, default since v2.9)
  • maxkbytes: automatically rotate logfiles when they reach this size. Set to '0' (default) to turn log switching off
  • maxkbytes: automatically rotate logfiles when they reach this size. Set to '0' (default) to turn log switching off
  • backupcount: on rotation, keep this many "old" files. Default is '3'
  • capture_warnings: shall the logger capture warnings? With Python 2.7 or later, we can do so and such have them obey our log level rules. Default is '0' (disabled/do not capture). Set to '1' to activate (which will have no effect if you run a Python version < 2.7)

Verification

This section is new with v2.1 and deals with the verification of your code documentation. It is mainly based on the JavaDoc style comments you make.

  • author_in_report: shall we display @author information for the items in bug/todo/verification reports? Default is 0 (no).
  • javadoc_mandatory: should JavaDoc comments be mandatory for all objects? Does currently not affect views.
  • javadoc_mandatory_objects: for which objects Javadoc should be mandatory?
  • mandatory_tags: list of JavaDoc tags you count mandatory, separated by spaces. The pseudo-tag desc can be used here to make sure each object has a description.
  • mandatory_code_tags: mandatory tags for code only (default: empty); e.g. if you wish to make the @author tag mandatory to code only. mandatory_tags will apply to both, code and non-code objects – mandatory_code_tags to code only.
  • mandatory_codetag_objects: which objects are to be considered "code" (default: "proc func pkg")
  • stats_javadoc_forms: Include bugs/todos/verification for forms into the stats? Default: 0, since all other form stats are excluded as well currently.
  • verify_javadoc: should the verification process be enabled? By default, it is turned off (0).
  • verify_forms: as above - shall we do so for forms as well? (Default: 0)

DepGraph

Everything here belongs to the dependency graph creation:

  • fontname: Font name to use for text, e.g. "Arial" (Default: "", i.e. let graphviz decide). If you set some other name, HyperSQL will not check whether that font exists, but simply pass it to Graphviz. If the font does not exist, an error will be returned by Graphviz – and it will still use its default font (the error will be logged by HyperSQL).
  • fontsize: Used to change the font size. The default here is "", which again means to let Graphviz decide. This value must be numeric, or it is ignored (with an error logged).
  • objects: Which object types should be included with the dependency graph. By default, we take them all (view pkg proc func synonym) – but with large projects, you may want to restrict it to e.g. "view pkg", which means only views and packages (but not functions and procedures).
  • processor: chose between the multiple available Graphviz processors. Default is "fdp". See the Wikipedia or the Graphviz project page for available ones.
  • Rank separators: If there's not enough (or too much) space between the different levels, you may play with these values. Default is "" again (let Graphviz decide)
    • ranksep_dot: ranksep for the dot processor (Graphviz default: 0.5)
    • ranksep_twopi: ranksep for twopi (Graphviz default: 1.0)
    • len_fdp: similar for fdp (Graphviz default: 0.3)
    • len_neato: similar for neato (Graphviz default: 1.0)
    • mindist_circo: similar for circo
  • file2file: Whether to draw the dependency graph for access from file to file (Default: 1)
  • file2object: Similar for access from file to object (Default: 0)
  • object2file: Similar for access from object to file (Default: 1)
  • object2object: Similar for access from object to object (Default: 1)
  • deltmp: Delete the temporary graphviz command file? Default: 1. If set to 0, the corresponding command files will remain with the .tmp suffix. This may be useful in order to play with different options, taking the command line from the log file.

Colors

Here goes everything concerning graph colors. The configured values are used for both, the statistic and the dependency graphs. Values here are tuples: the first defines the background, the second the text color. Notation has to follow the hexadecimal HTML definitions for RGB, e.g. #112233 for red=0x11, green=0x22, blue=0x33.

The default colors for objects are grouped: Programm objects (packages, procedures, functions) have blueish colors assigned, data objects (tables, views) brownish to gold. As red signalizes alerts, it is used as such (bugs, very large files).

Colors for database objects

The following settings define colors for database objects, and are used for statistic and dependency graphs:

  • file: Colors for files (#dddddd #000000)
  • form: Colors for forms (#993366 #ffffff)
  • func: Colors for functions (#66aaff #000000)
  • mview: Colors for materialized views (#bb6611 #ffffff)
  • pkg: Colors for packages (#0000ff #ffffff)
  • proc: Colors for procedures (#3366ff #ffffff)
  • sequence: Colors for sequences (#ffcc00 #000000)
  • synonym: Colors for synonyms (#00ff00 #000000)
  • tab: Colors for tables (#774411 #ffffff)
  • trigger: Colors for trigger (#33ffff #000000)
  • typ: Colors for types (#ffff33 #000000)
  • view: Colors for views (#eeaa55 #000000)

Colors for Statistic Graphs

For statistic graphs, we additionally have the following definitions:

  • Lines of Code:
    • code: Colors for "plain code" (#0000ff #ffffff)
    • comment: Colors for "plain comments" (#bb6611 #ffffff)
    • mixed: Lines mixed with code and (inline) comments (#eeaa55 #000000)
    • empty: Colors for empty lines (#dddddd #000000)
  • File statistics:
    • filebig: Colors for files larger than 100k (or having more than 1000 lines) (#ff0000 #ffffff)
    • file100k: files with 50..100k size (#ff4422 #ffffff)
    • file50k: 25..50k (#dd9944 #000000)
    • file25k: 10..25k (#ffcc00 #000000)
    • file10k: files up to 10k size (#00ff00 #000000)
    • file1000l: files up to 1000 lines (#0000ff #ffffff)
    • file400l: files up to 400 lines (#ffcc00 #000000)
  • Other reports:
    • bug: Colors for bugs (#ff0000 #ffffff)
    • warn: Colors for (JavaDoc) verification warnings (#eeaa55 #000000)
    • todo: Colors for items of the todo list (#3366ff #ffffff)

Forms

Unfortunately, the XML files generated by Oracles frmf2xml processor are somehow localized when it comes to the program units, so these need to be setup as well. The defaults are currently for the German localization, since this is the only one I had available – I'd prefer to have the defaults in English as well, so maybe someone can send them to me. Sure I could do a guess – but you know where such things usually end up...

So the four settings you probably need to adjust are the ones you make in your Form Developer when creating a new code segment:

  • pck_mark: "Package Body" (a package body)
  • pcks_mark: "Package Spez." (a package specification - probably "Package Spec" in the English variant)
  • proc_mark: "Prozedur" (a procedure – I would guess "Procedure" for the English Forms)
  • func_mark: "Funktion" (a function – that will be "Function" for sure, won't it?)