incremental build for Matlab < R2024b too

Author: scivision

Readme.md

@@ -10,13 +10,12 @@ Matlab or
 users coming from other languages will benefit from the functionality contained within this user-developed, unofficial "stdlib" standard library of functions.
 These system, filesystem, and HDF5 / HDF4 / NetCDF functions are used across numerous projects.
 
-Matlab ≥ R2022a is required to run the self-test suite.
 Matlab R2019b is the minimum required due to use of
 [arguments](https://www.mathworks.com/help/matlab/ref/arguments.html)
 syntax.
 URLs (e.g. https://, s3:// and similar) are treated as not existing.
 
-Self-tests can be run from that matlab-stdlib/ directory:
+Self-tests can be run from that matlab-stdlib/ directory with Matlab R2022b or newer:
 
 ```matlab
 buildtool test
@@ -25,9 +24,9 @@ buildtool test
 Functions requiring or optionally benefiting from MEX are indicated in the
 [API Documentation](https://geospace-code.github.io/matlab-stdlib).
 
-To build the optional high-performance
+Build the optional high-performance
 [MEX](https://www.mathworks.com/help/matlab/cpp-mex-file-applications.html)
-functions from the Matlab prompt:
+functions from the Matlab prompt in Matlab R2022b or newer:
 
 ```matlab
 buildtool mex

buildfile.m

@@ -15,6 +15,8 @@
   % can't use SourceFiles= if "mex" Task was run, even if
   % plan("test").DisableIncremental = true;
   % this means incremental tests can't be used with MEX files (as of R2024b)
+
+  plan("clean") = matlab.buildtool.tasks.CleanTask;
 end
 
 if ~isMATLABReleaseOlderThan("R2024a")
@@ -23,40 +25,45 @@
 
 plan("publish") = matlab.buildtool.Task(Description="HTML inline doc generate", Actions=@publishTask);
 
+%% MexTask
 bindir = fullfile(plan.RootFolder, pkg_name);
-if isMATLABReleaseOlderThan("R2024b")
-  plan("mex") = matlab.buildtool.Task(Actions=@(~)legacyMexTask(bindir));
-else
-  plan("clean") = matlab.buildtool.tasks.CleanTask;
+[compiler_id, compiler_opt] = get_compiler_options();
 
-  [compiler_id, compiler_opt] = get_compiler_options();
+if isMATLABReleaseOlderThan("R2024b")
+  % dummy task to allow "buildtool mex" to build all MEX targets
+  plan("mex") = matlab.buildtool.Task();
+  mex_deps = string.empty;
+end
 
-  for s = get_mex_sources()
-    src = s{1};
-    [~, name] = fileparts(src(1));
+for s = get_mex_sources()
+  src = s{1};
+  [~, name] = fileparts(src(1));
 
+  % name of MEX target function is name of first source file
+  if isMATLABReleaseOlderThan("R2024b")
+    mex_name = "mex_" + name;
+    % specifying .Inputs and .Outputs enables incremental builds
+    % https://www.mathworks.com/help/matlab/matlab_prog/improve-performance-with-incremental-builds.html
+    plan(mex_name) = matlab.buildtool.Task(Actions=@(context) legacyMexTask(context, compiler_id, compiler_opt));
+    plan(mex_name).Inputs = src;
+    plan(mex_name).Outputs = fullfile(bindir, name + "." + mexext());
+    mex_deps(end+1) = mex_name; %#ok<AGROW>
+  else
     plan("mex:" + name) = matlab.buildtool.tasks.MexTask(src, bindir, ...
       Options=[compiler_id, compiler_opt]);
   end
 end
 
+if isMATLABReleaseOlderThan("R2024b")
+  plan("mex").Dependencies = mex_deps;
 end
 
+end
 
-function legacyMexTask(bindir)
-
-[compiler_id, compiler_opt] = get_compiler_options();
-
-srcs = get_mex_sources();
 
-%% build C++ mex
-% https://www.mathworks.com/help/matlab/ref/mex.html
-for s = srcs
-  src = s{1};
-  [~, name] = fileparts(src(1));
-  disp("Building MEX target: " + name)
-  mex(s{1}{:}, "-outdir", bindir, compiler_id, compiler_opt)
-end
+function legacyMexTask(context, compiler_id, compiler_opt)
+bindir = fileparts(context.Task.Outputs.Path);
+mex(context.Task.Inputs.Path, "-outdir", bindir, compiler_id, compiler_opt)
 end