Overview

Globalyzer Lite reads and parses Globalyzer Project Definition XML Files to create projects and scans, execute those scans, and generate reports.

The following sections describe how to install and run Globalyzer Lite; how to integrate Globalyzer Lite with your build system; how to display Globalyzer Lite reports in the Lingoport Dashboard; and finally, how to customize Project Definition files on the fly.

How to install Globalyzer Lite

To install Globalyzer Lite, first unzip it in a directory of your choice. After unzipping, Globalyzer Lite needs to be installed on your machine:

On Windows: Open a Command Prompt, navigate to the directory where you unzipped Globalyzer Lite, then run: install-lite.bat
On Linux or MacOS: Open a terminal, navigate to the directory where you unzipped Globalyzer Lite, then run: ./install-lite.sh

The optional .globalyzerrc file

If desired, you may create a .globalyzerrc file within your home directory. You can use this file to specify server information, login information and proxy settings. You can also set these settings within Globalyzer Lite Project Definition Files (see below). Settings specified in project definition files will override those in the .globalyzerrc.

If you create a .globalyzerrc, username, password, and the Globalyzer server URL are required. Lingoport's server is at https://www.globalyzer.com/gzserver, although you may be using one or more servers set up internally within your company.

If you have a server defined in the project definition file (that is, server is not blank), it must match the .globalyzerrc setting. Globalyzer Lite will refuse to run if two different servers are specified. The purpose of this check is to protect against retrieving rule sets from the wrong server.

Below is a fully filled out .globalyzerrc:


server https://www.globalyzer.com/gzserver
username user@company.com
password aPasswordHere

proxy-host https://internalhost.company.com
proxy-port 81038
proxy-user ExampleUser
proxy-password ExamplePassword

How to run Globalyzer Lite

After unzipping, installing, possibly creating a .globalyzerrc, and defining a Globalyzer Lite Project Definition XML file (or receiving a predefined one from your team), you will be ready to use Globalyzer Lite. To use it, call globalyzer-lite.jar, passing in the XML file. This is illustrated in the examples below.

> java -jar globalyzer-lite.jar lingoport/LiteProjectDefinition.xml

Here is a simple example LiteProjectDefinition.xml file, configured using minimal settings. This file, and its more advanced settings, are documented in the Globalyzer Lite Project Definition File help page.

The below settings are for a windows system. If using OSX or Linux, paths would instead be specified in unix style.


    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <gzproject>
      <login>
        <username>bob@mycompany.com</username>
        <password>abc123</password>
        <server>http://globalyzer.com/gzserver</server>
      </login>

      <project-path>/home/Bob/project_source</project-path>
      <project-name>BobProject</project-name>

      <report-path>LiteReports</report-path>
      <report-type>ScanDetailedCSV</report-type>

      <scans>
        <scan>
          <scan-name>javascan</scan-name>
          <ruleset-name>java</ruleset-name>
          <ruleset-owner>bob@mycompany.com</ruleset-owner>
          <scan-items>
            <item>java</item>
          </scan-items>
        </scan>
        <scan>
          <scan-name>csharpscan</scan-name>
          <ruleset-name>csharp</ruleset-name>
          <ruleset-owner>bob@mycompany.com</ruleset-owner>
          <scan-items>
            <item></item>
          </scan-items>
        </scan>
        <scan>
          <scan-name>xmlscan</scan-name>
          <ruleset-name>xml</ruleset-name>
          <ruleset-owner>bob@mycompany.com</ruleset-owner>
          <scan-items>
            <item></item>
          </scan-items>
        </scan>
      </scans>
    </gzproject>

Run globalyzer-lite using the Project Definition File from the command line (Windows or Linux):

> java -jar globalyzer-lite.jar lingoport/LiteProjectDefinition.xml


        Reading Project Definition XML file.
        Validating input.
        Logging in.
        Creating project.
        Project path: /home/Bob/project_source
        Report path: LiteReports
        Creating scans.
         [1/3]  Creating javascan
                - Scan items: [java]
         [2/3]  Creating csharpscan
                - No scan items given, scanning all files matching rule set patterns
         [3/3]  Creating xmlscan
                - No scan items given, scanning all files matching rule set patterns
        Executing scans.
         [1/3]  Executing javascan             /home/Bob/project_source/lite_reports/javascan_detailed_report.csv
         [2/3]  Executing csharpscan           /home/Bob/project_source/lite_reports/csharpscan_detailed_report.csv
         [3/3]  Executing xmlscan              /home/Bob/project_source/lite_reports/xmlscan_detailed_report.csv
        Done.

Optionally, Globalyzer Lite supports using multiple command line arguments to override several options usually specified in a project definition file. These are as follows:

-f <string>
The location of the project description file. (Prefix optional)

> java -jar globalyzer-lite.jar -f lingoport/LiteProjectDefinition.xml

-l,--license <string>
Set custom location for Globalyzer.license file.

> java -jar globalyzer-lite.jar -l /home/Miguela/MyLicenseLocation lingoport/LiteProjectDefinition.xml
> java -jar globalyzer-lite.jar --license /home/Miguela/MyLicenseLocation lingoport/LiteProjectDefinition.xml

-rl,--ruleset-location <string>
Set custom location for exported rule sets.

> java -jar globalyzer-lite.jar -rl /home/Miguela/MyRulesets lingoport/LiteProjectDefinition.xml
> java -jar globalyzer-lite.jar --ruleset-location /home/Miguela/MyRulesets lingoport/LiteProjectDefinition.xml

-h,--help
Show the help message and all command line options.

> java -jar globalyzer-lite.jar -h
> java -jar globalyzer-lite.jar --help



		usage: help
		-co,--console-output <string>              Method for printing the
                                                    generated scan report output
							                     to the console. Requires use
							                     of one of:
							                     [ScanDetailedXML,
							                     ScanDetailedCSV]
							                     Valid input:
							                     [gnu, gnu_std, gnu-std]
							                     [vs, visual_studio,
						                         visual-studio]
							                     [ecd, eclipse-default,
						 	                     eclipse_default]
							                     [none]

		-db,--debug                                Print contents of all calls to
							                     the GlobalyzerAPI.

		-ddl,--data-dictionary-location <string>   Optional. Set custom location
							                     for Globalyzer Lite to write
							                     its internal dictionary
							                     information to. Default is
							                     '$HOME/.globalyzer'.

		-f <string>                                Location of project definition
							                     file. (Option prefix optional)

		-fwd,--filter-with-dictionary <string>     (Must be set to 'true' or
							                     'false') Whether or not to
						                         filter against a dictionary.
							                     By default, a dictionary will
							                     be used.

		-h,--help                                  Show this help message.

         -l,--license <string>                      Location of Globalyzer.license file.
							

		-pp,--project-path <string>                Path to the project that will
							                     be scanned.

		-rl,--ruleset-location <string>            Location of exported rule sets.
							
		-rp,--report-path <string>                 Path to write Globalyzer
							                     reports to.

		-si,--scan-items <string>                  Specify which
							                     files/directories to scan.
							                     (Overrides preferences for all
							                     scans). Place items together,
							                     separated by commas.
							                    'aFileName,aDirectoryPath,...'

		-st,--scan-timeout <string>                Timeout threshold, in seconds,
							                     for each file scanned.
							                     Defaults to 120 (2 minutes).
							                     Max 300 (5 minutes). SQL files
						                         are typically the slowest to
							                     scan.

		-vn,--version                              Display version number.

-si,--scan-items <string>
Specify which files/directories to scan. (Overrides preferences for all scans.) Place items together, separated by commas.

> java -jar globalyzer-lite.jar -si 'dir1,dir2,file1' lingoport/LiteProjectDefinition.xml
> java -jar globalyzer-lite.jar --scan-items 'dir1,dir2,file1 lingoport/LiteProjectDefinition.xml

	
    Reading Project Definition XML file.
    Validating input.
    Logging in.
    Creating project.
    Project path: /home/Bob/project_source
    Report path: LiteReports
    Creating scans.
     [1/3]  Creating javascan
            - Scan items: [dir1, dir2, file1]
     [2/3]  Creating csharpscan
            - Scan items: [dir1, dir2, file1]
     [3/3]  Creating xmlscan
            - Scan items: [dir1, dir2, file1]
    Executing scans.
     [1/3]  Executing javascan            /home/Bob/project_source/LiteReports/javascan_detailed_report.csv
     [2/3]  Executing csharpscan          /home/Bob/project_source/LiteReports/csharpscan_detailed_report.csv
     [3/3]  Executing xmlscan             /home/Bob/project_source/LiteReports/xmlscan_detailed_report.csv
    Done.

-st,--scan-timeout <string>
Timeout threshold, in seconds, for each file scanned. Default is 120 seconds (2 minutes). Max is 600 seconds (10 minutes).

> java -jar globalyzer-lite.jar -st 10 lingoport/LiteProjectDefinition.xml
> java -jar globalyzer-lite.jar --scan-timeout 300 lingoport/LiteProjectDefinition.xml

-pp,--project-path <string>
The path to the project that will be scanned.

> java -jar globalyzer-lite.jar -pp /home/Miguela/ProjectSource lingoport/LiteProjectDefinition.xml
> java -jar globalyzer-lite.jar --project-path /home/Miguela/ProjectSource lingoport/LiteProjectDefinition.xml


    Reading Project Definition XML file.
    Validating input.
    Logging in.
    Creating project.
    Project path: /home/Miguela/ProjectSource/
    Report path: LiteReports
    ....

-rp,--report-path <string>
The path to write Globalyzer reports to.

> java -jar globalyzer-lite.jar -rp NewLiteReports lingoport/LiteProjectDefinition.xml
> java -jar globalyzer-lite.jar --report-path NewLiteReports lingoport/LiteProjectDefinition.xml


    Reading Project Definition XML file.
    Validating input.
    Logging in.
    Creating project.
    Project path: /home/Bob/ProjectSource/
    Report path: NewLiteReports

-co,--console-output <string>
The method for printing the generated scan report output to an IDE console. This requires the use of specific report types in the Project Definition file: [ScanDetailedXML, ScanDetailedCSV]. The default value is 'none' and no output will be displayed to the IDE console. (See Report Information for more info.)
Valid inputs: [gnu, gnu_std, gnu-std, vs, visual_studio, visual-studio, ecd, eclipse-default, eclipse_default, none]

> java -jar globalyzer-lite.jar -co gnu lingoport/LiteProjectDefinition.xml
> java -jar globalyzer-lite.jar --console-output gnu lingoport/LiteProjectDefinition.xml


    Reading Project Definition XML file.
    Validating input.
    Logging in.
    Creating project.
    Project path: /home/Bob/ProjectSource/
    Report path: LiteReports
    Creating scans.
     [1/3]    Creating javascan
        - Scan items: [java]
     [2/3]    Creating csharpscan
        - No scan items given, scanning all files matching rule set patterns
     [3/3]    Creating xmlscan
        - No scan items given, scanning all files matching rule set patterns
    Executing scans.
     [1/3]    Executing javascan             /home/Bob/ProjectSource/LiteReports/javascan_detailed_report.csv
     [2/3]    Executing csharpscan           /home/Bob/ProjectSource/LiteReports/csharpscan_detailed_report.csv
     [3/3]    Executing xmlscan              /home/Bob/ProjectSource/LiteReports/xmlscan_detailed_report.csv
    javascan (ScanDetailedCSV) results:
    /home/Bob/ProjectSource/java/EditCorrespondenceControl_MethodFilter.java:189: Embedded Strings, P1: "montañas"
    /home/Bob/ProjectSource/java/EditCorrespondenceControl_MethodFilter.java:190: Embedded Strings, P3: "ok"
    /home/Bob/ProjectSource/java/EditCorrespondenceControl_MethodFilter.java:197: Embedded Strings, P2: "Please ..."

    csharpscan (ScanDetailedCSV) results:
    /home/Bob/ProjectSource/csharp/Detail.cshtml:9: Embedded Strings, P3: "text/javascript"
    /home/Bob/ProjectSource/csharp/Detail.cshtml:12: Embedded Strings, P3: "#price"
    /home/Bob/ProjectSource/csharp/Detail.cshtml:15: Embedded Strings, P3: "price"

    xmlscan (ScanDetailedCSV) results:
    /home/Bob/ProjectSource/actionscript/Form.mxml:5: Embedded Strings, P3: "components.*"
    /home/Bob/ProjectSource/actionscript/Form.mxml:20: Embedded Strings, P1: "Get a free gift!"
    /home/Bob/ProjectSource/actionscript/Form.mxml:21: Embedded Strings, P1: "Name"

-ddl,--data-dictionary-location <string>
Set custom location for Globalyzer Lite to write its internal dictionary information to. Default is $HOME/.globalyzer. A folder, 'dict', will be created inside this location. E.g. '$HOME/.globalyzer/dict'.

> java -jar globalyzer-lite.jar -ddl /home/Miguela/GlobalyzerDict lingoport/LiteProjectDefinition.xml
> java -jar globalyzer-lite.jar --data-dictionary-location /home/Miguela/GlobalyzerDict lingoport/LiteProjectDefinition.xml

-fwd,--filter-with-dictionary <string>
Whether or not to filter results against a dictionary. Default is 'true'.

> java -jar globalyzer-lite.jar -fwd true lingoport/LiteProjectDefinition.xml
> java -jar globalyzer-lite.jar --filter-with-dictionary false lingoport/LiteProjectDefinition.xml

-db,--debug
Prints out the content of all calls from Lite to the Globalyzer API. E.g.

...
GlobalyzerAPI.createProject("entered project name", "entered project path");
...

-vn,--version
Display the version of Globalyzer Lite being used.


> java -jar globalyzer-lite.jar -v
> java -jar globalyzer-lite.jar --version

    Globalyzer Lite Version: 6.8.0

Using Lite in an IDE

See the IDE usage instructions.

Customizing Project Definition Files on the Fly

You may wish to create a tokenized Project Definition File that can be reused for various projects. The tokens would be substituted with current project information via the build script, before calling Globalyzer Lite to read the file.

Simply use placeholder tokens in the XML file, then replace them during your build. For example:


<project-name>PROJECT_NAME_PLACEHOLDER</report-name>

You can then add the following sed command to your build:

sed --in-place "s|PROJECT_NAME_PLACEHOLDER|text to substitute|" $WORKSPACE/GlobalyzerProjectDefinition.xml

Your build script might then look like:

# Variables:
#   $WORKSPACE      : Source code location of the project to be scanned
#   $JOB_NAME       : Name of your Dashboard project
cp -f /path/to/TokenizedGlobalyzerProjectDefinition.xml $WORKSPACE/GlobalyzerProjectDefinition.xml
sed --in-place "s|PROJECT_NAME_PLACEHOLDER|$JOB_NAME|" $WORKSPACE/GlobalyzerProjectDefinition.xml
java -jar $LITE_HOME/globalyzer-lite.jar $WORKSPACE/GlobalyzerProjectDefinition.xml

If you're familiar with bash, sed and regular expressions, and wish for a more advanced method of substituting the contents of tags within the project definition, then the following bash function may be helpful:


replace_xml_token() {
  token_name=$1
  new_content=$2
  sed -ri "s|(<${token_name}>).*(</${token_name}>)|\1${new_content}\2|g" $WORKSPACE/ProjectDefinition.xml
}

Integrating Globalyzer Lite with Lingoport Dashboard

To display the reports generated by Globalyzer Lite on the Lingoport Dashboard, you must specify a specific report path. This report path must link to the GlobalyzerScans directory in your corresponding Dashboard Project.
For example:


<report-path>/var/lib/jenkins/Lingoport_Data/Dashboard/Projects/DashboardProjectName/GlobalyzerScans</report-path>

If you are configuring the Lingoport Dashboard for the first time, you may also need to create the Dashboard Project directory for your Dashboard Project and its GlobalyzerScans directory. Click here for information on the Lingoport Dashboard.

The next time DashboardUpload.sh is run for Globalyzer Scans, your results will appear on the Dashboard. For example:

# Variables:
#   $JOB_NAME       : Name of your Dashboard project
#   $WORKSPACE      : Source code location of the project to be scanned
#   $LITE_HOME      : Location Globalyzer Lite was unzipped to
#   $DASHBOARD_HOME : Location of the Lingoport Dashboard installation

To set the location of LITE_HOME and DASHBOARD_HOME, first go to https://jenkins.url:port/configure. Find "Global Properties" and check "Environment variables". Next, add a key-value pair for LITE_HOME and another for DASHBOARD_HOME.

Jenkins will automatically set WORKSPACE and JOB_NAME.


Shell script run:
  set -x
  java -jar $LITE_HOME/globalyzer-lite.jar $WORKSPACE/GlobalyzerProjectDefinition.xml \
    --project-path "$WORKSPACE" \
    --report-path "/var/lib/jenkins/Lingoport_Data/Dashboard/Projects/$JOB_NAME/GlobalyzerScans"
  cd /var/lib/jenkins/Lingoport_Data/Dashboard/Projects/$JOB_NAME
  $DASHBOARD_HOME/bin/DashboardUpload.sh "$WORKSPACE" "$JOB_NAME" "G"


Output:
+ env
JOB_NAME="projectName"
WORKSPACE="/var/lib/jenkins/jobs/$JOB_NAME/workspace"
LITE_HOME="/var/lib/jenkins/lingoport/globalyzer-lite-6.8.0"
DASHBOARD_HOME="/var/lib/jenkins/lingoport/dashboard-client-5.1.2.2"

+ java -jar $LITE_HOME/globalyzer-lite.jar $WORKSPACE/GlobalyzerProjectDefinition.xml \
    --project-path "$WORKSPACE" \
    --report-path "/var/lib/jenkins/Lingoport_Data/Dashboard/Projects/$JOB_NAME/GlobalyzerScans"

  Reading Project Definition XML File.
  ...
    [1/1]    Executing javascan             /var/lib/jenkins/Lingoport_Data/Dashboard/Projects/projectName/GlobalyzerScans/javascan_detailed_report.xml
  ...
  Done.

+ cd /var/lib/jenkins/Lingoport_Data/Dashboard/Projects/$JOB_NAME
+ $DASHBOARD_HOME/bin/DashboardUpload.sh "$WORKSPACE" "$JOB_NAME" "G"