Initial draft of MEX best practice

[rpurser47]

The proposed organization is meant for toolboxes that implement MEX functions using C/ C++/ Fortran for implementing features. They might also interface with external libraries.

[rpurser47]

This will require internal MathWorks review before it's merged into main.

[gulley]

Looks good.

I'm glad this is its own standalone document and not part of the main Toolbox Design doc.

At the top, maybe give etymology of MEX as "MATLAB EXecutable file".

"Let's explore the world of MEX integration!" This sounds a little too ChatGPT chirpy.

Maybe mention earlier that the actual compiled MEX files themselves are derived via the build process and so don't even appear in the folder. We only see, for example, subtract.m and subtract.cpp.

We should be clear about the fact that derived files shouldn't be checked into revision control. The whole concept of derived files is alien to a lot of our pure MATLAB users (i.e. they never really trained on any other language or language ecosystem).

Typo? line 47 "mex function" => "MEX function"?

[colbysparks]

It would be great if this documentation included some comments to address forward / backward compatibility of MEX binaries with different versions of MATLAB. From what I've read, there is no guarantee that a MEX file compiled and linked against one version of ML will work with another (this appears to be the official stance, and these forum posts agree: post 1, post 2).

With that in mind, it seems like the official best practices for building a toolbox which targets different versions of ML might be either:

• A: That your toolbox build-step should compile MEX files for every version of ML that you want to support, or
• B: It should require that the user has a C++ compiler installed so that it can build the MEX files for their specific ML version and system-architecture.

[rpurser47]

With that in mind, it seems like the official best practices for building a toolbox which targets different versions of ML might be either:

• A: That your toolbox build-step should compile MEX files for every version of ML that you want to support, or
• B: It should require that the user has a C++ compiler installed so that it can build the MEX files for their specific ML version and system-architecture.

Hi @colbysparks, thanks for commenting on this -- definitely interested in any and all insights you have.

• We can't guarantee forward and backward compatibility, but given that the C language mex interface and the C Matrix API has been pretty stable for many years, it's generally pretty safe. We did modernize the internal representation of arrays (especially complex), which is probably the single biggest change.
• C++ is a different animal. In C++, there's no guarantee that the ABI will remain consistent between OS versions and compiler versions. We work hard to shield users from this, but there's only so much we can do.

I would offer a third option: Automated multirelease testing of your MEX functions. Our GitHub Actions provide a way to run your tests automatically against a range of releases and platforms. Visit my Climate Data Store Toolbox for an example of doing that.

That said, I will consult with some of our experts to see if there's something we can do to provide guidance on this. Would you open an issue on the repository about this?

Thanks,
-Rob

[rpurser47]

• @bpancras to revise this (or delete the comment

[rpurser47]

When merged, this Closes: #10