Command line interface

Calling monkeyproof.cc4m.start without input arguments opens the graphical user interface that lets you choose what files to check and how. These options are also available from the MATLAB command window.

Syntax

  • monkeyproof.cc4m.start() opens the graphical user interface.

  • monkeyproof.cc4m.start(_, Name, Value) specifies additional named input arguments, example: monkeyproof.cc4m.start('runSeverities', 5).

  • monkeyproof.cc4m.start(_, Flag) specifies additional flags, example: monkeyproof.cc4m.start('-editor').

  • fileLocation = monkeyproof.cc4m.start(_) returns the path to the created report.

Named arguments

  • configFile The configuration file path.

  • file Absolute path(s) of the file(s) or folder to check.

    • MATLAB file (.m, .mlx, .mlapp, .slx, .mdl), only that specific file is checked.
    • Cell array of MATLAB file names or a semicolon-separated list of MATLAB file names, these are all checked.
    • Folder, all MATLAB files in that folder (non-recursively) are checked.
    • 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.
    • 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.

  • fileSizeThreshold The file size threshold in kB for skipping large files. Only used in combination with the -skipLargeFiles flag.

  • matlabPath Path to set before starting the run. The current path is restored after the run. If this option is used, the files selected for checking are not added to the MATLAB path if the path you specify does not say so.

    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.

  • reportsFolder Reports output folder.

  • runPriorities Only run the checks with the specified priorities (cell or string array). Allowed values are: Mandatory, Strongly recommended, and Recommended. If the input argument is not provided, checks with all priorities will run.

  • runSeverities Only the checks with a severity level below or equal to the specified value (1-10).

  • showReportEntries Number of report entries to show in one page.

Flags

  • -browse Open a file dialog to browse for a folder to check. Browsing for a file is not supported by this option.

  • -changedOnly Check only files that have uncommitted changes in a Git or SVN repository. If the selected folder is not inside a repository, no files are checked.

  • -comment A user provided comment that will be added to the report's content.

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

  • -doNotOpenReport The created report will not be opened at the end of the run.

  • -editor Run 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.

  • -excludeOxml Exclude mlx and mlapp files.

  • -excludeSimulink Exclude Simulink models.

  • -generateJSON Generate a JSON report instead of an HTML report.

  • -generateJSONSummary Generate a JSON summary report.

  • -ignoreExemptions Ignore exemptions and report the violations that are found.

  • -license Used to refresh the license.

  • -openReportInNewTab Open the created report in a new tab.

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

  • -recursive Check files in subfolders of the selected folder as well.

  • -reportPassed Report results for checks that have no violations.

  • -reportViolationsWhenUnsure Report violations when unsure. May lead to false positives.

  • -skipLargeFiles Skip files larger than the threshold specified with named argument fileSizeThreshold.

  • -skipTests Skip files labeled 'Test' (MATLAB project only).

System integration

In order to integrate CC4M in your (continuous integration) systems, you may want to utilize the additional capabilities described in this section.

Generating JSON reports

Generating JSON reports requires the feature to be enabled in your CC4M license

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 guidelines compliance over time, which can be especially advantageous to your development process when running CC4M on a designated machine.

The JSON report is saved to the same location as HTML reports. The summary 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 less severe 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.

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: Information about the environment.
      • CodeCheckerVersion: CC4M release number.
      • MATLABVersion: MATLAB release number.
      • OperatingSystem: The operating system.
    • RootFolder: Common 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.
    • NrMissingParamConfig: The number of missing parameter configurations.
    • MissingParamConfig: The missing parameter configurations.