Why does this require Mac or Linux to initialize the project?

Because basic Windows sucks as a programming environment. It doesn’t ship with any programming languages powerful enough to do even the basic text processing that our project initialization requires.

This might change now that Powershell is becoming more widespread.

Why is there so much stuff in this? It’s supposed to be a “basic” template!

Well: Matlab is a great tool, but as a programming language, its software development toolchain is somewhat anemic, and is oriented towards manual, interactive use. Plus its basic file IO API hs problems. So your project has to fill in the gaps.

For example: the Matlab .prj file format for generating Matlab Toolbox .mltbx files has a design flaw that bakes in absolute paths to your source code in the .prj file, which makes it unusable for projects with multiple developers. So we have to add in an additional layer to dynamically generate the .prj file from a .prj.in file and package_toolbox. And the Matlab Compiler and Toolbox builder both require you to have your project on the Matlab path and initialized, so we need to add in a layer of launcher scripts that can do that from the command line.

As far as Matlab itself, the fopen, copyfile, rmdir functions all return status codes instead of raising an error() on failure, which means you need to write a lot of return-value-checking code if you use them directly. You really need to have exception-oriented wrappers for all of them if you want to write concise, correct code.

And half the stuff in here is just about making decent documentation for your project; surely you want that!

If you really feel overwhelmed by all the stuff in your project repo, you can run make simplify after initializing it. This will pare the repo down by removing some nonessential features, like continuous integration, custom Java code, and custom C code.

Should I p-code my files?

No. P-coding is a weak obfuscation mechanism and provides no other benefits. It’s not strong enough to actually protect your intellectual property for proprietary software, and open source software shouldn’t be obfuscated.

But some users are going to want to P-code anyway, so we’re providing support for it.

Why isn’t MEX building part of the make build or make dist step?

Because you should actually check in all your compiled MEX files into your git repo! This makes it so that users can run your project directly from the repo. Users and even developers cannot be expected to have a setup on their machine where they can build the MEX files themselves. This is a different model from most programming languages.

You can use the dev-kit/buildallmexfiles.m function to build/rebuild all the MEX files in your source tree.

So, how can I build cross-platform MEX files to support all OSes?

Hell if I know. You’ll probably need to pay for a cloud CI system or set up your own multi-OS build farm.

This is why it’s good to avoid MEX files if you can.

Why do you put unit tests in the main Mcode/ dir instead of a separate top-level tests dir?

Because I think that projects, especially software libraries, should actually ship all their tests with the distribution, so that users can run the tests in their environment and ensure that the software operates correctly in that context.

The top-level dev-kit/ directory contains wrapper scripts for launching your tests from the main Mcode/ directory. This is a development tool that sits on top of the tests themselves.

GitHub is complaining about vulnerabilities!

When interacting with this project on GitHub, you may see this warning:

remote: GitHub found 7 vulnerabilities on janklab/MatlabProjectTemplate's default branch (3 high, 4 moderate). To find out more,

This is because the Java project for custom Java code declares dependencies on some of the Java libraries that Matlab ships with, and they are old versions with vulnerabilities. There is nothing we can do about this, because we’re stuck with the library versions that Matlab uses.

How about support for Git submodules for pulling in dependencies under lib/?

No. Git submodules suck, and are difficult for even experienced software developers to use. Stick with just copying the library distributions into lib/.