3.3 The Code Checker for MATLAB user interface
The graphical user interface of Code Checker for MATLAB on startup is shown in Figure 3.4↓
. 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.
Figure 3.3 General tab of the Code Checker for MATLAB GUI on startup
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 Figure 3.4↓
Figure 3.4 General tab of the GUI after choosing to check a file, folder or MATLAB project
After clicking File, several controls are shown.
By selecting Active in editor on the top switch, Code Checker for MATLAB 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 Code Checker for MATLAB.
button is used to browse for the file(s) to run Code Checker for MATLAB on. You can browse for any file with extension .m or .mlx. 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 Code Checker for MATLAB 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 3.9↓. The behaviour of this switch is equal for all three options (File, Folder, Project).
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, Code Checker for MATLAB 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 Code Checker for MATLAB.
button can be used to browse for the folder to run Code Checker for MATLAB 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.
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 Code Checker for MATLAB, you can easily check the files of a project.
Select Current project to have Code Checker for MATLAB 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.
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 Code Checker for MATLAB 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 Code Checker for MATLAB 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 Code Checker for MATLAB 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 3.10↓
tab shown in Figure 3.5↓
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 standards and rules onto the checks and reports of Code Checker for MATLAB. When running the Code Checker for MATLAB for the first time after installation (see Chapter 2↑
), the default configuration is created in the default folder that contains the configurations. For Windows this is:
After installing the CodeChecker, the predefined configuration MonkeyProof MATLAB Coding Standard++
becomes active. For more information on configuring checks, see Section 3.4↓
Figure 3.5 Configuration tab of the Code Checker for MATLAB GUI
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 Code Checker for MATLAB 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 Figure 3.6↓
. For more information on predefined configurations, see Chapter 5↓
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 Code Checker for MATLAB. 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 Chapter 4↓. 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.
Figure 3.6 Configuration tab of the Code Checker for MATLAB GUI after switching to a predefined configuration
tab as shown in Figure 3.7↓
lets you change the folder in which the HTML reports generated by Code Checker for MATLAB 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:
By default, only check results show up in the HTML report. By enabling Include metrics, you can have Code Checker for MATLAB include useful information such as a list of functions, a list of variables and a list of complexity values per function in the HTML report.
Use the Include passed checks option to have Code Checker for MATLAB 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.
Figure 3.7 Report tab of the Code Checker for MATLAB GUI
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.
Switch on Hide the user interface when starting a run to have the Code Checker for MATLAB user interface hide itself when the Run button is clicked. The user interface can be shown again using the shortcut (see Section 3↑) or the monkeyproof.cc4m.start command. Set the preference via the command line :
Switch the Run unconfigured checks to the right to have Code Checker for MATLAB run checks that are not in the selected configuration file. Default values are used for those checks. You can add unconfigured checks to your configuration file as described in Section 3.4.2↓. Set the preference via the command line :
Use the Open reports in a new tab preference to have Code Checker for MATLAB 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 :
With the Report violations when not entirely sure preference, you can choose whether you want Code Checker for MATLAB 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, Code Checker for MATLAB 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 :
Switch the Smart indent files before checking to the right to have Code Checker for MATLAB smart indent the selected files before checking them, or use the command line interface, see below. This feature for convenience purposes automatically modifies your code - it is your responsibility to make sure your code is (functionally) correct after these modifications.
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 :
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 :
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.
Smart indenting is always disabled for files in the MATLAB root since you are not allowed to change these.
Figure 3.8 Preferences tab of the Code Checker for MATLAB GUI
tab as shown in Figure 3.9↓
contains information about Code Checker for MATLAB:
The installed version of the Code Checker for MATLAB.
A button for opening the HTML documentation of Code Checker for MATLAB.
A button for accessing the Code Checker for MATLAB support forum.
A button for opening a license information dialog. From this dialog, you can extend or upgrade your Code Checker for MATLAB license. This dialog is described in Section 4↑.
Access the proxy settings by clicking Proxy settings.
Figure 3.9 About tab of the Code Checker for MATLAB GUI