Difference between revisions of "Globalyzer CI/CD (Continuous Integration and Continuous Delivery)"

From Lingoport Wiki
Jump to: navigation, search
(Project Definition Format)
 
(12 intermediate revisions by one other user not shown)
Line 4: Line 4:
 
[[File:GlobalyzerDashboard.png |700px]]
 
[[File:GlobalyzerDashboard.png |700px]]
   
== Using Globalyzer Lite in a Continuous Globalization System ==
+
== Using Globalyzer Lite in Lingoport's Continuous Globalization System ==
   
 
If the Lingoport Continuous Globalization System was installed and configured using the Stack Installer or Stack Updater, then Globalyzer Lite has already been integrated into the system.
 
If the Lingoport Continuous Globalization System was installed and configured using the Stack Installer or Stack Updater, then Globalyzer Lite has already been integrated into the system.
Line 19: Line 19:
   
 
You may also pass the reports to your own reporting system.
 
You may also pass the reports to your own reporting system.
  +
  +
== Using Globalyzer Lite in a General CI/CD integration ==
  +
  +
To get started using Globalyzer Lite in your CI/CD integration, please refer to [[Globalyzer_Lite_CICD_Integration |Globalyzer Lite CI/CD integration]]
   
 
== Using Globalyzer Lite from a command line ==
 
== Using Globalyzer Lite from a command line ==
Line 66: Line 70:
 
<report-path></report-path> <!-- may be specified via command line -->
 
<report-path></report-path> <!-- may be specified via command line -->
 
<report-type></report-type> <!-- See 'Report Information' -->
 
<report-type></report-type> <!-- See 'Report Information' -->
  +
<report-priorities></report-priorities> <!-- optional. List of priorities to include in reports -->
   
 
<data-dictionary-location></data-dictionary-location> <!-- optional -->
 
<data-dictionary-location></data-dictionary-location> <!-- optional -->
Line 152: Line 157:
   
 
More info at: https://docs.oracle.com/javase/7/docs/technotes/guides/net/proxies.html
 
More info at: https://docs.oracle.com/javase/7/docs/technotes/guides/net/proxies.html
  +
  +
== Exit Error Codes ==
  +
  +
If Globalyzer Lite fails, the exit code and reason should be written to the console.
  +
  +
{| style="text-align: left;"
  +
|- style="font-size: 125%;"
  +
! colspan="2" | Type
  +
|-
  +
! Name !! style="padding-left: 15px;" | Exit Code
  +
|-
  +
| ||
  +
  +
|- style="font-size: 125%;"
  +
! colspan="2" | Normal
  +
|-
  +
| EXIT_NORMAL || style="padding-left: 15px;" | 0
  +
|-
  +
| NULL_POINTER_EXCEPTION || style="padding-left: 15px;" | 1
  +
|-
  +
| ||
  +
  +
|- style="font-size: 125%;"
  +
! colspan="2" |XML Issues
  +
|-
  +
|NO_PATH_TO_XML_FILE || style="padding-left: 15px;" | 10
  +
|-
  +
| DUPLICATE_PARAMETER_IN_XML || style="padding-left: 15px;" | 11
  +
|-
  +
| XML_PARAMETER_BLANK || style="padding-left: 15px;" | 12
  +
|-
  +
| XML_INVALID_PARAMETER || style="padding-left: 15px;" | 13
  +
|-
  +
| UNABLE_TO_READ_SCHEMA || style="padding-left: 15px;" | 14
  +
|-
  +
| ||
  +
  +
|- style="font-size: 125%;"
  +
! colspan="2" | Globalyzer API compatibility
  +
|-
  +
| GLOBALYZER_API_REPORT_TYPE_NOT_MATCHED || style="padding-left: 15px;" | 30
  +
|-
  +
| GLOBALYZER_API_EXCEPTION || style="padding-left: 15px;" | 31
  +
|-
  +
| GLOBALYZER_CLIENT_SERVER_MISMATCH || style="padding-left: 15px;" | 32
  +
|- style="height:20px"
  +
|-
  +
| ||
  +
  +
|- style="font-size: 125%;"
  +
! colspan="2" | Input issues
  +
|-
  +
| IMPROPER_INPUT || style="padding-left: 15px;" | 51
  +
|-
  +
| INVALID_COMMANDS || style="padding-left: 15px;" | 52
  +
|-
  +
| PROJECT_PATH_DOES_NOT_EXIST || style="padding-left: 15px;" | 53
  +
|-
  +
| ATTEMPT_TO_READ_RC_FILE_FAILED || style="padding-left: 15px;" | 55
  +
| ||
  +
  +
|- style="font-size: 125%;"
  +
! colspan="2" | Output Issues
  +
|-
  +
| SCAN_FAILED || style="padding-left: 15px;" | 60
  +
|}
  +
  +
== Language Support ==
  +
Globalyzer Lite supports the same languages as the Globalyzer Workbench product. The Project Definition File can be created to scan a number of source code locations in different programming languages:
  +
  +
* ActionScript,
  +
* C#,
  +
* C/C++ (many variations),
  +
* Delphi,
  +
* HTML (in various web files),
  +
* Java,
  +
* JavaScript, (includes AngularJS, NodeJS, and other libraries)
  +
* Objective-C,
  +
* MXML,
  +
* Perl,
  +
* PHP,
  +
* Qt,
  +
* SQL (Oracle, MS SQL, MySQL, PostgreSQL),
  +
* Visual Basic (Classic, .NET),
  +
* VBScript, and
  +
* XML
  +
  +
== Using Local Rulesets ==
  +
Local Rule Sets is a '''Globalyzer Lite''' feature that allows scanning without accessing the Globalyzer Server.
  +
Rule sets are stored in local zip files rather than retrieved from the Server.
  +
  +
===Creating the local ruleset files===
  +
These rule set files can either be exported directly from the Server and copied to your '''<code>project-path/lingoport</code>''' directory, or exported from the Globalyzer Workbench client as an option when exporting your Globalyzer Workbench project to a Globalyzer Lite Project Definition File (Select <b>File->Export->Globalyzer->Export Project Definition (Lite)</b>).
  +
  +
<br>
  +
  +
[[File:Export_rule_sets.png|600px]]
  +
  +
<br>
  +
  +
===Using Local Rule Sets===
  +
To use Local Rule Sets, set the <b>use-local-rulesets</b> attribute to true in the Lite [[Globalyzer Lite#Project_Definition_Format|Project Definition file]].
  +
  +
When using local rule sets, you do not need to specify username/password/server information in your Project Definition File, but if you have a '''<home>/.globalyzerrc''' file the server information still must match the Project Definition File.
  +
  +
<br>
  +
  +
[[File:Lite_use_local_rulesets.png|600px]]
  +
  +
<br>
  +
  +
  +
When using local rule sets, if a local rule set is not found, Globalyzer will try to access the rule set on the server and the login information is available,
  +
  +
Use of this feature requires a '''Globalyzer License''' to be downloaded from the Server (from the Client Download page) and stored on your local machine.
  +
  +
<br>
  +
  +
[[File:Download_license.png|600px]]
  +
  +
<br>
  +
  +
  +
Place this license file in the following default locations, per OS:
  +
* Windows - <code>C:\Lingoport</code>
  +
* Linux - <code>{userhome}/lingoport</code> (<code>/var/lib/jenkins/lingoport</code> for the jenkins user on the Lingoport G11n system)
  +
* Mac - <code>/Applications/Lingoport</code>
  +
  +
=== Best Practice ===
  +
* From the Globalyzer Workbench, export the the Lite Project Definition File and Local Rule Sets in the '''lingoport''' directory under the '''top level directory of the repository'''.
  +
* Commit/Push the lingoport directory with the local Rule Set(s) and the Project Definition File to your repository
  +
  +
By following this practice, you ensure that the Rule Sets are maintained together with the source code; When either a '''CICD''' system or a developer with an '''IDE with Lite''' use the Locale Rule Sets to scan the code, the location of the files is standard and no specific customization is needed.

Latest revision as of 21:57, 18 June 2019

What is Globalyzer Lite and Globalyzer CI/CD?

Globalyzer Lite is the product that allows users to scan code and create reports without having to use the Globalyzer Workbench or set up a database. In the Lingoport Continuous Globalization Server, Globalyzer Lite (Globalyzer CI/CD) is an integral part of the process to create reports that are displayed in the Lingoport Dashboard showing the number of internationalization issues detected.

GlobalyzerDashboard.png

Using Globalyzer Lite in Lingoport's Continuous Globalization System

If the Lingoport Continuous Globalization System was installed and configured using the Stack Installer or Stack Updater, then Globalyzer Lite has already been integrated into the system.

  1. Check in a project definition file into source control.
  2. On-board a Jenkins project for the code base using one of the Globalyzer Lite templates like Lingoport.SampleLite or Lingoport.SampleLiteLRM.
  3. Check the Lingoport Dashboard and verify that the results are shown.

Globalyzer Lite is easy to integrate into other Continuous Integration (CI) systems as well.

  1. Check in a project definition file into source control (or, if you prefer, place one in the Jenkins server's filesystem).
  2. Run the following from Jenkins' shell:
    java -jar globalyzer-lite.jar -f "${WORKSPACE}/GlobalyzerProjectDefinitionFile.xml" --project-path "${WORKSPACE}" --report-path "globalyzer-lite-reports"
  3. Use the Lingoport Dashboard to display the results from the generated reports.

You may also pass the reports to your own reporting system.

Using Globalyzer Lite in a General CI/CD integration

To get started using Globalyzer Lite in your CI/CD integration, please refer to Globalyzer Lite CI/CD integration

Using Globalyzer Lite from a command line

Globalyzer Lite can be executed from a command prompt or shell via the following command:

java -jar globalyzer-lite.jar some_location/YourProjectDefinitionFile.xml

After Globalyzer Lite finishes each scan, a relevant Globalyzer report is created at the location specified in the Project Definition's report path.

Lite also allows for altering the following parameters via command line options:

  • The Project Path
  • The Report Path
  • The Files/Directories to scan
  • The location of the Globalyzer License (if using Local Rule Sets)

Project Definition Format

Here is the template for a project definition file. For the full instructions to setup a project definition file, see our help page.

   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- All items are allowed anywhere in the xml as long as the
     hierarchy is preserved -->
 <gzproject>
    <login>
        <server>  </server>    <!-- must match .globalyzerrc setting   -->
        <username></username>  <!-- must be specified in .globalyzerrc -->
        <password></password>  <!-- must be specified in .globalyzerrc -->
                               <!--    if .globalyzerrc is present     -->
        <use-local-rulesets></use-local-rulesets>  <!-- optional. May be 'true' or 'false'     -->
                                                   <!-- if true, you need a Globalyzer.license -->
        <!-- Optional Parameters (Delete this section if not using them) -->
        <optional>
            <!-- If using, host and port must be filled out -->
            <proxy-user>    </proxy-user>
            <proxy-password></proxy-password>
            <proxy-host>    </proxy-host>  <!-- required if using proxy -->
            <proxy-port>    </proxy-port>  <!-- required if using proxy -->
        </optional>
    </login>
    <!-- Paths may be absolute, or relative -->
    <project-path></project-path> <!-- may be specified via command line -->
    <project-name></project-name>

    <report-path></report-path>   <!-- may be specified via command line -->
    <report-type></report-type>   <!-- See 'Report Information' -->
    <report-priorities></report-priorities> <!-- optional. List of priorities to include in reports -->

    <data-dictionary-location></data-dictionary-location> <!-- optional -->
    <filter-with-dictionary></filter-with-dictionary> <!-- optional. May be 'true' or 'false' -->

    <scan-timeout>500</scan-timeout>  <!-- optional. Max value 600 (seconds) -->
    <generate-partial-results></generate-partial-results> <!-- optional. May be 'true' or 'false' -->
    <save-history></save-history> <!-- optional. May be 'true' or 'false' -->

    <scans>
        <scan>
            <!-- create and execute a single scan with this info -->
            <scan-name>    </scan-name>
            <ruleset-name> </ruleset-name>  <!-- must match existing -->
            <ruleset-owner></ruleset-owner>
        </scan>
        <scan>
            <!-- create and execute a single scan with this info -->
            <scan-name>    </scan-name>
            <ruleset-name> </ruleset-name>  <!-- must match existing -->
            <ruleset-owner></ruleset-owner>
            <!-- optional -->
            <use-machine-learning>true</use-machine-learning> <!-- May be 'true' or 'false'         -->
                                                              <!-- if true, you must have generated --> 
                                                              <!-- machine learning zip files       -->
                                                              <!-- from the Workbench               -->
            <!-- optional -->
            <encoding>UTF-8</encoding> <!-- encoding of files to scan -->
            <!-- optional -->
            <scan-items>         <!-- may be overridden via command line -->
                <item></item>    <!-- delete me if blank -->
                <item></item>    <!-- delete me if blank -->
            </scan-items>
            <!-- optional -->
            <comments>
                <!-- customize Globalyzer recognized comments -->
                <todo>SPECIAL_GLOBALYZER_TODO_COMMENT</todo>
                <ignore-next-line>GBLYZR_IGNORE_NEXT_LINE</ignore-next-line>
                <start-ignore>GLOBALYZER_START_IGNORE</start-ignore>
                <end-ignore>GBL_END_IGNORE</end-ignore>
            </comments>
            <!-- optional -->
            <checks>
              <!-- specify which issue types to detect -->
              <embedded-strings>true</embedded-strings>
              <locale-sensitive-methods>false</locale-sensitive-methods>
              <general-patterns>true</general-patterns>
              <static-file-references>false</static-file-references>
            </checks>
        </scan>
    </scans>
 </gzproject>

The .globalyzerrc File

Globalyzer Lite supports an optional .globalyzerrc file. This file may be used to specify login, server, and proxy parameters. Below is an example .globalyzerrc file. It contains all parameters that may be set within the rc file:

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

All settings besides 'server' are optional. And Project Definition Files do not need to specify parameters set in the .globalyzerrc file (with the exception of 'server'). Any parameter that is set in the Project Definition File will override the .globalyzerc file setting.

If you choose to use a .globalyzerrc, the 'server' parameter is mandatory. It must match the server specified in Project Definition Files. This helps prevent rule sets from being retrieved from the wrong server.

The .globalyzerrc file must be located in the home directory of the user using Globalyzer Lite. For a Lingoport Continuous Globalization Server, this means, it resides in the /var/lib/jenkins directory owned by the jenkins user.

Setting Proxy Settings via Java

If you prefer to specify proxy settings via Java, rather than through the Project Definition File, you may use any of the following Java settings.

-Dhttp.proxyHost=your.server.com
-Dhttp.proxyPort=80
-Dhttps.proxyHost=your.server.com
-Dhttps.proxyPort=80
-Dhttp.nonProxyHosts=123.210.123.210
-DsocksProxyHost=your.server.com
-DsocksProxyPort=1080

More info at: https://docs.oracle.com/javase/7/docs/technotes/guides/net/proxies.html

Exit Error Codes

If Globalyzer Lite fails, the exit code and reason should be written to the console.

Type
Name Exit Code
Normal
EXIT_NORMAL 0
NULL_POINTER_EXCEPTION 1
XML Issues
NO_PATH_TO_XML_FILE 10
DUPLICATE_PARAMETER_IN_XML 11
XML_PARAMETER_BLANK 12
XML_INVALID_PARAMETER 13
UNABLE_TO_READ_SCHEMA 14
Globalyzer API compatibility
GLOBALYZER_API_REPORT_TYPE_NOT_MATCHED 30
GLOBALYZER_API_EXCEPTION 31
GLOBALYZER_CLIENT_SERVER_MISMATCH 32
Input issues
IMPROPER_INPUT 51
INVALID_COMMANDS 52
PROJECT_PATH_DOES_NOT_EXIST 53
ATTEMPT_TO_READ_RC_FILE_FAILED 55
Output Issues
SCAN_FAILED 60

Language Support

Globalyzer Lite supports the same languages as the Globalyzer Workbench product. The Project Definition File can be created to scan a number of source code locations in different programming languages:

  • ActionScript,
  • C#,
  • C/C++ (many variations),
  • Delphi,
  • HTML (in various web files),
  • Java,
  • JavaScript, (includes AngularJS, NodeJS, and other libraries)
  • Objective-C,
  • MXML,
  • Perl,
  • PHP,
  • Qt,
  • SQL (Oracle, MS SQL, MySQL, PostgreSQL),
  • Visual Basic (Classic, .NET),
  • VBScript, and
  • XML

Using Local Rulesets

Local Rule Sets is a Globalyzer Lite feature that allows scanning without accessing the Globalyzer Server. Rule sets are stored in local zip files rather than retrieved from the Server.

Creating the local ruleset files

These rule set files can either be exported directly from the Server and copied to your project-path/lingoport directory, or exported from the Globalyzer Workbench client as an option when exporting your Globalyzer Workbench project to a Globalyzer Lite Project Definition File (Select File->Export->Globalyzer->Export Project Definition (Lite)).


Export rule sets.png


Using Local Rule Sets

To use Local Rule Sets, set the use-local-rulesets attribute to true in the Lite Project Definition file.

When using local rule sets, you do not need to specify username/password/server information in your Project Definition File, but if you have a <home>/.globalyzerrc file the server information still must match the Project Definition File.


Lite use local rulesets.png



When using local rule sets, if a local rule set is not found, Globalyzer will try to access the rule set on the server and the login information is available,

Use of this feature requires a Globalyzer License to be downloaded from the Server (from the Client Download page) and stored on your local machine.


Download license.png



Place this license file in the following default locations, per OS:

  • Windows - C:\Lingoport
  • Linux - {userhome}/lingoport (/var/lib/jenkins/lingoport for the jenkins user on the Lingoport G11n system)
  • Mac - /Applications/Lingoport

Best Practice

  • From the Globalyzer Workbench, export the the Lite Project Definition File and Local Rule Sets in the lingoport directory under the top level directory of the repository.
  • Commit/Push the lingoport directory with the local Rule Set(s) and the Project Definition File to your repository

By following this practice, you ensure that the Rule Sets are maintained together with the source code; When either a CICD system or a developer with an IDE with Lite use the Locale Rule Sets to scan the code, the location of the files is standard and no specific customization is needed.