Pro Features

This section describes the features available when you have obtained a Pro license for CC4M. These features are about the MATLAB command window interface. You can check whether or not you have a Pro license by tyring to use the command window interface. As example, have a file open in the MATLAB editor and call

>> monkeyproof.cc4m.start('-editor');

If this is not working you do not yet have the Pro license. If you are interested in the Pro license, contact us at info@monkeyproofsolutions.nl. For support, Pro users can send an e-mail to support@monkeyproofsolutions.nl. We aim to get back to you within one workday. Alternatively, you can check out our Code Checker for MATLAB forum.

Run from the command window

Calling monkeyproof.cc4m.start without input arguments opens the graphical user interface that lets you choose what files to check and how. Almost all of these options are also available from the MATLAB command window. In the different options and syntaxes described in this section, character vectors and cell arrays thereof are used. The same options can also be used using strings and string arrays.

Select files for checking

The file(s) or folder to run CC4M on can be set using the following syntaxes:

>> monkeyproof.cc4m.start('file', location);

Runs the checks on the file(s)/folder location (absolute path).

  • If location is a MATLAB file (.m or .mlx), only that specific file is checked.

  • If location is a cell array of MATLAB file names or a semicolon-separated list of MATLAB file names, these are all checked.

  • If location is a folder, all MATLAB files in that folder (non-recursively) are checked.

  • If location is a file with extension .txt, the file is read and the list of MATLAB files within it is checked. All files listed in the txt-file must be on a separate line.

  • If location is a file with extension .prj, the files in the given MATLAB project are checked. The project will be loaded (closing the open project if any) before checking the code.

Instead of providing the file/folder/project to check directly in the input, the following options can be used:

>> monkeyproof.cc4m.start(option);

Where option can be one of the following:

  • '-editor' runs the checks on the file that is currently open in the MATLAB editor (if there is one open and it is an m-file). Even though live editor files can be checked using CC4M, this option does not support it and you will have to enter the live editor file using another option.

  • '-pwd' runs the checks on the current working directory (as would be returned by MATLAB when calling function pwd).

  • '-browse' lets you browse for a folder whose files to check. Browsing for a file to check is not supported by this option.

  • '-currentProject' runs the checks on the files of the currently open MATLAB project.

Additional options

The runPriorities parameter can be used to run only the checks with the given priorities. The syntax for doing this is as follows:

monkeyproof.cc4m.start(_, 'runPriorities', {'Recommended', 'Strongly recommended'});

This would run all checks (that are not disabled by your configuration file) with priority Strongly recommended and Recommended. The supported priorities are: Mandatory, Strongly recommended, and Recommended. If the parameter is omitted from the inputs, checks with all priorities will run. This option applies check filtering on top of what is configured in your configuration file.

The runSeverities parameter can be used to run only the checks with a severity level below or equal to the maximum level set. The syntax for doing this is as follows:

monkeyproof.cc4m.start(_, 'runSeverities', 5);

This would run all checks (that are not disabled by your configuration file) with a severity level between 1 and 5. The supported severities are in the range of 1 through 10. The most important ones are of severity level 1 and next levels are reserved for more pedantic issues. If the parameter is omitted from the inputs, checks with all severity levels will run. This option applies check filtering on top of what is configured in your configuration file.

Additional options can be provided as input arguments to further customize the run. The syntax is as follows:

monkeyproof.cc4m.start(_, option1, _, optionN);

where option1 through optionN can be the following:

  • '-recursive' is used when a folder is selected. It makes sure all files in all subfolders of the selected folder are also checked.

  • '-changedOnly' removes files that have not changed with respect to a Git or SVN repository from the list of files to check. If no repository is found or the selected folder is outside a repository, no files are checked.

  • Including '-includeMetrics' in the inputs causes CC4M to include full reports of all metrics, even if there are no violations.

  • '-reportPassed' causes the CC4M report to contain results for all checks, even those that have passed. If a check passed without violations, only its configuration values are shown.

  • '-ignoreExemptions' runs the checks and all exemptions are ignored. This means that if code is marked as exempt from specific checks, it is still reported as a violation if it violates the rules.

  • When checking the files in a MATLAB project, you can add option '-skipTests' to have CC4M skip all project files labeled Test. When not checking a MATLAB project, this option is ignored.

  • '-doNotOpenReport' disables opening of the created report after the run.

  • '-skipLargeFiles' lets you automatically skip large files so that they will not be checked when selected. You can set which files are considered 'large' by using

    monkeyproof.cc4m.setPreference('FileSizeThresholdKb', sizeInKb);

Additionally the file location of the created report can be returned:

fileLocation = monkeyproof.cc4m.start(_);

Setting the MATLAB path

In order to make sure that the right folders are on the MATLAB path at the time of checking, an additional input parameter can be provided. The syntax is as follows:

monkeyproof.cc4m.start('matlabPath', 'C:\Files\myFolder;C:\AnotherFolder');
monkeyproof.cc4m.start('matlabPath', 'C:\Files\MyDocuments\MyPath.txt');

The MATLAB path to set can be a semicolon-separated character array of the different parts of the path. Alternatively, the path can be provided in a txt-file. This text file can have the different parts of the path on separate lines, or they can be separated by semicolons.

The path used during the CC4M run is set as follows:

  1. Keep all folders that contain MATLAB-installed functionality on the path.

  2. Keep all CC4M code on the path.

  3. Add the parts of the path specified in the input by the user to the path.

The approach listed above allows you to specify only the paths of the code that you want to check and of the local code it depends on.

Some additional remarks regarding this feature:

  • It is not a problem if the same folders are added to the path multiple times.

  • After the report has been generated, the original MATLAB path is restored.

  • If this option is used, the code selected for checking is not added to the MATLAB path if the path you specify does not say so.

Adding an additional comment to the report

It's optional for the user to add an additional comment to the report, for example the URL of the pull request that triggered the CC4M run. The syntax is as follows:

>> monkeyproof.cc4m.start(..., 'comment', 'I-Triggered-The-CodeCheckerForMATLAB-Run');

System integration

In order to integrate CC4M in your (continuous integration) systems, you may want to utilize the additional capabilities described in this section. The feature to generate a JSON report is not available with a Pro license by default. If you wish to use them, please contact us at info@monkeyproofsolutions.nl. The feature to generate a JSON summary is available with a Pro license.

Generating JSON reports

By adding '-generateJSON' to the inputs of your call to monkeyproof.cc4m.start, a JSON report will be generated instead of an HTML report. The versatility of JSON allows you to integrate the results with other tools or programming languages. Together with the command window interface described in section Run from the command window, your code can be checked automatically (for example using hooks, or periodic triggers) and the results can easily be stored and interpreted at a later point in time. This facilitates analyzing your coding rules compliance over time, which can be especially advantageous to your development process when running CC4M on a designated computer.

The JSON report is saved to the same location as HTML reports would be. This location can be obtained using monkeyproof.cc4m.getReportsFolder() and changed using

monkeyproof.cc4m.setReportsFolder(<The/Folder>). The report has extension .json. This option is not available from the graphical user interface.

The elements of the JSON report are as follows:

  • MetaData: Global information regarding the run.

    • CheckPrioritiesRun: The priorities of the checks that were run.

    • MatlabPath: Can assume one of several forms:

      • “Custom” indicates that a custom MATLAB path was provided for the CC4M run.

      • “Local” means that no changes were made to the path for the CC4M run.

      • “xxxx.txt” where xxxx is the absolute path to a text-file indicates that the MATLAB path was provided using a text-file.

    • Version: CC4M release number.

  • MatlabErrors: Information on what files could not be checked due to errors in them.

    • FileName: Path of the file containing the error(s).

    • ErrorMessages: One or more error messages and the location of their source.

      • Msg: The error message as given in the MATLAB editor.

      • LineStart: The line number at which the error is shown.

      • LineEnd: The end line of the cause of the error.

      • ColumnStart: The start column at which the error is shown.

      • ColumnEnd: The end column of the error.

  • CheckResults: Per checked file, the results.

    • FileName: Path to the file that is checked.

    • Checks: List of checks and their results.

      • Name: Unique name of the check.

      • CheckResult: Status of the check. For example “fail”.

      • RuleID: Identifier of the rule.

      • RuleLink: URL of the rule.

      • Priority: Priority of the check as configured. Can be “Recommended”, “Strongly recommended”, or “Mandatory”.

      • SeverityLevel: Severity level of the check as configured. Severity level of the rule can be in the range from 1 to 10. The most important ones are of severity level 1 and next levels are reserved for more pedantic issues.

      • DefaultConfig: true if the default values of a check or parameter were used due to problems with the configuration. This is the case when a check is configured multiple times, if it is missing from the configuration file, or if a check's parameters are configured more than once or not at all.

      • ReferencedConfig: If applicable, the referenced set of configurations the check configuration came from. This field is not there if the check configuration is defined in the active set of configurations.

      • Results: Information on the possible violations of the check. Per violation:

        • Msg: Description on what went wrong.

        • LineNr: Line number at which the violation was detected.

        • ColNr: Column at which the violation was detected.

        • IsExempt: Whether or not the violation is exempt from the rules.

        • ExemptionReason: The comment on the line of code after the exemption (if any).

Generating JSON summary

By adding '-generateJSONSummary' to the inputs of your call to monkeyproof.cc4m.start, a JSON summary will be generated together with the HTML report. The JSON summary can easily be integrated with other tools or programming languages. Together with the command window interface described in section Run from the command window, your code can be checked automatically (for example using hooks, or periodic triggers). This facilitates analyzing your coding guideline compliance over time. And if, based on the information in the JSON summary, you want to see all detailed results, one can open the HTML report corresponding to the run.

The JSON summary is saved to the same location as HTML reports. The summary has extension .json. This option is not available from the graphical user interface but unlike the JSON report, this feature is available with a Pro license by default.

The elements of the JSON summary are as follows:

  • MetaData: Global information regarding the run.

    • RunDuration:Message containing the number of violations for X rules in Y files out of Z files with the elapsed time.

    • TimeOfCheck:Date and time the run is executed.

    • UserName:Name of user that executed the run.

    • UserComment:A user comment that the user added to the report's content (if any), for example the pull request URL related to the run.

    • Settings:Settings for the run. Such as: file/folder/project, including subfolder, all files or only local changes, priorities selected etc.

    • EnvironmentInfo:lnformation about the environment.

      • CodeCheckerVersion:CC4M release number.

      • MATLABVersion:MATLAB release number.

      • OperatingSystem:The operating system.

    • RootFolder:Comon root of the files checked.

    • ReportsFolder:Folder that contains both the JSON summary and the HTML report.

    • HTMLReport:Link to the HTML report that contains the complete set of results.

    • TrialInfo:If applicable, information about the expiring trial license.

  • Results: The results.

    • FilesChecked:Path to the files that are checked.

    • NrChecksRun:The total number of checks ran.

    • NrViolations:The total number of violations.

      • PerCheck:Results per check.

        • RuleID: Rule identifier the check is related to.

        • CheckName: Name of the check.

        • Priority: Priority of the rule.

        • SeverityLevel: Severity level of the rule.

        • NrViolatedFiles: The number of files that violate this rule.

        • NrViolations: The number of violations.

    • PerPriority:Results per priority.

      • Mandatory: The number of rules with priority Mandatory that got violated.

      • StronglyRecommended:The number of rules with priority Strongly Recommended that got violated.

      • Recommended:The number of rules with priority Recommended that got violated.

    • FilesWithError:List of files that could not be checked due to errors in them.

  • Configuration: Information about the used configuration.

    • Type:The type of the configuration used; Predefined or Custom.

    • Name:The name of the configuration used.

    • NrChecks:The number of enabled checks and reports after applying priority filtering.

    • NrReferencedChecks: The number of check configurations that came from referenced sets of configurations (if any).

    • NrReferencedConfigs: The number of referenced sets of configurations used for the currently active set of check configurations (if any).

    • ReferencedConfigs: A list of referenced sets of configurations used for the currently active set of check configurations (if any).

    • NrCustomChecks:The number of custom checks in the configuration.

    • NrDisabledChecks:The number of disabled checks and reports.

    • NrMissingConfigs:The number of missing checks configurations.

    • MissingConfigs:The missing checks configurations.

    • NrDuplicateConfigs:The number of duplicate checks configurations.

    • DuplicateConfigs:The duplicate checks configurations.

    • NrMissingParamConfig:The number of missing parameter configurations.

    • MissingParamConfig:The missing parameter configurations.