User Guide

Using CC4M from MATLAB

For a quick introduction on how to check your code using CC4M, see this video. The tool runs by clicking the shortcut (see section Shortcut for the MATLAB Editor) or is started from the command-line calling monkeyproof.cc4m.start. More information on the user interface is given in section The CC4M user interface. The checker allows for checking one or more selected files, files in a folder (and its sub-folders) or a MATLAB Project. A choice can be made between checking all files or only those with local changes with respect to a SubVersion or GIT repository.

Supported file types are:

• MATLAB code (.m)
• Live Editor files (.mlx)
• App Designer apps (.mlapp)
• Simulink models (.slx, .mdl)
  • MATLAB Function blocks
  • MATLAB Functions in Stateflow Charts

For all file types except .m limitations apply as described in section Live Editor files, App Designer files and Simulink models. For obvious reasons, p-code files (obfuscated versions of m-code files) cannot be analyzed by CC4M.

Results from the metrics and all checks are shown in one result report. This result report contains the following sections:

• Meta data
• Summary
• Results
• Additional information
  • List of checks and parameters missing.
  • List of disabled checks.
  • List of toolboxes installed.

The content of most of these sections is described in section Metrics. Upon running CC4M, the report is saved as a webpage (.html) in the reports folder automatically for future reference. The report will be given a unique name based on a timestamp.

When running CC4M for the first time (see section Complete and verify installation), the reports folder is created at a default location. For Windows this is:

%APPDATA%\Roaming\cc4m\cc4m_reports

For Mac this is:

~/Library/Application Support/cc4m/cc4m_reports

For Linux this is:

~/.matlab/cc4m/cc4m_reports

The reports folder can be changed or requested from the command line or the GUI. See Function Reference for an overview of the options.

Using CC4M from Simulink (BETA)

Since R2021b Simulink has a toolstrip. From this toolstrip you can run CC4M on your model. The CC4M support for the toolstrip is still under construction. Included is a basic version that supports running the Monkeyproof MATLAB Coding Standard, the Coder Compatibility, and the new TargetLink Compatibility configurations.

Using the "Browse" option from the CC4M user interface allows for selecting models as well. Using the UI also enables using any configuration available.

Simulink integration limitations

• Analysis is performed on the complete model
• MATLAB Function Blocks are reported as "file" in the reports
• From the toolstrip only 3 predefined configurataions are available. When using the UI all other configurations can be used.

The CC4M user interface

The graphical user interface of CC4M on startup is shown in the figure below. It can be opened by entering monkeyproof.cc4m.start() in your command window or using the shortcut. The GUI consists of a number of tabs, each with multiple controls. This section describes all of them.

General

The General tab lets you select what files to check. The first step is to select whether you would like to check a file, folder, or MATLAB project. After making a selection, the relevant controls are shown. The controls for each of the options are shown in the figure below.

File

After clicking File, several controls are shown.

• By selecting Active in editor on the top switch, CC4M automatically selects the currently active file in the MATLAB editor. When the switch is set to Browse, the selected file(s) shown in the text field will be checked by CC4M.

• The button is used to browse for the file(s) to run CC4M on. You can browse for any file with extension .m, .mlx, .mlapp, .slx or .mdl. It is allowed to select multiple files. The results of all checked files are placed in one report. The files can also be selected by entering them in the text field. Multiple files can be selected this way by separating them with semicolons. Non-existing files will result in a warning and the button will be disabled until the selection is valid.

• The switch labeled Changed files only (when enabled: ) allows you to narrow the selection of files by only running CC4M on the selected files that have changed locally with respect to your Git or SVN repository. For this option, all selected files must be within the same repository. When disabled (), selected files are checked regardless of their status with respect to the repository.

• The bottom switch, Ignore exemptions allows you to switch off all exemptions to coding standards in your code for the duration of the run. For more information on exemptions, see section Exemptions. The behaviour of this switch is equal for all three options (File, Folder, Project).

Folder

If you would like to check the code of files in a folder, select the Folder at the top.

• By selecting Current directory on the top switch, CC4M automatically selects the current directory for checking. When the switch is set to Browse, the selected folder shown in the text field will be checked by CC4M.

• The button can be used to browse for the folder to run CC4M on. Similar to the File option described above, the folder can also be selected by entering it in the text field.

• Include subfolders, when turned on, selects the m-files in the selected folder and in all subfolders. This option can be very useful for checking an entire codebase, or a section thereof.

• Narrow the selection of files to check by enabling the Changed files only switch if desired. The selected folder must be (in) a repository for this to work. If the folder contains the repository in a subdirectory, no changed files are found.

Project

MATLAB projects provide a convenient way to set the bounds of your code and to define startup and shutdown tasks (among others). By selecting the Project option in CC4M, you can easily check the files of a project.

• Select Current project to have CC4M check the project that is currently open (if any). If there is no project open, the run cannot be started. This is also shown in the figure. By selecting Browse, the project file shown in the textfield will be checked.

• Use the button to browse for a project to check (.prj file). Alternatively, enter the absolute path of the project file in the textfield.

• Project files to be checked can be filtered by enabling the Skip files labeled 'Test' option. This removes all files labeled Test from the list of files that will be checked. Test files do not always have to meet (the same) coding standards as other files do. Applying the label to your test files is also useful for easily generating a testsuite for the project.

• The files to check can be further filtered by enabling Changed files only. This supports filtering files in the project based on their Git or SVN status. The selection includes files added to the project that have not yet been committed. In the case of a Git repository, uncommitted changes and staged changes are considered 'changes'. Newly added files need to be staged to be considered as 'changes'. If your changes have been committed locally, they will not be checked by CC4M if the Changed files only option is enabled.

After choosing the right options and starting the run, the selected project will be loaded if it is not loaded yet. You will be prompted to agree to this. Please note that because only one MATLAB project can be open at a time, loading a project closes any other open project.

MATLAB projects were introduced in MATLAB R2019a. If you are using a release older than that, the Project option will be disabled.

Starting the run

Once all settings are valid, the button will be enabled. This button is available on every tab in the GUI. After clicking it, the settings are applied and CC4M will run the checks on the files you selected using the rule configurations file of your choice. This action hides the GUI. Before running the checks on the files or folders you have selected, the code to check will be temporarily added to the MATLAB path so that the relevant information for properly performing the code analyses is available. During the analysis, property values may be initialized when gathering class information, if the checked code has class definitions among them. This may cause unexpected behaviour if the calculation of the initial values of properties deals with peripherals such as printing to the command window or reading from or writing to files. Potential errors during the initialization of properties are caught and will not interfere with the code analysis.

After analyzing the report and applying changes accordingly, you might want to run CC4M again to make sure the code satisfies the coding standards. Opening the GUI again using the shortcut or monkeyproof.cc4m.start()within the same MATLAB session restores the selected GUI settings so that the same file(s) can easily be checked again. Alternatively, use the rerun all button in the report that was generated as described in section Rerun functionality.

Configuration

The Configuration tab shown in figure Configuration tab of the CC4M GUI is used to select the rule configuration file that is used for checking your code. A rules configuration file is an xml file that can be used to map your own MATLAB coding standard onto the checks and reports of CC4M. When running CC4M for the first time after installation (see section Complete and verify installation), the default configuration is created in the default folder that contains the configurations. For Windows this is:

    %APPDATA%\Roaming\cc4m\cc4m_configurations

For Mac:

    ~/Library/Application Support/cc4m/cc4m_configurations

for Linux:

    ~/.matlab/cc4m/cc4m_configurations

After installing the CodeChecker, the predefined configuration MonkeyProof MATLAB Coding Standard++ becomes active. For more information on configuring checks, see section Configuring checks.

When the top switch is set to Custom, it means that a custom configuration file is selected for use during the checks. When the switch is set to Predefined, a configuration shipped with CC4M will be used to run the checks. Choosing this option hides the configurations folder selection and Import rules configuration file(s) controls as they are irrelevant for predefined configurations. The window you see will look like the one shown in the figure below. For more information on predefined configurations, see section Predefined Configurations.

• The button is used to select a folder in which your rules configuration files are stored locally. The folder can also be selected by typing it in the text field. Typing a non-existent folder will result in a warning and the button will be disabled until the selection is valid. If the selected folder exists, but contains no xml files, a warning and an additional button 'Place default configuration in selected folder' will be shown. Upon clicking this button, a configuration file with default settings will be placed in the selected configuration folder. Selecting a configuration folder is unavailable as long as the switch at the top of the tab is set to Predefined.

• The Import rules configuration file(s) option can be used to import one or multiple configuration files from for example a network drive to the configurations folder you selected above. Clicking this button will open a dialog that lets you choose any number of xml files. Upon clicking Open, the selected files are copied to the rules configurations folder you selected. If any of the configuration files to import already exists in the destination folder, you will be asked whether or not to overwrite them. By importing a rules configurations file instead of directly linking to it, you still have access to it, even if there is no internet connection or if it changes. This button is unavailable as long as the switch at the top of the tab is set to Predefined.

• The dropdown box under Rule configurations file lets you select a configuration file that is in the selected configurations folder. If the switch at the top of the tab The contents of this file are used to apply your coding rules to CC4M. Click the Open button next to the dropdown box to open the selected configurations file in the Configuration Editor. This lets you interactively edit the configuration file as described in section Configuration Editor. Click the New button next to the Open button to create a new configuration file. For MATLAB R2020b and newer, the description of the configuration set/file is shown below the dropdown box.

• Under Run checks by priority, you can filter the checks you wish to run by the priority you appointed to each of them. At least one of the boxes must be checked. Information on this selection is also shown in the meta data of the report.

Report

The Report tab, as shown in the figure below lets you change the folder in which the HTML reports generated by CC4M will be stored. If the entered folder does not exist, the folder and at most one parent will be created for you. In addition, there are some options that let you choose what to show in the report that is generated after the run:

• Use the Include passed checks option to have CC4M include entries for all checks in the HTML report, regardless of whether any violations were reported for them.

• Use the dropdown menu to select the number of entries to show in the check result table.

Preferences

On the Preferences tab, you can turn certain options on or off. The preferences available are listed below. These preferences can also be obtained and changed via the command line interface. However, the preferences only apply when running checks via the user interface.

• Switch on Hide the user interface when starting a run to have the CC4M user interface hide itself when the Run button is clicked. The user interface can be shown again using the shortcut (see section Shortcut for the MATLAB Editor) or the monkeyproof.cc4m.start command. Set the preference via the command line :

  monkeyproof.cc4m.setPreference('HideGuiOnRun', true);
  

• Use the Open reports in a new tab preference to have CC4M open its reports in a new tab instead of in the currently active tab of the MATLAB web browser (if any). This allows you to compare the results of multiple reports. It must be noted that auto-fixes and the rerun functionality will only work for the most recently generated report. Set the preference via the command line :

  monkeyproof.cc4m.setPreference('OpenReportInNewTab', true);
  

• With the Report violations when not entirely sure preference, you can choose whether you want CC4M to report violations when not completely sure about them. To illustrate this, consider the following example:

  var = myUnknownFcn();
  var.My_Field = true;
  

  In this case, CC4M is unable to detect whether var is a struct or an object. If it is a struct, it violates checkStructFieldCasing. Only when this preference is switched on will this situation be reported as a violation. By keeping this preference switched off, you can reduce the number of reported violations that are not actually violations of your coding standards. Set the preference via the command line :

  monkeyproof.cc4m.setPreference('ReportViolationsWhenUnsure', true);
  

• Switch the Exclude Live Editor files and App Designer files to the right to exclude the files in Open XML format from being checked.

  monkeyproof.cc4m.setPreference('ExcludeOxml', true);
  

• Switch the Exclude Simulink files to the right to exclude Simulink models from being checked.

  monkeyproof.cc4m.setPreference('ExcludeSimulink', true);
  

• With the Skip or check large files preference, you can choose what needs to be done with large files. Large file will take relatively long to process and may pollute the results report. Additionally, large files may be generated and not require checking at all. The preference has three options :

  • Ask every time: When one or more large files are selected for checking, you will be asked every run whether you would like to check or skip the large files.

  • Skip: Always skip large files if they are selected. Do not check them.

  • Check: Always check large files if they are selected.

  Set the preference via the command line :

  monkeyproof.cc4m.setPreference('SkipOrCheckLargeFiles', 'Skip');
  

• The File size threshold [kB] preference lets you specify the threshold in kilobytes above which selected files are considered 'large'. The value can be between 50 and 1000 kB. As a rule of thumb, you can assume that a thousand lines of code constitute about 50 kB. Set the preference via the command line :

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

The current value of a preference can be obtained , for example, by the command below where defaultValue is returned if the preference has not been set yet.

monkeyproof.cc4m.getPreference('FileSizeThresholdKb', defaultValue);

About

The About tab as shown in the figure below contains information about CC4M:

• The installed version of the CC4M.

• A button for opening the HTML documentation of CC4M.

• A button for accessing the CC4M support forum.

• A button for opening a license information dialog. From this dialog, you can extend or upgrade your CC4M license. This dialog is described in section License dialog.

• Access the proxy settings by clicking Proxy settings.

Configuring checks

CC4M has metrics and checks that are configurable. This way, the code checker can be adapted to fit the company's or the team's coding standards. A configuration file allows to define:

• Description of the check.
• Category of the check.
• Rule identifier the check is related to.
• Hyperlink to content of the rules.
• If the check is used (enabled) or not.
• Priority of the check.
• Severity level of the check.
• Parameter values: further customization.

The reports contain the configurations defined for the check and link it to an internal rules, see the figure below. It also includes a link to directly open the configuration of a specific check in the Configuration Editor. If you have specified a rules link, this will be accessible by clicking the rules ID in the report. If the link refers to a webpage, the rules link must start with https:// or http://. If your rules link contains a local drive address (i.e. C:\), links to specific pages in a PDF will simply open the file to the first page.

In order to provide insight in the settings of a check, information on its parameters is given in the report generated by CC4M. For every check that is enabled and has at least one parameter, the name, description, type, value and allowed values are shown. This information is obtained from the active configuration file. A link is also included that can be used to open the Configuration Editor to a specific parameter. An example of the information on a parameter for the check on variable casing as given in the report is shown in the figure below.

Edit the configuration files

Section Configuration Editor describes the Configuration Editor for CC4M. It is used to open the configuration file of your choice interactively. The Configuration Editor can be opened by using the Open button on the Configuration tab in the CC4M GUI. The selected configuration file will be activated and opened. The Configuration Editor can also be opened from the Meta data section in a CC4M report using the Open button next to the configuration file path. To start editing the configuration of a specific check or parameter, use the links in the check result tables of a CC4M report. You will not be able to save any configuration files in the folder for predefined configurations shipped with CC4M (see section Predefined Configurations).

You could also edit the XML file directly in the text editor of your choice. However, this is not recommended because it is unintuitive and error-prone. The Configuration Editor makes sure that the edits you make and save, make the configuration file pass validation.

Update the configuration file

If a new version of CC4M is released, new checks and check parameters may be added. Your existing configuration file can be updated so that it will include these missing parts with default values. After updating, the newly added check configurations can be edited so that they apply the settings reflecting your coding standards and rules. Configuration files can be updated using one of two syntaxes:

monkeyproof.cc4m.updateConfigurationFile();

% Update the specified configuration file.
monkeyproof.cc4m.updateConfigurationFile('<myFolder>/<configName>.xml');

As described in section Configuration Editor, this option is also available in the Configuration Editor by clicking Add unused checks. If you have run CC4M and a report was generated, it will include a section on missing check or parameter configuration. It also includes a link to directly update the configuration file. After using any of these last two options, a dialog is shown that tells you what checks and parameters were added. If you call monkeyproof.cc4m.updateConfigurationFile from the MATLAB command window, the list of added checks and parameters is given as an output to the function call.

Considerations

Comments in the configuration file get lost during this process. It is therefore advisable to -if applicable- adjust the description of a check or parameter instead of placing the additional information in comments the xml file.

Empty lines in the xml file are also lost during this process.

Remark

It is not allowed to update a predefined configuration.

Multiple configurations per check

To allow for a better mapping of your coding standards onto your CC4M configurations file, one check can be configured multiple times. The Code Checker distinguishes between different configurations based on the rule identifier. This is useful for example when there are multiple guidelines on what MATLAB-installed functions to avoid using, each with their own rationale, ID and list of function names. Results for a check that is configured more than once do have an individual checks result table in the report. Based on the rules identifier you can distinguish between the different results.

You can exempt specific configurations of a check or all configurations of the same check. This is described in section Exemptions.

Referencing configurations

There's the option to include other configuration files from within the active configuration file. This option allows one to stack rules that are split over several configuration files, for example a configuration file related to naming conventions, another configuration file related to layout and another configuration file related to code generation. More information about referencing configurations can be found in section Reference configurations.

Missing checks

If the checks available within CC4M do not cover something you want to have checked, please contact us at info@monkeyproofsolutions.nl.

Disabled checks and reports

A check or report can be disabled using your configuration. If a check/report is disabled, it will not be performed and you will therefore not see any results for it in the final report. However, a table listing all disabled checks and reports can be found at the bottom of the report. It also includes a link to the configuration of the check/report so that you can easily enable the check and change its configurations. For quick access to this table, a link to it is included in the metadata at the top of the report as described in section Meta data and summary, which also shows the number of disabled checks and reports.

Exemptions

You might want to exempt certain parts of your code from specific checks. By doing this, results for those checks on those parts of the code will not be contained in the report shown after CC4M is finished checking your files. Code can be made exempt from checks in a way that is similar to MATLAB's mlint that lets you disable warnings in the editor by using syntax like %#ok<NASGU>. Every check has its own unique five-letter exemption tag, except for the checks that you are not allowed to add exemptions for:

• checkCodeInterpretable

These tags can be used to exempt a line of code from a check by placing %@ok<MYTAG> behind it (where MYTAG is the tag of a check) somewhere in a comment on the line of code. By adding a '*' before the tag (so %@ok<``*``MYTAG>), you can exempt the entire file from a check. An example is shown below:

x = rand();
if x > 0.99 %@ok<IFELS> This is my explanation on why I don't want an 'else' here.
    disp('Hurray!')
    return
end %@ok<*AVFUN>

Normally (if the check is enabled), we would see this part of the code show up in the report because the if does not have an else section. However, by using the exemption tag for checkIfElse, it will not show up in the report. On the last line, we can see a file-wide exemption for checkAvoidFunctions. Doing this will make sure that return (or any function whose use you configure as discouraged) is not reported as a function to avoid for this file. The placement of this file-wide exemption within the file is irrelevant, as long as it is a comment.

As described in section Multiple configurations per check, a check can be configured more than once. In order to exempt your code of a specific configuration of a check (related to a specific rule) append the exemption tag with a dash followed by the rule ID. For example, to exempt your code of a configuration of checkAvoidFunctions with rule ID A1_0, add the exemption %@ok<AVFUN-A1_0>.

The exemptions can be ignored by switching on Ignore exemptions in the GUI.

Multiple exemptions can be defined on a single line like so:

y = x>0.99 %@ok<IFELS, *AVFUN, SURSP-MYID> My explanation.

Add exemptions automatically

In order to easily add exemptions to your code, you can use the Add exemptions column in reports generated by CC4M. This is shown in figure Add exemptions where the button in the third row has been clicked. Upon clicking the Add exemption button, an exemption tag is added to the file in which the violation was found and the file is opened at the place where you can add a comment on why the code is exempt from the check. The exemption tag will include the ruleID (if any) so that the automatically added exemption only exempts your code for one of configurations of a check. This is shown at the bottom of the figure. By clicking the Add file-wide exemption button, you can add a file-wide exemption (with *-notation) as described above. This feature takes pre-existing comments and exemptions into account when inserting the new exemptions.

For the automatic exemptions to work, the lines and line numbers at which to add the exemptions should not have been edited between running the check and clicking the Add exemption button. Doing so might result in a warning. After a button has been clicked and an exemption was added, the button will be disabled. This feature helps to keep track of the exemption buttons that have been clicked previously, but they do not reflect the most up-to-date state of the code. This feature for convenience purposes automatically modifies your code - it is your responsibility to make sure your code is (functionally) correct after these modifications.

Supporting functionality

• In order to easily add an exemption to your code without using a CC4M report, you can use function getExemption:

  >> theTag = monkeyproof.cc4m.getExemption('checkAvoidFunctions');
  

  This will return the exemption tag for the given check name as it can be used in your code (for example %@ok<FCNPF>). You can provide the full check name including packages, only the check name or even a partial check name as the input.

• The exemption tags of each of the checks are also given in this document under each individual description of the checks in section Checks.

• To get an overview of all exemption tags, use getAllExemptions:

  tagsTable = monkeyproof.cc4m.getAllExemptions();
  

  This will return a table containing the exemption tag for every check:

  

Limitation

• Note that adding exemptions is always disabled for MATLAB-installed files since you are not allowed to change these.

Rerun functionality

In the report, in the Meta Data and in the Summary sections, a Rerun all button can be used to quickly rerun CC4M using the settings that were used to create the report you are currently viewing. This is very useful to check if the changes you made after viewing the report result in improved rule compliance. It can also be useful if the configuration file has changed.

Remarks

• Although the report is intended to be portable, differences may occur due to external circumstances, such as using a different version of CC4M, different MATLAB toolboxes being installed, a different MATLAB path configuration, etc.

Automatic fixes

For several checks, auto-fixers are available. By clicking the Fix all button in the report (see figure Link to an auto-fixer in the CC4M report all violations for a specific (configuration of a) check are fixed. By clicking the Fix all in this file button all violations for a specific (configuration of a) check in a checked file are fixed. There is also a Fix on this line button, to fix individual violations. For this to work, the lines at which the violations were encountered should not have been edited between running the check and clicking the auto-fix link. Doing so might result in a warning. Similarly, fixing the same line twice will fix the violations the first time, and could trigger a warning on the second attempt. After a button has been clicked and its fix has been applied, the button will be disabled. This feature helps to keep track of the fix buttons that have been clicked previously, but they do not reflect the most up-to-date state of the code. After fixes have been applied, it is advised to run the check again to verify that the code now passes the check. Automated fixes are not available from the Model Advisor. This feature for convenience purposes automatically modifies your code - it is your responsibility to make sure your code is (functionally) correct after these modifications.

The checks for which fixes are currently available are:

• checkCopyrightNotice

• checkCommandSyntax

• checkExpressionAlignment¹

• checkFollowedBySpace

• checkMissingComma

• checkMissingSemicolon

• checkNoInputArg

• checkSurrBySpaces

• checkTabCharacterUsed

• checkWhiteSpaceEndOfLine

• checkZeroBeforeDecimalPoint

Limitation

• Note that automatic fixes are always disabled for MATLAB-installed files since you are not allowed to change these.

Live Editor files, App Designer files and Simulink models

Starting from MATLAB R2016a, Live Editor files (.mlx) and App Designer apps (.mlapp) can be created. CC4M supports checking these files as well as MATLAB code in Simulink models. However, there are some differences compared to the functionality for MATLAB code (.m):

• For Live Editor files and App Designer files, conversion from binary to text must take place before checking the code, which may involve opening the file in the Live Editor. This impacts performance and may focus the Live Editor.

• In MATLAB versions before R2020a, when the active file in the editor is a Live Editor file, the text field in the GUI is empty and the run cannot be started until a file is selected through different means.

• Auto-fixing Live Editor files and App Designer is disabled.

• Adding exemptions to Live Editor files and App Designer directly from the report is not possible. The exemption tag is provided in the Command Window and can be pasted in the appropriate place manually.

• For Live Editor Files, App Designer apps and Simulink models, compatibility issues between MATLAB releases may exist. If a file cannot be used in a MATLAB release, CC4M can also not check it in that release. It is recommended to verify if errors or warnings occur when opening files before running the checks.

• Links in the HTML report use MATLAB's opentoline function to link to the code. For App Designer apps, in some MATLAB releases this does not always put the cursor at the correct position. In those cases you may hover your mouse cursor over the link in the report and look at the status bar (bottom left) to see the line and column numbers.