Resource Standard Metrics Wizard
User Manual 

 

Introduction

 

Resource Standard Metrics™  (RSM) by M Squared Technologies LLC™ is a command line program that consumes C, C++, C# and Java source code files and produces source code metrics (LOC, Effective LOC, and Logical LOC), source code quality analysis for a single file, set of files or differentials between separate baselines.  As a command line program, RSM is cross complied to operate on the following operating systems (OS); Windows XP, Vista, 7, Linux, and all Unix Variants including the Mac OS-X (a Linux/Unix like OS).  RSM comes in various licenses from single user, network and site licenses for Windows, Linux, and Universal UNIX.  Recompilable source code for the Universal UNIX product license is provided with these licenses for compilation on the end users specific hardware and UNIX operating system.  A GCC 3.0+ ANSI-C compiler is required to recompile RSM under a UNIX like operating system. 

 

The complexity of the command line options for RSM necessitated a need to create a RSM User Interface (UI).  This program is called the RSM Wizard and is provided as a Windows application because the majority of users requesting a UI were windows users.  The Wizard is designed to step the end user through the required components of the RSM command line. 

 

These components are:

 

 

 

 

 

 

As if by magic, the Wizard takes all these components and builds the RSM command line.  The Wizard command line continuously updates as you modify the components in the Wizard.  If you uncheck the “Auto” check box, the command line freezes, allowing a copy from the text box.  This copy can be pasted into a script, if you are scripting RSM for command line operation.

 

When you are satisfied with the content of all the components, click the “Execute” button.  The Wizard will launch RSM with the command line.  RSM will create the output file and through the operating system, attempt to launch the application associated by the file extension.  For the HTML format, the default web browser may be launched.  For the .txt extension, the default text editor may be launched or you can select a text editor under “Wizard Main Menu” – “Edit” – “Wizard” - “Preferences”.  You may also select a XML editor for the XML file extension.  We recommend a free text editor called “Notepad++” which can be downloaded from SourceForge.net and linked into the Wizard preferences.  The CSV file format may launch the Microsoft Office Excel, if it is installed.  Associating a file type (*.csv, *.html, etc) is covered by the following hyperlinked Microsoft MSDN Document.

RSM Wizard Installation

The Wizard uses a Windows installer to install RSM and the Wizard in the “Program Files” folder.  The data files for the Wizard are placed in the user’s home directory.  The home directory under Windows XP is shown in the following example:

 

            C:\Documents and Settings\USER NAME\M2 RSM Wizard

                        \input                - “Input file lists in the form of filename.lst”

                        \output              - “RSM output, filename.htm, filename.txt, filename.csv, filename.xml”

                        \reports             - “User created reports in the form of filename.rpt”

                        \solutions          - “Wizard solutions in the form of filename.rsm”

                        \workfiles          - “Work files for differential metrics, filename.dat”

 

Microsoft Vista and Windows 7 use a “Users” directory instead of “Documents and Settings”.

 

Files should be stored in these locations to keep the Wizard data files organized and owned by the end user.  The Save button will allow you to locate the correct folder if it is not already shown and then allow the rename of the default filename. 


RSM Wizard User Interface

 

Figure 1: RSM Wizard User Interface

Main Menu

The Main Menu is located at the very top of the user interface and has the following sub menus.

 

                        File

                                    Solution

                                                Load – “Loads a previously saved solution.”

                                                Save – “Saves the Wizard RSM elements for later RSM execution.”

                                    Exit – “Exits the application to the operating system.”

                       

Edit

            Wizard

                        Preferences – “User options for the application.”

            RSM

                        Configuration File – “Configures the performance of RSM. A must read!”

                        Macro Configuration File – “Specifies macro names that appear like

functions.”

                        Differential Configuration File – “Rarely modified, enables removed LOC

to be additive to the differential metrics.”

                        User Defined Quality Notice File – “UDQNs are defined in this file.”

                       

                        Action

                                    Execute

“Launches RSM with the Wizard elements.”

                        Help

                                    About

Application information, version, copyright, etc.

                                    Wizard

                                                Help All Sections – “All section help documents rolled into one.”

                                                Help By Section – “Help for each section of the RSM Wizard”

                                                Tutorials – “Some step by step tutorials.”

                                    RSM

                                                License Data – “Information about your RSM license.”

                                                User’s Manual – “User’s Manual for RSM.”

                                                Web Site – ‘Link to the RSM web site and on-line documentation.”

                                                Updates – “Link to RSM support page for updates.”

                                    Web Site – “Link to M Squared Technologies web site.”

                                    License – “End Users License Agreement (EULA)”

Guided Process Steps

The Wizard user interface is divided into regions that support the various components of the RSM command line.  There is a suggested order or guided process for using each region.  This process is supported by region buttons that activate and deactivate portions of the user interface.  There is a general Help button that details the guided process.

 

Figure 2: RSM Wizard Guided Process Buttons

 

Each region can be operated independently when the “Free Play” region button is selected or the user can chose to step through the guided process by pressing in order each numbered button.  When a button is pressed the associated region of the user interface is activated and all other regions are deactivated.

 

The numbered sequence of buttons will hopefully help the user understand how to use the Wizard in the correct order for building the RSM command line. 

 

The following sequential steps represent the suggested process for using the Wizard.

 

 

The Solution region, Figure 3, shows the path/file name for the solution, a name expansion/contraction (+/-), Load, and Save Buttons.  The first thing you may want to do is to load a previously saved solution to execute or modify it.  In addition, if you are starting a new Wizard session, it would be best to name the solution, using the Save button, so that you do not forget at the end of your Wizard session.

 

A RSM Wizard solution is a XML file that contains the state of the Wizard.  When a solution is loaded, the RSM Wizard is placed back into the state when the solution was saved.  This capability is used to load different metric and analysis states for various projects.

 

The Save button shows the solution folder that was created on installation.  The installation folders for RSM Wizard data are located in your “username” Windows home directory.  The user home directory differs between the different Windows operating systems.  For Windows XP your home directory will be under a directory called “Documents and Settings”, under Vista and Windows 7 there will be a directory called “Users”.

 

 

Figure 3: RSM Wizard Solution Region

 



Figure 4: RSM Wizard User Directories

 



The RSM Wizard provides file and directory tools that facilitate the creation of a source code file list that serves as input to RSM program.  These tools are divided into two user interface regions.  The “Selection Tree of Path or Files” region, Figure 5, supports the acquisition of paths or files from the file system. 

 

Figure 5: Selection Tree of Paths or Files Region

 

The second region, “RSM Input File List”, Figure 6, support the edit and saving of the file list that is used by the RSM –F command option.  The format for the RSM input file list supports both individual files (Figure 6) and paths (Figure 7).  The file format is documented in the RSM –h help text or the RSM on-line documentation under the –F Command Option and is shown in the file list display field. 

 

Figure 6: RSM File List Tool “Files Mode”

 

Figure 7: RSM Input File List “Path Mode”

 

The user must first select an “Acquisition Mode” for either Paths (using recursive descent and rsm.cfg settings) or individual Files (using Wizard filters and rsm.cfg settings).  If Paths mode is chosen, paths are placed in the RSM file list, RSM will create a metrics summary rollup for these paths.  This is useful for getting subcomponent metrics rollups for a project when the subcomponents are divided into paths (.\project\ui, \project\controller, etc.).

 

The “Selection Tree of Path or Files” region is shown in Figure 5.  Most users will select the “Files” mode for collecting files from the file system.  In this mode you can use several filtering tools that will help in the selection of just the source code files to be analyzed. 

 

Figure 8: Source code acquisition mode

 

The following sequence is the typical process for using the “Files” mode.

 

 

The “Set Path” button activates a system dialog for the selection of a directory that is the top of the source code tree.  Once the path is selected, it is shown in the path display/edit field, Figure 9.  The Path Recurse check box activates or deactivates recursive descent for file collection. 

 

Figure 9: Path display/edit field

 

Next you will want to consider the various filters that will narrow the search domain for the selection of files when [Acquire Files] is pressed.

 

File Filters

 

 

The extension filter is a comma separated list of extensions that adds (+) only those files that match an extension in the tree.  The dot or period is not used and do not use spaces unless they are important.  The check box activates or deactivates the extension filter.

 

 

 

The pattern filter removes (-) files when the file path matches one of the substrings in the comma separated list.  This example shows two substrings “.gui.cs” and “.ui.cpp” where the dot or period and spaces are important for matching the substring.  The pattern filter is superior to the extension filter where “ui.cpp” is filtered even though cpp matches the extension filter.

 

 

The directory filter is superior to all other filters.  Directories that match the filter are ignored for file processing.  This filter must be used to filter out your configuration management directories.

 

 

The Clear Tree Button removes all the entries from the tree window.  Removing files from the Wizard user interface DOES NOT delete them from the file system.

 

 

 

The Acquire Files button reads the path and begins to acquire files according to the recurse check box and filters.  The resultant directory tree and files are shown in the display box, Figure 5.  The Right Mouse Button is active for a tree entry.  This submenu can clean up, review or edit the files before they are placed into the file list, Figure 10.

 

Figure 10: File tree submenu

 

 

Pressing this button will initiate a descent of the file tree placing files into the Input file list edit window, Figure 6.  Depending on the size of the source code tree, this process may take some time.  Each time Files To List Button is pressed, the File List is automatically cleared.  To build up a list of files from different and sequential processes of “Set Path, Acquire Files, Files to List” the Append Check Box must be checked.

 

  When the Append Check Box is checked, it disables the automatic clearing of the list when the Files to List button is pressed.  For Example:  We will assemble files from two baseline trees using the Append Check Box Checked.

 

[Clear Tree]

[Clear] File List

 

[Set Path]
“C:\Program Files\MSquared\M2 RSM Wizard\example code\Lotto Baseline 1”

 

                                    [Acquire Files]

                                    [Files To List]

                                    Append Check Box Checked

 

                                    [Clear Tree]                              

 

                                    [Set Path]
                                    “C:\Program Files\MSquared\M2 RSM Wizard\example code\Lotto Baseline 2”

 

                                    [Acquire Files]

                                    [Files To List]

 

The result of this process is shown in Figure 11.  Once the file list is assembled, it can be edited with RMB “cut”, “copy” and “paste” similar to any edit field.  You can also type entries directly into the edit field.  It is important to save the File List to a file that is named relative to the baseline and version.  A file list can be used in many solutions with many reports.

 

 

 

Load, Save and Clear function similarly to the other load, save and clear buttons.  File Lists are saved to the directory:  “User Home\M2 RSM Wizard\input”.  When you load a file list, this is the location that should be used to retrieve the RSM input files.  Figure 11 shows an input file name of rsm_file_list.lst.  This is the default file name and is compressed for easy reading on the user interface.

 

 

The name expansion/contraction button expands and contracts the file name from “rsm_file_list.lst” to “C:\Documents and Settings\Username\M2 RSM Wizard\input\rsm_file_list.lst”.

 

 

 

Each region has a local help button that describes the purpose and use of the functions supported by the region.  This help will provide assistance to those users who like directed help text.

Figure 11:  RSM Input File List with Append

 

The name of the saved input file list file is automatically added to the command line with the “-F” RSM switch. 

 

 

The RSM Wizard orchestrates the components of the RSM command line and RSM generates the output report.  This region, Figure 12, supports the functionality for specifying the output format and the report or output path/file name.

 

Figure 12: RSM Output File Region

 

The Format selection check boxes are mutually exclusive and are dependent on the RSM switches selected for a report.  It is best to let the RSM Wizard choose the output format.  Once a report is selected or created, the disallowed formats will be grayed out allowing you to change the format as desired.

 

The output file name is supported by the name expand/contract button.  Expanding the name will help you identify where the file is stored on the file system.  RSM output reports should be stored in: “c:\Documents and Settings\username\M2 RSM Wizard\output” for Windows XP or “c:\Users\username\M2 RSM Wizard\output”.  You can choose to store input and output files in any location you select, but the RSM Wizard will assume you have used the default user locations.

 

     

 

The Open button enables a file selection dialog so that a file can be “Opened” according to the file system rules for opening a file.  The file system open may launch a web browser for a *.htm files, a text editor for *.txt files, a XML editor for *.xml files or a spreadsheet program for a *.csv files.

 

 

The Set button enables a file dialog for setting the name of the output file.  You must use one of the active output format file extensions.  The RSM Wizard will automatically select the correct output format from the file name extension. The file is created when RSM executes.  It is best to name the output with the code base, version and report type.

 

 

The RSM Wizard Reports region, Figure 14, comes with over fifty predefined reports.  These reports were created using the RSM Wizard.  You can use this region to select a report for execution or to create a new report.  A RSM Wizard Report is a file that contains the name of the report and the various RSM switches (including output format), switch options, and compound options.

 

Figure 13: RSM Command Line Construct

 

RSM Switch – A switch is a command line token that begins with a dash “-“.  The following are examples of RSM Switches:

 

      -F         Supports File Lists

      -H         Supports HTML output

      -f          Supports functional metrics and analysis

      -w         Supports differential work files

 

Hyperlinks connect to the RSM on-line documentation.

 

Reports are installed in the C:\Program Files\MSquared\M2 RSM Wizard\Reports.  These reports are system level reports and can be shared by all users of the install machine.  Pre-defined reports by M Squared Technologies begin with the prefix “M2 – “ followed by the name of the report, and concluded with a suffix of the report output  (Text), (HTML), (XML), or (CSV).  This naming convention is suggested for creating uniquely named reports which is a requirement for the Wizard. 

 

User reports are created by each user using the Wizard.  They are stored in the users home directory\M2 RSM Wizard\Reports.  If you want to share a personal report, you must move the file from your users home directory “c:\Users\username\M2 RSM Wizard\Reports” to system directory “C:\Program Files\MSquared\M2 RSM Wizard\Reports”.

 

Figure 14: RSM Reports, Switches, Options and Compound Options

 

 

Selecting a Report

 

Select a report from the report list by using a single left mouse button click to turn it blue, Figure 14.  This report is now selected for the final step of execution by clicking the [Execute] button.  Selection and execution can be accomplished in one step by a double left mouse button click of the report name.

 

When a report is selected, the report name, filename, lock and interactivity icons, and the switches and options are updated with the contents of the report file.  The report list window has a slider bar and operates with the up and down arrows from the keyboard.  Browsing the reports is a great way to learn about the various switches and options that are used in RSM.  Many UNIX and Linux users of RSM use the Windows RSM Wizard and RSM for interactive training about the switches and options.

 

Browsing Reports

 

The report list window, Figure 14, on the “RSM Reports” Tab, facilitates browsing of reports using the up and down arrows of the keyboard.  Begin by left mouse button clicking a report name in the window then press the up or down arrows.  As each report is selected, the appropriate report data is loaded into computer memory and displayed on the user interface.  Select each Switch/Option tab to review the switches and options used for a specific report.  The protection and interactivity state for each report is represented by the icons shown above the report window.

 

*  The Lock icon indicates whether the report is protected from deletion or edit.  The lock state for a user report can be changed on the “Switch u – z” Tab. When the icon is in the unlocked state, the report can be changed or deleted.  System or predefined reports that are located in the program install directory “c:\Program Files\MSquared\M2 RSM Wizard\reports” are protected from changing the lock state.  If you desire to escalate a user report to system status, lock the report and move it to the system directory.  Do not copy the report as this would violate the unique constraint on the report name.

 

 The report interactivity icon indicates whether the report runs automatically or whether it requires user input in additional dialogs.  Interactivity is not a state that can be changed by the user, but it is defined by the switches and options chosen for the report.

                 

                   

The swoosh image for the interactivity icon indicates automatic operation of the report once executed by a double click or the [Execute] Button.

 

                 

The person image for the interactivity icon indicates that user input is required while running this report within the RSM Wizard.

 

Report Region Buttons

 

  The Delete button will permanently delete the selected user report file.

 

  This button reloads the report files from the system and user report directories.

 

  This button will automatically launch your emailer for product support.

 

 

This button launches the report region help information.

 

Creating a Report

 

One of the most powerful aspects of the RSM Wizard is the ability to create new reports and have the Wizard construct the RSM command line.  Reports you create are defined as user reports.  These are classified differently than system reports.  System reports are stored in the Wizard installation directory “c:\Program Files\MSquared\M2 RSM Wizard\reports” and are not allowed to be deleted from the Wizard or unlocked for change.  User reports on the other hand are allowed to be deleted and changed.

 

 

When the “New” button is pressed, the switches and options from the currently selected report will be used for the new report or you can reset the report switches.  In the following example we will use the report name “My Report”.  We will reset all the report switches and   

 

 

The Wizard presents the default report name “New Report”.  The report name and file name edit fields are open for edit.  We enter “My Report” for the report name.  By clicking the left mouse on the file name field, the file name will automatically use the report name as the report file name.  You may change the file name to be different, but it is good practice to keep them the same.

 

 

Once the report is named, you can set the appropriate RSM switches and options.  The report “My Report” is selected as shown in Figure 15 by the blue high light.

 

Figure 15: Report Region for My Report Example

 

Switches and options are set using the Switch Tabs.  The switches and options are not associated with the report until the report is saved.  Then all the switches and output format are saved to the report.  For our example we will use:

 

      -fa        Functional Analysis

      -c         Complexity Metrics

      -o         Object Analysis

      -n         Quality Notices

      -S” Object and Function Metrics and Analysis”    Page Header String      

      -v         Verbose Metrics per file and project

      -x         Extended Report Options

 

Hyperlinks connect to the RSM on-line documentation.

 

 

 

                  Figure 16:  Switches for report example, -c and –fa

 

 

Figure 17: Switches for report example -n, -o, and -S

 

 

Figure 18: Switches for report example -v and –x

 

The output format choices depend on the switches chosen.  HTML was selected as the output format so that the file will open by the default web browser, show color in the report and scale with the increasing size of the report..

 

 

     

 

The Save button saves the switches, output format, name and file name to the report file.  RSM Wizard reports use the *.rpt as the file extension.  This extension must be used when saving the report file.

 

Figure 19: Report save dialog

 

 

 

The final step in the guided process is to execute RSM.  The RSM Wizard has constructed the command line for RSM.  Pressing the Execute button will create and launch an execution script for RSM using the command line.

 

The icon below is an embedded HTML document.  Double click the icon to launch the report within your web browser.

 

 

 

Figure 20:  RSM Command Line region

 

Figure 20 shows the RSM Command Line region.  This region is recalculated about 3 times per second when the “Auto” check bock is checked.  To copy and paste from the command line edit field, uncheck the “Auto” check box.  The following text break down is copied from the command line field.  The copy and paste facilities are supported in the edit field using the right mouse button. 

 

Command Line:

 

-H -O"C:\Documents and Settings\JoeUser\M2 RSM Wizard\output\my_newreport.htm" -c -fa -n -o -S"Object and Function Metrics and Analysis" -v -xNOCONFIG -F"C:\Documents and Settings\JoeUser\M2 RSM Wizard\input\rsm_file_list.lst"

 

Break Down by RSM Switch:

 

There is an implied order to RSM switches for best practices and some switches must be the last switch in the command line.  Switch example and order documentation is provided in the RSM on-line users manual ( ) or the embedded user manual provided with the installation of the product, manual.htm.

 

Note:  The RSM command line does not use relative path syntax by the switches.  You may use relative paths when the command interpreter or command shell expands the relative path and not the RSM program.  The RSM program does not expand relative paths.  The paths shown in the example are used by RSM switches so no relative paths are allowed.

 

RSM On-line Users Manual - Hyperlink

 

-H

-O"C:\Documents and Settings\JoeUser\M2 RSM Wizard\output\my_newreport.htm"

-c

-fa

-n

-o

-S"Object and Function Metrics and Analysis"

-v

-xNOCONFIG

-F"C:\Documents and Settings\JoeUser\M2 RSM Wizard\input\rsm_file_list.lst"

 

The following are new switches to our example.  They are created by the RSM Wizard.

 

-H                           HTML output format

-O                           Output file name matching the output format

-xNOCONFIG          Do not show the path/filename for the configuration file

-F                           Input file list

 

Note:  All paths used in the Windows command lines for RSM must be delimited with quotation marks.  Leaving out the quotes is a common error for command scripts.

 

 

The guided process buttons provide a simple perspective to using the Wizard.  Experienced users will opt to use the “Free Play” button as this opens the entire user interface.  Free play has some pitfalls.  You may inadvertently over write files before you rename them when you exit the wizard it will automatically save and retain its state unless this is turned off in the preferences.

Summary

The RSM Wizard provides a user interface to the Resource Standard Metrics program.  It simplifies the management of source code file lists and RSM switches and options.  The RSM command line is automatically built and executed by the Wizard.  The Wizard also provides an interactive learning aid to the RSM user for understanding the construct for each switch and the interdependencies between the switches.  By turning off the “Auto” check box, the Wizard command line can be cut and pasted into scripts or documents.  Many users use the Wizard under windows to build scripts for their UNIX build servers because it is easier than doing it by hand.