| > Show on single page > Show on multiple pages |
Copyright © 2016 Squoring Technologies
Licence
No part of this publication may be reproduced, transmitted, stored in a retrieval system, nor translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of the copyright owner, Squoring Technologies.
Squoring Technologies reserves the right to revise this publication and to make changes from time to time without obligation to notify authorised users of such changes. Consult Squoring Technologies to determine whether any such changes have been made.
The terms and conditions governing the licensing of Squoring Technologies software consist solely of those set forth in the written contracts between Squoring Technologies and its customers.
All third-party products are trademarks or registered trademarks of their respective companies.
Warranty
Squoring Technologies makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Squoring Technologies shall not be liable for errors contained herein nor for incidental or consequential damages in connection with the furnishing, performance or use of this material.
Abstract
This edition of the Eclipse Plugin Guide applies to Squore 16.0.5 and to all subsequent releases and modifications until otherwise indicated in new editions.
Table of Contents
The following conventions are used in this manual.
| Typeface or Symbol | Meaning |
| Bold | Book titles, important items, or items that can be selected including buttons and menu choices. For example: Click the Next button to continue |
| Italic | A name of a user defined textual element. For example:
Username
: admin
|
Courier New
| Files and directories; file extensions, computer output. For example:
Edit the config.xml file |
Courier Bold
| Commands, screen messages requiring user action. For example:
Username
: admin
|
| > | Menu choices. For example: Select
File > Open
. This means select the File menu, then select the Open
command from it. |
| <...> | Generic terms. For example:
<SQUORE_HOME> refers to the Squore
installation directory. |
Notes
Screenshots displayed in this manual may differ slightly from the ones in the actual product.
The following acronyms and abbreviations are used in this manual.
| CI | Continuous Integration |
| CLI | Command Line Interface |
| DP | Data Provider, a Squore module capable of handling input from various other systems and import information into Squore |
| RC | Repository Connector, a Squore module capable of extracting source code from source code management systems. |
Table of Contents
This document was released by Squoring Technologies.
It is part of the user documentation of the Squore software product edited and distributed by Squoring Technologies.
This document is the Eclipse Plugin Guide for Squore.
Its objective is to guide you through various aspects of the Squore Eclipse Plugin:
Chapter 2, Introducing the Squore Eclipse Plugin positions the Squore Eclipse Plugin inside the Squore ecosystem, explaining its main features.
Chapter 3, Installing and setting up the Squore Eclipse Plugin describes the steps to follow in order to install the Squore Eclipse Plugin.
Chapter 4, Getting Started With the Squore Eclipse Plugin walks you through the features provided by the Squore Eclipse Plugin.
If you are already familiar with Squore, you can navigate this manual by looking for what has changed since the previous version. New functionality is tagged with (new in 16.0) throughout this manual. A summary of the new features described in this manual is available in the entry * What's New in Squore 16.0? of this manual's Eclipse Plugin Guide.
For information on how to use and configure Squore, the full suite of manuals includes:
Squore Installation Checklist
Squore Installation and Administration Guide
Squore Getting Started Guide
Squore Command Line Interface
Squore Eclipse Plugin Guide
Squore Configuration Guide
Squore Reference Manual
If the information provided in this manual is erroneous or inaccurate, or if you encounter problems during your installation, contact Squoring Technologies Product Support: http://support.squoring.com/
You will need a valid Squore customer account to submit a support request. You can create an account on the support website if you do not have one already.
For any communication:
support@squoring.com
Squoring Technologies Product Support
76, allées Jean Jaurès / 31000 Toulouse - FRANCE
Approval of this version of the document and any further updates are the responsibility of Squoring Technologies.
The version of this manual included in your Squore installation may have been updated. If you would like to check for updated user guides, consult the Squoring Technologies documentation site to consult or download the latest Squore manuals at http://support.squoring.com/documentation/16.0.5. Manuals are constantly updated and published as soon as they are available.
Table of Contents
Squore analyzes projects (in a broad sense) to provide high level indicators and produce personalised dashboards and tailored action lists for each kind of connected user. The whole process can be automated, and integrated in a continuous integration framework.
Information generated in this fashion can be refreshed with any desired rate, and the results will be available each time the Squore process concludes a new build. However, this scenario is best suited to a daily cycle at most, where all input files are the result of a daily commit, and results are generated along with the nightly build.
The Squore Eclipse Plugin is destined to operate at a faster rate, the objective being to deliver results during the development process, before files are committed and fed to the continuous integration process. Tightening the processing loop has several consequences for the Squore Eclipse Plugin behavior:
It doesn't need to be connected to a central Squore server to rate a project, unless for project activation / licence validation purposes.
By limiting communication with the server to a minimum, we make sure projects can evolve outside the global rating cycle, but still offer the rating service.
Should the server be unreachable, rating service is still available for a whole week, before being deactivated. Once a connection is available again, and the credentials are validated, the rating capabilities are restored.
It must be able to process and rate a project locally
The Squore Eclipse Plugin embeds the Squore rating module, much like Squore CLI.
This allows us to retrieve data from Data Providers, assemble them, and launch the Squore Analysis and Decision Engines.
Since the core module used for these phases are the exact same one used by Squore Server, the results are identical.
It must use a configuration (in terms of Analysis Model and Data Providers) synchronised with the one installed on Squore Server
Since the Squore Eclipse Plugin uses a Squore rating module, it needs a rating environment, which must be synchronised with the server's, to ensure results equivalence.
The Squore Eclipse Plugin will perform such synchronisation during the product activation, which is a feature available in the Squore Eclipse Plugin preferences page.
It must be able to manage projects using other languages than Java (e.g. C, C++, C# Ada)
The Squore Eclipse Plugin benefits from the Squore source code analyzer, which provides support for several languages (see Squore documentation for more details).
Analysis results will be available at folder and file level.
It must be integrated into the Eclipse IDE, taking advantage of its extendability
The Eclipse plugin development framework offers a number of mechanisms to enhance various parts of the IDE.The added features have been designed to be both unobtrusive and informative.
It must enhance a project's available information by displaying ratings, Action Items, Findings for each compatible object
The added information is assigned to each artefact, which means at project, file, module, class and function level. Each of these elements will have a rating, as well as a list of Action Items and Findings, depending on the model. A search view offering project artefacts sorted by rating is also available.
It must be able to manage local versions, which are dissociated from the source code control versioning mechanism
One of the differences between the Squore Eclipse Plugin and Squore is that Squore Server uses a database to store the project builds across multiple versions, whereas the Squore Eclipse Plugin uses a local file storage mechanism, to maintain a local history.
This allows functions such as DELTA_VALUE or PREVIOUS_VALUE to work as expected, and produce trend analysis indicators.
The data used to produce that trend are these of the current version, and the last rated version.
As hinted by its name, the Squore Eclipse Plugin is a developer tool. Its objective is to provide the user with enough information to help him:
As the Squore Eclipse Plugin seamlessly integrates Squore results in the IDE, and uses the same model as the one on Squore Server, the developer will gain visibility over the evaluation process, and improve his development practices to match the standard defined by the model.
The integrated rating feedback also gives the developer the opportunity to actively participate to the global effort on quality improvement.
Table of Contents
The following is a list of the officially supported operating systems:
CentOS 6
Fedora 19
RedHat EL 6
SuSe Linux 11.1
Ubuntu Server 14.04
Windows 7
Windows 8
Windows 10
Windows Server 2008 R2
Windows Server 2012 R2
For a successful installation of Squore, you will need:
The latest version of the Squore Eclipse Plugin, which can be downloaded from http://eclipse.squoring.com
A user account with system administrator privileges
The Oracle Java Development Kit version 1.7.0_51 or higher
Java 1.8 is not supported.
It is technically possible to run Squore using a 32-bit JDK, however this will limit the memory available to 1GB of RAM to run the application, which will result in poor performance. If you still want to attempt such an installation, consult the troubleshooting page at http://openwiki.squoring.com/index.php/Running_Squore_On_A_32-bit_Java_Installation
An operational Eclipse IDE. The versions currently supported are:
3.7 32 bits (Indigo)
3.7 64 bits (Indigo)
4.2 32 bits (Juno)
4.2 64 bits (Juno)
4.3 32 bits (Kepler)
4.3 64 bits (Kepler)
At least 2 GB of space available on the disk for a full installation
A compatible version of Eclipse must be downloaded from http://www.eclipse.org/downloads/ .
On Linux platforms, the following must be installed before installing Squore:
Perl version 5.10.1 or greater including the following extra-modules:
Mandatory packages:
Algorithm::Diff [module details]
Archive::Zip [module details]
Date::Calc [module details]
Digest::SHA [module details]
HTTP::Request [module details]
JSON [module details]
LWP::UserAgent [module details]
Time::HiRes [module details]
XML::Parser [module details]
Optional packages for working with Microsoft Excel:
HTML::Entities [module details]
Spreadsheet::BasicRead [module details]
Optional packages for working with OSLC systems:
Date::Parse [module details]
WWW::Mechanize [module details]
XML::LibXML [module details]
Optional packages for working with GitHub systems:
Date::Parse [module details]
Mail::Box::Manager [module details]
Mail::Message::Body::Lines [module details]
Mail::Message::Construct [module details]
Mail::Mbox::MessageParser [module details]
Net::GitHub [module details]
Optional packages for working with Semios/Prometil systems:
File::Slurp [module details]
If some of these modules are not available as packages on your operating system, use your perl installation's cpan to install the modules. Using the OS packages is recommended, as it avoids having to reinstall via cpan after upgrading your version of perl.
Tcl version 8.5 or greater,
An Eclipse installation (Indigo and up)
On Red Hat Enterprise Linux and CentOS (6.5 and 7.1), the dependencies are satisfied by the following packages:
Mandatory packages:
java-1.7.0-openjdk
perl
perl-Algorithm-Diff
perl-Archive-Zip
perl-Date-Calc
perl-Digest-SHA
perl-JSON
perl-libwww-perl
perl-Time-HiRes
perl-XML-Parser
tcl
A compatible installation of Eclipse downloaded from http://eclipse.org/downloads .
Optional packages for working with Microsoft Excel:
perl-HTML-Parser
perl-CPAN (CPAN utility requirement)
perl-Spreadsheet-ParseExcel (available in the EPEL repository)
perl-Spreadsheet-XLSX (available in the EPEL repository)
The module Spreadsheet::BasicRead is not available as a package and must therefore be installed using cpan (make sure cpan is properly configured, by running cpan without arguments first):
sudo cpan -i Spreadsheet::BasicRead
Optional packages for working with OSLC systems:
perl-TimeDate
perl-WWW-Mechanize (available in the EPEL repository)
perl-XML-LibXML
Optional packages for working with GitHub systems:
perl-TimeDate
perl-Mail-Box (available in the EPEL repository)
perl-Mail-Mbox-MessageParser (available in the EPEL repository)
perl-Net-GitHub (available in the EPEL repository)
Optional packages for working with Semios/Prometil systems:
perl-File-Slurp
For more information about how to install the Extra Packages for Enterprise Linux (EPEL) repository, consult https://fedoraproject.org/wiki/EPEL.
On Ubuntu 14.04.3 LTS, the dependencies are satisfied by the following packages:
Mandatory packages:
libalgorithm-diff-perl
libarchive-zip-perl
libdate-calc-perl
libhttp-message-perl
libjson-perl
libwww-perl
libxml-parser-perl
openjdk-7-jdk
perl
tcl
A compatible installation of Eclipse downloaded from http://eclipse.org/downloads .
Optional packages for working with Microsoft Excel:
make (CPAN utility requirement)
libhtml-parser-perl
libspreadsheet-parseexcel-perl
libspreadsheet-xlsx-perl
The module Spreadsheet::BasicRead is not available as a package and must therefore be installed using cpan (make sure cpan is properly configured, by running cpan without arguments first):
sudo cpan -i Spreadsheet::BasicRead
Optional packages for working with OSLC systems:
libtimedate-perl
libwww-mechanize-perl
libxml-libxml-perl
Optional packages for working with GitHub systems:
libtimedate-perl
libmail-box-perl
libmail-mbox-messageparser-perl
libnet-github-perl
Optional packages for working with Semios/Prometil systems:
libfile-slurp-perl
If you have deployed some third-party tools on Squore Server, they will automatically be downloaded to your client when you launch the client synchronisation script.
AntiC and Cppcheck on Linux also require special attention: Cppcheck must be installed and available in the path, and antiC must be compiled with the command:
# cd <SQUORE_HOME>/addons/Antic_auto/bin/ && gcc antic.c -o antic
For more information, refer to the Command Line Interface Manual, which contains the full details about special installation procedures for Data Providers and Repository Connectors.
The Squore Eclipse Plugin complies with the Eclipse requirements, and is an OS-independent package to be deployed in the Eclipse plugins directory. Installation is done through an update site.
Create a new update site within Eclipse
Select Help > Install new software;.
Click on Available Software Sites;.
Add a new site;
Give it a name (for example: "Squore Eclipse Plugin");
Set the location as follows:
http://eclipse.squoring.com
Go back to the "Install" window with the "OK" buttons;
Select the newly created update site;
Proceed with the plugin installation as with any Eclipse plugin.
Notes:
If the Squore Eclipse Plugin does not appear, please uncheck "Group items by category".
To speed-up installation procedure, it is possible to uncheck "Contact all update sites during install to find required software", as no external software is needed by the Squore Eclipse Plugin.
Should the plugin fail to deploy, Eclipse will notify the user of the problem cause, and will start its operations as usual. If necessary, copy and send the generated Eclipse log to support@squoring.com.
To use the Squore Eclipse Plugin, it must be activated, the server must be reachable with proper credentials, and rating preferences must be provided.
All these operations are accessible through the Windows>Preferences>Squore Eclipse Plugin page. Note that all provided information uses the Eclipse secure storage.
The Squore Eclipse Plugin preferences page
This section serves two purposes: provide status informations on the Squore Eclipse Plugin and the associated Squore server.
The Activate product button launches a product activation on the server, using the provided credentials;
The Check server button launches a server reachability check, and display the returned status.
This section contains all data required to connect to a server.
The server URL;
The user login;
The user password.
The reference rating environment is the one used by the server. The Squore Eclipse Plugin must work with the same environment. This section allows the user to synchronize with the Squore server, and specify the Squore Eclipse Plugin rating parameters.
The Synchronise with server button launches a full synchronization with the server's rating environment.
This can be a lengthy operation (depending on the server configuration), and the Eclipse status bar will inform you of its progress. You can close the preferences page during that operation.
A reference to Perl must be provided in this section. Perl being a prerequisite for Squore Eclipse Plugin, the location of the perl binary must be defined here. Typical values are:
/usr/bin/perl on Unix
C:\Applications\perl\perl\bin\perl.exe on Windows
A reference to Tcl must be provided in this section. Tcl being a prerequisite for Squore Eclipse Plugin, the location of the Tcl binary must be defined here. Typical values are:
/usr/bin/tclsh on Unix
C:\Applications\tclsh\tclsh85.exe on Windows
To successfully activate the Squore Eclipse Plugin, the following steps must be taken:
Provide the URL of a running server in the Server url field;
Provide valid credentials using the User login and User password fields;
Click on the Apply button;
Click on the Check server button. The associated text will display a status of the connection with the server;
Click on the Activate product button. The associated text should change to "Product activated";
Click on the Synchronize with server button;
Once the synchronisation is complete, select the Wizard with which the rating will be performed;
Set the Perl directory;
Set the Tcl directory.
Once the Squore Eclipse Plugin is installed in Eclipse, obtaining a Java project rating is rather straightforward.
First locate the contextual menu entry for the Java project you want to rate. This menu is only available on Java Projects.
Contextual menu on a Java project
Expanding this menu will offer you rating actions and display options.
Rating (or "building") a project with Squore Eclipse Plugin can either be performed as a baseline build or a draft build.
Rating actions
When choosing baseline build, the project rating will produce a new reference version, with which all subsequent ratings will be compared to. This will affect rating computations based on metrics previous values, as well as all trends displayed in the Squore Eclipse Plugin views.
The baseline mode is useful when a stable state of the project has been reached, and a development phase is about to begin.
When choosing draft build, the project is rated as usual, but the reference version is not modified. Multiple draft builds will always compare to the last defined baseline.
The draft mode is useful during a development phase, when the project can undergo several back and forth changes, and the user wants to keep comparing the current version to the last stable one.
The "Show" sub-menu will allow selection of several views providing rating-related information. Each one of these views displays data for the project artefact currently selected.
Display options
Rating card
Full Rating card
A finding and its location in the source code
A finding full description
Action Items
Highlights
Activating and anchoring these views to the workspace will enhance the project with global rating data, as well as useful information to help understand and ameliorate that rating.
Main view