Contents > 5 Running SDMetrics from the Command Line
5 Running SDMetrics from the Command Line
You can run SDMetrics from the command line or shell scripts. This
is useful to integrate SDMetrics in automated processes.
The SDMetrics command line syntax is:
java com.sdmetrics.SDMetrics -xmi xmifile [-proj projfile] [-customPF pfsetname]
[-meta mmfile] [-trans transformationfile] [-metrics metricsfile]
[-filter filterstring]* [-nonmatching] [-ignore]
[-compare 2ndxmifile] [-mapping mapfile] [-relative]
[-gHisto] [-gCumDist] [-gKiviat] [-gFormat format]
[-gHTMLPerDiag] [-gHTMLPerType] [-gHTMLForAll]
[-gUseFrames] [-gWidth width] [-gHeight height]
[-model] [-stats] [-relmat] [-rules [-rulefilter filter]]
[-nometrics] [-s] [-one] [-f format] basename
The arguments in square brackets  are optional. When followed by an
asterisk (*), the bracket contents can be repeated an arbitrary number
of times, otherwise, at most one occurrence is allowed.
The meaning of the arguments is as follows.
Project file settings:
- xmi xmifile: XMI file for the design to be analyzed.
- proj projfile: name of a project settings file
created via the GUI.
SDMetrics reads the project settings file and processes the project files
as specified in there.
- customPF pfsetname: specifies the name of the project files
set to use for the analysis. If not specified, SDMetrics will automatically
determine a project file set to use
- meta mmfile: file containing the SDMetrics
If you do not specify a metamodel definition file, the
metamodel of the project file set is used.
- trans transformationfile: file containing the XMI
transformations to be used to read the XMI file.
If you do not specify a transformation file, the transformation
file of the project file set is used.
- metrics metricsfile: file containing the definition of
If you do not specify a metrics definition file, the
metrics definition of the project file set are used.
Design comparison settings:
- filter filterstring: adds filter filterstring
to the list of element filters to apply.
- nonmatching: When set, SDMetrics rejects elements that
match none of the filters. The default (switch not set) is to reject
elements that match at least one of the filter strings.
- ignore: When set, links to rejected elements are not
considered during metric calculation. The default (switch not set) is
to consider links to rejected elements.
Output file settings:
- compare 2ndxmifile: perform a design comparison with the
design specified via the -xmifile or -proj switch,
and output the metric deltas. Note that 2ndxmifile contains
the second or newer design.
- mapping mapfile: file with element mappings to use for
the design comparison.
- relative: Show deltas as relative percentages in output.
Graph export settings:
- basename: Base name of the file(s) the output will be
- model: additionally create a set of tables containing the
UML model. Files will have suffix "MODEL" appended to the
- stats: additionally create a set of tables containing the
descriptive statistics. Files will have suffix "SD" appended to
the base name.
- relmat: additionally create a set of tables containing
the relation matrices. Files will have suffix "RM" appended to
the base name.
- rules: additionally create a set of tables containing
the design rule violations. Files will have suffix "RULES" appended
to the base name.
- rulefilter filter an optional rule filter string
specifying the rules to apply.
- nometrics: suppress export of metric data. Metric data
tables are always created by default, unless you set this switch.
- s: sanitized output; when set, model element names are
not written to the output files (metric data tables only).
- one: one file; when set, each set of tables is written to
one file, otherwise each data table is written to a separate
- f format: format of the output file(s). Admissible
txt: Tab-separated text tables.
This is the default if no format is specified.
csv: Comma-separated text tables.
html: HTML files containing the data in HTML tables.
ods: OpenDocument spreadsheet files for OpenOffice/LibreOffice.
xml: XML spreadsheet files for Microsoft Excel XP.
sxc: Spreadsheet files for OpenOffice.org 1.0 and later.
- gHisto: additionally export metric histograms. Files will
have suffix "HISTO" appended to the base name.
- gCumDist: additionally export cumulative distribution
graphs for metrics. Files will have suffix "CUMDIST" appended to the
- gKiviat: additionally export kiviat diagrams for model
elements. Files will have suffix "KIVIAT" appended to the base name.
- gFormat format: format for the graphs to generate: SVG (default), PNG, or JPG
- gHTMLPerDiag: create one HTML page for each individual graph
- gHTMLPerType: create one HTML page for each element type
- gHTMLForAll: create one HTML page for all graphs
- gUseFrames: use frames for HTML graph pages
- gWidth width: width of the graphs in pixels (default: 640)
- gHeight height height of the graphs in pixels (default: 400)
- java com.sdmetrics.SDMetrics -proj mypsettings.txt -s -f html
Reads the project files and filter settings from file
mypsettings.txt and writes the sanitized output to separate
- java com.sdmetrics.SDMetrics -xmi myDesign.xmi data
XMI file myDesign.xmi with standard XMI transformations,
metamodel, and metrics, and writes the output in separate text files
with tab-separated tables (output files start with name
- java com.sdmetrics.SDMetrics -xmi myDesign.xmi -rules
-rulefilter design -format html data
Reads XMI file myDesign.xmi with standard XMI
transformations, metamodel, and metrics, writes the metric data to
separate HTML files (output files start with name data),
checks the design rules and writes the design rule violations to
separate HTML files (output files start with name dataRULES).
- java com.sdmetrics.SDMetrics -xmi myDesign.xmi -metrics
myMetrics.xml -filter #.java -filter #.javax -nometrics -stats -one -f
Reads XMI file myDesign.xmi with standard XMI transformations
and metamodel, calculates metrics defined in myMetrics.xml,
filters elements defined in the java and javax packages, and writes the
descriptive statistics for the metrics to an OpenOffice.org Calc
workbook file named dstats.sxc.
(Note: on some platforms,
the # character may have a special meaning and needs to be protected
from the shell, usually by preceding it with a backslash or enclosing
the filter name in quotes).
- java com.sdmetrics.SDMetrics -xmi myDesign.xmi -filter
MyModel.MyPackage -nonmatching -model -one -f csv myDes
Reads XMI file myDesign.xmi with standard XMI transformation
and metamodel, filters all elements outside package
MyPackage, and writes the metric data to file
myDes.csv, and dumps the model to file
- java com.sdmetrics.SDMetrics -xmi myOldDesign.xmi -compare
myNewDesign.xmi -mappings MyMappings.txt -stats -one -f xml
Reads XMI files myOldDesign.xmi and myNewDesign.xmi,
calculates the metric deltas using the element mappings from file
MyMappings.txt, and writes the metric deltas and comparison
of descriptive statistics to files deltas.xml and
- java com.sdmetrics.SDMetrics -xmi myDesign.xmi -one -f xml -gHisto
-CumDist -gFormat PNG -gHTMLforall -gUseFrames myDes
Reads XMI file myDesign.xmi, writes the metric data to file
myDes.xml, creates a set of PNG files with histograms
(myDesHISTO_*.png) and cumulative distributions (myDesCUMDIST_*.png)
for all metrics, and creates a set of HTML pages with frames that show
the graphs (myDesHISTO_index.html, myDesCUMDIST_index.html plus
additional HTML navigation pages).