2

When I create a MEX file in MATLAB, I'm in the habit of also creating a .m file with the same name, a function signature identical to the MEX file, and otherwise containing nothing but help text in the form of comments, that are then displayed when one types help myfcn.

When one does this, a small side-effect is that MATLAB Code Analyzer picks up on the fact that the input and output arguments specified in the function signature are unused, and flags them with an orange underline.

Recently I've discovered that several MathWorks internal functions follow something similar to this pattern, but also including the following line, separated by a blank line from the main help text:

%#mex

This %#mex pragma appears to be undocumented (at least I can't find any reference to it). It would appear to be used to directly indicate that a .m file is intended only to provide help text for a MEX file. It has the effect of suppressing any Code Analyzer messages in the file.

Is anyone familiar with the intended use of the %#mex pragma? Does it have any other effects other suppressing Code Analyzer messages?

Examples:

\toolbox\compiler\mcc.m
\toolbox\images\images\private\ddist.m
\toolbox\matlab\audiovideo\private\readavi.m
\toolbox\matlab\imagesci\hdf.m
\toolbox\matlab\sparfun\arpackc.m
\toolbox\matlab\specgraph\private\ditherc.m
Amro
  • 123,847
  • 25
  • 243
  • 454
Sam Roberts
  • 23,951
  • 1
  • 40
  • 64

1 Answers1

2

Apparently this was documented in older releases. Here is a page from the archived documentation going all the way back to version 3.0 of the MATLAB Compiler (circa MATLAB 6.5 R13):

%#mex

This pragma informs the MATLAB Compiler to select the MEX-file over an existing M-file.

If you are using the %#function pragma to define functions that are not available in M-code, you should use the %#external pragma to define the function. For example:

function y = gamma(x)
    %#mex
    error('gamma MEX-file is missing');

Here is another related page that explains when this pragma is used:

It is now possible to call MEX-files from Compiler-generated stand-alone applications. The Compiler will compile MEX-files whenever they are specified on the command line or are located using the -h option to find helper functions. The MEX-files will then be loaded and called by the stand-alone code.

If an M-file and a MEX-file appear in the same directory and the M-file contains at least one function, the Compiler will compile the M-file instead of the MEX-file. If the MEX-file is desired instead, you must use the %#mex pragma. For more information on this pragma, see the %#mex reference page.

of course the MATLAB Compiler was a completely different product back then, capable of producing standalone C/C++ programs and MEX-files (no MCR dependency like today's version)

It seems that mlint still recognizes this pragma and completely excludes the M-file from analysis.

Amro
  • 123,847
  • 25
  • 243
  • 454
  • 1
    MATLAB Compiler product changed completely starting with MATLAB 7: http://www.mathworks.com/help/releases/R14/toolbox/compiler/ch01intro5.html#42226. It became a deployment solution rather than a code translation solution... The reasoning was that the newly introduced JIT accelerator makes compilation for speeding up code obsolete, so there was no longer a need to translate MATLAB into C code. Hence the MCR was born to execute packaged M-code. – Amro Sep 13 '13 at 00:07
  • 2
    Thanks @Amro, great detective work. On a historical note, IIRC the motive for introducing the new version of the compiler was not particularly that the JIT had made its speedups redundant, it's that it turned out that hardly anyone was using it to speed up code anyway; instead most users were using it as a solution for sharing applications to others without MATLAB. Those users were frustrated that a big subset of MATLAB code was not supported. Thus the MCR-based Compiler, which supports the entire MATLAB language. – Sam Roberts Sep 13 '13 at 08:39
  • 2
    ... There was still a need for some to convert MATLAB code into C code for speedup (despite the JIT, which in early versions was not always that great), and those users were pretty annoyed by the move to the MCR-based Compiler - they had a long wait until Embedded MATLAB (and later MATLAB Coder) came along. – Sam Roberts Sep 13 '13 at 08:40
  • I see, thanks for the insight! I was not a MATLAB user back then, but I probably wouldn't have liked the move to the MCR-based compiler either :) I can see the use for a self-contained MATLAB math library that you can link against in C/C++ programs just like any other numeric library, certainly nicer than code generation with MATLAB Coder – Amro Sep 13 '13 at 09:41