Command-line Interface

All MISS_HIT tools (except mh_diff) are built on the same framework, so they share many common aspects. For example the configuration files, but also the command-line interface.

All tools have two operating modes:

• Ad-hoc mode (the default)
• Project mode

To analyse one or more files, you don't need to do anything special. Just call the tool and provide the files you want to analyze. For example, this style checks my_file.m:

$ mh_style my_file.m

You can also provide directories. In this example we use the bug-finder to analyze other_file.m, and all applicable files in some_directory or its sub-directories:

$ mh_lint other_file.m some_directory

Finally, omitting files or directories will analyze all files in the current working directory and all its sub-directories. For example, this produces code metrics for all files:

$ mh_metric

Note: project mode is work in progress. Do not yet rely on it working.

Project mode is intended for larger projects, or multiple projects in one source tree (possibly sharing some common code). Project mode requires one or more configuration files, declaring at least one library or entry point. To analyze a project, indicate its name with the --entry-point parameter. For example, to produce code metrics for the potato project:

$ mh_metric --entry-point=potato_app.m

Project mode will also be required for advanced static analysis in mh_lint and mh_bmc (since it defines the search order and location for user-defined functions and classes).

Project mode is also helpful for users that maintain a large shared cope-base with multiple entry points. A common use case is to produce a code metric report, but only for the bits you're responsible for or are delivering: defining an entry-point or library provides you with a convenient short-hand instead of having to remember each time which directories/files you're responsible for.

Please note that MISS_HIT will not consider files and directories that would be invisible to MATLAB in project mode. Consider for example a projet layout like this:

  /
    miss_hit.cfg
    file1.m
    foo/
      file2.m
    +bar/
      file3.m

The configuration file contains the following information:

entrypoint "Potato" {}

When running MISS_HIT without project mode, all files are considered. However, when running MISS_HIT in project mode, only files file1.m and file3.m are considered. File file2.m is not considered because directory foo is not on the path, as declared in our entrypoint.

If you want to include file2.m in your analysis, then you have to include that directory in your entry point, like so:

entrypoint "Potato" {
  paths {
    ".",
    "foo"
  }
}

This behaviour is consistent with how MATLAB deals with its search path. For more information consult:

• Files and Folders that MATLAB Accesses
• Folders Containing Class Definitions

All MISS_HIT tools (except mh_diff) have these options. Some MISS_HIT tools have command-line additional options, which are described in the relevant tool user manuals.

Displays tool version and quits.

Show the tool version as the very first thing, but continue running as normal. This is helpful when debugging e.g. CI issues.

Can be specified more than once. Causes tool to analyze the given file or directory. If not given, causes the tool will analyze the entire working directory and all its sub-directories.

Specifies an entry point (as declared in a configuration file). When combined with additional file or directory arguments, the tool analyzes only that sub-set of the specified entry-point.

By default MISS_HIT uses multi-threaded analysis, which for large projects can significantly speed up analysis time. Using this option turns off this feature. This can be useful for debugging.

Note: you do not need to use this option to get a predictable report or error messages! Messages and reports are always sorted.

Do not attempt to parse configuration files.

By default this is cp1252. This option can be used to override the input encoding we use to parse m files. Note that this is not applicable to Simulink models, since they contain the correct encoding to use.

You can specify any valid Python input encoding here.

By default error messages come with a bit of context to help you identify the issue. For example:

In add_one.m, line 3
|     rv = x + 1;
|            ^ check (medium): operation saturates for some inputs
In add_one.m, line 3
|     rv = x + 1;
|            ^ info: counter-example trace: x = 2147483647

Using the brief option trims this down to one line per message, as shown below. This is especially useful for integration into IDEs.

add_one.m:3:11: check (medium): operation saturates for some inputs
add_one.m:3:11: info: counter-example trace: x = 2147483647

By default, MISS_HIT assumes a recent version of MATLAB. This option adds some support for Octave, but please note that this is quite limited. For now only the # comments are supported.

Please see issue #43 for outstanding features.

Ignores the special pragmas that MISS_HIT supports.

Ignore justification pragmas that mention a ticket. The use case here are justifications put into the code, which really are temporary justifications, e.g: "its ok for now, but we'll fix it in ticket ABC-123". For example you might want to process these normally during CI, but may want to check from time to time so that you can reduce technical debt.

Debug/developer option. This displays the search PATH for resolving user-defined functions and classes.